doc/man3/OSSL_CMP_exec_IR_ses.pod

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