806 lines
35 KiB
Groff
Executable File
806 lines
35 KiB
Groff
Executable File
.\" 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>.
|