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