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