doc/man3/OSSL_CMP_exec_certreq.pod

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