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