| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "OSSL_CMP_CTX_NEW 3SSL" |
| 58 |
.TH OSSL_CMP_CTX_NEW 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
OSSL_CMP_CTX_new, |
| 65 |
OSSL_CMP_CTX_free, |
| 66 |
OSSL_CMP_CTX_reinit, |
| 67 |
OSSL_CMP_CTX_get0_libctx, OSSL_CMP_CTX_get0_propq, |
| 68 |
OSSL_CMP_CTX_set_option, |
| 69 |
OSSL_CMP_CTX_get_option, |
| 70 |
OSSL_CMP_CTX_set_log_cb, |
| 71 |
OSSL_CMP_CTX_set_log_verbosity, |
| 72 |
OSSL_CMP_CTX_print_errors, |
| 73 |
OSSL_CMP_CTX_set1_serverPath, |
| 74 |
OSSL_CMP_CTX_set1_server, |
| 75 |
OSSL_CMP_CTX_set_serverPort, |
| 76 |
OSSL_CMP_CTX_set1_proxy, |
| 77 |
OSSL_CMP_CTX_set1_no_proxy, |
| 78 |
OSSL_CMP_CTX_set_http_cb, |
| 79 |
OSSL_CMP_CTX_set_http_cb_arg, |
| 80 |
OSSL_CMP_CTX_get_http_cb_arg, |
| 81 |
OSSL_CMP_transfer_cb_t, |
| 82 |
OSSL_CMP_CTX_set_transfer_cb, |
| 83 |
OSSL_CMP_CTX_set_transfer_cb_arg, |
| 84 |
OSSL_CMP_CTX_get_transfer_cb_arg, |
| 85 |
OSSL_CMP_CTX_set1_srvCert, |
| 86 |
OSSL_CMP_CTX_set1_expected_sender, |
| 87 |
OSSL_CMP_CTX_set0_trusted, |
| 88 |
OSSL_CMP_CTX_set0_trustedStore, |
| 89 |
OSSL_CMP_CTX_get0_trusted, |
| 90 |
OSSL_CMP_CTX_get0_trustedStore, |
| 91 |
OSSL_CMP_CTX_set1_untrusted, |
| 92 |
OSSL_CMP_CTX_get0_untrusted, |
| 93 |
OSSL_CMP_CTX_set1_cert, |
| 94 |
OSSL_CMP_CTX_build_cert_chain, |
| 95 |
OSSL_CMP_CTX_set1_pkey, |
| 96 |
OSSL_CMP_CTX_set1_referenceValue, |
| 97 |
OSSL_CMP_CTX_set1_secretValue, |
| 98 |
OSSL_CMP_CTX_set1_recipient, |
| 99 |
OSSL_CMP_CTX_push0_geninfo_ITAV, |
| 100 |
OSSL_CMP_CTX_reset_geninfo_ITAVs, |
| 101 |
OSSL_CMP_CTX_get0_geninfo_ITAVs, |
| 102 |
OSSL_CMP_CTX_set1_extraCertsOut, |
| 103 |
OSSL_CMP_CTX_set0_newPkey, |
| 104 |
OSSL_CMP_CTX_get0_newPkey, |
| 105 |
OSSL_CMP_CTX_set1_issuer, |
| 106 |
OSSL_CMP_CTX_set1_serialNumber, |
| 107 |
OSSL_CMP_CTX_set1_subjectName, |
| 108 |
OSSL_CMP_CTX_push1_subjectAltName, |
| 109 |
OSSL_CMP_CTX_set0_reqExtensions, |
| 110 |
OSSL_CMP_CTX_reqExtensions_have_SAN, |
| 111 |
OSSL_CMP_CTX_push0_policy, |
| 112 |
OSSL_CMP_CTX_set1_oldCert, |
| 113 |
OSSL_CMP_CTX_set1_p10CSR, |
| 114 |
OSSL_CMP_CTX_push0_genm_ITAV, |
| 115 |
OSSL_CMP_certConf_cb_t, |
| 116 |
OSSL_CMP_certConf_cb, |
| 117 |
OSSL_CMP_CTX_set_certConf_cb, |
| 118 |
OSSL_CMP_CTX_set_certConf_cb_arg, |
| 119 |
OSSL_CMP_CTX_get_certConf_cb_arg, |
| 120 |
OSSL_CMP_CTX_get_status, |
| 121 |
OSSL_CMP_CTX_get0_statusString, |
| 122 |
OSSL_CMP_CTX_get_failInfoCode, |
| 123 |
OSSL_CMP_CTX_get0_validatedSrvCert, |
| 124 |
OSSL_CMP_CTX_get0_newCert, |
| 125 |
OSSL_CMP_CTX_get1_newChain, |
| 126 |
OSSL_CMP_CTX_get1_caPubs, |
| 127 |
OSSL_CMP_CTX_get1_extraCertsIn, |
| 128 |
OSSL_CMP_CTX_set1_transactionID, |
| 129 |
OSSL_CMP_CTX_set1_senderNonce |
| 130 |
\&\- functions for managing the CMP client context data structure |
| 131 |
.SH SYNOPSIS |
| 132 |
.IX Header "SYNOPSIS" |
| 133 |
.Vb 1 |
| 134 |
\& #include <openssl/cmp.h> |
| 135 |
\& |
| 136 |
\& OSSL_CMP_CTX *OSSL_CMP_CTX_new(OSSL_LIB_CTX *libctx, const char *propq); |
| 137 |
\& void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx); |
| 138 |
\& int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx); |
| 139 |
\& OSSL_LIB_CTX *OSSL_CMP_CTX_get0_libctx(const OSSL_CMP_CTX *ctx); |
| 140 |
\& const char *OSSL_CMP_CTX_get0_propq(const OSSL_CMP_CTX *ctx); |
| 141 |
\& int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val); |
| 142 |
\& int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt); |
| 143 |
\& |
| 144 |
\& /* logging and error reporting: */ |
| 145 |
\& int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb); |
| 146 |
\& #define OSSL_CMP_CTX_set_log_verbosity(ctx, level) |
| 147 |
\& void OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx); |
| 148 |
\& |
| 149 |
\& /* message transfer: */ |
| 150 |
\& int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path); |
| 151 |
\& int OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address); |
| 152 |
\& int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port); |
| 153 |
\& int OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name); |
| 154 |
\& int OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names); |
| 155 |
\& int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb); |
| 156 |
\& int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg); |
| 157 |
\& void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx); |
| 158 |
\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx, |
| 159 |
\& const OSSL_CMP_MSG *req); |
| 160 |
\& int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx, |
| 161 |
\& OSSL_CMP_transfer_cb_t cb); |
| 162 |
\& int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg); |
| 163 |
\& void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx); |
| 164 |
\& |
| 165 |
\& /* server authentication: */ |
| 166 |
\& int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert); |
| 167 |
\& int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx, |
| 168 |
\& const X509_NAME *name); |
| 169 |
\& #define OSSL_CMP_CTX_set0_trusted OSSL_CMP_CTX_set0_trustedStore |
| 170 |
\& int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store); |
| 171 |
\& #define OSSL_CMP_CTX_get0_trusted OSSL_CMP_CTX_get0_trustedStore |
| 172 |
\& X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx); |
| 173 |
\& int OSSL_CMP_CTX_set1_untrusted(OSSL_CMP_CTX *ctx, STACK_OF(X509) *certs); |
| 174 |
\& STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted(const OSSL_CMP_CTX *ctx); |
| 175 |
\& |
| 176 |
\& /* client authentication: */ |
| 177 |
\& int OSSL_CMP_CTX_set1_cert(OSSL_CMP_CTX *ctx, X509 *cert); |
| 178 |
\& int OSSL_CMP_CTX_build_cert_chain(OSSL_CMP_CTX *ctx, X509_STORE *own_trusted, |
| 179 |
\& STACK_OF(X509) *candidates); |
| 180 |
\& int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey); |
| 181 |
\& int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx, |
| 182 |
\& const unsigned char *ref, int len); |
| 183 |
\& int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, |
| 184 |
\& const unsigned char *sec, int len); |
| 185 |
\& |
| 186 |
\& /* CMP message header and extra certificates: */ |
| 187 |
\& int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name); |
| 188 |
\& int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); |
| 189 |
\& int OSSL_CMP_CTX_reset_geninfo_ITAVs(OSSL_CMP_CTX *ctx); |
| 190 |
\& STACK_OF(OSSL_CMP_ITAV) |
| 191 |
\& *OSSL_CMP_CTX_get0_geninfo_ITAVs(const OSSL_CMP_CTX *ctx); |
| 192 |
\& int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx, |
| 193 |
\& STACK_OF(X509) *extraCertsOut); |
| 194 |
\& |
| 195 |
\& /* certificate template: */ |
| 196 |
\& int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey); |
| 197 |
\& EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv); |
| 198 |
\& int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name); |
| 199 |
\& int OSSL_CMP_CTX_set1_serialNumber(OSSL_CMP_CTX *ctx, const ASN1_INTEGER *sn); |
| 200 |
\& int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name); |
| 201 |
\& int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx, |
| 202 |
\& const GENERAL_NAME *name); |
| 203 |
\& int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts); |
| 204 |
\& int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx); |
| 205 |
\& int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo); |
| 206 |
\& int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert); |
| 207 |
\& int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr); |
| 208 |
\& |
| 209 |
\& /* misc body contents: */ |
| 210 |
\& int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); |
| 211 |
\& |
| 212 |
\& /* certificate confirmation: */ |
| 213 |
\& typedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert, |
| 214 |
\& int fail_info, const char **txt); |
| 215 |
\& int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info, |
| 216 |
\& const char **text); |
| 217 |
\& int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb); |
| 218 |
\& int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg); |
| 219 |
\& void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx); |
| 220 |
\& |
| 221 |
\& /* result fetching: */ |
| 222 |
\& int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx); |
| 223 |
\& OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx); |
| 224 |
\& int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx); |
| 225 |
\& |
| 226 |
\& X509 *OSSL_CMP_CTX_get0_validatedSrvCert(const OSSL_CMP_CTX *ctx); |
| 227 |
\& X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx); |
| 228 |
\& STACK_OF(X509) *OSSL_CMP_CTX_get1_newChain(const OSSL_CMP_CTX *ctx); |
| 229 |
\& STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx); |
| 230 |
\& STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx); |
| 231 |
\& |
| 232 |
\& /* for testing and debugging purposes: */ |
| 233 |
\& int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx, |
| 234 |
\& const ASN1_OCTET_STRING *id); |
| 235 |
\& int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx, |
| 236 |
\& const ASN1_OCTET_STRING *nonce); |
| 237 |
.Ve |
| 238 |
.SH DESCRIPTION |
| 239 |
.IX Header "DESCRIPTION" |
| 240 |
This is the context API for using CMP (Certificate Management Protocol) with |
| 241 |
OpenSSL. |
| 242 |
.PP |
| 243 |
\&\fBOSSL_CMP_CTX_new()\fR allocates an \fBOSSL_CMP_CTX\fR structure associated with |
| 244 |
the library context \fIlibctx\fR and property query string \fIpropq\fR, |
| 245 |
both of which may be NULL to select the defaults. |
| 246 |
It initializes the remaining fields to their default values \- for instance, |
| 247 |
the logging verbosity is set to OSSL_CMP_LOG_INFO, |
| 248 |
the message timeout is set to 120 seconds, |
| 249 |
and the proof-of-possession method is set to OSSL_CRMF_POPO_SIGNATURE. |
| 250 |
.PP |
| 251 |
\&\fBOSSL_CMP_CTX_free()\fR deallocates an OSSL_CMP_CTX structure. |
| 252 |
If the argument is NULL, nothing is done. |
| 253 |
.PP |
| 254 |
\&\fBOSSL_CMP_CTX_reinit()\fR prepares the given \fIctx\fR for a further transaction by |
| 255 |
clearing the internal CMP transaction (aka session) status, PKIStatusInfo, |
| 256 |
and any previous results (newCert, newChain, caPubs, and extraCertsIn) |
| 257 |
from the last executed transaction. |
| 258 |
It also clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_genm_ITAV()\fR. |
| 259 |
All other field values (i.e., CMP options) are retained for potential reuse. |
| 260 |
.PP |
| 261 |
\&\fBOSSL_CMP_CTX_get0_libctx()\fR returns the \fIlibctx\fR argument that was used |
| 262 |
when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. |
| 263 |
.PP |
| 264 |
\&\fBOSSL_CMP_CTX_get0_propq()\fR returns the \fIpropq\fR argument that was used |
| 265 |
when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. |
| 266 |
.PP |
| 267 |
\&\fBOSSL_CMP_CTX_set_option()\fR sets the given value for the given option |
| 268 |
(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure. |
| 269 |
.PP |
| 270 |
The following options can be set: |
| 271 |
.IP \fBOSSL_CMP_OPT_LOG_VERBOSITY\fR 4 |
| 272 |
.IX Item "OSSL_CMP_OPT_LOG_VERBOSITY" |
| 273 |
The level of severity needed for actually outputting log messages |
| 274 |
due to errors, warnings, general info, debugging, etc. |
| 275 |
Default is OSSL_CMP_LOG_INFO. See also \fBOSSL_CMP_log_open\fR\|(3). |
| 276 |
.IP \fBOSSL_CMP_OPT_KEEP_ALIVE\fR 4 |
| 277 |
.IX Item "OSSL_CMP_OPT_KEEP_ALIVE" |
| 278 |
If the given value is 0 then HTTP connections are not kept open |
| 279 |
after receiving a response, which is the default behavior for HTTP 1.0. |
| 280 |
If the value is 1 or 2 then persistent connections are requested. |
| 281 |
If the value is 2 then persistent connections are required, |
| 282 |
i.e., in case the server does not grant them an error occurs. |
| 283 |
The default value is 1: prefer to keep the connection open. |
| 284 |
.IP \fBOSSL_CMP_OPT_MSG_TIMEOUT\fR 4 |
| 285 |
.IX Item "OSSL_CMP_OPT_MSG_TIMEOUT" |
| 286 |
Number of seconds a CMP request-response message round trip |
| 287 |
is allowed to take before a timeout error is returned. |
| 288 |
A value <= 0 means no limitation (waiting indefinitely). |
| 289 |
Default is to use the \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR setting. |
| 290 |
.IP \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR 4 |
| 291 |
.IX Item "OSSL_CMP_OPT_TOTAL_TIMEOUT" |
| 292 |
Maximum total number of seconds a transaction may take, |
| 293 |
including polling etc. |
| 294 |
A value <= 0 means no limitation (waiting indefinitely). |
| 295 |
Default is 0. |
| 296 |
.IP \fBOSSL_CMP_OPT_USE_TLS\fR 4 |
| 297 |
.IX Item "OSSL_CMP_OPT_USE_TLS" |
| 298 |
Use this option to indicate to the HTTP implementation |
| 299 |
whether TLS is going to be used for the connection (resulting in HTTPS). |
| 300 |
The value 1 indicates that TLS is used for client-side HTTP connections, |
| 301 |
which needs to be implemented via a callback function set by |
| 302 |
\&\fBOSSL_CMP_CTX_set_http_cb()\fR. |
| 303 |
The value 0 indicates that TLS is not used. |
| 304 |
Default is \-1 for backward compatibility: TLS is used by the client side |
| 305 |
if and only if \fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets a non-NULL \fIarg\fR. |
| 306 |
.IP \fBOSSL_CMP_OPT_VALIDITY_DAYS\fR 4 |
| 307 |
.IX Item "OSSL_CMP_OPT_VALIDITY_DAYS" |
| 308 |
Number of days new certificates are asked to be valid for. |
| 309 |
.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR 4 |
| 310 |
.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT" |
| 311 |
Do not take default Subject Alternative Names |
| 312 |
from the reference certificate. |
| 313 |
.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL\fR 4 |
| 314 |
.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL" |
| 315 |
Demand that the given Subject Alternative Names are flagged as critical. |
| 316 |
.IP \fBOSSL_CMP_OPT_POLICIES_CRITICAL\fR 4 |
| 317 |
.IX Item "OSSL_CMP_OPT_POLICIES_CRITICAL" |
| 318 |
Demand that the given policies are flagged as critical. |
| 319 |
.IP \fBOSSL_CMP_OPT_POPO_METHOD\fR 4 |
| 320 |
.IX Item "OSSL_CMP_OPT_POPO_METHOD" |
| 321 |
Select the proof of possession method to use. Possible values are: |
| 322 |
.Sp |
| 323 |
.Vb 8 |
| 324 |
\& OSSL_CRMF_POPO_NONE \- ProofOfPossession field omitted, |
| 325 |
\& which implies central key generation |
| 326 |
\& OSSL_CRMF_POPO_RAVERIFIED \- assert that the RA has already |
| 327 |
\& verified the PoPo |
| 328 |
\& OSSL_CRMF_POPO_SIGNATURE \- sign a value with private key, |
| 329 |
\& which is the default. |
| 330 |
\& OSSL_CRMF_POPO_KEYENC \- decrypt the encrypted certificate |
| 331 |
\& ("indirect method") |
| 332 |
.Ve |
| 333 |
.Sp |
| 334 |
Note that a signature-based POPO can only be produced if a private key |
| 335 |
is provided as the newPkey or client's pkey component of the CMP context. |
| 336 |
.IP \fBOSSL_CMP_OPT_DIGEST_ALGNID\fR 4 |
| 337 |
.IX Item "OSSL_CMP_OPT_DIGEST_ALGNID" |
| 338 |
The NID of the digest algorithm to be used in RFC 9810's MSG_SIG_ALG |
| 339 |
for signature-based message protection and Proof-of-Possession (POPO). |
| 340 |
Default is SHA256. |
| 341 |
.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 |
| 342 |
.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." |
| 343 |
.PD 0 |
| 344 |
.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 |
| 345 |
.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." |
| 346 |
.IP \fBOSSL_CMP_OPT_REVOCATION_REASON\fR 4 |
| 347 |
.IX Item "OSSL_CMP_OPT_REVOCATION_REASON" |
| 348 |
.PD |
| 349 |
The reason code to be included in a Revocation Request (RR); |
| 350 |
values: 0..10 (RFC 5210, 5.3.1) or \-1 for none, which is the default. |
| 351 |
.IP \fBOSSL_CMP_OPT_IMPLICIT_CONFIRM\fR 4 |
| 352 |
.IX Item "OSSL_CMP_OPT_IMPLICIT_CONFIRM" |
| 353 |
Request server to enable implicit confirm mode, where the client |
| 354 |
does not need to send confirmation upon receiving the |
| 355 |
certificate. If the server does not enable implicit confirmation |
| 356 |
in the return message, then confirmation is sent anyway. |
| 357 |
.IP \fBOSSL_CMP_OPT_DISABLE_CONFIRM\fR 4 |
| 358 |
.IX Item "OSSL_CMP_OPT_DISABLE_CONFIRM" |
| 359 |
Do not confirm enrolled certificates, to cope with broken servers |
| 360 |
not supporting implicit confirmation correctly. |
| 361 |
\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant |
| 362 |
exclusively to allow interoperability with server implementations violating |
| 363 |
RFC 9810. |
| 364 |
.IP \fBOSSL_CMP_OPT_UNPROTECTED_SEND\fR 4 |
| 365 |
.IX Item "OSSL_CMP_OPT_UNPROTECTED_SEND" |
| 366 |
Send request or response messages without CMP-level protection. |
| 367 |
.IP \fBOSSL_CMP_OPT_UNPROTECTED_ERRORS\fR 4 |
| 368 |
.IX Item "OSSL_CMP_OPT_UNPROTECTED_ERRORS" |
| 369 |
Accept unprotected error responses which are either explicitly |
| 370 |
unprotected or where protection verification failed. Applies to regular |
| 371 |
error messages as well as certificate responses (IP/CP/KUP) and |
| 372 |
revocation responses (RP) with rejection. |
| 373 |
\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant |
| 374 |
exclusively to allow interoperability with server implementations violating |
| 375 |
RFC 9810. |
| 376 |
.IP \fBOSSL_CMP_OPT_IGNORE_KEYUSAGE\fR 4 |
| 377 |
.IX Item "OSSL_CMP_OPT_IGNORE_KEYUSAGE" |
| 378 |
Ignore key usage restrictions in the signer's certificate when |
| 379 |
validating signature-based protection in received CMP messages. |
| 380 |
Else, 'digitalSignature' must be allowed by CMP signer certificates. |
| 381 |
.IP \fBOSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR\fR 4 |
| 382 |
.IX Item "OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR" |
| 383 |
Allow retrieving a trust anchor from extraCerts and using that |
| 384 |
to validate the certificate chain of an IP message. |
| 385 |
This is a quirk option added to support 3GPP TS 33.310. |
| 386 |
.Sp |
| 387 |
Note that using this option is dangerous as the certificate obtained |
| 388 |
this way has not been authenticated (at least not at CMP level). |
| 389 |
Taking it over as a trust anchor implements trust-on-first-use (TOFU). |
| 390 |
.IP \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR 4 |
| 391 |
.IX Item "OSSL_CMP_OPT_NO_CACHE_EXTRACERTS" |
| 392 |
Do not cache certificates received in the extraCerts CMP message field. |
| 393 |
Otherwise they are stored to potentially help validate further messages. |
| 394 |
.Sp |
| 395 |
In any case, after successfully validating an incoming message, its protection |
| 396 |
certificate (if any) is cached for reuse with validation of subsequent messages. |
| 397 |
This is done not only for efficiency but also |
| 398 |
to eliminate the need for the sender to include its certificate and related chain |
| 399 |
in the extraCerts field of subsequent messages of the same transaction. |
| 400 |
.PP |
| 401 |
\&\fBOSSL_CMP_CTX_get_option()\fR reads the current value of the given option |
| 402 |
(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) from the given OSSL_CMP_CTX structure. |
| 403 |
.PP |
| 404 |
\&\fBOSSL_CMP_CTX_set_log_cb()\fR sets in \fIctx\fR the callback function \fIcb\fR |
| 405 |
for handling error queue entries and logging messages. |
| 406 |
When \fIcb\fR is NULL errors are printed to STDERR (if available, else ignored) |
| 407 |
any log messages are ignored. |
| 408 |
Alternatively, \fBOSSL_CMP_log_open\fR\|(3) may be used to direct logging to STDOUT. |
| 409 |
.PP |
| 410 |
\&\fBOSSL_CMP_CTX_set_log_verbosity()\fR is a macro setting the |
| 411 |
OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level. |
| 412 |
.PP |
| 413 |
\&\fBOSSL_CMP_CTX_print_errors()\fR outputs any entries in the OpenSSL error queue. It |
| 414 |
is similar to \fBERR_print_errors_cb\fR\|(3) but uses the CMP log callback function |
| 415 |
if set in the \fIctx\fR for uniformity with CMP logging if given. Otherwise it uses |
| 416 |
\&\fBERR_print_errors\fR\|(3) to print to STDERR (unless OPENSSL_NO_STDIO is defined). |
| 417 |
.PP |
| 418 |
\&\fBOSSL_CMP_CTX_set1_serverPath()\fR sets the HTTP path of the CMP server on the host, |
| 419 |
also known as "CMP alias". |
| 420 |
The default is \f(CW\*(C`/\*(C'\fR. |
| 421 |
.PP |
| 422 |
\&\fBOSSL_CMP_CTX_set1_server()\fR sets the given server \fIaddress\fR |
| 423 |
(which may be a hostname or IP address or NULL) in the given \fIctx\fR. |
| 424 |
If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non-NULL argument, |
| 425 |
this server address information is used for diagnostic output only. |
| 426 |
.PP |
| 427 |
\&\fBOSSL_CMP_CTX_set_serverPort()\fR sets the port of the CMP server to connect to. |
| 428 |
If not used or the \fIport\fR argument is 0 |
| 429 |
the default port applies, which is 80 for HTTP and 443 for HTTPS. |
| 430 |
If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non-NULL argument, |
| 431 |
this server port information is used for diagnostic output only. |
| 432 |
.PP |
| 433 |
\&\fBOSSL_CMP_CTX_set1_proxy()\fR sets the HTTP proxy to be used for connecting to |
| 434 |
the given CMP server unless overruled by any "no_proxy" settings (see below). |
| 435 |
If TLS is not used this defaults to the value of |
| 436 |
the environment variable \f(CW\*(C`http_proxy\*(C'\fR if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR. |
| 437 |
Otherwise defaults to the value of \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR. |
| 438 |
An empty proxy string specifies not to use a proxy. |
| 439 |
Otherwise the format is |
| 440 |
\&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR, |
| 441 |
where any given userinfo, path, query, and fragment is ignored. |
| 442 |
If the host string is an IPv6 address, it must be enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. |
| 443 |
The default port number is 80, or 443 in case \f(CW\*(C`https:\*(C'\fR is given. |
| 444 |
.PP |
| 445 |
\&\fBOSSL_CMP_CTX_set1_no_proxy()\fR sets the list of server hostnames not to use |
| 446 |
an HTTP proxy for. The names may be separated by commas and/or whitespace. |
| 447 |
Defaults to the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR. |
| 448 |
.PP |
| 449 |
\&\fBOSSL_CMP_CTX_set_http_cb()\fR sets the optional BIO connect/disconnect callback |
| 450 |
function, which has the prototype |
| 451 |
.PP |
| 452 |
.Vb 1 |
| 453 |
\& typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *arg, int connect, int detail); |
| 454 |
.Ve |
| 455 |
.PP |
| 456 |
The callback may modify the \fIbio\fR provided by \fBOSSL_CMP_MSG_http_perform\fR\|(3) |
| 457 |
as described for the \fIbio_update_fn\fR parameter of \fBOSSL_HTTP_open\fR\|(3). |
| 458 |
The callback may make use of a custom defined argument \fIarg\fR, |
| 459 |
as described for the \fIarg\fR parameter of \fBOSSL_HTTP_open\fR\|(3). |
| 460 |
The argument is stored in the OSSL_CMP_CTX using \fBOSSL_CMP_CTX_set_http_cb_arg()\fR. |
| 461 |
See also the \fBOSSL_CMP_OPT_USE_TLS\fR option described above. |
| 462 |
.PP |
| 463 |
\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets the argument, respectively a pointer to |
| 464 |
a structure containing arguments such as an \fBSSL_CTX\fR structure, |
| 465 |
optionally to be used by the http connect/disconnect callback function. |
| 466 |
\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not |
| 467 |
needed any more. \fIarg\fR may be NULL to clear the entry. |
| 468 |
If a non-NULL argument is set, it is an error to use \fBOSSL_CMP_CTX_set1_proxy()\fR |
| 469 |
or \fBOSSL_CMP_CTX_set1_no_proxy()\fR for setting non-NULL strings. |
| 470 |
.PP |
| 471 |
\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR gets the argument, respectively the pointer to a |
| 472 |
structure containing arguments, previously set by |
| 473 |
\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR or NULL if unset. |
| 474 |
.PP |
| 475 |
\&\fBOSSL_CMP_CTX_set_transfer_cb()\fR sets the message transfer callback function, |
| 476 |
which has the type |
| 477 |
.PP |
| 478 |
.Vb 2 |
| 479 |
\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx, |
| 480 |
\& const OSSL_CMP_MSG *req); |
| 481 |
.Ve |
| 482 |
.PP |
| 483 |
Default is NULL, which implies the use of \fBOSSL_CMP_MSG_http_perform\fR\|(3). |
| 484 |
The callback should send the CMP request message it obtains via the \fIreq\fR |
| 485 |
parameter and on success return the response, else it must return NULL. |
| 486 |
The transfer callback may make use of a custom defined argument stored in |
| 487 |
the ctx by means of \fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR, which may be retrieved |
| 488 |
again through \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR. |
| 489 |
.PP |
| 490 |
\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR sets an argument, respectively a pointer to a |
| 491 |
structure containing arguments, optionally to be used by the transfer callback. |
| 492 |
\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not |
| 493 |
needed any more. \fIarg\fR may be NULL to clear the entry. |
| 494 |
.PP |
| 495 |
\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR gets the argument, respectively the pointer |
| 496 |
to a structure containing arguments, previously set by |
| 497 |
\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR or NULL if unset. |
| 498 |
.PP |
| 499 |
\&\fBOSSL_CMP_CTX_set1_srvCert()\fR sets the expected server cert in \fIctx\fR and trusts |
| 500 |
it directly (even if it is expired) when verifying signed response messages. |
| 501 |
This pins the accepted CMP server |
| 502 |
and results in ignoring whatever may be set using \fBOSSL_CMP_CTX_set0_trusted()\fR. |
| 503 |
Any previously set value is freed. |
| 504 |
The \fIcert\fR argument may be NULL to clear the entry. |
| 505 |
If set, the subject of the certificate is also used |
| 506 |
as default value for the recipient of CMP requests |
| 507 |
and as default value for the expected sender of CMP responses. |
| 508 |
.PP |
| 509 |
\&\fBOSSL_CMP_CTX_set1_expected_sender()\fR sets the Distinguished Name (DN) |
| 510 |
expected in the sender field of incoming CMP messages. |
| 511 |
Defaults to the subject of the pinned server certificate, if any. |
| 512 |
This can be used to make sure that only a particular entity is accepted as |
| 513 |
CMP message signer, and attackers are not able to use arbitrary certificates |
| 514 |
of a trusted PKI hierarchy to fraudulently pose as CMP server. |
| 515 |
Note that this gives slightly more freedom than \fBOSSL_CMP_CTX_set1_srvCert()\fR, |
| 516 |
which pins the server to the holder of a particular certificate, while the |
| 517 |
expected sender name will continue to match after updates of the server cert. |
| 518 |
.PP |
| 519 |
\&\fBOSSL_CMP_CTX_set0_trusted()\fR is an alias of the original |
| 520 |
\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR. |
| 521 |
It sets in the CMP context \fIctx\fR the certificate store of type X509_STORE |
| 522 |
containing trusted certificates, typically of root CAs. |
| 523 |
This is ignored when a certificate is pinned using \fBOSSL_CMP_CTX_set1_srvCert()\fR. |
| 524 |
The store may also hold CRLs and a certificate verification callback function |
| 525 |
used for signature-based peer authentication. |
| 526 |
Any store entry already set before is freed. |
| 527 |
When given a NULL parameter the entry is cleared. |
| 528 |
.PP |
| 529 |
\&\fBOSSL_CMP_CTX_get0_trusted()\fR is an alias of the original |
| 530 |
\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR. |
| 531 |
It extracts from the CMP context \fIctx\fR the pointer to the currently set |
| 532 |
certificate store containing trust anchors etc., or an empty store if unset. |
| 533 |
.PP |
| 534 |
\&\fBOSSL_CMP_CTX_set1_untrusted()\fR sets up a list of non-trusted certificates |
| 535 |
of intermediate CAs that may be useful for path construction for the own CMP |
| 536 |
signer certificate, for the own TLS certificate (if any), when verifying peer |
| 537 |
CMP protection certificates, and when verifying newly enrolled certificates. |
| 538 |
The reference counts of those certificates handled successfully are increased. |
| 539 |
This list of untrusted certificates in \fIctx\fR will get augmented by extraCerts |
| 540 |
in received CMP messages unless \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR is set. |
| 541 |
.PP |
| 542 |
\&\fBOSSL_CMP_CTX_get0_untrusted()\fR returns a pointer to the |
| 543 |
list of untrusted certs in \fIctx\fR, which may be empty if unset. |
| 544 |
.PP |
| 545 |
\&\fBOSSL_CMP_CTX_set1_cert()\fR sets the CMP \fIsigner certificate\fR, |
| 546 |
also called \fIprotection certificate\fR, |
| 547 |
related to the private key used for signature-based CMP message protection. |
| 548 |
Therefore the public key of this \fIcert\fR must correspond to |
| 549 |
the private key set before or thereafter via \fBOSSL_CMP_CTX_set1_pkey()\fR. |
| 550 |
When using signature-based protection of CMP request messages |
| 551 |
this CMP signer certificate will be included first in the extraCerts field. |
| 552 |
It serves as fallback reference certificate, see \fBOSSL_CMP_CTX_set1_oldCert()\fR. |
| 553 |
The subject of this \fIcert\fR will be used as the sender field of outgoing |
| 554 |
messages, while the subject of any cert set via \fBOSSL_CMP_CTX_set1_oldCert()\fR, |
| 555 |
the subject of any PKCS#10 CSR set via \fBOSSL_CMP_CTX_set1_p10CSR()\fR, |
| 556 |
and any value set via \fBOSSL_CMP_CTX_set1_subjectName()\fR are used as fallback. |
| 557 |
.PP |
| 558 |
The \fIcert\fR argument may be NULL to clear the entry. |
| 559 |
.PP |
| 560 |
\&\fBOSSL_CMP_CTX_build_cert_chain()\fR builds a certificate chain for the CMP signer |
| 561 |
certificate previously set in the \fIctx\fR. It adds the optional \fIcandidates\fR, |
| 562 |
a list of intermediate CA certs that may already constitute the targeted chain, |
| 563 |
to the untrusted certs that may already exist in the \fIctx\fR. |
| 564 |
Then the function uses this augmented set of certs for chain construction. |
| 565 |
If \fIown_trusted\fR is NULL it builds the chain as far down as possible and |
| 566 |
ignores any verification errors. Else the CMP signer certificate must be |
| 567 |
verifiable where the chain reaches a trust anchor contained in \fIown_trusted\fR. |
| 568 |
On success the function stores the resulting chain in \fIctx\fR |
| 569 |
for inclusion in the extraCerts field of signature-protected messages. |
| 570 |
Calling this function is optional; by default a chain construction |
| 571 |
is performed on demand that is equivalent to calling this function |
| 572 |
with the \fIcandidates\fR and \fIown_trusted\fR arguments being NULL. |
| 573 |
.PP |
| 574 |
\&\fBOSSL_CMP_CTX_set1_pkey()\fR sets the client's private key corresponding to the |
| 575 |
CMP signer certificate set via \fBOSSL_CMP_CTX_set1_cert()\fR. |
| 576 |
This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG) |
| 577 |
of outgoing messages |
| 578 |
unless a symmetric secret has been set via \fBOSSL_CMP_CTX_set1_secretValue()\fR. |
| 579 |
The \fIpkey\fR argument may be NULL to clear the entry. |
| 580 |
.PP |
| 581 |
\&\fBOSSL_CMP_CTX_set1_secretValue()\fR sets in \fIctx\fR the byte string \fIsec\fR of length |
| 582 |
\&\fIlen\fR to use as pre-shared secret, or clears it if the \fIsec\fR argument is NULL. |
| 583 |
If present, this secret is used to create MAC-based authentication and integrity |
| 584 |
protection (rather than applying signature-based protection) |
| 585 |
of outgoing messages and to verify authenticity and integrity of incoming |
| 586 |
messages that have MAC-based protection (protectionAlg = \f(CW\*(C`MSG_MAC_ALG\*(C'\fR). |
| 587 |
.PP |
| 588 |
\&\fBOSSL_CMP_CTX_set1_referenceValue()\fR sets the given referenceValue \fIref\fR with |
| 589 |
length \fIlen\fR in the given \fIctx\fR or clears it if the \fIref\fR argument is NULL. |
| 590 |
According to RFC 9810 section 5.1.1, if no value for the sender field in |
| 591 |
CMP message headers can be determined (i.e., no CMP signer certificate |
| 592 |
and no subject DN is set via \fBOSSL_CMP_CTX_set1_subjectName()\fR |
| 593 |
then the sender field will contain the NULL-DN |
| 594 |
and the senderKID field of the CMP message header must be set. |
| 595 |
When signature-based protection is used the senderKID will be set to |
| 596 |
the subjectKeyIdentifier of the CMP signer certificate as far as present. |
| 597 |
If not present or when MAC-based protection is used |
| 598 |
the \fIref\fR value is taken as the fallback value for the senderKID. |
| 599 |
.PP |
| 600 |
\&\fBOSSL_CMP_CTX_set1_recipient()\fR sets the recipient name that will be used in the |
| 601 |
PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server. |
| 602 |
.PP |
| 603 |
The recipient field in the header of a CMP message is mandatory. |
| 604 |
If not given explicitly the recipient is determined in the following order: |
| 605 |
the subject of the CMP server certificate set using \fBOSSL_CMP_CTX_set1_srvCert()\fR, |
| 606 |
the value set using \fBOSSL_CMP_CTX_set1_issuer()\fR, |
| 607 |
the issuer of the certificate set using \fBOSSL_CMP_CTX_set1_oldCert()\fR, |
| 608 |
the issuer of the CMP signer certificate, |
| 609 |
as far as any of those is present, else the NULL-DN as last resort. |
| 610 |
.PP |
| 611 |
\&\fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR to be |
| 612 |
added to the generalInfo field of the CMP PKIMessage header of a request |
| 613 |
message sent with this context. |
| 614 |
.PP |
| 615 |
\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR |
| 616 |
clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR. |
| 617 |
.PP |
| 618 |
\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR returns the list of ITAVs set in \fIctx\fR |
| 619 |
for inclusion in the generalInfo field of the CMP PKIMessage header of requests |
| 620 |
or NULL if not set. |
| 621 |
.PP |
| 622 |
\&\fBOSSL_CMP_CTX_set1_extraCertsOut()\fR sets the stack of extraCerts that will be |
| 623 |
sent to remote. |
| 624 |
.PP |
| 625 |
\&\fBOSSL_CMP_CTX_set0_newPkey()\fR can be used to explicitly set the given EVP_PKEY |
| 626 |
structure as the private or public key to be certified in the CMP context. |
| 627 |
The \fIpriv\fR parameter must be 0 if and only if the given key is a public key. |
| 628 |
.PP |
| 629 |
\&\fBOSSL_CMP_CTX_get0_newPkey()\fR gives the key to use for certificate enrollment |
| 630 |
dependent on fields of the CMP context structure: |
| 631 |
the newPkey (which may be a private or public key) if present, |
| 632 |
else the public key in the p10CSR if present, else the client's private key. |
| 633 |
If the \fIpriv\fR parameter is not 0 and the selected key does not have a |
| 634 |
private component then NULL is returned. |
| 635 |
.PP |
| 636 |
\&\fBOSSL_CMP_CTX_set1_issuer()\fR sets the name of the intended issuer that |
| 637 |
will be set in the CertTemplate, i.e., the X509 name of the CA server. |
| 638 |
.PP |
| 639 |
\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR sets the serial number optionally used to |
| 640 |
select the certificate to be revoked in Revocation Requests (RR). |
| 641 |
.PP |
| 642 |
\&\fBOSSL_CMP_CTX_set1_subjectName()\fR sets the subject DN that will be used in |
| 643 |
the CertTemplate structure when requesting a new cert. For Key Update Requests |
| 644 |
(KUR), it defaults to the subject DN of the reference certificate, |
| 645 |
see \fBOSSL_CMP_CTX_set1_oldCert()\fR. This default is used for Initialization |
| 646 |
Requests (IR) and Certification Requests (CR) only if no SANs are set. |
| 647 |
The \fIsubjectName\fR is also used as fallback for the sender field |
| 648 |
of outgoing CMP messages if no reference certificate is available. |
| 649 |
.PP |
| 650 |
\&\fBOSSL_CMP_CTX_push1_subjectAltName()\fR adds the given X509 name to the list of |
| 651 |
alternate names on the certificate template request. This cannot be used if |
| 652 |
any Subject Alternative Name extension is set via |
| 653 |
\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR. |
| 654 |
By default, unless \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR has been set, |
| 655 |
the Subject Alternative Names are copied from the reference certificate, |
| 656 |
see \fBOSSL_CMP_CTX_set1_oldCert()\fR. |
| 657 |
If set and the subject DN is not set with \fBOSSL_CMP_CTX_set1_subjectName()\fR then |
| 658 |
the certificate template of an IR and CR will not be filled with the default |
| 659 |
subject DN from the reference certificate. |
| 660 |
If a subject DN is desired it needs to be set explicitly with |
| 661 |
\&\fBOSSL_CMP_CTX_set1_subjectName()\fR. |
| 662 |
.PP |
| 663 |
\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR sets the X.509v3 extensions to be used in |
| 664 |
IR/CR/KUR. |
| 665 |
.PP |
| 666 |
\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR returns 1 if the context contains |
| 667 |
a Subject Alternative Name extension, else 0 or \-1 on error. |
| 668 |
.PP |
| 669 |
\&\fBOSSL_CMP_CTX_push0_policy()\fR adds the certificate policy info object |
| 670 |
to the X509_EXTENSIONS of the requested certificate template. |
| 671 |
.PP |
| 672 |
\&\fBOSSL_CMP_CTX_set1_oldCert()\fR sets the old certificate to be updated in |
| 673 |
Key Update Requests (KUR) or to be revoked in Revocation Requests (RR). |
| 674 |
For RR, this is ignored if an issuer name and a serial number are provided using |
| 675 |
\&\fBOSSL_CMP_CTX_set1_issuer()\fR and \fBOSSL_CMP_CTX_set1_serialNumber()\fR, respectively. |
| 676 |
For IR/CR/KUR this sets the \fIreference certificate\fR, |
| 677 |
which otherwise defaults to the CMP signer certificate. |
| 678 |
The \fIreference certificate\fR determined this way, if any, is used for providing |
| 679 |
default public key, subject DN, Subject Alternative Names, and issuer DN entries |
| 680 |
in the requested certificate template of IR/CR/KUR messages. |
| 681 |
.PP |
| 682 |
The subject of the reference certificate is used as the sender field value |
| 683 |
in CMP message headers. |
| 684 |
Its issuer is used as default recipient in CMP message headers. |
| 685 |
.PP |
| 686 |
\&\fBOSSL_CMP_CTX_set1_p10CSR()\fR sets the PKCS#10 CSR to use in P10CR messages. |
| 687 |
If such a CSR is provided, its subject and public key fields are also |
| 688 |
used as fallback values for the certificate template of IR/CR/KUR/RR messages, |
| 689 |
and any extensions included are added to the template of IR/CR/KUR messages. |
| 690 |
.PP |
| 691 |
\&\fBOSSL_CMP_CTX_push0_genm_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR which |
| 692 |
will be the body of a General Message sent with this context. |
| 693 |
.PP |
| 694 |
\&\fBOSSL_CMP_certConf_cb()\fR is the default certificate confirmation callback function. |
| 695 |
If the callback argument is not NULL it must point to a trust store. |
| 696 |
In this case the function checks that the newly enrolled certificate can be |
| 697 |
verified using this trust store and untrusted certificates from the \fIctx\fR, |
| 698 |
which have been augmented by the list of extraCerts received. |
| 699 |
During this verification, any certificate status checking is disabled. |
| 700 |
If the callback argument is NULL the function tries building an approximate |
| 701 |
chain as far as possible using the same untrusted certificates from the \fIctx\fR, |
| 702 |
and if this fails it takes the received extraCerts as fallback. |
| 703 |
The resulting cert chain can be retrieved using \fBOSSL_CMP_CTX_get1_newChain()\fR. |
| 704 |
This chain excludes the leaf certificate, i.e., the newly enrolled certificate. |
| 705 |
Also the trust anchor (the root certificate) is not included. |
| 706 |
.PP |
| 707 |
\&\fBOSSL_CMP_CTX_set_certConf_cb()\fR sets the callback used for evaluating the newly |
| 708 |
enrolled certificate before the library sends, depending on its result, |
| 709 |
a positive or negative certConf message to the server. The callback has type |
| 710 |
.PP |
| 711 |
.Vb 2 |
| 712 |
\& typedef int (*OSSL_CMP_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert, |
| 713 |
\& int fail_info, const char **txt); |
| 714 |
.Ve |
| 715 |
.PP |
| 716 |
and should inspect the certificate it obtains via the \fIcert\fR parameter and may |
| 717 |
overrule the pre-decision given in the \fIfail_info\fR and \fI*txt\fR parameters. |
| 718 |
If it accepts the certificate it must return 0, indicating success. Else it must |
| 719 |
return a bit field reflecting PKIFailureInfo with at least one failure bit and |
| 720 |
may set the \fI*txt\fR output parameter to point to a string constant with more |
| 721 |
detail. The transfer callback may make use of a custom defined argument stored |
| 722 |
in the \fIctx\fR by means of \fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, which may be |
| 723 |
retrieved again through \fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR. |
| 724 |
Typically, the callback will check at least that the certificate can be verified |
| 725 |
using a set of trusted certificates. |
| 726 |
It also could compare the subject DN and other fields of the newly |
| 727 |
enrolled certificate with the certificate template of the request. |
| 728 |
.PP |
| 729 |
\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR sets an argument, respectively a pointer to a |
| 730 |
structure containing arguments, optionally to be used by the certConf callback. |
| 731 |
\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not |
| 732 |
needed any more. \fIarg\fR may be NULL to clear the entry. |
| 733 |
.PP |
| 734 |
\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR gets the argument, respectively the pointer |
| 735 |
to a structure containing arguments, previously set by |
| 736 |
\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, or NULL if unset. |
| 737 |
.PP |
| 738 |
\&\fBOSSL_CMP_CTX_get_status()\fR returns for client contexts the PKIstatus from |
| 739 |
the last received CertRepMessage or Revocation Response or error message: |
| 740 |
=item \fBOSSL_CMP_PKISTATUS_accepted\fR on successful receipt of a GENP message: |
| 741 |
.IP \fBOSSL_CMP_PKISTATUS_request\fR 4 |
| 742 |
.IX Item "OSSL_CMP_PKISTATUS_request" |
| 743 |
if an IR/CR/KUR/RR/GENM request message could not be produced, |
| 744 |
.IP \fBOSSL_CMP_PKISTATUS_trans\fR 4 |
| 745 |
.IX Item "OSSL_CMP_PKISTATUS_trans" |
| 746 |
on a transmission error or transaction error for this type of request, and |
| 747 |
.IP \fBOSSL_CMP_PKISTATUS_unspecified\fR 4 |
| 748 |
.IX Item "OSSL_CMP_PKISTATUS_unspecified" |
| 749 |
if no such request was attempted or \fBOSSL_CMP_CTX_reinit()\fR has been called. |
| 750 |
.PP |
| 751 |
For server contexts it returns |
| 752 |
\&\fBOSSL_CMP_PKISTATUS_trans\fR if a transaction is open, |
| 753 |
otherwise \fBOSSL_CMP_PKISTATUS_unspecified\fR. |
| 754 |
.PP |
| 755 |
\&\fBOSSL_CMP_CTX_get0_statusString()\fR returns the statusString from the last received |
| 756 |
CertRepMessage or Revocation Response or error message, or NULL if unset. |
| 757 |
.PP |
| 758 |
\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR returns the error code from the failInfo field |
| 759 |
of the last received CertRepMessage or Revocation Response or error message, |
| 760 |
or \-1 if no such response was received or \fBOSSL_CMP_CTX_reinit()\fR has been called. |
| 761 |
This is a bit field and the flags for it are specified in the header file |
| 762 |
\&\fI<openssl/cmp.h>\fR. |
| 763 |
The flags start with OSSL_CMP_CTX_FAILINFO, for example: |
| 764 |
OSSL_CMP_CTX_FAILINFO_badAlg. Returns \-1 if the failInfoCode field is unset. |
| 765 |
.PP |
| 766 |
\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR returns |
| 767 |
the successfully validated certificate, if any, that the CMP server used |
| 768 |
in the current transaction for signature-based response message protection, |
| 769 |
or NULL if the server used MAC-based protection. |
| 770 |
The value is relevant only at the end of a successful transaction. |
| 771 |
It may be used to check the authorization of the server based on its cert. |
| 772 |
.PP |
| 773 |
\&\fBOSSL_CMP_CTX_get0_newCert()\fR returns the pointer to the newly obtained |
| 774 |
certificate in case it is available, else NULL. |
| 775 |
.PP |
| 776 |
\&\fBOSSL_CMP_CTX_get1_newChain()\fR returns a pointer to a duplicate of the stack of |
| 777 |
X.509 certificates computed by \fBOSSL_CMP_certConf_cb()\fR (if this function has |
| 778 |
been called) on the last received certificate response message IP/CP/KUP. |
| 779 |
.PP |
| 780 |
\&\fBOSSL_CMP_CTX_get1_caPubs()\fR returns a pointer to a duplicate of the list of |
| 781 |
X.509 certificates in the caPubs field of the last received certificate |
| 782 |
response message (of type IP, CP, or KUP), |
| 783 |
or an empty stack if no caPubs have been received in the current transaction. |
| 784 |
.PP |
| 785 |
\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR returns a pointer to a duplicate of the list |
| 786 |
of X.509 certificates contained in the extraCerts field of the last received |
| 787 |
response message (except for pollRep and PKIConf), or |
| 788 |
an empty stack if no extraCerts have been received in the current transaction. |
| 789 |
.PP |
| 790 |
\&\fBOSSL_CMP_CTX_set1_transactionID()\fR sets the given transaction ID in the given |
| 791 |
OSSL_CMP_CTX structure. |
| 792 |
.PP |
| 793 |
\&\fBOSSL_CMP_CTX_set1_senderNonce()\fR stores the last sent sender \fInonce\fR in |
| 794 |
the \fIctx\fR. This will be used to validate the recipNonce in incoming messages. |
| 795 |
.SH NOTES |
| 796 |
.IX Header "NOTES" |
| 797 |
CMP is defined in RFC 9810 (and CRMF in RFC 4211). |
| 798 |
.SH "RETURN VALUES" |
| 799 |
.IX Header "RETURN VALUES" |
| 800 |
\&\fBOSSL_CMP_CTX_free()\fR and \fBOSSL_CMP_CTX_print_errors()\fR do not return anything. |
| 801 |
.PP |
| 802 |
\&\fBOSSL_CMP_CTX_new()\fR, |
| 803 |
\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, |
| 804 |
\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR, |
| 805 |
\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR, |
| 806 |
\&\fBOSSL_CMP_CTX_get0_trusted()\fR, |
| 807 |
\&\fBOSSL_CMP_CTX_get0_untrusted()\fR, |
| 808 |
\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR, |
| 809 |
\&\fBOSSL_CMP_CTX_get0_newPkey()\fR, |
| 810 |
\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR, |
| 811 |
\&\fBOSSL_CMP_CTX_get0_statusString()\fR, |
| 812 |
\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR, |
| 813 |
\&\fBOSSL_CMP_CTX_get0_newCert()\fR, |
| 814 |
\&\fBOSSL_CMP_CTX_get0_newChain()\fR, |
| 815 |
\&\fBOSSL_CMP_CTX_get1_caPubs()\fR, and |
| 816 |
\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR |
| 817 |
return the intended pointer value as described above or NULL on error. |
| 818 |
.PP |
| 819 |
\&\fBOSSL_CMP_CTX_get_option()\fR, |
| 820 |
\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR, |
| 821 |
\&\fBOSSL_CMP_CTX_get_status()\fR, and |
| 822 |
\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR |
| 823 |
return the intended value as described above or \-1 on error. |
| 824 |
.PP |
| 825 |
\&\fBOSSL_CMP_certConf_cb()\fR returns \fIfail_info\fR if it is not equal to 0, |
| 826 |
else 0 on successful validation, |
| 827 |
or else a bit field with the \fBOSSL_CMP_PKIFAILUREINFO_incorrectData\fR bit set. |
| 828 |
.PP |
| 829 |
All other functions, including \fBOSSL_CMP_CTX_reinit()\fR |
| 830 |
and \fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR, |
| 831 |
return 1 on success, 0 on error. |
| 832 |
.SH EXAMPLES |
| 833 |
.IX Header "EXAMPLES" |
| 834 |
The following code omits error handling. |
| 835 |
.PP |
| 836 |
Set up a CMP client context for sending requests and verifying responses: |
| 837 |
.PP |
| 838 |
.Vb 5 |
| 839 |
\& cmp_ctx = OSSL_CMP_CTX_new(); |
| 840 |
\& OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address); |
| 841 |
\& OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string); |
| 842 |
\& OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias); |
| 843 |
\& OSSL_CMP_CTX_set0_trusted(cmp_ctx, ts); |
| 844 |
.Ve |
| 845 |
.PP |
| 846 |
Set up symmetric credentials for MAC-based message protection such as PBM: |
| 847 |
.PP |
| 848 |
.Vb 2 |
| 849 |
\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); |
| 850 |
\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); |
| 851 |
.Ve |
| 852 |
.PP |
| 853 |
Set up the details for certificate requests: |
| 854 |
.PP |
| 855 |
.Vb 2 |
| 856 |
\& OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name); |
| 857 |
\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey); |
| 858 |
.Ve |
| 859 |
.PP |
| 860 |
Perform an Initialization Request transaction: |
| 861 |
.PP |
| 862 |
.Vb 1 |
| 863 |
\& initialCert = OSSL_CMP_exec_IR_ses(cmp_ctx); |
| 864 |
.Ve |
| 865 |
.PP |
| 866 |
Reset the transaction state of the CMP context and the credentials: |
| 867 |
.PP |
| 868 |
.Vb 3 |
| 869 |
\& OSSL_CMP_CTX_reinit(cmp_ctx); |
| 870 |
\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, NULL, 0); |
| 871 |
\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, NULL, 0); |
| 872 |
.Ve |
| 873 |
.PP |
| 874 |
Perform a Certification Request transaction, making use of the new credentials: |
| 875 |
.PP |
| 876 |
.Vb 4 |
| 877 |
\& OSSL_CMP_CTX_set1_cert(cmp_ctx, initialCert); |
| 878 |
\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, initialKey); |
| 879 |
\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, curentKey); |
| 880 |
\& currentCert = OSSL_CMP_exec_CR_ses(cmp_ctx); |
| 881 |
.Ve |
| 882 |
.PP |
| 883 |
Perform a Key Update Request, signed using the cert (and key) to be updated: |
| 884 |
.PP |
| 885 |
.Vb 6 |
| 886 |
\& OSSL_CMP_CTX_reinit(cmp_ctx); |
| 887 |
\& OSSL_CMP_CTX_set1_cert(cmp_ctx, currentCert); |
| 888 |
\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, currentKey); |
| 889 |
\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, updatedKey); |
| 890 |
\& currentCert = OSSL_CMP_exec_KUR_ses(cmp_ctx); |
| 891 |
\& currentKey = updatedKey; |
| 892 |
.Ve |
| 893 |
.PP |
| 894 |
Perform a General Message transaction including, as an example, |
| 895 |
the id-it-signKeyPairTypes OID and prints info on the General Response contents: |
| 896 |
.PP |
| 897 |
.Vb 1 |
| 898 |
\& OSSL_CMP_CTX_reinit(cmp_ctx); |
| 899 |
\& |
| 900 |
\& ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1); |
| 901 |
\& OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, NULL); |
| 902 |
\& OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav); |
| 903 |
\& |
| 904 |
\& STACK_OF(OSSL_CMP_ITAV) *itavs; |
| 905 |
\& itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx); |
| 906 |
\& print_itavs(itavs); |
| 907 |
\& sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free); |
| 908 |
.Ve |
| 909 |
.SH "SEE ALSO" |
| 910 |
.IX Header "SEE ALSO" |
| 911 |
\&\fBOSSL_CMP_exec_IR_ses\fR\|(3), \fBOSSL_CMP_exec_CR_ses\fR\|(3), |
| 912 |
\&\fBOSSL_CMP_exec_KUR_ses\fR\|(3), \fBOSSL_CMP_exec_GENM_ses\fR\|(3), |
| 913 |
\&\fBOSSL_CMP_exec_certreq\fR\|(3), \fBOSSL_CMP_MSG_http_perform\fR\|(3), |
| 914 |
\&\fBERR_print_errors_cb\fR\|(3), \fBOSSL_HTTP_open\fR\|(3) |
| 915 |
.SH HISTORY |
| 916 |
.IX Header "HISTORY" |
| 917 |
The OpenSSL CMP functions were added in OpenSSL 3.0. |
| 918 |
.PP |
| 919 |
\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_get0_trusted()\fR and |
| 920 |
\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_set0_trusted()\fR, |
| 921 |
using macros, while keeping the old names for backward compatibility, |
| 922 |
in OpenSSL 3.2. |
| 923 |
.PP |
| 924 |
\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR was added in OpenSSL 3.0.8. |
| 925 |
.PP |
| 926 |
\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR, |
| 927 |
\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, and |
| 928 |
\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR were added in OpenSSL 3.2. |
| 929 |
.PP |
| 930 |
\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR and |
| 931 |
the \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR option were added in OpenSSL 3.3. |
| 932 |
.PP |
| 933 |
Support for central key generation, requested via \fBOSSL_CRMF_POPO_NONE\fR, |
| 934 |
was added in OpenSSL 3.5. |
| 935 |
.SH COPYRIGHT |
| 936 |
.IX Header "COPYRIGHT" |
| 937 |
Copyright 2007\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 938 |
.PP |
| 939 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 940 |
this file except in compliance with the License. You can obtain a copy |
| 941 |
in the file LICENSE in the source distribution or at |
| 942 |
<https://www.openssl.org/source/license.html>. |