.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OSSL_CMP_CTX_NEW 3"
.TH OSSL_CMP_CTX_NEW 3 "2020-03-02" "3.0.0-dev" "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_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_serverName,
OSSL_CMP_CTX_set_serverPort,
OSSL_CMP_CTX_set1_proxyName,
OSSL_CMP_CTX_set_proxyPort,
OSSL_CMP_DEFAULT_PORT,
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_trustedStore,
OSSL_CMP_CTX_get0_trustedStore,
OSSL_CMP_CTX_set1_untrusted_certs,
OSSL_CMP_CTX_get0_untrusted_certs,
OSSL_CMP_CTX_set1_clCert,
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_set1_extraCertsOut,
OSSL_CMP_CTX_set0_newPkey,
OSSL_CMP_CTX_get0_newPkey,
OSSL_CMP_CTX_set1_issuer,
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_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_newCert,
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(void);
\& void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx);
\& int OSSL_CMP_CTX_reinit(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(OSSL_CMP_CTX *ctx);
\&
\& /* message transfer: */
\& int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
\& int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name);
\& int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);
\& int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name);
\& int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port);
\& #define OSSL_CMP_DEFAULT_PORT 80
\& 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);
\& int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store);
\& X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx);
\& int OSSL_CMP_CTX_set1_untrusted_certs(OSSL_CMP_CTX *ctx,
\&                                       STACK_OF(X509) *certs);
\& STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted_certs(const OSSL_CMP_CTX *ctx);
\&
\& /* client authentication: */
\& int OSSL_CMP_CTX_set1_clCert(OSSL_CMP_CTX *ctx, X509 *cert);
\& 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,
\&                                   const 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_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_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_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_newCert(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 test purposes only: */
\& 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 \s-1API\s0 for using \s-1CMP\s0 (Certificate Management Protocol) with
OpenSSL.
.PP
\&\fIOSSL_CMP_CTX_new()\fR allocates and initializes an \s-1OSSL_CMP_CTX\s0 structure to
default values, e.g., proof-of-possession method is set to POPOSigningKey.
.PP
\&\fIOSSL_CMP_CTX_free()\fR deallocates an \s-1OSSL_CMP_CTX\s0 structure.
.PP
\&\fIOSSL_CMP_CTX_reinit()\fR prepares the given \fBctx\fR for a further transaction by
clearing the internal \s-1CMP\s0 transaction (aka session) status, PKIStatusInfo,
and any previous results (newCert, caPubs, and extraCertsIn)
from the last executed transaction.
All other field values (i.e., \s-1CMP\s0 options) are retained for potential re-use.
.PP
\&\fIOSSL_CMP_CTX_set_option()\fR sets the given value for the given option
(e.g., \s-1OSSL_CMP_OPT_IMPLICITCONFIRM\s0) in the given \s-1OSSL_CMP_CTX\s0 structure.
.PP
The following options can be set:
.IP "\fB\s-1OSSL_CMP_OPT_LOG_VERBOSITY\s0\fR" 4
.IX Item "OSSL_CMP_OPT_LOG_VERBOSITY"
.Vb 3
\&        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 L<OSSL_CMP_log_open(3)>.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_MSGTIMEOUT\s0\fR" 4
.IX Item "OSSL_CMP_OPT_MSGTIMEOUT"
.Vb 2
\&        Number of seconds (or 0 for infinite) a CMP message round trip is
\&        allowed to take before a timeout error is returned. Default is 120.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_TOTALTIMEOUT\s0\fR" 4
.IX Item "OSSL_CMP_OPT_TOTALTIMEOUT"
.Vb 2
\&        Maximum total number of seconds an enrollment (including polling)
\&        may take. Default is 0 (infinite).
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_VALIDITYDAYS\s0\fR" 4
.IX Item "OSSL_CMP_OPT_VALIDITYDAYS"
.Vb 1
\&        Number of days new certificates are asked to be valid for.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\s0\fR" 4
.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT"
.Vb 2
\&        Do not take default Subject Alternative Names
\&        from the reference certificate.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL\s0\fR" 4
.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL"
.Vb 1
\&        Demand that the given Subject Alternative Names are flagged as critical.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_POLICIES_CRITICAL\s0\fR" 4
.IX Item "OSSL_CMP_OPT_POLICIES_CRITICAL"
.Vb 1
\&        Demand that the given policies are flagged as critical.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_POPOMETHOD\s0\fR" 4
.IX Item "OSSL_CMP_OPT_POPOMETHOD"
.Vb 1
\&        Select the proof of possession method to use. Possible values are:
\&
\&            OSSL_CRMF_POPO_NONE       \- ProofOfPossession field omitted
\&            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")
\&
\&        Note that a signature\-based POPO can only be produced if a private key
\&        is provided as the newPkey or client pkey component of the CMP context.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_DIGEST_ALGNID\s0\fR" 4
.IX Item "OSSL_CMP_OPT_DIGEST_ALGNID"
.Vb 3
\&        The digest algorithm NID to be used in RFC 4210\*(Aqs MSG_SIG_ALG,
\&        if applicable used for message protection and Proof\-of\-Possession.
\&        Default is SHA256.
\&
\&    OSSL_CMP_OPT_OWF_ALGNID
\&        The digest algorithm NID to be used as one\-way function (OWF)
\&        in RFC 4210\*(Aqs MSG_MAC_ALG, if applicable used for message protection.
\&        Default is SHA256.
\&
\&    OSSL_CMP_OPT_MAC_ALGNID
\&        The MAC algorithm NID to be used in RFC 4210\*(Aqs MSG_MAC_ALG,
\&        if applicable used for message protection. 
\&        Default is HMAC\-SHA1 as per RFC 4210.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_REVOCATION_REASON\s0\fR" 4
.IX Item "OSSL_CMP_OPT_REVOCATION_REASON"
.Vb 2
\&        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.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_IMPLICITCONFIRM\s0\fR" 4
.IX Item "OSSL_CMP_OPT_IMPLICITCONFIRM"
.Vb 4
\&        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.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_DISABLECONFIRM\s0\fR" 4
.IX Item "OSSL_CMP_OPT_DISABLECONFIRM"
.Vb 5
\&        Do not confirm enrolled certificates, to cope with broken servers
\&        not supporting implicit confirmation correctly.
\&B<WARNING:> This setting leads to unspecified behavior and it is meant
\&exclusively to allow interoperability with server implementations violating
\&RFC 4210.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_UNPROTECTED_SEND\s0\fR" 4
.IX Item "OSSL_CMP_OPT_UNPROTECTED_SEND"
.Vb 1
\&        Send messages without CMP\-level protection.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_UNPROTECTED_ERRORS\s0\fR" 4
.IX Item "OSSL_CMP_OPT_UNPROTECTED_ERRORS"
.Vb 7
\&        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.
\&B<WARNING:> This setting leads to unspecified behavior and it is meant
\&exclusively to allow interoperability with server implementations violating
\&RFC 4210.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_IGNORE_KEYUSAGE\s0\fR" 4
.IX Item "OSSL_CMP_OPT_IGNORE_KEYUSAGE"
.Vb 3
\&        Ignore key usage restrictions in signer certificate when
\&        validating signature\-based protection in received CMP messages.
\&        Else, \*(AqdigitalSignature\*(Aq must be allowed by CMP signer certificates.
.Ve
.IP "\fB\s-1OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR\s0\fR" 4
.IX Item "OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR"
.Vb 2
\&        Allow retrieving a trust anchor from extraCerts and using that
\&        to validate the certificate chain of an IP message.
.Ve
.PP
\&\fIOSSL_CMP_CTX_get_option()\fR reads the current value of the given option
(e.g., \s-1OSSL_CMP_OPT_IMPLICITCONFIRM\s0) from the given \s-1OSSL_CMP_CTX\s0 structure.
.PP
\&\fIOSSL_CMP_CTX_set_log_cb()\fR sets in \fBctx\fR the callback function \f(CW\*(C`cb\*(C'\fR
for handling error queue entries and logging messages.
When \f(CW\*(C`cb\*(C'\fR is \s-1NULL\s0 errors are printed to \s-1STDERR\s0 (if available, else ignored)
any log messages are ignored.
Alternatively, \fIOSSL_CMP_log_open\fR\|(3) may be used to direct logging to \s-1STDOUT\s0.
.PP
\&\fIOSSL_CMP_CTX_set_log_verbosity()\fR is a macro setting the
\&\s-1OSSL_CMP_OPT_LOG_VERBOSITY\s0 context option to the given level.
.PP
\&\fIOSSL_CMP_CTX_print_errors()\fR outputs any entries in the OpenSSL error queue.
It is similar to \fB\f(BIERR_print_errors_cb()\fB\fR but uses the \s-1CMP\s0 log callback function
if set in the \f(CW\*(C`ctx\*(C'\fR for uniformity with \s-1CMP\s0 logging if given. Otherwise it uses
\&\fB\f(BIERR_print_errors\fB\|(3)\fR to print to \s-1STDERR\s0 (unless \s-1OPENSSL_NO_STDIO\s0 is defined).
.PP
\&\fIOSSL_CMP_CTX_set1_serverPath()\fR sets the \s-1HTTP\s0 path of the \s-1CMP\s0 server on the host.
.PP
\&\fIOSSL_CMP_CTX_set1_serverName()\fR sets the given server Address (as \s-1IP\s0 or name)
in the given \s-1OSSL_CMP_CTX\s0 structure.
.PP
\&\fIOSSL_CMP_CTX_set_serverPort()\fR sets the port of the \s-1CMP\s0 server to connect to.
Port defaults to \s-1OSSL_CMP_DEFAULT_PORT\s0 = 80 if not set explicitly.
.PP
\&\fIOSSL_CMP_CTX_set1_proxyName()\fR sets the hostname of the \s-1HTTP\s0 proxy to be used
for connecting to the \s-1CA\s0 server.
.PP
\&\fIOSSL_CMP_CTX_set_proxyPort()\fR sets the port of the \s-1HTTP\s0 proxy.
Port defaults to \s-1OSSL_CMP_DEFAULT_PORT\s0 = 80 if not set explicitly.
.PP
\&\fIOSSL_CMP_CTX_set_http_cb()\fR sets the optional \s-1BIO\s0 connect/disconnect callback
function, which has the prototype
.PP
.Vb 1
\& typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *ctx, int connect, int detail);
.Ve
.PP
The callback may modify the \s-1BIO\s0 \fBbio\fR provided by \fIOSSL_CMP_MSG_http_perform()\fR,
whereby it may make use of a custom defined argument \fBctx\fR
stored in the \s-1OSSL_CMP_CTX\s0 by means of \fIOSSL_CMP_CTX_set_http_cb_arg()\fR.
During connection establishment, just after calling \fIBIO_connect_retry()\fR,
the function is invoked with the \fBconnect\fR argument being 1 and the \fBdetail\fR
argument being 1 if \s-1HTTPS\s0 is requested, i.e., \s-1SSL/TLS\s0 should be enabled. On
disconnect \fBconnect\fR is 0 and \fBdetail\fR is 1 in case no error occurred, else 0.
For instance, on connect the function may prepend a \s-1TLS\s0 \s-1BIO\s0 to implement \s-1HTTPS\s0;
after disconnect it may do some diagnostic output and/or specific cleanup.
The function should return \s-1NULL\s0 to indicate failure.
After disconnect the modified \s-1BIO\s0 will be deallocated using \fIBIO_free_all()\fR.
.PP
\&\fIOSSL_CMP_CTX_set_http_cb_arg()\fR sets an argument, respectively a pointer to
a structure containing arguments,
optionally to be used by the http connect/disconnect callback function.
\&\fBarg\fR is not consumed, and it must therefore explicitly be freed when not
needed any more. \fBarg\fR may be \s-1NULL\s0 to clear the entry.
.PP
\&\fIOSSL_CMP_CTX_get_http_cb_arg()\fR gets the argument, respectively the pointer to a
structure containing arguments, previously set by
\&\fIOSSL_CMP_CTX_set_http_cb_arg()\fR or \s-1NULL\s0 if unset.
.PP
\&\fIOSSL_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
Returns 1 on success, 0 on error.
.PP
Default is \s-1NULL\s0, which implies the use of \fIOSSL_CMP_MSG_http_perform\fR\|(3).
The callback should send the \s-1CMP\s0 request message it obtains via the \fBreq\fR
parameter and on success return the response.
The transfer callback may make use of a custom defined argument stored in
the ctx by means of \fIOSSL_CMP_CTX_set_transfer_cb_arg()\fR, which may be retrieved
again through \fIOSSL_CMP_CTX_get_transfer_cb_arg()\fR.
.PP
\&\fIOSSL_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.
\&\fBarg\fR is not consumed, and it must therefore explicitly be freed when not
needed any more. \fBarg\fR may be \s-1NULL\s0 to clear the entry.
.PP
\&\fIOSSL_CMP_CTX_get_transfer_cb_arg()\fR gets the argument, respectively the pointer
to a structure containing arguments, previously set by
\&\fIOSSL_CMP_CTX_set_transfer_cb_arg()\fR or \s-1NULL\s0 if unset.
.PP
\&\fIOSSL_CMP_CTX_set1_srvCert()\fR pins the server certificate to be directly trusted
(even if it is expired) for verifying response messages.
The cert pointer is not consumed. It may be \s-1NULL\s0 to clear the entry.
.PP
\&\fIOSSL_CMP_CTX_set1_expected_sender()\fR sets the Distinguished Name (\s-1DN\s0) expected to
be given in the sender response for messages protected with \s-1MSG_SIG_ALG\s0. This
may be used to enforce that during validation of received messages the given \s-1DN\s0
matches the sender field of the PKIMessage header, which in turn is used to
identify the server certificate.
This can be used to ensure that only a particular entity is accepted to act as
\&\s-1CMP\s0 server, and attackers are not able to use arbitrary certificates of a
trusted \s-1PKI\s0 hierarchy to fraudulently pose as server.
This defaults to the subject \s-1DN\s0 of the certificate set via
\&\fIOSSL_CMP_CTX_set1_srvCert()\fR, if any.
.PP
\&\fIOSSL_CMP_CTX_set0_trustedStore()\fR sets the X509_STORE type certificate store
containing trusted (root) \s-1CA\s0 certificates. The certificate store may also hold
CRLs and a certificate verification callback function used for \s-1CMP\s0 server
authentication. Any already existing store entry is freed. When given a \s-1NULL\s0
parameter the entry is cleared.
.PP
\&\fIOSSL_CMP_CTX_get0_trustedStore()\fR returns a pointer to the certificate store
containing trusted root \s-1CA\s0 certificates, which may be empty if unset.
.PP
\&\fIOSSL_CMP_CTX_set1_untrusted_certs()\fR takes over a list of certificates containing
non-trusted intermediate certs used for path construction in authentication
of the \s-1CMP\s0 server and potentially others (\s-1TLS\s0 server, newly enrolled cert).
The reference counts of those certificates handled successfully are increased.
.PP
OSSL_CMP_CTX_get0_untrusted_certs(\s-1OSSL_CMP_CTX\s0 *ctx) returns a pointer to the
list of untrusted certs, which my be empty if unset.
.PP
\&\fIOSSL_CMP_CTX_set1_clCert()\fR sets the client certificate in the given
\&\s-1OSSL_CMP_CTX\s0 structure. The client certificate will then be used by the
functions to set the \*(L"sender\*(R" field for outgoing messages and it will be
included in the extraCerts field.
.PP
\&\fIOSSL_CMP_CTX_set1_pkey()\fR sets the private key corresponding to the client
certificate set with \fB\f(BIOSSL_CMP_CTX_set1_clCert()\fB\fR in the given \s-1CMP\s0 context.
Used to create the protection in case of \s-1MSG_SIG_ALG\s0.
.PP
\&\fIOSSL_CMP_CTX_set1_referenceValue()\fR sets the given referenceValue in the given
\&\fBctx\fR or clears it if the \fBref\fR argument is \s-1NULL\s0.
.PP
\&\fIOSSL_CMP_CTX_set1_secretValue()\fR sets the \fBsec\fR with the length \fBlen\fR in the
given \fBctx\fR or clears it if the \fBsec\fR argument is \s-1NULL\s0.
.PP
\&\fIOSSL_CMP_CTX_set1_recipient()\fR sets the recipient name that will be used in the
PKIHeader of a request message, i.e. the X509 name of the (\s-1CA\s0) server.
Setting is overruled by subject of srvCert if set.
If neither srvCert nor recipient are set, the recipient of the \s-1PKI\s0 message is
determined in the following order: issuer, issuer of old cert (oldCert),
issuer of client cert (clCert), else NULL-DN.
When a response is received, its sender must match the recipient of the request.
.PP
\&\fIOSSL_CMP_CTX_push0_geninfo_ITAV()\fR adds \fBitav\fR to the stack in the \fBctx\fR to be
added to the GeneralInfo field of the \s-1CMP\s0 PKIMessage header of a request
message sent with this context.  Consumes the pointer to \fBitav\fR.
.PP
\&\fIOSSL_CMP_CTX_set1_extraCertsOut()\fR sets the stack of extraCerts that will be
sent to remote.
.PP
\&\fIOSSL_CMP_CTX_set0_newPkey()\fR can be used to explicitly set the given \s-1EVP_PKEY\s0
structure as the private or public key to be certified in the \s-1CMP\s0 context.
The \fBpriv\fR parameter must be 0 if and only if the given key is a public key.
.PP
\&\fIOSSL_CMP_CTX_get0_newPkey()\fR gives the key to use for certificate enrollment
dependent on fields of the \s-1CMP\s0 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 private key.
If the \fBpriv\fR parameter is not 0 and the selected key does not have a
private component then \s-1NULL\s0 is returned.
.PP
\&\fIOSSL_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 \s-1CA\s0 server.
.PP
\&\fIOSSL_CMP_CTX_set1_subjectName()\fR sets the subject \s-1DN\s0 that will be used in
the CertTemplate structure when requesting a new cert. For Key Update Requests
(\s-1KUR\s0), it defaults to the subject \s-1DN\s0 of the reference certificate,
see \fB\f(BIOSSL_CMP_CTX_set1_oldCert()\fB\fR. This default is used for Initialization
Requests (\s-1IR\s0) and Certification Requests (\s-1CR\s0) only if no SANs are set.
.PP
If clCert is not set (e.g. in case of \s-1IR\s0 with \s-1MSG_MAC_ALG\s0), the subject \s-1DN\s0
is also used as sender of the \s-1PKI\s0 message.
.PP
\&\fIOSSL_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
\&\fIOSSL_CMP_CTX_set0_reqExtensions()\fR.
By default, unless \s-1OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\s0 has been set,
the Subject Alternative Names are copied from the reference certificate,
see \fIOSSL_CMP_CTX_set1_oldCert()\fR.
.PP
If set and the subject \s-1DN\s0 is not set with \fIOSSL_CMP_CTX_set1_subjectName()\fR, then
the certificate template of an \s-1IR\s0 and \s-1CR\s0 will not be filled with the default
subject \s-1DN\s0 from the reference certificate (see \fIOSSL_CMP_CTX_set1_oldCert()\fR.
If a subject \s-1DN\s0 is desired it needs to be set explicitly with
\&\fIOSSL_CMP_CTX_set1_subjectName()\fR.
.PP
\&\fIOSSL_CMP_CTX_set0_reqExtensions()\fR sets the X.509v3 extensions to be used in
\&\s-1IR/CR/KUR\s0.
.PP
\&\fIOSSL_CMP_CTX_reqExtensions_have_SAN()\fR returns 1 if the context contains
a Subject Alternative Name extension, else 0 or \-1 on error.
.PP
\&\fIOSSL_CMP_CTX_push0_policy()\fR adds the certificate policy info object
to the X509_EXTENSIONS of the requested certificate template.
.PP
\&\fIOSSL_CMP_CTX_set1_oldCert()\fR sets the old certificate to be updated in
Key Update Requests (\s-1KUR\s0) or to be revoked in Revocation Requests (\s-1RR\s0).
It must be given for \s-1RR\s0, else it defaults to \fBclCert\fR.
The reference certificate determined in this way, if any, is also used for
deriving default subject \s-1DN\s0 and Subject Alternative Names for \s-1IR\s0, \s-1CR\s0, and \s-1KUR\s0.
Its issuer, if any, is used as default recipient in the \s-1CMP\s0 message header.
.PP
\&\fIOSSL_CMP_CTX_set1_p10CSR()\fR sets the PKCS#10 \s-1CSR\s0 to be used in P10CR.
.PP
\&\fIOSSL_CMP_CTX_push0_genm_ITAV()\fR adds \fBitav\fR to the stack in the \fBctx\fR which
will be the body of a General Message sent with this context.
Consumes the pointer to \fBitav\fR.
.PP
\&\fIOSSL_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 \fBcert\fR parameter and may
overrule the pre-decision given in the \fBfail_info\fR and \fB*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 \fB*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 \fBctx\fR by means of \fIOSSL_CMP_CTX_set_certConf_cb_arg()\fR, which may be
retrieved again through \fIOSSL_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 \s-1DN\s0 and other fields of the newly
enrolled certificate with the certificate template of the request.
.PP
\&\fIOSSL_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.
\&\fBarg\fR is not consumed, and it must therefore explicitly be freed when not
needed any more. \fBarg\fR may be \s-1NULL\s0 to clear the entry.
.PP
\&\fIOSSL_CMP_CTX_get_certConf_cb_arg()\fR gets the argument, respectively the pointer
to a structure containing arguments, previously set by
\&\fIOSSL_CMP_CTX_set_certConf_cb_arg()\fR, or \s-1NULL\s0 if unset.
.PP
\&\fIOSSL_CMP_CTX_get_status()\fR returns the PKIstatus from the last received
CertRepMessage or Revocation Response or error message, or \-1 if unset.
.PP
\&\fIOSSL_CMP_CTX_get0_statusString()\fR returns the statusString from the last received
CertRepMessage or Revocation Response or error message, or \s-1NULL\s0 if unset.
.PP
\&\fIOSSL_CMP_CTX_get_failInfoCode()\fR returns the error code from the failInfo field
of the last received CertRepMessage or Revocation Response or error message.
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 \s-1OSSL_CMP_CTX_FAILINFO\s0, for example:
OSSL_CMP_CTX_FAILINFO_badAlg. Returns \-1 if the failInfoCode field is unset.
.PP
\&\fIOSSL_CMP_CTX_get0_newCert()\fR returns the pointer to the newly obtained
certificate in case it is available, else \s-1NULL\s0.
.PP
\&\fIOSSL_CMP_CTX_get1_caPubs()\fR returns a pointer to a duplicate of the stack of
X.509 certificates received in the caPubs field of last received certificate
response message \s-1IP/CP/KUP\s0.
.PP
\&\fIOSSL_CMP_CTX_get1_extraCertsIn()\fR returns a pointer to a duplicate of the stack
of X.509 certificates received in the last received non-empty extraCerts field.
Returns an empty stack if no extraCerts have been received in the current
transaction.
.PP
\&\fIOSSL_CMP_CTX_set1_transactionID()\fR sets the given transaction \s-1ID\s0 in the given
\&\s-1OSSL_CMP_CTX\s0 structure.
.PP
\&\fIOSSL_CMP_CTX_set1_senderNonce()\fR stores the last sent sender \fBnonce\fR in
the \fBctx\fR. This will be used to validate the recipNonce in incoming messages.
.SH "NOTES"
.IX Header "NOTES"
\&\s-1CMP\s0 is defined in \s-1RFC\s0 4210 (and \s-1CRMF\s0 in \s-1RFC\s0 4211).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIOSSL_CMP_CTX_free()\fR and \fIOSSL_CMP_CTX_print_errors()\fR do not return anything.
.PP
\&\fIOSSL_CMP_CTX_new()\fR,
\&\fIOSSL_CMP_CTX_get_http_cb_arg()\fR,
\&\fIOSSL_CMP_CTX_get_transfer_cb_arg()\fR,
\&\fIOSSL_CMP_CTX_get0_trustedStore()\fR,
\&\fIOSSL_CMP_CTX_get0_untrusted_certs()\fR,
\&\fIOSSL_CMP_CTX_get0_newPkey()\fR,
\&\fIOSSL_CMP_CTX_get_certConf_cb_arg()\fR,
\&\fIOSSL_CMP_CTX_get0_statusString()\fR,
\&\fIOSSL_CMP_CTX_get0_newCert()\fR,
\&\fIOSSL_CMP_CTX_get1_caPubs()\fR, and
\&\fIOSSL_CMP_CTX_get1_extraCertsIn()\fR
return the intended pointer value as described above or \s-1NULL\s0 on error.
.PP
\&\fIOSSL_CMP_CTX_get_option()\fR,
\&\fIOSSL_CMP_CTX_reqExtensions_have_SAN()\fR,
\&\fIOSSL_CMP_CTX_get_status()\fR, and
\&\fIOSSL_CMP_CTX_get_failInfoCode()\fR
return the intended value as described above or \-1 on error.
.PP
All other functions return 1 on success, 0 on error.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following code does an Initialization Request:
.PP
.Vb 6
\&        cmp_ctx = OSSL_CMP_CTX_new();
\&        OSSL_CMP_CTX_set1_serverName(cmp_ctx, opt_serverName);
\&        OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
\&        OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
\&        OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
\&        OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
\&
\&        initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
.Ve
.PP
The following code does an Initialization Request using an
external identity certificate (\s-1RFC\s0 4210, Appendix E.7):
.PP
.Vb 6
\&        cmp_ctx = OSSL_CMP_CTX_new();
\&        OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
\&        OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
\&        OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
\&        OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
\&        OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
\&
\&        initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
.Ve
.PP
Here externalCert is an X509 certificate granted to the \s-1EE\s0 by another \s-1CA\s0
which is trusted by the current \s-1CA\s0 the code will connect to.
.PP
The following code does a Key Update Request:
.PP
.Vb 6
\&        cmp_ctx = OSSL_CMP_CTX_new();
\&        OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
\&        OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
\&        OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
\&        OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
\&        OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
\&
\&        updatedClCert = OSSL_CMP_exec_KUR_ses(cmp_ctx);
.Ve
.PP
The following code (which omits error handling) sends a General Message
including, as an example, the id-it-signKeyPairTypes \s-1OID\s0 and prints info on
the General Response contents.
.PP
.Vb 4
\&    cmp_ctx = OSSL_CMP_CTX_new();
\&    OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
\&    OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
\&    OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
\&
\&    ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1);
\&    OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_new(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"
\&\fIOSSL_CMP_exec_IR_ses\fR\|(3), \fIOSSL_CMP_exec_KUR_ses\fR\|(3),
\&\fIOSSL_CMP_exec_GENM_ses\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The OpenSSL \s-1CMP\s0 support was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2007\-2019 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.