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