1=pod 2 3=head1 NAME 4 5OSSL_CMP_exec_certreq, 6OSSL_CMP_exec_IR_ses, 7OSSL_CMP_exec_CR_ses, 8OSSL_CMP_exec_P10CR_ses, 9OSSL_CMP_exec_KUR_ses, 10OSSL_CMP_IR, 11OSSL_CMP_CR, 12OSSL_CMP_P10CR, 13OSSL_CMP_KUR, 14OSSL_CMP_try_certreq, 15OSSL_CMP_exec_RR_ses, 16OSSL_CMP_exec_GENM_ses, 17OSSL_CMP_get1_caCerts, 18OSSL_CMP_get1_rootCaKeyUpdate, 19OSSL_CMP_get1_crlUpdate, 20OSSL_CMP_get1_certReqTemplate 21- functions implementing CMP client transactions 22 23=head1 SYNOPSIS 24 25 #include <openssl/cmp.h> 26 27 X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type, 28 const OSSL_CRMF_MSG *crm); 29 X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx); 30 X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx); 31 X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx); 32 X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx); 33 #define OSSL_CMP_IR 34 #define OSSL_CMP_CR 35 #define OSSL_CMP_P10CR 36 #define OSSL_CMP_KUR 37 int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, 38 const OSSL_CRMF_MSG *crm, int *checkAfter); 39 int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx); 40 41 STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx); 42 int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out); 43 int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx, 44 const X509 *oldWithOld, X509 **newWithNew, 45 X509 **newWithOld, X509 **oldWithNew); 46 int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert, 47 const X509_CRL *last_crl, 48 X509_CRL **crl); 49 int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx, 50 OSSL_CRMF_CERTTEMPLATE **certTemplate, 51 OSSL_CMP_ATAVS **keySpec); 52=head1 DESCRIPTION 53 54This is the OpenSSL API for doing CMP (Certificate Management Protocol) 55client-server transactions, i.e., sequences of CMP requests and responses. 56 57All functions take a populated OSSL_CMP_CTX structure as their first argument. 58Usually the server name, port, and path ("CMP alias") need to be set, as well as 59credentials the client can use for authenticating itself to the server. 60In order to authenticate the server the client typically needs a trust store. 61The functions return their respective main results directly, while there are 62also accessor functions for retrieving various results and status information 63from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details. 64 65The default conveying protocol is HTTP. 66Timeout values may be given per request-response pair and per transaction. 67See L<OSSL_CMP_MSG_http_perform(3)> for details. 68 69OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI. 70 71OSSL_CMP_exec_CR_ses() requests an additional certificate. 72 73OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate. 74 75OSSL_CMP_exec_KUR_ses() obtains an updated certificate. 76 77These four types of certificate enrollment are implemented as macros 78calling OSSL_CMP_exec_certreq(). 79 80OSSL_CMP_exec_certreq() performs a certificate request of the type specified 81by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR. 82For IR, CR, and KUR, the certificate template to be used in the request 83may be supplied via the I<crm> parameter pointing to a CRMF structure. 84Typically I<crm> is NULL, then the template ingredients are taken from I<ctx> 85and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>, 86L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc. 87For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead. 88The enrollment session may be blocked (with polling and sleeping in between) 89until the server side can fully process and ultimately answer the request. 90 91OSSL_CMP_try_certreq() is an alternative to the above functions that is 92more flexible regarding what to do after receiving a checkAfter value. 93When called for the first time (with no certificate request in progress for 94the given I<ctx>) it starts a new transaction by sending a certificate request 95constructed as stated above using the I<req_type> and optional I<crm> parameter. 96Otherwise (when according to I<ctx> a 'waiting' status has been received before) 97it continues polling for the pending request 98unless the I<req_type> argument is < 0, which aborts the request. 99If the requested certificate is available the function returns 1 and the 100caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate. 101If no error occurred but no certificate is available yet then 102OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried 103and returns -1 after assigning the received checkAfter value 104via the output pointer argument (unless it is NULL). 105The checkAfter value indicates the number of seconds the caller should let pass 106before trying again. The caller is free to sleep for the given number of seconds 107or for some other time and/or to do anything else before retrying by calling 108OSSL_CMP_try_certreq() again with the same parameter values as before. 109OSSL_CMP_try_certreq() then polls 110to see whether meanwhile the requested certificate is available. 111If the caller decides to abort the pending certificate request and provides 112a negative value as the I<req_type> argument then OSSL_CMP_try_certreq() 113aborts the CMP transaction by sending an error message to the server. 114 115OSSL_CMP_exec_RR_ses() requests the revocation of the certificate 116specified in the I<ctx> using the issuer DN and serial number set by 117OSSL_CMP_CTX_set1_issuer(3) and OSSL_CMP_CTX_set1_serialNumber(3), respectively, 118otherwise the issuer DN and serial number 119of the certificate set by L<OSSL_CMP_CTX_set1_oldCert(3)>, 120otherwise the subject DN and public key 121of the certificate signing request set by L<OSSL_CMP_CTX_set1_p10CSR(3)>. 122RFC 4210 is vague in which PKIStatus should be returned by the server. 123We take "accepted" and "grantedWithMods" as clear success and handle 124"revocationWarning" and "revocationNotification" just as warnings because CAs 125typically return them as an indication that the certificate was already revoked. 126"rejection" is a clear error. The values "waiting" and "keyUpdateWarning" 127make no sense for revocation and thus are treated as an error as well. 128The revocation session may be blocked (with polling and sleeping in between) 129until the server can fully process and ultimately answer the request. 130 131OSSL_CMP_exec_GENM_ses() sends a genm general message containing the sequence of 132infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>) 133optionally provided in the I<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>. 134The message exchange may be blocked (with polling and sleeping in between) 135until the server can fully process and ultimately answer the request. 136On success the function records in I<ctx> status B<OSSL_CMP_PKISTATUS_accepted> 137and returns the list of B<ITAV>s received in a genp response message. 138This can be used, for instance, 139with infoType C<signKeyPairTypes> to obtain the set of signature 140algorithm identifiers that the CA will certify for subject public keys. 141See RFC 4210 section 5.3.19 and appendix E.5 for details. 142Functions implementing more specific genm/genp exchanges are described next. 143 144OSSL_CMP_get1_caCerts() uses a genm/genp message exchange with infoType caCerts 145to obtain a list of CA certificates from the CMP server referenced by I<ctx>. 146On success it assigns to I<*out> the list of certificates received, 147which must be freed by the caller. 148NULL output means that no CA certificates were provided by the server. 149 150OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message 151with infoType rootCaCert to obtain from the CMP server referenced by I<ctx> 152in a genp response message with infoType rootCaKeyUpdate any update of the 153given root CA certificate I<oldWithOld> and verifies it as far as possible. 154See RFC 4210 section 4.4 for details. 155On success it assigns to I<*newWithNew> the root certificate received. 156When the I<newWithOld> and I<oldWithNew> output parameters are not NULL, 157it assigns to them the corresponding transition certificates. 158NULL means that the respective certificate was not provided by the server. 159All certificates obtained this way must be freed by the caller. 160 161B<WARNING:> 162The I<newWithNew> certificate is meant to be a certificate that will be trusted. 163The trust placed in it cannot be stronger than the trust placed in 164the I<oldwithold> certificate if present, otherwise it cannot be stronger than 165the weakest trust in any of the certificates in the trust store of I<ctx>. 166 167OSSL_CMP_get1_crlUpdate() uses a genm request message with infoType crlStatusList 168to obtain CRL from the CMP server referenced by I<ctx> in a genp response message 169with infoType crls. It uses I<last_crl> and I<crlcert> to create 170a request with a status field as described for L<OSSL_CMP_CRLSTATUS_create(3)>. 171On success it assigns to I<*crl> the CRL received. 172NULL means that no CRL was provided by the server. 173The CRL obtained this way must be freed by the caller. 174 175OSSL_CMP_get1_certReqTemplate() uses a genm request message with 176infoType certReqTemplate to obtain a certificate request template from the 177CMP server referenced by I<ctx>. On success it assigns to I<*certTemplate> 178the certificate template received. NULL output means that no certificate 179request template was provided by the server. 180The optional I<keySpec> output parameter is assigned the key specification 181if received, otherwise it set to NULL. 182Both must be freed by the caller. 183 184=head1 NOTES 185 186CMP is defined in RFC 4210 (and CRMF in RFC 4211). 187 188The CMP client implementation is limited to one request per CMP message 189(and consequently to at most one response component per CMP message). 190 191When a client obtains from a CMP server CA certificates that it is going to 192trust, for instance via the caPubs field of a certificate response or using 193functions like OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate(), 194authentication of the CMP server is particularly critical. 195So special care must be taken setting up server authentication in I<ctx> 196using functions such as 197L<OSSL_CMP_CTX_set0_trusted(3)> (for certificate-based authentication) or 198L<OSSL_CMP_CTX_set1_secretValue(3)> (for MAC-based protection). 199If authentication is certificate-based, L<OSSL_CMP_CTX_get0_validatedSrvCert(3)> 200should be used to obtain the server validated certificate 201and perform an authorization check based on it. 202 203=head1 RETURN VALUES 204 205OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(), 206OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a 207pointer to the newly obtained X509 certificate on success, NULL on error. 208This pointer will be freed implicitly by OSSL_CMP_CTX_free() or 209CSSL_CMP_CTX_reinit(). 210 211OSSL_CMP_try_certreq() returns 1 if the requested certificate is available 212via L<OSSL_CMP_CTX_get0_newCert(3)> 213or on successfully aborting a pending certificate request, 0 on error, and -1 214in case a 'waiting' status has been received and checkAfter value is available. 215In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL 216and the output parameter I<checkAfter> has been used to 217assign the received value unless I<checkAfter> is NULL. 218 219OSSL_CMP_exec_RR_ses(), OSSL_CMP_get1_caCerts(), 220OSSL_CMP_get1_rootCaKeyUpdate(), OSSL_CMP_get1_crlUpdate() 221and OSSL_CMP_get1_certReqTemplate() 222return 1 on success, 0 on error. 223 224OSSL_CMP_exec_GENM_ses() returns NULL on error, 225otherwise a pointer to the sequence of B<ITAV> received, which may be empty. 226This pointer must be freed by the caller. 227 228=head1 EXAMPLES 229 230See OSSL_CMP_CTX for examples on how to prepare the context for these 231functions. 232 233=head1 SEE ALSO 234 235L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>, 236L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>, 237L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, 238L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>, 239L<OSSL_CMP_MSG_http_perform(3)>, L<OSSL_CMP_CRLSTATUS_create(3)> 240 241=head1 HISTORY 242 243The OpenSSL CMP support was added in OpenSSL 3.0. 244 245OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate() 246were added in OpenSSL 3.2. 247 248Support for delayed delivery of all types of response messages 249was added in OpenSSL 3.3. 250 251OSSL_CMP_get1_crlUpdate() and OSSL_CMP_get1_certReqTemplate() 252were added in OpenSSL 3.4. 253 254=head1 COPYRIGHT 255 256Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved. 257 258Licensed under the Apache License 2.0 (the "License"). You may not use 259this file except in compliance with the License. You can obtain a copy 260in the file LICENSE in the source distribution or at 261L<https://www.openssl.org/source/license.html>. 262 263=cut 264
