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 17- functions implementing CMP client transactions 18 19=head1 SYNOPSIS 20 21 #include <openssl/cmp.h> 22 23 X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type, 24 const OSSL_CRMF_MSG *crm); 25 X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx); 26 X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx); 27 X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx); 28 X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx); 29 #define OSSL_CMP_IR 30 #define OSSL_CMP_CR 31 #define OSSL_CMP_P10CR 32 #define OSSL_CMP_KUR 33 int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, 34 const OSSL_CRMF_MSG *crm, int *checkAfter); 35 int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx); 36 STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx); 37 38=head1 DESCRIPTION 39 40This is the OpenSSL API for doing CMP (Certificate Management Protocol) 41client-server transactions, i.e., sequences of CMP requests and responses. 42 43All functions take a populated OSSL_CMP_CTX structure as their first argument. 44Usually the server name, port, and path ("CMP alias") need to be set, as well as 45credentials the client can use for authenticating itself to the server. 46In order to authenticate the server the client typically needs a trust store. 47The functions return their respective main results directly, while there are 48also accessor functions for retrieving various results and status information 49from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details. 50 51The default conveying protocol is HTTP. 52Timeout values may be given per request-response pair and per transaction. 53See L<OSSL_CMP_MSG_http_perform(3)> for details. 54 55OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI. 56 57OSSL_CMP_exec_CR_ses() requests an additional certificate. 58 59OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate. 60 61OSSL_CMP_exec_KUR_ses() obtains an updated certificate. 62 63These four types of certificate enrollment are implemented as macros 64calling OSSL_CMP_exec_certreq(). 65 66OSSL_CMP_exec_certreq() performs a certificate request of the type specified 67by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR. 68For IR, CR, and KUR, the certificate template to be used in the request 69may be supplied via the I<crm> parameter pointing to a CRMF structure. 70Typically I<crm> is NULL, then the template ingredients are taken from I<ctx> 71and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>, 72L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc. 73For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead. 74The enrollment session may be blocked by sleeping until the addressed 75CA (or an intermediate PKI component) can fully process and answer the request. 76 77OSSL_CMP_try_certreq() is an alternative to the above functions that is 78more flexible regarding what to do after receiving a checkAfter value. 79When called for the first time (with no certificate request in progress for 80the given I<ctx>) it starts a new transaction by sending a certificate request 81constructed as stated above using the I<req_type> and optional I<crm> parameter. 82Otherwise (when according to I<ctx> a 'waiting' status has been received before) 83it continues polling for the pending request 84unless the I<req_type> argument is < 0, which aborts the request. 85If the requested certificate is available the function returns 1 and the 86caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate. 87If no error occurred but no certificate is available yet then 88OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried 89and returns -1 after assigning the received checkAfter value 90via the output pointer argument (unless it is NULL). 91The checkAfter value indicates the number of seconds the caller should let pass 92before trying again. The caller is free to sleep for the given number of seconds 93or for some other time and/or to do anything else before retrying by calling 94OSSL_CMP_try_certreq() again with the same parameter values as before. 95OSSL_CMP_try_certreq() then polls 96to see whether meanwhile the requested certificate is available. 97If the caller decides to abort the pending certificate request and provides 98a negative value as the I<req_type> argument then OSSL_CMP_try_certreq() 99aborts the CMP transaction by sending an error message to the server. 100 101OSSL_CMP_exec_RR_ses() requests the revocation of the certificate 102specified in the I<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>. 103RFC 4210 is vague in which PKIStatus should be returned by the server. 104We take "accepted" and "grantedWithMods" as clear success and handle 105"revocationWarning" and "revocationNotification" just as warnings because CAs 106typically return them as an indication that the certificate was already revoked. 107"rejection" is a clear error. The values "waiting" and "keyUpdateWarning" 108make no sense for revocation and thus are treated as an error as well. 109 110OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of 111infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>) 112optionally provided in the I<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>. 113On success it records in I<ctx> the status B<OSSL_CMP_PKISTATUS_accepted> 114and returns the list of B<ITAV>s received in the GENP message. 115This can be used, for instance, to poll for CRLs or CA Key Updates. 116See RFC 4210 section 5.3.19 and appendix E.5 for details. 117 118=head1 NOTES 119 120CMP is defined in RFC 4210 (and CRMF in RFC 4211). 121 122The CMP client implementation is limited to one request per CMP message 123(and consequently to at most one response component per CMP message). 124 125When a client obtains from a CMP server CA certificates that it is going to 126trust, for instance via the caPubs field of a certificate response, 127authentication of the CMP server is particularly critical. 128So special care must be taken setting up server authentication in I<ctx> 129using functions such as 130L<OSSL_CMP_CTX_set0_trustedStore(3)> (for certificate-based authentication) or 131L<OSSL_CMP_CTX_set1_secretValue(3)> (for MAC-based protection). 132 133=head1 RETURN VALUES 134 135OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(), 136OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a 137pointer to the newly obtained X509 certificate on success, NULL on error. 138This pointer will be freed implicitly by OSSL_CMP_CTX_free() or 139CSSL_CMP_CTX_reinit(). 140 141OSSL_CMP_try_certreq() returns 1 if the requested certificate is available 142via L<OSSL_CMP_CTX_get0_newCert(3)> 143or on successfully aborting a pending certificate request, 0 on error, and -1 144in case a 'waiting' status has been received and checkAfter value is available. 145In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL 146and the output parameter I<checkAfter> has been used to 147assign the received value unless I<checkAfter> is NULL. 148 149OSSL_CMP_exec_RR_ses() returns 1 on success, 0 on error. 150 151OSSL_CMP_exec_GENM_ses() returns NULL on error, 152otherwise a pointer to the sequence of B<ITAV> received, which may be empty. 153This pointer must be freed by the caller. 154 155=head1 EXAMPLES 156 157See OSSL_CMP_CTX for examples on how to prepare the context for these 158functions. 159 160=head1 SEE ALSO 161 162L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>, 163L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>, 164L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, 165L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>, 166L<OSSL_CMP_MSG_http_perform(3)> 167 168=head1 HISTORY 169 170The OpenSSL CMP support was added in OpenSSL 3.0. 171 172=head1 COPYRIGHT 173 174Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. 175 176Licensed under the Apache License 2.0 (the "License"). You may not use 177this file except in compliance with the License. You can obtain a copy 178in the file LICENSE in the source distribution or at 179L<https://www.openssl.org/source/license.html>. 180 181=cut 182