]>
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, | |
8 | OSSL_CMP_CTX_set_option, | |
9 | OSSL_CMP_CTX_get_option, | |
10 | OSSL_CMP_CTX_set_log_cb, | |
11 | OSSL_CMP_CTX_set_log_verbosity, | |
12 | OSSL_CMP_CTX_print_errors, | |
13 | OSSL_CMP_CTX_set1_serverPath, | |
14 | OSSL_CMP_CTX_set1_serverName, | |
15 | OSSL_CMP_CTX_set_serverPort, | |
16 | OSSL_CMP_CTX_set1_proxyName, | |
17 | OSSL_CMP_CTX_set_proxyPort, | |
18 | OSSL_CMP_DEFAULT_PORT, | |
19 | OSSL_CMP_CTX_set_http_cb, | |
20 | OSSL_CMP_CTX_set_http_cb_arg, | |
21 | OSSL_CMP_CTX_get_http_cb_arg, | |
22 | OSSL_CMP_CTX_set_transfer_cb, | |
23 | OSSL_CMP_CTX_set_transfer_cb_arg, | |
24 | OSSL_CMP_CTX_get_transfer_cb_arg, | |
25 | OSSL_CMP_CTX_set1_srvCert, | |
26 | OSSL_CMP_CTX_set1_expected_sender, | |
27 | OSSL_CMP_CTX_set0_trustedStore, | |
28 | OSSL_CMP_CTX_get0_trustedStore, | |
29 | OSSL_CMP_CTX_set1_untrusted_certs, | |
30 | OSSL_CMP_CTX_get0_untrusted_certs, | |
31 | OSSL_CMP_CTX_set1_clCert, | |
32 | OSSL_CMP_CTX_set1_pkey, | |
33 | OSSL_CMP_CTX_set1_referenceValue, | |
34 | OSSL_CMP_CTX_set1_secretValue, | |
35 | OSSL_CMP_CTX_set1_recipient, | |
36 | OSSL_CMP_CTX_push0_geninfo_ITAV, | |
37 | OSSL_CMP_CTX_set1_extraCertsOut, | |
38 | OSSL_CMP_CTX_set0_newPkey, | |
39 | OSSL_CMP_CTX_get0_newPkey, | |
40 | OSSL_CMP_CTX_set1_issuer, | |
41 | OSSL_CMP_CTX_set1_subjectName, | |
42 | OSSL_CMP_CTX_push1_subjectAltName, | |
43 | OSSL_CMP_CTX_set0_reqExtensions, | |
44 | OSSL_CMP_CTX_reqExtensions_have_SAN, | |
45 | OSSL_CMP_CTX_push0_policy, | |
46 | OSSL_CMP_CTX_set1_oldCert, | |
47 | OSSL_CMP_CTX_set1_p10CSR, | |
48 | OSSL_CMP_CTX_push0_genm_ITAV, | |
49 | OSSL_CMP_CTX_set_certConf_cb, | |
50 | OSSL_CMP_CTX_set_certConf_cb_arg, | |
51 | OSSL_CMP_CTX_get_certConf_cb_arg, | |
52 | OSSL_CMP_CTX_get_status, | |
53 | OSSL_CMP_CTX_get0_statusString, | |
54 | OSSL_CMP_CTX_get_failInfoCode, | |
55 | OSSL_CMP_CTX_get0_newCert, | |
56 | OSSL_CMP_CTX_get1_caPubs, | |
57 | OSSL_CMP_CTX_get1_extraCertsIn, | |
58 | OSSL_CMP_CTX_set1_transactionID, | |
59 | OSSL_CMP_CTX_set1_senderNonce | |
60 | - functions for managing the CMP client context data structure | |
61 | ||
62 | =head1 SYNOPSIS | |
63 | ||
64 | #include <openssl/cmp.h> | |
65 | ||
66 | OSSL_CMP_CTX *OSSL_CMP_CTX_new(void); | |
67 | void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx); | |
68 | int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx); | |
69 | int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val); | |
70 | int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt); | |
71 | ||
72 | /* logging and error reporting: */ | |
73 | int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_log_cb_t cb); | |
74 | #define OSSL_CMP_CTX_set_log_verbosity(ctx, level) | |
75 | void OSSL_CMP_CTX_print_errors(OSSL_CMP_CTX *ctx); | |
76 | ||
77 | /* message transfer: */ | |
78 | int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path); | |
79 | int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name); | |
80 | int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port); | |
81 | int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name); | |
82 | int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port); | |
83 | #define OSSL_CMP_DEFAULT_PORT 80 | |
84 | typedef BIO (*OSSL_cmp_http_cb_t) (OSSL_CMP_CTX *ctx, BIO *hbio, | |
85 | unsigned long detail); | |
86 | int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_http_cb_t cb); | |
87 | int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg); | |
88 | void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx); | |
89 | typedef int (*OSSL_cmp_transfer_cb_t) (OSSL_CMP_CTX *ctx, | |
90 | const OSSL_CMP_MSG *req, | |
91 | OSSL_CMP_MSG **res); | |
92 | int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx, | |
93 | OSSL_cmp_transfer_cb_t cb); | |
94 | int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg); | |
95 | void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx); | |
96 | ||
97 | /* server authentication: */ | |
98 | int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert); | |
99 | int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx, | |
100 | const X509_NAME *name); | |
101 | int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store); | |
102 | X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx); | |
103 | int OSSL_CMP_CTX_set1_untrusted_certs(OSSL_CMP_CTX *ctx, | |
104 | STACK_OF(X509) *certs); | |
105 | STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted_certs(const OSSL_CMP_CTX *ctx); | |
106 | ||
107 | /* client authentication: */ | |
108 | int OSSL_CMP_CTX_set1_clCert(OSSL_CMP_CTX *ctx, X509 *cert); | |
109 | int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey); | |
110 | int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx, | |
111 | const unsigned char *ref, int len); | |
112 | int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, const unsigned char *sec, | |
113 | const int len); | |
114 | ||
115 | /* CMP message header and extra certificates: */ | |
116 | int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name); | |
117 | int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); | |
118 | int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx, | |
119 | STACK_OF(X509) *extraCertsOut); | |
120 | ||
121 | /* certificate template: */ | |
122 | int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey); | |
123 | EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv); | |
124 | int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name); | |
125 | int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name); | |
126 | int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx, | |
127 | const GENERAL_NAME *name); | |
128 | int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts); | |
129 | int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx); | |
130 | int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo); | |
131 | int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert); | |
132 | int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr); | |
133 | ||
134 | /* misc body contents: */ | |
135 | int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); | |
136 | ||
137 | /* certificate confirmation: */ | |
138 | typedef int (*OSSL_cmp_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert, | |
139 | int fail_info, const char **txt); | |
140 | int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_certConf_cb_t cb); | |
141 | int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg); | |
142 | void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx); | |
143 | ||
144 | /* result fetching: */ | |
145 | int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx); | |
146 | OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx); | |
147 | int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx); | |
148 | ||
149 | X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx); | |
150 | STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx); | |
151 | STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx); | |
152 | ||
153 | /* for test purposes only: */ | |
154 | int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx, | |
155 | const ASN1_OCTET_STRING *id); | |
156 | int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx, | |
157 | const ASN1_OCTET_STRING *nonce); | |
158 | ||
159 | =head1 DESCRIPTION | |
160 | ||
161 | This is the context API for using CMP (Certificate Management Protocol) with | |
162 | OpenSSL. | |
163 | ||
164 | OSSL_CMP_CTX_new() allocates and initializes an OSSL_CMP_CTX structure to | |
165 | default values, e.g., proof-of-possession method is set to POPOSigningKey. | |
166 | ||
167 | OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure. | |
168 | ||
169 | OSSL_CMP_CTX_reinit() prepares the given B<ctx> for a further transaction by | |
170 | clearing the internal CMP transaction (aka session) status, PKIStatusInfo, | |
171 | and any previous results (newCert, caPubs, and extraCertsIn) | |
172 | from the last executed transaction. | |
173 | All other field values (i.e., CMP options) are retained for potential re-use. | |
174 | ||
175 | OSSL_CMP_CTX_set_option() sets the given value for the given option | |
176 | (e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) in the given OSSL_CMP_CTX structure. | |
177 | ||
178 | The following options can be set: | |
179 | ||
180 | =over 4 | |
181 | ||
182 | =item B<OSSL_CMP_OPT_LOG_VERBOSITY> | |
183 | ||
184 | The level of severity needed for actually outputting log messages | |
185 | due to errors, warnings, general info, debugging, etc. | |
186 | Default is OSSL_CMP_LOG_INFO. See also L<OSSL_CMP_log_open(3)>. | |
187 | ||
188 | =item B<OSSL_CMP_OPT_MSGTIMEOUT> | |
189 | ||
190 | Number of seconds (or 0 for infinite) a CMP message round trip is | |
191 | allowed to take before a timeout error is returned. Default is 120. | |
192 | ||
193 | =item B<OSSL_CMP_OPT_TOTALTIMEOUT> | |
194 | ||
195 | Maximum total number of seconds an enrollment (including polling) | |
196 | may take. Default is 0 (infinite). | |
197 | ||
198 | =item B<OSSL_CMP_OPT_VALIDITYDAYS> | |
199 | ||
200 | Number of days new certificates are asked to be valid for. | |
201 | ||
202 | =item B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT> | |
203 | ||
204 | Do not take default Subject Alternative Names | |
205 | from the reference certificate. | |
206 | ||
207 | =item B<OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL> | |
208 | ||
209 | Demand that the given Subject Alternative Names are flagged as critical. | |
210 | ||
211 | =item B<OSSL_CMP_OPT_POLICIES_CRITICAL> | |
212 | ||
213 | Demand that the given policies are flagged as critical. | |
214 | ||
215 | =item B<OSSL_CMP_OPT_POPOMETHOD> | |
216 | ||
217 | Select the proof of possession method to use. Possible values are: | |
218 | ||
219 | OSSL_CRMF_POPO_NONE - ProofOfPossession field omitted | |
220 | OSSL_CRMF_POPO_RAVERIFIED - assert that the RA has already | |
221 | verified the PoPo | |
222 | OSSL_CRMF_POPO_SIGNATURE - sign a value with private key, | |
223 | which is the default. | |
224 | OSSL_CRMF_POPO_KEYENC - decrypt the encrypted certificate | |
225 | ("indirect method") | |
226 | ||
227 | Note that a signature-based POPO can only be produced if a private key | |
228 | is provided as the newPkey or client pkey component of the CMP context. | |
229 | ||
230 | =item B<OSSL_CMP_OPT_DIGEST_ALGNID> | |
231 | ||
232 | The digest algorithm NID to be used in RFC 4210's MSG_SIG_ALG, | |
233 | if applicable used for message protection and Proof-of-Possession. | |
234 | Default is SHA256. | |
235 | ||
236 | OSSL_CMP_OPT_OWF_ALGNID | |
237 | The digest algorithm NID to be used as one-way function (OWF) | |
238 | in RFC 4210's MSG_MAC_ALG, if applicable used for message protection. | |
239 | Default is SHA256. | |
240 | ||
241 | OSSL_CMP_OPT_MAC_ALGNID | |
242 | The MAC algorithm NID to be used in RFC 4210's MSG_MAC_ALG, | |
243 | if applicable used for message protection. | |
244 | Default is HMAC-SHA1 as per RFC 4210. | |
245 | ||
246 | =item B<OSSL_CMP_OPT_REVOCATION_REASON> | |
247 | ||
248 | The reason code to be included in a Revocation Request (RR); | |
249 | values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default. | |
250 | ||
251 | =item B<OSSL_CMP_OPT_IMPLICITCONFIRM> | |
252 | ||
253 | Request server to enable implicit confirm mode, where the client | |
254 | does not need to send confirmation upon receiving the | |
255 | certificate. If the server does not enable implicit confirmation | |
256 | in the return message, then confirmation is sent anyway. | |
257 | ||
258 | =item B<OSSL_CMP_OPT_DISABLECONFIRM> | |
259 | ||
260 | Do not confirm enrolled certificates, to cope with broken servers | |
261 | not supporting implicit confirmation correctly. | |
262 | B<WARNING:> This setting leads to unspecified behavior and it is meant | |
263 | exclusively to allow interoperability with server implementations violating | |
264 | RFC 4210. | |
265 | ||
266 | =item B<OSSL_CMP_OPT_UNPROTECTED_SEND> | |
267 | ||
268 | Send messages without CMP-level protection. | |
269 | ||
270 | =item B<OSSL_CMP_OPT_UNPROTECTED_ERRORS> | |
271 | ||
272 | Accept unprotected error responses which are either explicitly | |
273 | unprotected or where protection verification failed. Applies to regular | |
274 | error messages as well as certificate responses (IP/CP/KUP) and | |
275 | revocation responses (RP) with rejection. | |
276 | B<WARNING:> This setting leads to unspecified behavior and it is meant | |
277 | exclusively to allow interoperability with server implementations violating | |
278 | RFC 4210. | |
279 | ||
280 | =item B<OSSL_CMP_OPT_IGNORE_KEYUSAGE> | |
281 | ||
282 | Ignore key usage restrictions in signer certificate when | |
283 | validating signature-based protection in received CMP messages. | |
284 | Else, 'digitalSignature' must be allowed by CMP signer certificates. | |
285 | ||
286 | =item B<OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR> | |
287 | ||
288 | Allow retrieving a trust anchor from extraCerts and using that | |
289 | to validate the certificate chain of an IP message. | |
290 | ||
291 | =back | |
292 | ||
293 | OSSL_CMP_CTX_get_option() reads the current value of the given option | |
294 | (e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) from the given OSSL_CMP_CTX structure. | |
295 | ||
296 | OSSL_CMP_CTX_set_log_cb() sets in B<ctx> the callback function C<cb> | |
297 | for handling error queue entries and logging messages. | |
298 | When C<cb> is NULL errors are printed to STDERR (if available, else ignored) | |
299 | any log messages are ignored. | |
300 | Alternatively, L<OSSL_CMP_log_open(3)> may be used to direct logging to STDOUT. | |
301 | ||
302 | OSSL_CMP_CTX_set_log_verbosity() is a macro setting the | |
303 | OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level. | |
304 | ||
305 | OSSL_CMP_CTX_print_errors() outputs any entries in the OpenSSL error queue. | |
306 | It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function | |
307 | if set in the C<ctx> for uniformity with CMP logging if given. Otherwise it uses | |
308 | B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined). | |
309 | ||
310 | OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host. | |
311 | ||
312 | OSSL_CMP_CTX_set1_serverName() sets the given server Address (as IP or name) | |
313 | in the given OSSL_CMP_CTX structure. | |
314 | ||
315 | OSSL_CMP_CTX_set_serverPort() sets the port of the CMP server to connect to. | |
316 | Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly. | |
317 | ||
9c0586d5 | 318 | OSSL_CMP_CTX_set1_proxyName() sets the hostname of the HTTP proxy to be used |
7960dbec DDO |
319 | for connecting to the CA server. |
320 | ||
321 | OSSL_CMP_CTX_set_proxyPort() sets the port of the HTTP proxy. | |
322 | Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly. | |
323 | ||
324 | OSSL_CMP_CTX_set_http_cb() sets the optional http connect/disconnect callback | |
325 | function, which has the prototype | |
326 | ||
327 | typedef BIO *(*OSSL_cmp_http_cb_t)(OSSL_CMP_CTX *ctx, BIO *hbio, | |
328 | unsigned long detail); | |
329 | ||
330 | It may modify the HTTP BIO given in the B<hbio> argument | |
331 | used by OSSL_CMP_MSG_http_perform(). | |
332 | On connect the B<detail> argument is 1. | |
333 | On disconnect it is 0 if no error occurred or else the last error code. | |
334 | For instance, on connect a TLS BIO may be prepended to implement HTTPS, | |
335 | and on disconnect some error diagnostics and/or cleanup may be done. | |
336 | The callback function should return NULL to indicate failure. | |
337 | It may make use of a custom defined argument stored in the ctx | |
338 | by means of OSSL_CMP_CTX_set_http_cb_arg(), | |
339 | which may be retrieved again through OSSL_CMP_CTX_get_http_cb_arg(). | |
340 | ||
341 | OSSL_CMP_CTX_set_http_cb_arg() sets an argument, respectively a pointer to | |
342 | a structure containing arguments, | |
343 | optionally to be used by the http connect/disconnect callback function. | |
344 | B<arg> is not consumed, and it must therefore explicitly be freed when not | |
345 | needed any more. B<arg> may be NULL to clear the entry. | |
346 | ||
347 | OSSL_CMP_CTX_get_http_cb_arg() gets the argument, respectively the pointer to a | |
348 | structure containing arguments, previously set by | |
349 | OSSL_CMP_CTX_set_http_cb_arg() or NULL if unset. | |
350 | ||
351 | OSSL_CMP_CTX_set_transfer_cb() sets the message transfer callback function, | |
352 | which has the type | |
353 | ||
354 | typedef int (*OSSL_cmp_transfer_cb_t)(const OSSL_CMP_CTX *ctx, | |
355 | const OSSL_CMP_MSG *req, | |
356 | OSSL_CMP_MSG **res); | |
357 | Returns 1 on success, 0 on error. | |
358 | ||
359 | Default is NULL, which implies the use of L<OSSL_CMP_MSG_http_perform(3)>. | |
360 | The callback should send the CMP request it obtains via the B<req> parameter | |
361 | and on success place the response in the B<*res> output parameter. | |
362 | The transfer callback may make use of a custom defined argument stored in | |
363 | the ctx by means of OSSL_CMP_CTX_set_transfer_cb_arg(), which may be retrieved | |
364 | again through OSSL_CMP_CTX_get_transfer_cb_arg(). | |
365 | On success the cb must return 0, else a CMP error reason code defined in cmp.h. | |
366 | ||
367 | ||
368 | OSSL_CMP_CTX_set_transfer_cb_arg() sets an argument, respectively a pointer to a | |
369 | structure containing arguments, optionally to be used by the transfer callback. | |
370 | B<arg> is not consumed, and it must therefore explicitly be freed when not | |
371 | needed any more. B<arg> may be NULL to clear the entry. | |
372 | ||
373 | OSSL_CMP_CTX_get_transfer_cb_arg() gets the argument, respectively the pointer | |
374 | to a structure containing arguments, previously set by | |
375 | OSSL_CMP_CTX_set_transfer_cb_arg() or NULL if unset. | |
376 | ||
377 | OSSL_CMP_CTX_set1_srvCert() pins the server certificate to be directly trusted | |
378 | (even if it is expired) for verifying response messages. | |
379 | The cert pointer is not consumed. It may be NULL to clear the entry. | |
380 | ||
381 | OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN) expected to | |
382 | be given in the sender response for messages protected with MSG_SIG_ALG. This | |
383 | may be used to enforce that during validation of received messages the given DN | |
384 | matches the sender field of the PKIMessage header, which in turn is used to | |
385 | identify the server certificate. | |
386 | This can be used to ensure that only a particular entity is accepted to act as | |
387 | CMP server, and attackers are not able to use arbitrary certificates of a | |
388 | trusted PKI hierarchy to fraudulently pose as server. | |
389 | This defaults to the subject DN of the certificate set via | |
390 | OSSL_CMP_CTX_set1_srvCert(), if any. | |
391 | ||
392 | OSSL_CMP_CTX_set0_trustedStore() sets the X509_STORE type certificate store | |
393 | containing trusted (root) CA certificates. The certificate store may also hold | |
394 | CRLs and a certificate verification callback function used for CMP server | |
395 | authentication. Any already existing store entry is freed. When given a NULL | |
396 | parameter the entry is cleared. | |
397 | ||
398 | OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the certificate store | |
399 | containing trusted root CA certificates, which may be empty if unset. | |
400 | ||
401 | OSSL_CMP_CTX_set1_untrusted_certs() takes over a list of certificates containing | |
402 | non-trusted intermediate certs used for path construction in authentication | |
403 | of the CMP server and potentially others (TLS server, newly enrolled cert). | |
404 | The reference counts of those certificates handled successfully are increased. | |
405 | ||
406 | OSSL_CMP_CTX_get0_untrusted_certs(OSSL_CMP_CTX *ctx) returns a pointer to the | |
407 | list of untrusted certs, which my be empty if unset. | |
408 | ||
409 | OSSL_CMP_CTX_set1_clCert() sets the client certificate in the given | |
410 | OSSL_CMP_CTX structure. The client certificate will then be used by the | |
411 | functions to set the "sender" field for outgoing messages and it will be | |
412 | included in the extraCerts field. | |
413 | ||
414 | OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the client | |
415 | certificate set with B<OSSL_CMP_CTX_set1_clCert()> in the given CMP context. | |
416 | Used to create the protection in case of MSG_SIG_ALG. | |
417 | ||
418 | OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue in the given | |
419 | B<ctx> or clears it if the B<ref> argument is NULL. | |
420 | ||
421 | OSSL_CMP_CTX_set1_secretValue() sets the B<sec> with the length B<len> in the | |
422 | given B<ctx> or clears it if the B<sec> argument is NULL. | |
423 | ||
424 | OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the | |
425 | PKIHeader of a request message, i.e. the X509 name of the (CA) server. | |
426 | Setting is overruled by subject of srvCert if set. | |
427 | If neither srvCert nor recipient are set, the recipient of the PKI message is | |
428 | determined in the following order: issuer, issuer of old cert (oldCert), | |
429 | issuer of client cert (clCert), else NULL-DN. | |
430 | When a response is received, its sender must match the recipient of the request. | |
431 | ||
432 | OSSL_CMP_CTX_push0_geninfo_ITAV() adds B<itav> to the stack in the B<ctx> to be | |
433 | added to the GeneralInfo field of the CMP PKIMessage header of a request | |
434 | message sent with this context. Consumes the pointer to B<itav>. | |
435 | ||
436 | OSSL_CMP_CTX_set1_extraCertsOut() sets the stack of extraCerts that will be | |
437 | sent to remote. | |
438 | ||
439 | OSSL_CMP_CTX_set0_newPkey() can be used to explicitly set the given EVP_PKEY | |
440 | structure as the private or public key to be certified in the CMP context. | |
441 | The B<priv> parameter must be 0 if and only if the given key is a public key. | |
442 | ||
443 | OSSL_CMP_CTX_get0_newPkey() gives the key to use for certificate enrollment | |
444 | dependent on fields of the CMP context structure: | |
445 | the newPkey (which may be a private or public key) if present, | |
446 | else the public key in the p10CSR if present, else the client private key. | |
447 | If the B<priv> parameter is not 0 and the selected key does not have a | |
448 | private component then NULL is returned. | |
449 | ||
450 | OSSL_CMP_CTX_set1_issuer() sets the name of the intended issuer that | |
451 | will be set in the CertTemplate, i.e., the X509 name of the CA server. | |
452 | ||
453 | OSSL_CMP_CTX_set1_subjectName() sets the subject DN that will be used in | |
454 | the CertTemplate structure when requesting a new cert. For Key Update Requests | |
455 | (KUR), it defaults to the subject DN of the reference certificate, | |
456 | see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization | |
457 | Requests (IR) and Certification Requests (CR) only if no SANs are set. | |
458 | ||
459 | If clCert is not set (e.g. in case of IR with MSG_MAC_ALG), the subject DN | |
460 | is also used as sender of the PKI message. | |
461 | ||
462 | OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of | |
463 | alternate names on the certificate template request. This cannot be used if | |
464 | any Subject Alternative Name extension is set via | |
465 | OSSL_CMP_CTX_set0_reqExtensions(). | |
466 | By default, unless OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT has been set, | |
467 | the Subject Alternative Names are copied from the reference certificate, | |
468 | see OSSL_CMP_CTX_set1_oldCert(). | |
469 | ||
470 | If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName(), then | |
471 | the certificate template of an IR and CR will not be filled with the default | |
472 | subject DN from the reference certificate (see OSSL_CMP_CTX_set1_oldCert(). | |
473 | If a subject DN is desired it needs to be set explicitly with | |
474 | OSSL_CMP_CTX_set1_subjectName(). | |
475 | ||
476 | OSSL_CMP_CTX_set0_reqExtensions() sets the X.509v3 extensions to be used in | |
477 | IR/CR/KUR. | |
478 | ||
479 | OSSL_CMP_CTX_reqExtensions_have_SAN() returns 1 if the context contains | |
480 | a Subject Alternative Name extension, else 0 or -1 on error. | |
481 | ||
482 | OSSL_CMP_CTX_push0_policy() adds the certificate policy info object | |
483 | to the X509_EXTENSIONS of the requested certificate template. | |
484 | ||
485 | OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in | |
486 | Key Update Requests (KUR) or to be revoked in Revocation Requests (RR). | |
487 | It must be given for RR, else it defaults to B<clCert>. | |
488 | The reference certificate determined in this way, if any, is also used for | |
489 | deriving default subject DN and Subject Alternative Names for IR, CR, and KUR. | |
490 | Its issuer, if any, is used as default recipient in the CMP message header. | |
491 | ||
492 | OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR. | |
493 | ||
494 | OSSL_CMP_CTX_push0_genm_ITAV() adds B<itav> to the stack in the B<ctx> which | |
495 | will be the body of a General Message sent with this context. | |
496 | Consumes the pointer to B<itav>. | |
497 | ||
498 | OSSL_CMP_CTX_set_certConf_cb() sets the callback used for evaluating the newly | |
499 | enrolled certificate before the library sends, depending on its result, | |
500 | a positive or negative certConf message to the server. The callback has type | |
501 | ||
502 | typedef int (*OSSL_cmp_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert, | |
503 | int fail_info, const char **txt); | |
504 | ||
505 | and should inspect the certificate it obtains via the B<cert> parameter and may | |
506 | overrule the pre-decision given in the B<fail_info> and B<*txt> parameters. | |
507 | If it accepts the certificate it must return 0, indicating success. Else it must | |
508 | return a bit field reflecting PKIFailureInfo with at least one failure bit and | |
509 | may set the B<*txt> output parameter to point to a string constant with more | |
510 | detail. The transfer callback may make use of a custom defined argument stored | |
511 | in the B<ctx> by means of OSSL_CMP_CTX_set_certConf_cb_arg(), which may be | |
512 | retrieved again through OSSL_CMP_CTX_get_certConf_cb_arg(). | |
513 | Typically, the callback will check at least that the certificate can be verified | |
514 | using a set of trusted certificates. | |
515 | It also could compare the subject DN and other fields of the newly | |
516 | enrolled certificate with the certificate template of the request. | |
517 | ||
518 | OSSL_CMP_CTX_set_certConf_cb_arg() sets an argument, respectively a pointer to a | |
519 | structure containing arguments, optionally to be used by the certConf callback. | |
520 | B<arg> is not consumed, and it must therefore explicitly be freed when not | |
521 | needed any more. B<arg> may be NULL to clear the entry. | |
522 | ||
523 | OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer | |
524 | to a structure containing arguments, previously set by | |
525 | OSSL_CMP_CTX_set_certConf_cb_arg(), or NULL if unset. | |
526 | ||
527 | OSSL_CMP_CTX_get_status() returns the PKIstatus from the last received | |
528 | CertRepMessage or Revocation Response or error message, or -1 if unset. | |
529 | ||
530 | OSSL_CMP_CTX_get0_statusString() returns the statusString from the last received | |
531 | CertRepMessage or Revocation Response or error message, or NULL if unset. | |
532 | ||
533 | OSSL_CMP_CTX_get_failInfoCode() returns the error code from the failInfo field | |
534 | of the last received CertRepMessage or Revocation Response or error message. | |
6e4618a0 RS |
535 | This is a bit field and the flags for it are specified in the header file |
536 | F<< <openssl/cmp.h> >>. | |
7960dbec DDO |
537 | The flags start with OSSL_CMP_CTX_FAILINFO, for example: |
538 | OSSL_CMP_CTX_FAILINFO_badAlg. Returns -1 if the failInfoCode field is unset. | |
539 | ||
540 | OSSL_CMP_CTX_get0_newCert() returns the pointer to the newly obtained | |
541 | certificate in case it is available, else NULL. | |
542 | ||
543 | OSSL_CMP_CTX_get1_caPubs() returns a pointer to a duplicate of the stack of | |
544 | X.509 certificates received in the caPubs field of last received certificate | |
545 | response message IP/CP/KUP. | |
546 | ||
547 | OSSL_CMP_CTX_get1_extraCertsIn() returns a pointer to a duplicate of the stack | |
548 | of X.509 certificates received in the last received non-empty extraCerts field. | |
549 | Returns an empty stack if no extraCerts have been received in the current | |
550 | transaction. | |
551 | ||
552 | OSSL_CMP_CTX_set1_transactionID() sets the given transaction ID in the given | |
553 | OSSL_CMP_CTX structure. | |
554 | ||
555 | OSSL_CMP_CTX_set1_senderNonce() stores the last sent sender B<nonce> in | |
556 | the B<ctx>. This will be used to validate the recipNonce in incoming messages. | |
557 | ||
558 | =head1 NOTES | |
559 | ||
560 | CMP is defined in RFC 4210 (and CRMF in RFC 4211). | |
561 | ||
562 | =head1 RETURN VALUES | |
563 | ||
564 | OSSL_CMP_CTX_free() and OSSL_CMP_CTX_print_errors() do not return anything. | |
565 | ||
566 | OSSL_CMP_CTX_new(), | |
567 | OSSL_CMP_CTX_get_http_cb_arg(), | |
568 | OSSL_CMP_CTX_get_transfer_cb_arg(), | |
569 | OSSL_CMP_CTX_get0_trustedStore(), | |
570 | OSSL_CMP_CTX_get0_untrusted_certs(), | |
571 | OSSL_CMP_CTX_get0_newPkey(), | |
572 | OSSL_CMP_CTX_get_certConf_cb_arg(), | |
573 | OSSL_CMP_CTX_get0_statusString(), | |
574 | OSSL_CMP_CTX_get0_newCert(), | |
575 | OSSL_CMP_CTX_get1_caPubs(), and | |
576 | OSSL_CMP_CTX_get1_extraCertsIn() | |
577 | return the intended pointer value as described above or NULL on error. | |
578 | ||
579 | OSSL_CMP_CTX_get_option(), | |
580 | OSSL_CMP_CTX_reqExtensions_have_SAN(), | |
581 | OSSL_CMP_CTX_get_status(), and | |
582 | OSSL_CMP_CTX_get_failInfoCode() | |
583 | return the intended value as described above or -1 on error. | |
584 | ||
585 | All other functions return 1 on success, 0 on error. | |
586 | ||
587 | =head1 EXAMPLES | |
588 | ||
589 | The following code does an Initialization Request: | |
590 | ||
591 | cmp_ctx = OSSL_CMP_CTX_new(); | |
592 | OSSL_CMP_CTX_set1_serverName(cmp_ctx, opt_serverName); | |
593 | OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); | |
594 | OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); | |
595 | OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1); | |
596 | OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert); | |
597 | ||
598 | initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx); | |
599 | ||
600 | The following code does an Initialization Request using an | |
601 | external identity certificate (RFC 4210, Appendix E.7): | |
602 | ||
603 | cmp_ctx = OSSL_CMP_CTX_new(); | |
604 | OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname); | |
605 | OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert); | |
606 | OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey); | |
607 | OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1); | |
608 | OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert); | |
609 | ||
610 | initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx); | |
611 | ||
612 | Here externalCert is an X509 certificate granted to the EE by another CA | |
613 | which is trusted by the current CA the code will connect to. | |
614 | ||
615 | ||
616 | The following code does a Key Update Request: | |
617 | ||
618 | cmp_ctx = OSSL_CMP_CTX_new(); | |
619 | OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname); | |
620 | OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey); | |
621 | OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1); | |
622 | OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert); | |
623 | OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert); | |
624 | ||
625 | updatedClCert = OSSL_CMP_exec_KUR_ses(cmp_ctx); | |
626 | ||
627 | The following code (which omits error handling) sends a General Message | |
628 | including, as an example, the id-it-signKeyPairTypes OID and prints info on | |
629 | the General Response contents. | |
630 | ||
631 | cmp_ctx = OSSL_CMP_CTX_new(); | |
632 | OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname); | |
633 | OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); | |
634 | OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); | |
635 | ||
636 | ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1); | |
637 | OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_new(type, NULL); | |
638 | OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav); | |
639 | ||
640 | STACK_OF(OSSL_CMP_ITAV) *itavs; | |
641 | itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx); | |
642 | print_itavs(itavs); | |
643 | sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free); | |
644 | ||
645 | =head1 SEE ALSO | |
646 | ||
647 | L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_KUR_ses(3)>, | |
648 | L<OSSL_CMP_exec_GENM_ses(3)> | |
649 | ||
650 | =head1 HISTORY | |
651 | ||
652 | The OpenSSL CMP support was added in OpenSSL 3.0. | |
653 | ||
654 | =head1 COPYRIGHT | |
655 | ||
656 | Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved. | |
657 | ||
658 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
659 | this file except in compliance with the License. You can obtain a copy | |
660 | in the file LICENSE in the source distribution or at | |
661 | L<https://www.openssl.org/source/license.html>. | |
662 | ||
663 | =cut |