Debian Codegraph @

upstream/debian-unstable/man3/OSSL_CMP_exec_certreq.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_CMP_EXEC_CERTREQ 3SSL"
58 .TH OSSL_CMP_EXEC_CERTREQ 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_CMP_exec_certreq,
65 OSSL_CMP_exec_IR_ses,
66 OSSL_CMP_exec_CR_ses,
67 OSSL_CMP_exec_P10CR_ses,
68 OSSL_CMP_exec_KUR_ses,
69 OSSL_CMP_IR,
70 OSSL_CMP_CR,
71 OSSL_CMP_P10CR,
72 OSSL_CMP_KUR,
73 OSSL_CMP_try_certreq,
74 OSSL_CMP_exec_RR_ses,
75 OSSL_CMP_exec_GENM_ses,
76 OSSL_CMP_get1_caCerts,
77 OSSL_CMP_get1_rootCaKeyUpdate,
78 OSSL_CMP_get1_crlUpdate,
79 OSSL_CMP_get1_certReqTemplate
80 \&\- functions implementing CMP client transactions
81 .SH SYNOPSIS
82 .IX Header "SYNOPSIS"
83 .Vb 1
84 \& #include <openssl/cmp.h>
85 \&
86 \& X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type,
87 \& const OSSL_CRMF_MSG *crm);
88 \& X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
89 \& X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
90 \& X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
91 \& X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
92 \& #define OSSL_CMP_IR
93 \& #define OSSL_CMP_CR
94 \& #define OSSL_CMP_P10CR
95 \& #define OSSL_CMP_KUR
96 \& int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type,
97 \& const OSSL_CRMF_MSG *crm, int *checkAfter);
98 \& int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
99 \&
100 \& STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
101 \& int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
102 \& int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx,
103 \& const X509 *oldWithOld, X509 **newWithNew,
104 \& X509 **newWithOld, X509 **oldWithNew);
105 \& int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert,
106 \& const X509_CRL *last_crl,
107 \& X509_CRL **crl);
108 \& int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx,
109 \& OSSL_CRMF_CERTTEMPLATE **certTemplate,
110 \& OSSL_CMP_ATAVS **keySpec);
111 \&=head1 DESCRIPTION
112 .Ve
113 .PP
114 This is the OpenSSL API for doing CMP (Certificate Management Protocol)
115 client-server transactions, i.e., sequences of CMP requests and responses.
116 .PP
117 All functions take a populated OSSL_CMP_CTX structure as their first argument.
118 Usually the server name, port, and path ("CMP alias") need to be set, as well as
119 credentials the client can use for authenticating itself to the server.
120 In order to authenticate the server the client typically needs a trust store.
121 The functions return their respective main results directly, while there are
122 also accessor functions for retrieving various results and status information
123 from the \fIctx\fR. See \fBOSSL_CMP_CTX_new\fR\|(3) etc. for details.
124 .PP
125 The default conveying protocol is HTTP.
126 Timeout values may be given per request-response pair and per transaction.
127 See \fBOSSL_CMP_MSG_http_perform\fR\|(3) for details.
128 .PP
129 \&\fBOSSL_CMP_exec_IR_ses()\fR requests an initial certificate from the given PKI.
130 .PP
131 \&\fBOSSL_CMP_exec_CR_ses()\fR requests an additional certificate.
132 .PP
133 \&\fBOSSL_CMP_exec_P10CR_ses()\fR conveys a legacy PKCS#10 CSR requesting a certificate.
134 .PP
135 \&\fBOSSL_CMP_exec_KUR_ses()\fR obtains an updated certificate.
136 .PP
137 These four types of certificate enrollment are implemented as macros
138 calling \fBOSSL_CMP_exec_certreq()\fR.
139 .PP
140 \&\fBOSSL_CMP_exec_certreq()\fR performs a certificate request of the type specified
141 by the \fIreq_type\fR parameter, which may be IR, CR, P10CR, or KUR.
142 For IR, CR, and KUR, the certificate template to be used in the request
143 may be supplied via the \fIcrm\fR parameter pointing to a CRMF structure.
144 Typically \fIcrm\fR is NULL, then the template ingredients are taken from \fIctx\fR
145 and need to be filled in using \fBOSSL_CMP_CTX_set1_subjectName\fR\|(3),
146 \&\fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), etc.
147 For P10CR, \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3) needs to be used instead.
148 The enrollment session may be blocked (with polling and sleeping in between)
149 until the server side can fully process and ultimately answer the request.
150 .PP
151 \&\fBOSSL_CMP_try_certreq()\fR is an alternative to the above functions that is
152 more flexible regarding what to do after receiving a checkAfter value.
153 When called for the first time (with no certificate request in progress for
154 the given \fIctx\fR) it starts a new transaction by sending a certificate request
155 constructed as stated above using the \fIreq_type\fR and optional \fIcrm\fR parameter.
156 Otherwise (when according to \fIctx\fR a 'waiting' status has been received before)
157 it continues polling for the pending request
158 unless the \fIreq_type\fR argument is < 0, which aborts the request.
159 If the requested certificate is available the function returns 1 and the
160 caller can use \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) to retrieve the new certificate.
161 If no error occurred but no certificate is available yet then
162 \&\fBOSSL_CMP_try_certreq()\fR remembers in the CMP context that it should be retried
163 and returns \-1 after assigning the received checkAfter value
164 via the output pointer argument (unless it is NULL).
165 The checkAfter value indicates the number of seconds the caller should let pass
166 before trying again. The caller is free to sleep for the given number of seconds
167 or for some other time and/or to do anything else before retrying by calling
168 \&\fBOSSL_CMP_try_certreq()\fR again with the same parameter values as before.
169 \&\fBOSSL_CMP_try_certreq()\fR then polls
170 to see whether meanwhile the requested certificate is available.
171 If the caller decides to abort the pending certificate request and provides
172 a negative value as the \fIreq_type\fR argument then \fBOSSL_CMP_try_certreq()\fR
173 aborts the CMP transaction by sending an error message to the server.
174 .PP
175 \&\fBOSSL_CMP_exec_RR_ses()\fR requests the revocation of the certificate
176 specified in the \fIctx\fR using the issuer DN and serial number set by
177 \&\fBOSSL_CMP_CTX_set1_issuer\fR\|(3) and \fBOSSL_CMP_CTX_set1_serialNumber\fR\|(3), respectively,
178 otherwise the issuer DN and serial number
179 of the certificate set by \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3),
180 otherwise the subject DN and public key
181 of the certificate signing request set by \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3).
182 RFC 9810 is vague in which PKIStatus should be returned by the server.
183 We take "accepted" and "grantedWithMods" as clear success and handle
184 "revocationWarning" and "revocationNotification" just as warnings because CAs
185 typically return them as an indication that the certificate was already revoked.
186 "rejection" is a clear error. The values "waiting" and "keyUpdateWarning"
187 make no sense for revocation and thus are treated as an error as well.
188 The revocation session may be blocked (with polling and sleeping in between)
189 until the server can fully process and ultimately answer the request.
190 .PP
191 \&\fBOSSL_CMP_exec_GENM_ses()\fR sends a genm general message containing the sequence of
192 infoType and infoValue pairs (InfoTypeAndValue; short: \fBITAV\fR)
193 optionally provided in the \fIctx\fR using \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3).
194 The message exchange may be blocked (with polling and sleeping in between)
195 until the server can fully process and ultimately answer the request.
196 On success the function records in \fIctx\fR status \fBOSSL_CMP_PKISTATUS_accepted\fR
197 and returns the list of \fBITAV\fRs received in a genp response message.
198 This can be used, for instance,
199 with infoType \f(CW\*(C`signKeyPairTypes\*(C'\fR to obtain the set of signature
200 algorithm identifiers that the CA will certify for subject public keys.
201 See RFC 9810 section 5.3.19 and appendix D.5 for details.
202 Functions implementing more specific genm/genp exchanges are described next.
203 .PP
204 \&\fBOSSL_CMP_get1_caCerts()\fR uses a genm/genp message exchange with infoType caCerts
205 to obtain a list of CA certificates from the CMP server referenced by \fIctx\fR.
206 On success it assigns to \fI*out\fR the list of certificates received,
207 which must be freed by the caller.
208 NULL output means that no CA certificates were provided by the server.
209 .PP
210 \&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR uses a genm request message
211 with infoType rootCaCert to obtain from the CMP server referenced by \fIctx\fR
212 in a genp response message with infoType rootCaKeyUpdate any update of the
213 given root CA certificate \fIoldWithOld\fR and verifies it as far as possible.
214 See RFC 9810 section 4.4 for details.
215 On success it assigns to \fI*newWithNew\fR the root certificate received.
216 When the \fInewWithOld\fR and \fIoldWithNew\fR output parameters are not NULL,
217 it assigns to them the corresponding transition certificates.
218 NULL means that the respective certificate was not provided by the server.
219 All certificates obtained this way must be freed by the caller.
220 .PP
221 \&\fBWARNING:\fR
222 The \fInewWithNew\fR certificate is meant to be a certificate that will be trusted.
223 The trust placed in it cannot be stronger than the trust placed in
224 the \fIoldwithold\fR certificate if present, otherwise it cannot be stronger than
225 the weakest trust in any of the certificates in the trust store of \fIctx\fR.
226 .PP
227 \&\fBOSSL_CMP_get1_crlUpdate()\fR uses a genm request message with infoType crlStatusList
228 to obtain CRL from the CMP server referenced by \fIctx\fR in a genp response message
229 with infoType crls. It uses \fIlast_crl\fR and \fIcrlcert\fR to create
230 a request with a status field as described for \fBOSSL_CMP_CRLSTATUS_create\fR\|(3).
231 On success it assigns to \fI*crl\fR the CRL received.
232 NULL means that no CRL was provided by the server.
233 The CRL obtained this way must be freed by the caller.
234 .PP
235 \&\fBOSSL_CMP_get1_certReqTemplate()\fR uses a genm request message with
236 infoType certReqTemplate to obtain a certificate request template from the
237 CMP server referenced by \fIctx\fR. On success it assigns to \fI*certTemplate\fR
238 the certificate template received. NULL output means that no certificate
239 request template was provided by the server.
240 The optional \fIkeySpec\fR output parameter is assigned the key specification
241 if received, otherwise it set to NULL.
242 Both must be freed by the caller.
243 .SH NOTES
244 .IX Header "NOTES"
245 CMP is defined in RFC 9810 (and CRMF in RFC 4211).
246 .PP
247 The CMP client implementation is limited to one request per CMP message
248 (and consequently to at most one response component per CMP message).
249 .PP
250 When a client obtains from a CMP server CA certificates that it is going to
251 trust, for instance via the caPubs field of a certificate response or using
252 functions like \fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR,
253 authentication of the CMP server is particularly critical.
254 So special care must be taken setting up server authentication in \fIctx\fR
255 using functions such as
256 \&\fBOSSL_CMP_CTX_set0_trusted\fR\|(3) (for certificate-based authentication) or
257 \&\fBOSSL_CMP_CTX_set1_secretValue\fR\|(3) (for MAC-based protection).
258 If authentication is certificate-based, \fBOSSL_CMP_CTX_get0_validatedSrvCert\fR\|(3)
259 should be used to obtain the server validated certificate
260 and perform an authorization check based on it.
261 .SH "RETURN VALUES"
262 .IX Header "RETURN VALUES"
263 \&\fBOSSL_CMP_exec_certreq()\fR, \fBOSSL_CMP_exec_IR_ses()\fR, \fBOSSL_CMP_exec_CR_ses()\fR,
264 \&\fBOSSL_CMP_exec_P10CR_ses()\fR, and \fBOSSL_CMP_exec_KUR_ses()\fR return a
265 pointer to the newly obtained X509 certificate on success, NULL on error.
266 This pointer will be freed implicitly by \fBOSSL_CMP_CTX_free()\fR or
267 \&\fBCSSL_CMP_CTX_reinit()\fR.
268 .PP
269 \&\fBOSSL_CMP_try_certreq()\fR returns 1 if the requested certificate is available
270 via \fBOSSL_CMP_CTX_get0_newCert\fR\|(3)
271 or on successfully aborting a pending certificate request, 0 on error, and \-1
272 in case a 'waiting' status has been received and checkAfter value is available.
273 In the latter case \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) yields NULL
274 and the output parameter \fIcheckAfter\fR has been used to
275 assign the received value unless \fIcheckAfter\fR is NULL.
276 .PP
277 \&\fBOSSL_CMP_exec_RR_ses()\fR, \fBOSSL_CMP_get1_caCerts()\fR,
278 \&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR, \fBOSSL_CMP_get1_crlUpdate()\fR
279 and \fBOSSL_CMP_get1_certReqTemplate()\fR
280 return 1 on success, 0 on error.
281 .PP
282 \&\fBOSSL_CMP_exec_GENM_ses()\fR returns NULL on error,
283 otherwise a pointer to the sequence of \fBITAV\fR received, which may be empty.
284 This pointer must be freed by the caller.
285 .SH EXAMPLES
286 .IX Header "EXAMPLES"
287 See OSSL_CMP_CTX for examples on how to prepare the context for these
288 functions.
289 .SH "SEE ALSO"
290 .IX Header "SEE ALSO"
291 \&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_CTX_free\fR\|(3),
292 \&\fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), \fBOSSL_CMP_CTX_set0_newPkey\fR\|(3),
293 \&\fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3),
294 \&\fBOSSL_CMP_CTX_get0_newCert\fR\|(3), \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3),
295 \&\fBOSSL_CMP_MSG_http_perform\fR\|(3), \fBOSSL_CMP_CRLSTATUS_create\fR\|(3)
296 .SH HISTORY
297 .IX Header "HISTORY"
298 The OpenSSL CMP functions were added in OpenSSL 3.0.
299 .PP
300 \&\fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR
301 were added in OpenSSL 3.2.
302 .PP
303 Support for delayed delivery of all types of response messages
304 was added in OpenSSL 3.3.
305 .PP
306 \&\fBOSSL_CMP_get1_crlUpdate()\fR and \fBOSSL_CMP_get1_certReqTemplate()\fR
307 were added in OpenSSL 3.4.
308 .SH COPYRIGHT
309 .IX Header "COPYRIGHT"
310 Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved.
311 .PP
312 Licensed under the Apache License 2.0 (the "License"). You may not use
313 this file except in compliance with the License. You can obtain a copy
314 in the file LICENSE in the source distribution or at
315 <https://www.openssl.org/source/license.html>.