Latest update.

doc/man3/OSSL_CMP_exec_IR_ses.pod

@@ -0,0 +1,172 @@
+=pod
+
+=head1 NAME
+
+OSSL_CMP_exec_IR_ses,
+OSSL_CMP_exec_CR_ses,
+OSSL_CMP_exec_P10CR_ses,
+OSSL_CMP_exec_KUR_ses,
+OSSL_CMP_IR,
+OSSL_CMP_CR,
+OSSL_CMP_P10CR,
+OSSL_CMP_KUR,
+OSSL_CMP_try_certreq,
+OSSL_CMP_exec_RR_ses,
+OSSL_CMP_exec_GENM_ses,
+OSSL_CMP_certConf_cb
+- functions implementing CMP client transactions
+
+=head1 SYNOPSIS
+
+ #include <openssl/cmp.h>
+
+ X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
+ X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
+ X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
+ X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
+ #define OSSL_CMP_IR
+ #define OSSL_CMP_CR
+ #define OSSL_CMP_P10CR
+ #define OSSL_CMP_KUR
+ int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, int *checkAfter);
+ int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info,
+                          const char **text);
+ X509 *OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
+ STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
+
+=head1 DESCRIPTION
+
+This is the OpenSSL API for doing CMP (Certificate Management Protocol)
+client-server transactions, i.e., sequences of CMP requests and responses.
+
+All functions take a populated OSSL_CMP_CTX structure as their first argument.
+Usually the server name, port, and path ("CMP alias") need to be set, as well as
+credentials the client can use for authenticating itself to the client.
+In order to authenticate the server the client typically needs a trust store.
+For performing certificate enrollment requests the certificate template needs
+to be sufficiently filled in, giving at least the subject name and key.
+The functions return their respective main results directly, while there are
+also accessor functions for retrieving various results and status information
+from the B<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.
+
+The default conveying protocol is HTTP.
+Timeout values may be given per request-response pair and per transaction.
+See L<OSSL_CMP_MSG_http_perform(3)> for details.
+
+OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI.
+
+OSSL_CMP_exec_CR_ses() requests an additional certificate.
+
+OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate.
+
+OSSL_CMP_exec_KUR_ses() obtains an updated certificate.
+
+All these four types of certificate enrollment may be blocked by sleeping until the
+CAs or an intermedate PKI component can fully process and answer the request.
+
+OSSL_CMP_try_certreq() is an alternative to these four functions that is
+more uniform regarding the type of the certificate request to use and
+more flexible regarding what to do after receiving a checkAfter value.
+When called for the first time (with no certificate request in progress for
+the given B<ctx>) it starts a new transaction by sending a certificate request
+of the given type,
+which may be IR, CR, P10CR, or KUR as specified by the B<req_type> parameter.
+Otherwise (when according to B<ctx> a 'waiting' status has been received before)
+it continues polling for the pending request
+unless the B<req_type> argument is < 0, which aborts the request.
+If the requested certificate is available the function returns 1 and the
+caller can use B<OSSL_CMP_CTX_get0_newCert()> to retrieve the new certificate.
+If no error occurred but no certificate is available yet then
+OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried
+and returns -1 after assigning the received checkAfter value
+via the output pointer argument (unless it is NULL).
+The checkAfter value indicates the number of seconds the caller should let pass
+before trying again. The caller is free to sleep for the given number of seconds
+or for some other time and/or to do anything else before retrying by calling
+OSSL_CMP_try_certreq() again with the same parameter values as before.
+OSSL_CMP_try_certreq() then polls
+to see whether meanwhile the requested certificate is available.
+If the caller decides to abort the pending certificate request and provides
+a negative value as the B<req_type> argument then OSSL_CMP_try_certreq()
+aborts the CMP transaction by sending an error message to the server.
+
+OSSL_CMP_certConf_cb() is a basic certificate confirmation callback validating
+that the new certificate can be verified with the trusted/untrusted certificates
+in B<ctx>.
+As there is no requirement in RFC 4210 that the certificate can be
+validated by the client, this callback is not set by default in the context.
+
+OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
+specified in the B<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>.
+RFC 4210 is vague in which PKIStatus should be returned by the server.
+We take "accepted" and "grantedWithMods" as clear success and handle
+"revocationWarning" and "revocationNotification" just as warnings because CAs
+typically return them as an indication that the certificate was already revoked.
+"rejection" is a clear error. The values "waiting" and "keyUpdateWarning"
+make no sense for revocation and thus are treated as an error as well.
+
+OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of
+infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
+provided in the B<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
+It returns the list of B<ITAV>s received in the GenRep.
+This can be used, for instance, to poll for CRLs or CA Key Updates.
+See RFC 4210 section 5.3.19 and appendix E.5 for details.
+
+=head1 NOTES
+
+CMP is defined in RFC 4210 (and CRMF in RFC 4211).
+
+So far the CMP client implementation is limited to one request per CMP message
+(and consequently to at most one response component per CMP message).
+
+=head1 RETURN VALUES
+
+OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(),
+OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
+pointer to the newly obtained X509 certificate on success, B<NULL> on error.
+This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
+CSSL_CMP_CTX_reinit().
+
+OSSL_CMP_try_certreq() returns 1 if the requested certificate is available
+via B<OSSL_CMP_CTX_get0_newCert()>
+or on successfully aborting a pending certificate request, 0 on error, and -1
+in case a 'waiting' status has been received and checkAfter value is available.
+In the latter case B<OSSL_CMP_CTX_get0_newCert()> yields NULL
+and the output parameter B<checkAfter> has been used to
+assign the received value unless B<checkAfter> is NULL.
+
+OSSL_CMP_certConf_cb() returns B<fail_info> if it is not equal to B<0>,
+else B<0> on successful validation,
+or else a bit field with the B<OSSL_CMP_PKIFAILUREINFO_incorrectData> bit set.
+
+OSSL_CMP_exec_RR_ses() returns the
+pointer to the revoked certificate on success, B<NULL> on error.
+This pointer will be freed implicitly by OSSL_CMP_CTX_free().
+
+OSSL_CMP_exec_GENM_ses() returns a
+pointer to the received B<ITAV> sequence on success, B<NULL> on error.
+This pointer must be freed by the caller.
+
+=head1 EXAMPLES
+
+See OSSL_CMP_CTX for examples on how to prepare the context for these
+functions.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_MSG_http_perform(3)>
+
+=head1 HISTORY
+
+The OpenSSL CMP support was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut