diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_CMP_CTX_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_CMP_CTX_new.3 | 945 |
1 files changed, 945 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_CMP_CTX_new.3 b/secure/lib/libcrypto/man/man3/OSSL_CMP_CTX_new.3 new file mode 100644 index 000000000000..b1879efa0628 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/OSSL_CMP_CTX_new.3 @@ -0,0 +1,945 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_CTX_NEW 3ossl" +.TH OSSL_CMP_CTX_NEW 3ossl 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_CTX_new, +OSSL_CMP_CTX_free, +OSSL_CMP_CTX_reinit, +OSSL_CMP_CTX_get0_libctx, OSSL_CMP_CTX_get0_propq, +OSSL_CMP_CTX_set_option, +OSSL_CMP_CTX_get_option, +OSSL_CMP_CTX_set_log_cb, +OSSL_CMP_CTX_set_log_verbosity, +OSSL_CMP_CTX_print_errors, +OSSL_CMP_CTX_set1_serverPath, +OSSL_CMP_CTX_set1_server, +OSSL_CMP_CTX_set_serverPort, +OSSL_CMP_CTX_set1_proxy, +OSSL_CMP_CTX_set1_no_proxy, +OSSL_CMP_CTX_set_http_cb, +OSSL_CMP_CTX_set_http_cb_arg, +OSSL_CMP_CTX_get_http_cb_arg, +OSSL_CMP_transfer_cb_t, +OSSL_CMP_CTX_set_transfer_cb, +OSSL_CMP_CTX_set_transfer_cb_arg, +OSSL_CMP_CTX_get_transfer_cb_arg, +OSSL_CMP_CTX_set1_srvCert, +OSSL_CMP_CTX_set1_expected_sender, +OSSL_CMP_CTX_set0_trusted, +OSSL_CMP_CTX_set0_trustedStore, +OSSL_CMP_CTX_get0_trusted, +OSSL_CMP_CTX_get0_trustedStore, +OSSL_CMP_CTX_set1_untrusted, +OSSL_CMP_CTX_get0_untrusted, +OSSL_CMP_CTX_set1_cert, +OSSL_CMP_CTX_build_cert_chain, +OSSL_CMP_CTX_set1_pkey, +OSSL_CMP_CTX_set1_referenceValue, +OSSL_CMP_CTX_set1_secretValue, +OSSL_CMP_CTX_set1_recipient, +OSSL_CMP_CTX_push0_geninfo_ITAV, +OSSL_CMP_CTX_reset_geninfo_ITAVs, +OSSL_CMP_CTX_get0_geninfo_ITAVs, +OSSL_CMP_CTX_set1_extraCertsOut, +OSSL_CMP_CTX_set0_newPkey, +OSSL_CMP_CTX_get0_newPkey, +OSSL_CMP_CTX_set1_issuer, +OSSL_CMP_CTX_set1_serialNumber, +OSSL_CMP_CTX_set1_subjectName, +OSSL_CMP_CTX_push1_subjectAltName, +OSSL_CMP_CTX_set0_reqExtensions, +OSSL_CMP_CTX_reqExtensions_have_SAN, +OSSL_CMP_CTX_push0_policy, +OSSL_CMP_CTX_set1_oldCert, +OSSL_CMP_CTX_set1_p10CSR, +OSSL_CMP_CTX_push0_genm_ITAV, +OSSL_CMP_certConf_cb_t, +OSSL_CMP_certConf_cb, +OSSL_CMP_CTX_set_certConf_cb, +OSSL_CMP_CTX_set_certConf_cb_arg, +OSSL_CMP_CTX_get_certConf_cb_arg, +OSSL_CMP_CTX_get_status, +OSSL_CMP_CTX_get0_statusString, +OSSL_CMP_CTX_get_failInfoCode, +OSSL_CMP_CTX_get0_validatedSrvCert, +OSSL_CMP_CTX_get0_newCert, +OSSL_CMP_CTX_get1_newChain, +OSSL_CMP_CTX_get1_caPubs, +OSSL_CMP_CTX_get1_extraCertsIn, +OSSL_CMP_CTX_set1_transactionID, +OSSL_CMP_CTX_set1_senderNonce +\&\- functions for managing the CMP client context data structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/cmp.h> +\& +\& OSSL_CMP_CTX *OSSL_CMP_CTX_new(OSSL_LIB_CTX *libctx, const char *propq); +\& void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx); +\& OSSL_LIB_CTX *OSSL_CMP_CTX_get0_libctx(const OSSL_CMP_CTX *ctx); +\& const char *OSSL_CMP_CTX_get0_propq(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val); +\& int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt); +\& +\& /* logging and error reporting: */ +\& int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb); +\& #define OSSL_CMP_CTX_set_log_verbosity(ctx, level) +\& void OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx); +\& +\& /* message transfer: */ +\& int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path); +\& int OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address); +\& int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port); +\& int OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name); +\& int OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names); +\& int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb); +\& int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx); +\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx, +\& const OSSL_CMP_MSG *req); +\& int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx, +\& OSSL_CMP_transfer_cb_t cb); +\& int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx); +\& +\& /* server authentication: */ +\& int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx, +\& const X509_NAME *name); +\& #define OSSL_CMP_CTX_set0_trusted OSSL_CMP_CTX_set0_trustedStore +\& int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store); +\& #define OSSL_CMP_CTX_get0_trusted OSSL_CMP_CTX_get0_trustedStore +\& X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set1_untrusted(OSSL_CMP_CTX *ctx, STACK_OF(X509) *certs); +\& STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted(const OSSL_CMP_CTX *ctx); +\& +\& /* client authentication: */ +\& int OSSL_CMP_CTX_set1_cert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_build_cert_chain(OSSL_CMP_CTX *ctx, X509_STORE *own_trusted, +\& STACK_OF(X509) *candidates); +\& int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey); +\& int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx, +\& const unsigned char *ref, int len); +\& int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, +\& const unsigned char *sec, int len); +\& +\& /* CMP message header and extra certificates: */ +\& int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); +\& int OSSL_CMP_CTX_reset_geninfo_ITAVs(OSSL_CMP_CTX *ctx); +\& STACK_OF(OSSL_CMP_ITAV) +\& *OSSL_CMP_CTX_get0_geninfo_ITAVs(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx, +\& STACK_OF(X509) *extraCertsOut); +\& +\& /* certificate template: */ +\& int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey); +\& EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv); +\& int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_set1_serialNumber(OSSL_CMP_CTX *ctx, const ASN1_INTEGER *sn); +\& int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx, +\& const GENERAL_NAME *name); +\& int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts); +\& int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo); +\& int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr); +\& +\& /* misc body contents: */ +\& int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); +\& +\& /* certificate confirmation: */ +\& typedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert, +\& int fail_info, const char **txt); +\& int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info, +\& const char **text); +\& int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb); +\& int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx); +\& +\& /* result fetching: */ +\& int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx); +\& OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx); +\& +\& X509 *OSSL_CMP_CTX_get0_validatedSrvCert(const OSSL_CMP_CTX *ctx); +\& X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_newChain(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx); +\& +\& /* for testing and debugging purposes: */ +\& int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx, +\& const ASN1_OCTET_STRING *id); +\& int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx, +\& const ASN1_OCTET_STRING *nonce); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is the context API for using CMP (Certificate Management Protocol) with +OpenSSL. +.PP +\&\fBOSSL_CMP_CTX_new()\fR allocates an \fBOSSL_CMP_CTX\fR structure associated with +the library context \fIlibctx\fR and property query string \fIpropq\fR, +both of which may be NULL to select the defaults. +It initializes the remaining fields to their default values \- for instance, +the logging verbosity is set to OSSL_CMP_LOG_INFO, +the message timeout is set to 120 seconds, +and the proof\-of\-possession method is set to OSSL_CRMF_POPO_SIGNATURE. +.PP +\&\fBOSSL_CMP_CTX_free()\fR deallocates an OSSL_CMP_CTX structure. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_CMP_CTX_reinit()\fR prepares the given \fIctx\fR for a further transaction by +clearing the internal CMP transaction (aka session) status, PKIStatusInfo, +and any previous results (newCert, newChain, caPubs, and extraCertsIn) +from the last executed transaction. +It also clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_genm_ITAV()\fR. +All other field values (i.e., CMP options) are retained for potential reuse. +.PP +\&\fBOSSL_CMP_CTX_get0_libctx()\fR returns the \fIlibctx\fR argument that was used +when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. +.PP +\&\fBOSSL_CMP_CTX_get0_propq()\fR returns the \fIpropq\fR argument that was used +when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. +.PP +\&\fBOSSL_CMP_CTX_set_option()\fR sets the given value for the given option +(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure. +.PP +The following options can be set: +.IP \fBOSSL_CMP_OPT_LOG_VERBOSITY\fR 4 +.IX Item "OSSL_CMP_OPT_LOG_VERBOSITY" +The level of severity needed for actually outputting log messages +due to errors, warnings, general info, debugging, etc. +Default is OSSL_CMP_LOG_INFO. See also \fBOSSL_CMP_log_open\fR\|(3). +.IP \fBOSSL_CMP_OPT_KEEP_ALIVE\fR 4 +.IX Item "OSSL_CMP_OPT_KEEP_ALIVE" +If the given value is 0 then HTTP connections are not kept open +after receiving a response, which is the default behavior for HTTP 1.0. +If the value is 1 or 2 then persistent connections are requested. +If the value is 2 then persistent connections are required, +i.e., in case the server does not grant them an error occurs. +The default value is 1: prefer to keep the connection open. +.IP \fBOSSL_CMP_OPT_MSG_TIMEOUT\fR 4 +.IX Item "OSSL_CMP_OPT_MSG_TIMEOUT" +Number of seconds a CMP request\-response message round trip +is allowed to take before a timeout error is returned. +A value <= 0 means no limitation (waiting indefinitely). +Default is to use the \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR setting. +.IP \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR 4 +.IX Item "OSSL_CMP_OPT_TOTAL_TIMEOUT" +Maximum total number of seconds a transaction may take, +including polling etc. +A value <= 0 means no limitation (waiting indefinitely). +Default is 0. +.IP \fBOSSL_CMP_OPT_USE_TLS\fR 4 +.IX Item "OSSL_CMP_OPT_USE_TLS" +Use this option to indicate to the HTTP implementation +whether TLS is going to be used for the connection (resulting in HTTPS). +The value 1 indicates that TLS is used for client\-side HTTP connections, +which needs to be implemented via a callback function set by +\&\fBOSSL_CMP_CTX_set_http_cb()\fR. +The value 0 indicates that TLS is not used. +Default is \-1 for backward compatibility: TLS is used by the client side +if and only if \fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets a non\-NULL \fIarg\fR. +.IP \fBOSSL_CMP_OPT_VALIDITY_DAYS\fR 4 +.IX Item "OSSL_CMP_OPT_VALIDITY_DAYS" +Number of days new certificates are asked to be valid for. +.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR 4 +.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT" +Do not take default Subject Alternative Names +from the reference certificate. +.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL\fR 4 +.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL" +Demand that the given Subject Alternative Names are flagged as critical. +.IP \fBOSSL_CMP_OPT_POLICIES_CRITICAL\fR 4 +.IX Item "OSSL_CMP_OPT_POLICIES_CRITICAL" +Demand that the given policies are flagged as critical. +.IP \fBOSSL_CMP_OPT_POPO_METHOD\fR 4 +.IX Item "OSSL_CMP_OPT_POPO_METHOD" +Select the proof of possession method to use. Possible values are: +.Sp +.Vb 8 +\& OSSL_CRMF_POPO_NONE \- ProofOfPossession field omitted, +\& which implies central key generation +\& OSSL_CRMF_POPO_RAVERIFIED \- assert that the RA has already +\& verified the PoPo +\& OSSL_CRMF_POPO_SIGNATURE \- sign a value with private key, +\& which is the default. +\& OSSL_CRMF_POPO_KEYENC \- decrypt the encrypted certificate +\& ("indirect method") +.Ve +.Sp +Note that a signature\-based POPO can only be produced if a private key +is provided as the newPkey or client\*(Aqs pkey component of the CMP context. +.IP \fBOSSL_CMP_OPT_DIGEST_ALGNID\fR 4 +.IX Item "OSSL_CMP_OPT_DIGEST_ALGNID" +The NID of the digest algorithm to be used in RFC 9810\*(Aqs MSG_SIG_ALG +for signature\-based message protection and Proof\-of\-Possession (POPO). +Default is SHA256. +.IP "\fBOSSL_CMP_OPT_OWF_ALGNID\fR The NID of the digest algorithm to be used as one\-way function (OWF) for MAC\-based message protection with password\-based MAC (PBM). See RFC 9810 section 5.1.3.1 for details. Default is SHA256." 4 +.IX Item "OSSL_CMP_OPT_OWF_ALGNID The NID of the digest algorithm to be used as one-way function (OWF) for MAC-based message protection with password-based MAC (PBM). See RFC 9810 section 5.1.3.1 for details. Default is SHA256." +.PD 0 +.IP "\fBOSSL_CMP_OPT_MAC_ALGNID\fR The NID of the MAC algorithm to be used for message protection with PBM. Default is HMAC\-SHA1, for backward compatibility with RFC 4210." 4 +.IX Item "OSSL_CMP_OPT_MAC_ALGNID The NID of the MAC algorithm to be used for message protection with PBM. Default is HMAC-SHA1, for backward compatibility with RFC 4210." +.IP \fBOSSL_CMP_OPT_REVOCATION_REASON\fR 4 +.IX Item "OSSL_CMP_OPT_REVOCATION_REASON" +.PD +The reason code to be included in a Revocation Request (RR); +values: 0..10 (RFC 5210, 5.3.1) or \-1 for none, which is the default. +.IP \fBOSSL_CMP_OPT_IMPLICIT_CONFIRM\fR 4 +.IX Item "OSSL_CMP_OPT_IMPLICIT_CONFIRM" +Request server to enable implicit confirm mode, where the client +does not need to send confirmation upon receiving the +certificate. If the server does not enable implicit confirmation +in the return message, then confirmation is sent anyway. +.IP \fBOSSL_CMP_OPT_DISABLE_CONFIRM\fR 4 +.IX Item "OSSL_CMP_OPT_DISABLE_CONFIRM" +Do not confirm enrolled certificates, to cope with broken servers +not supporting implicit confirmation correctly. +\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant +exclusively to allow interoperability with server implementations violating +RFC 9810. +.IP \fBOSSL_CMP_OPT_UNPROTECTED_SEND\fR 4 +.IX Item "OSSL_CMP_OPT_UNPROTECTED_SEND" +Send request or response messages without CMP\-level protection. +.IP \fBOSSL_CMP_OPT_UNPROTECTED_ERRORS\fR 4 +.IX Item "OSSL_CMP_OPT_UNPROTECTED_ERRORS" +Accept unprotected error responses which are either explicitly +unprotected or where protection verification failed. Applies to regular +error messages as well as certificate responses (IP/CP/KUP) and +revocation responses (RP) with rejection. +\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant +exclusively to allow interoperability with server implementations violating +RFC 9810. +.IP \fBOSSL_CMP_OPT_IGNORE_KEYUSAGE\fR 4 +.IX Item "OSSL_CMP_OPT_IGNORE_KEYUSAGE" +Ignore key usage restrictions in the signer\*(Aqs certificate when +validating signature\-based protection in received CMP messages. +Else, \*(AqdigitalSignature\*(Aq must be allowed by CMP signer certificates. +.IP \fBOSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR\fR 4 +.IX Item "OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR" +Allow retrieving a trust anchor from extraCerts and using that +to validate the certificate chain of an IP message. +This is a quirk option added to support 3GPP TS 33.310. +.Sp +Note that using this option is dangerous as the certificate obtained +this way has not been authenticated (at least not at CMP level). +Taking it over as a trust anchor implements trust\-on\-first\-use (TOFU). +.IP \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR 4 +.IX Item "OSSL_CMP_OPT_NO_CACHE_EXTRACERTS" +Do not cache certificates received in the extraCerts CMP message field. +Otherwise they are stored to potentially help validate further messages. +.Sp +In any case, after successfully validating an incoming message, its protection +certificate (if any) is cached for reuse with validation of subsequent messages. +This is done not only for efficiency but also +to eliminate the need for the sender to include its certificate and related chain +in the extraCerts field of subsequent messages of the same transaction. +.PP +\&\fBOSSL_CMP_CTX_get_option()\fR reads the current value of the given option +(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) from the given OSSL_CMP_CTX structure. +.PP +\&\fBOSSL_CMP_CTX_set_log_cb()\fR sets in \fIctx\fR the callback function \fIcb\fR +for handling error queue entries and logging messages. +When \fIcb\fR is NULL errors are printed to STDERR (if available, else ignored) +any log messages are ignored. +Alternatively, \fBOSSL_CMP_log_open\fR\|(3) may be used to direct logging to STDOUT. +.PP +\&\fBOSSL_CMP_CTX_set_log_verbosity()\fR is a macro setting the +OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level. +.PP +\&\fBOSSL_CMP_CTX_print_errors()\fR outputs any entries in the OpenSSL error queue. It +is similar to \fBERR_print_errors_cb\fR\|(3) but uses the CMP log callback function +if set in the \fIctx\fR for uniformity with CMP logging if given. Otherwise it uses +\&\fBERR_print_errors\fR\|(3) to print to STDERR (unless OPENSSL_NO_STDIO is defined). +.PP +\&\fBOSSL_CMP_CTX_set1_serverPath()\fR sets the HTTP path of the CMP server on the host, +also known as "CMP alias". +The default is \f(CW\*(C`/\*(C'\fR. +.PP +\&\fBOSSL_CMP_CTX_set1_server()\fR sets the given server \fIaddress\fR +(which may be a hostname or IP address or NULL) in the given \fIctx\fR. +If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non\-NULL argument, +this server address information is used for diagnostic output only. +.PP +\&\fBOSSL_CMP_CTX_set_serverPort()\fR sets the port of the CMP server to connect to. +If not used or the \fIport\fR argument is 0 +the default port applies, which is 80 for HTTP and 443 for HTTPS. +If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non\-NULL argument, +this server port information is used for diagnostic output only. +.PP +\&\fBOSSL_CMP_CTX_set1_proxy()\fR sets the HTTP proxy to be used for connecting to +the given CMP server unless overruled by any "no_proxy" settings (see below). +If TLS is not used this defaults to the value of +the environment variable \f(CW\*(C`http_proxy\*(C'\fR if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR. +Otherwise defaults to the value of \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR. +An empty proxy string specifies not to use a proxy. +Otherwise the format is +\&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR, +where any given userinfo, path, query, and fragment is ignored. +If the host string is an IPv6 address, it must be enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +The default port number is 80, or 443 in case \f(CW\*(C`https:\*(C'\fR is given. +.PP +\&\fBOSSL_CMP_CTX_set1_no_proxy()\fR sets the list of server hostnames not to use +an HTTP proxy for. The names may be separated by commas and/or whitespace. +Defaults to the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR. +.PP +\&\fBOSSL_CMP_CTX_set_http_cb()\fR sets the optional BIO connect/disconnect callback +function, which has the prototype +.PP +.Vb 1 +\& typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *arg, int connect, int detail); +.Ve +.PP +The callback may modify the \fIbio\fR provided by \fBOSSL_CMP_MSG_http_perform\fR\|(3) +as described for the \fIbio_update_fn\fR parameter of \fBOSSL_HTTP_open\fR\|(3). +The callback may make use of a custom defined argument \fIarg\fR, +as described for the \fIarg\fR parameter of \fBOSSL_HTTP_open\fR\|(3). +The argument is stored in the OSSL_CMP_CTX using \fBOSSL_CMP_CTX_set_http_cb_arg()\fR. +See also the \fBOSSL_CMP_OPT_USE_TLS\fR option described above. +.PP +\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets the argument, respectively a pointer to +a structure containing arguments such as an \fBSSL_CTX\fR structure, +optionally to be used by the http connect/disconnect callback function. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +If a non\-NULL argument is set, it is an error to use \fBOSSL_CMP_CTX_set1_proxy()\fR +or \fBOSSL_CMP_CTX_set1_no_proxy()\fR for setting non\-NULL strings. +.PP +\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR gets the argument, respectively the pointer to a +structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_set_transfer_cb()\fR sets the message transfer callback function, +which has the type +.PP +.Vb 2 +\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx, +\& const OSSL_CMP_MSG *req); +.Ve +.PP +Default is NULL, which implies the use of \fBOSSL_CMP_MSG_http_perform\fR\|(3). +The callback should send the CMP request message it obtains via the \fIreq\fR +parameter and on success return the response, else it must return NULL. +The transfer callback may make use of a custom defined argument stored in +the ctx by means of \fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR, which may be retrieved +again through \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR. +.PP +\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR sets an argument, respectively a pointer to a +structure containing arguments, optionally to be used by the transfer callback. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR gets the argument, respectively the pointer +to a structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_srvCert()\fR sets the expected server cert in \fIctx\fR and trusts +it directly (even if it is expired) when verifying signed response messages. +This pins the accepted CMP server +and results in ignoring whatever may be set using \fBOSSL_CMP_CTX_set0_trusted()\fR. +Any previously set value is freed. +The \fIcert\fR argument may be NULL to clear the entry. +If set, the subject of the certificate is also used +as default value for the recipient of CMP requests +and as default value for the expected sender of CMP responses. +.PP +\&\fBOSSL_CMP_CTX_set1_expected_sender()\fR sets the Distinguished Name (DN) +expected in the sender field of incoming CMP messages. +Defaults to the subject of the pinned server certificate, if any. +This can be used to make sure that only a particular entity is accepted as +CMP message signer, and attackers are not able to use arbitrary certificates +of a trusted PKI hierarchy to fraudulently pose as CMP server. +Note that this gives slightly more freedom than \fBOSSL_CMP_CTX_set1_srvCert()\fR, +which pins the server to the holder of a particular certificate, while the +expected sender name will continue to match after updates of the server cert. +.PP +\&\fBOSSL_CMP_CTX_set0_trusted()\fR is an alias of the original +\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR. +It sets in the CMP context \fIctx\fR the certificate store of type X509_STORE +containing trusted certificates, typically of root CAs. +This is ignored when a certificate is pinned using \fBOSSL_CMP_CTX_set1_srvCert()\fR. +The store may also hold CRLs and a certificate verification callback function +used for signature\-based peer authentication. +Any store entry already set before is freed. +When given a NULL parameter the entry is cleared. +.PP +\&\fBOSSL_CMP_CTX_get0_trusted()\fR is an alias of the original +\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR. +It extracts from the CMP context \fIctx\fR the pointer to the currently set +certificate store containing trust anchors etc., or an empty store if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_untrusted()\fR sets up a list of non\-trusted certificates +of intermediate CAs that may be useful for path construction for the own CMP +signer certificate, for the own TLS certificate (if any), when verifying peer +CMP protection certificates, and when verifying newly enrolled certificates. +The reference counts of those certificates handled successfully are increased. +This list of untrusted certificates in \fIctx\fR will get augmented by extraCerts +in received CMP messages unless \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR is set. +.PP +\&\fBOSSL_CMP_CTX_get0_untrusted()\fR returns a pointer to the +list of untrusted certs in \fIctx\fR, which may be empty if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_cert()\fR sets the CMP \fIsigner certificate\fR, +also called \fIprotection certificate\fR, +related to the private key used for signature\-based CMP message protection. +Therefore the public key of this \fIcert\fR must correspond to +the private key set before or thereafter via \fBOSSL_CMP_CTX_set1_pkey()\fR. +When using signature\-based protection of CMP request messages +this CMP signer certificate will be included first in the extraCerts field. +It serves as fallback reference certificate, see \fBOSSL_CMP_CTX_set1_oldCert()\fR. +The subject of this \fIcert\fR will be used as the sender field of outgoing +messages, while the subject of any cert set via \fBOSSL_CMP_CTX_set1_oldCert()\fR, +the subject of any PKCS#10 CSR set via \fBOSSL_CMP_CTX_set1_p10CSR()\fR, +and any value set via \fBOSSL_CMP_CTX_set1_subjectName()\fR are used as fallback. +.PP +The \fIcert\fR argument may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_build_cert_chain()\fR builds a certificate chain for the CMP signer +certificate previously set in the \fIctx\fR. It adds the optional \fIcandidates\fR, +a list of intermediate CA certs that may already constitute the targeted chain, +to the untrusted certs that may already exist in the \fIctx\fR. +Then the function uses this augmented set of certs for chain construction. +If \fIown_trusted\fR is NULL it builds the chain as far down as possible and +ignores any verification errors. Else the CMP signer certificate must be +verifiable where the chain reaches a trust anchor contained in \fIown_trusted\fR. +On success the function stores the resulting chain in \fIctx\fR +for inclusion in the extraCerts field of signature\-protected messages. +Calling this function is optional; by default a chain construction +is performed on demand that is equivalent to calling this function +with the \fIcandidates\fR and \fIown_trusted\fR arguments being NULL. +.PP +\&\fBOSSL_CMP_CTX_set1_pkey()\fR sets the client\*(Aqs private key corresponding to the +CMP signer certificate set via \fBOSSL_CMP_CTX_set1_cert()\fR. +This key is used create signature\-based protection (protectionAlg = MSG_SIG_ALG) +of outgoing messages +unless a symmetric secret has been set via \fBOSSL_CMP_CTX_set1_secretValue()\fR. +The \fIpkey\fR argument may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_set1_secretValue()\fR sets in \fIctx\fR the byte string \fIsec\fR of length +\&\fIlen\fR to use as pre\-shared secret, or clears it if the \fIsec\fR argument is NULL. +If present, this secret is used to create MAC\-based authentication and integrity +protection (rather than applying signature\-based protection) +of outgoing messages and to verify authenticity and integrity of incoming +messages that have MAC\-based protection (protectionAlg = \f(CW\*(C`MSG_MAC_ALG\*(C'\fR). +.PP +\&\fBOSSL_CMP_CTX_set1_referenceValue()\fR sets the given referenceValue \fIref\fR with +length \fIlen\fR in the given \fIctx\fR or clears it if the \fIref\fR argument is NULL. +According to RFC 9810 section 5.1.1, if no value for the sender field in +CMP message headers can be determined (i.e., no CMP signer certificate +and no subject DN is set via \fBOSSL_CMP_CTX_set1_subjectName()\fR +then the sender field will contain the NULL\-DN +and the senderKID field of the CMP message header must be set. +When signature\-based protection is used the senderKID will be set to +the subjectKeyIdentifier of the CMP signer certificate as far as present. +If not present or when MAC\-based protection is used +the \fIref\fR value is taken as the fallback value for the senderKID. +.PP +\&\fBOSSL_CMP_CTX_set1_recipient()\fR sets the recipient name that will be used in the +PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server. +.PP +The recipient field in the header of a CMP message is mandatory. +If not given explicitly the recipient is determined in the following order: +the subject of the CMP server certificate set using \fBOSSL_CMP_CTX_set1_srvCert()\fR, +the value set using \fBOSSL_CMP_CTX_set1_issuer()\fR, +the issuer of the certificate set using \fBOSSL_CMP_CTX_set1_oldCert()\fR, +the issuer of the CMP signer certificate, +as far as any of those is present, else the NULL\-DN as last resort. +.PP +\&\fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR to be +added to the generalInfo field of the CMP PKIMessage header of a request +message sent with this context. +.PP +\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR +clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR. +.PP +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR returns the list of ITAVs set in \fIctx\fR +for inclusion in the generalInfo field of the CMP PKIMessage header of requests +or NULL if not set. +.PP +\&\fBOSSL_CMP_CTX_set1_extraCertsOut()\fR sets the stack of extraCerts that will be +sent to remote. +.PP +\&\fBOSSL_CMP_CTX_set0_newPkey()\fR can be used to explicitly set the given EVP_PKEY +structure as the private or public key to be certified in the CMP context. +The \fIpriv\fR parameter must be 0 if and only if the given key is a public key. +.PP +\&\fBOSSL_CMP_CTX_get0_newPkey()\fR gives the key to use for certificate enrollment +dependent on fields of the CMP context structure: +the newPkey (which may be a private or public key) if present, +else the public key in the p10CSR if present, else the client\*(Aqs private key. +If the \fIpriv\fR parameter is not 0 and the selected key does not have a +private component then NULL is returned. +.PP +\&\fBOSSL_CMP_CTX_set1_issuer()\fR sets the name of the intended issuer that +will be set in the CertTemplate, i.e., the X509 name of the CA server. +.PP +\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR sets the serial number optionally used to +select the certificate to be revoked in Revocation Requests (RR). +.PP +\&\fBOSSL_CMP_CTX_set1_subjectName()\fR sets the subject DN that will be used in +the CertTemplate structure when requesting a new cert. For Key Update Requests +(KUR), it defaults to the subject DN of the reference certificate, +see \fBOSSL_CMP_CTX_set1_oldCert()\fR. This default is used for Initialization +Requests (IR) and Certification Requests (CR) only if no SANs are set. +The \fIsubjectName\fR is also used as fallback for the sender field +of outgoing CMP messages if no reference certificate is available. +.PP +\&\fBOSSL_CMP_CTX_push1_subjectAltName()\fR adds the given X509 name to the list of +alternate names on the certificate template request. This cannot be used if +any Subject Alternative Name extension is set via +\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR. +By default, unless \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR has been set, +the Subject Alternative Names are copied from the reference certificate, +see \fBOSSL_CMP_CTX_set1_oldCert()\fR. +If set and the subject DN is not set with \fBOSSL_CMP_CTX_set1_subjectName()\fR then +the certificate template of an IR and CR will not be filled with the default +subject DN from the reference certificate. +If a subject DN is desired it needs to be set explicitly with +\&\fBOSSL_CMP_CTX_set1_subjectName()\fR. +.PP +\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR sets the X.509v3 extensions to be used in +IR/CR/KUR. +.PP +\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR returns 1 if the context contains +a Subject Alternative Name extension, else 0 or \-1 on error. +.PP +\&\fBOSSL_CMP_CTX_push0_policy()\fR adds the certificate policy info object +to the X509_EXTENSIONS of the requested certificate template. +.PP +\&\fBOSSL_CMP_CTX_set1_oldCert()\fR sets the old certificate to be updated in +Key Update Requests (KUR) or to be revoked in Revocation Requests (RR). +For RR, this is ignored if an issuer name and a serial number are provided using +\&\fBOSSL_CMP_CTX_set1_issuer()\fR and \fBOSSL_CMP_CTX_set1_serialNumber()\fR, respectively. +For IR/CR/KUR this sets the \fIreference certificate\fR, +which otherwise defaults to the CMP signer certificate. +The \fIreference certificate\fR determined this way, if any, is used for providing +default public key, subject DN, Subject Alternative Names, and issuer DN entries +in the requested certificate template of IR/CR/KUR messages. +.PP +The subject of the reference certificate is used as the sender field value +in CMP message headers. +Its issuer is used as default recipient in CMP message headers. +.PP +\&\fBOSSL_CMP_CTX_set1_p10CSR()\fR sets the PKCS#10 CSR to use in P10CR messages. +If such a CSR is provided, its subject and public key fields are also +used as fallback values for the certificate template of IR/CR/KUR/RR messages, +and any extensions included are added to the template of IR/CR/KUR messages. +.PP +\&\fBOSSL_CMP_CTX_push0_genm_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR which +will be the body of a General Message sent with this context. +.PP +\&\fBOSSL_CMP_certConf_cb()\fR is the default certificate confirmation callback function. +If the callback argument is not NULL it must point to a trust store. +In this case the function checks that the newly enrolled certificate can be +verified using this trust store and untrusted certificates from the \fIctx\fR, +which have been augmented by the list of extraCerts received. +During this verification, any certificate status checking is disabled. +If the callback argument is NULL the function tries building an approximate +chain as far as possible using the same untrusted certificates from the \fIctx\fR, +and if this fails it takes the received extraCerts as fallback. +The resulting cert chain can be retrieved using \fBOSSL_CMP_CTX_get1_newChain()\fR. +This chain excludes the leaf certificate, i.e., the newly enrolled certificate. +Also the trust anchor (the root certificate) is not included. +.PP +\&\fBOSSL_CMP_CTX_set_certConf_cb()\fR sets the callback used for evaluating the newly +enrolled certificate before the library sends, depending on its result, +a positive or negative certConf message to the server. The callback has type +.PP +.Vb 2 +\& typedef int (*OSSL_CMP_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert, +\& int fail_info, const char **txt); +.Ve +.PP +and should inspect the certificate it obtains via the \fIcert\fR parameter and may +overrule the pre\-decision given in the \fIfail_info\fR and \fI*txt\fR parameters. +If it accepts the certificate it must return 0, indicating success. Else it must +return a bit field reflecting PKIFailureInfo with at least one failure bit and +may set the \fI*txt\fR output parameter to point to a string constant with more +detail. The transfer callback may make use of a custom defined argument stored +in the \fIctx\fR by means of \fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, which may be +retrieved again through \fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR. +Typically, the callback will check at least that the certificate can be verified +using a set of trusted certificates. +It also could compare the subject DN and other fields of the newly +enrolled certificate with the certificate template of the request. +.PP +\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR sets an argument, respectively a pointer to a +structure containing arguments, optionally to be used by the certConf callback. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR gets the argument, respectively the pointer +to a structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_get_status()\fR returns for client contexts the PKIstatus from +the last received CertRepMessage or Revocation Response or error message: +=item \fBOSSL_CMP_PKISTATUS_accepted\fR on successful receipt of a GENP message: +.IP \fBOSSL_CMP_PKISTATUS_request\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_request" +if an IR/CR/KUR/RR/GENM request message could not be produced, +.IP \fBOSSL_CMP_PKISTATUS_trans\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_trans" +on a transmission error or transaction error for this type of request, and +.IP \fBOSSL_CMP_PKISTATUS_unspecified\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_unspecified" +if no such request was attempted or \fBOSSL_CMP_CTX_reinit()\fR has been called. +.PP +For server contexts it returns +\&\fBOSSL_CMP_PKISTATUS_trans\fR if a transaction is open, +otherwise \fBOSSL_CMP_PKISTATUS_unspecified\fR. +.PP +\&\fBOSSL_CMP_CTX_get0_statusString()\fR returns the statusString from the last received +CertRepMessage or Revocation Response or error message, or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR returns the error code from the failInfo field +of the last received CertRepMessage or Revocation Response or error message, +or \-1 if no such response was received or \fBOSSL_CMP_CTX_reinit()\fR has been called. +This is a bit field and the flags for it are specified in the header file +\&\fI<openssl/cmp.h>\fR. +The flags start with OSSL_CMP_CTX_FAILINFO, for example: +OSSL_CMP_CTX_FAILINFO_badAlg. Returns \-1 if the failInfoCode field is unset. +.PP +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR returns +the successfully validated certificate, if any, that the CMP server used +in the current transaction for signature\-based response message protection, +or NULL if the server used MAC\-based protection. +The value is relevant only at the end of a successful transaction. +It may be used to check the authorization of the server based on its cert. +.PP +\&\fBOSSL_CMP_CTX_get0_newCert()\fR returns the pointer to the newly obtained +certificate in case it is available, else NULL. +.PP +\&\fBOSSL_CMP_CTX_get1_newChain()\fR returns a pointer to a duplicate of the stack of +X.509 certificates computed by \fBOSSL_CMP_certConf_cb()\fR (if this function has +been called) on the last received certificate response message IP/CP/KUP. +.PP +\&\fBOSSL_CMP_CTX_get1_caPubs()\fR returns a pointer to a duplicate of the list of +X.509 certificates in the caPubs field of the last received certificate +response message (of type IP, CP, or KUP), +or an empty stack if no caPubs have been received in the current transaction. +.PP +\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR returns a pointer to a duplicate of the list +of X.509 certificates contained in the extraCerts field of the last received +response message (except for pollRep and PKIConf), or +an empty stack if no extraCerts have been received in the current transaction. +.PP +\&\fBOSSL_CMP_CTX_set1_transactionID()\fR sets the given transaction ID in the given +OSSL_CMP_CTX structure. +.PP +\&\fBOSSL_CMP_CTX_set1_senderNonce()\fR stores the last sent sender \fInonce\fR in +the \fIctx\fR. This will be used to validate the recipNonce in incoming messages. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810 (and CRMF in RFC 4211). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_CTX_free()\fR and \fBOSSL_CMP_CTX_print_errors()\fR do not return anything. +.PP +\&\fBOSSL_CMP_CTX_new()\fR, +\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, +\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get0_trusted()\fR, +\&\fBOSSL_CMP_CTX_get0_untrusted()\fR, +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR, +\&\fBOSSL_CMP_CTX_get0_newPkey()\fR, +\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get0_statusString()\fR, +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR, +\&\fBOSSL_CMP_CTX_get0_newCert()\fR, +\&\fBOSSL_CMP_CTX_get0_newChain()\fR, +\&\fBOSSL_CMP_CTX_get1_caPubs()\fR, and +\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR +return the intended pointer value as described above or NULL on error. +.PP +\&\fBOSSL_CMP_CTX_get_option()\fR, +\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR, +\&\fBOSSL_CMP_CTX_get_status()\fR, and +\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR +return the intended value as described above or \-1 on error. +.PP +\&\fBOSSL_CMP_certConf_cb()\fR returns \fIfail_info\fR if it is not equal to 0, +else 0 on successful validation, +or else a bit field with the \fBOSSL_CMP_PKIFAILUREINFO_incorrectData\fR bit set. +.PP +All other functions, including \fBOSSL_CMP_CTX_reinit()\fR +and \fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR, +return 1 on success, 0 on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following code omits error handling. +.PP +Set up a CMP client context for sending requests and verifying responses: +.PP +.Vb 5 +\& cmp_ctx = OSSL_CMP_CTX_new(); +\& OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address); +\& OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string); +\& OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias); +\& OSSL_CMP_CTX_set0_trusted(cmp_ctx, ts); +.Ve +.PP +Set up symmetric credentials for MAC\-based message protection such as PBM: +.PP +.Vb 2 +\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); +\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); +.Ve +.PP +Set up the details for certificate requests: +.PP +.Vb 2 +\& OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey); +.Ve +.PP +Perform an Initialization Request transaction: +.PP +.Vb 1 +\& initialCert = OSSL_CMP_exec_IR_ses(cmp_ctx); +.Ve +.PP +Reset the transaction state of the CMP context and the credentials: +.PP +.Vb 3 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, NULL, 0); +\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, NULL, 0); +.Ve +.PP +Perform a Certification Request transaction, making use of the new credentials: +.PP +.Vb 4 +\& OSSL_CMP_CTX_set1_cert(cmp_ctx, initialCert); +\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, initialKey); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, curentKey); +\& currentCert = OSSL_CMP_exec_CR_ses(cmp_ctx); +.Ve +.PP +Perform a Key Update Request, signed using the cert (and key) to be updated: +.PP +.Vb 6 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& OSSL_CMP_CTX_set1_cert(cmp_ctx, currentCert); +\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, currentKey); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, updatedKey); +\& currentCert = OSSL_CMP_exec_KUR_ses(cmp_ctx); +\& currentKey = updatedKey; +.Ve +.PP +Perform a General Message transaction including, as an example, +the id\-it\-signKeyPairTypes OID and prints info on the General Response contents: +.PP +.Vb 1 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& +\& ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1); +\& OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, NULL); +\& OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav); +\& +\& STACK_OF(OSSL_CMP_ITAV) *itavs; +\& itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx); +\& print_itavs(itavs); +\& sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_exec_IR_ses\fR\|(3), \fBOSSL_CMP_exec_CR_ses\fR\|(3), +\&\fBOSSL_CMP_exec_KUR_ses\fR\|(3), \fBOSSL_CMP_exec_GENM_ses\fR\|(3), +\&\fBOSSL_CMP_exec_certreq\fR\|(3), \fBOSSL_CMP_MSG_http_perform\fR\|(3), +\&\fBERR_print_errors_cb\fR\|(3), \fBOSSL_HTTP_open\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_get0_trusted()\fR and +\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_set0_trusted()\fR, +using macros, while keeping the old names for backward compatibility, +in OpenSSL 3.2. +.PP +\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR was added in OpenSSL 3.0.8. +.PP +\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR, +\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, and +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR were added in OpenSSL 3.2. +.PP +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR and +the \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR option were added in OpenSSL 3.3. +.PP +Support for central key generation, requested via \fBOSSL_CRMF_POPO_NONE\fR, +was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |