]>
Commit | Line | Data |
---|---|---|
7e765f46 DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
299e0f1e | 5 | OSSL_CMP_exec_certreq, |
7e765f46 DDO |
6 | OSSL_CMP_exec_IR_ses, |
7 | OSSL_CMP_exec_CR_ses, | |
8 | OSSL_CMP_exec_P10CR_ses, | |
9 | OSSL_CMP_exec_KUR_ses, | |
10 | OSSL_CMP_IR, | |
11 | OSSL_CMP_CR, | |
12 | OSSL_CMP_P10CR, | |
13 | OSSL_CMP_KUR, | |
14 | OSSL_CMP_try_certreq, | |
15 | OSSL_CMP_exec_RR_ses, | |
d477484d | 16 | OSSL_CMP_exec_GENM_ses, |
01b04851 | 17 | OSSL_CMP_get1_caCerts, |
40a200f9 DDO |
18 | OSSL_CMP_get1_rootCaKeyUpdate, |
19 | OSSL_CMP_get1_crlUpdate | |
7e765f46 DDO |
20 | - functions implementing CMP client transactions |
21 | ||
22 | =head1 SYNOPSIS | |
23 | ||
24 | #include <openssl/cmp.h> | |
25 | ||
299e0f1e DDO |
26 | X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type, |
27 | const OSSL_CRMF_MSG *crm); | |
7e765f46 DDO |
28 | X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx); |
29 | X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx); | |
30 | X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx); | |
31 | X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx); | |
32 | #define OSSL_CMP_IR | |
33 | #define OSSL_CMP_CR | |
34 | #define OSSL_CMP_P10CR | |
35 | #define OSSL_CMP_KUR | |
299e0f1e DDO |
36 | int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, |
37 | const OSSL_CRMF_MSG *crm, int *checkAfter); | |
3d46c81a | 38 | int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx); |
ec5a9cd1 | 39 | |
7e765f46 | 40 | STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx); |
ec5a9cd1 | 41 | int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out); |
01b04851 DDO |
42 | int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx, |
43 | const X509 *oldWithOld, X509 **newWithNew, | |
44 | X509 **newWithOld, X509 **oldWithNew); | |
40a200f9 DDO |
45 | int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert, |
46 | const X509_CRL *last_crl, | |
47 | X509_CRL **crl); | |
7e765f46 DDO |
48 | |
49 | =head1 DESCRIPTION | |
50 | ||
51 | This is the OpenSSL API for doing CMP (Certificate Management Protocol) | |
52 | client-server transactions, i.e., sequences of CMP requests and responses. | |
53 | ||
54 | All functions take a populated OSSL_CMP_CTX structure as their first argument. | |
55 | Usually the server name, port, and path ("CMP alias") need to be set, as well as | |
89ed128d | 56 | credentials the client can use for authenticating itself to the server. |
7e765f46 | 57 | In order to authenticate the server the client typically needs a trust store. |
7e765f46 DDO |
58 | The functions return their respective main results directly, while there are |
59 | also accessor functions for retrieving various results and status information | |
f5f4fbaa | 60 | from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details. |
7e765f46 DDO |
61 | |
62 | The default conveying protocol is HTTP. | |
63 | Timeout values may be given per request-response pair and per transaction. | |
64 | See L<OSSL_CMP_MSG_http_perform(3)> for details. | |
65 | ||
66 | OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI. | |
67 | ||
68 | OSSL_CMP_exec_CR_ses() requests an additional certificate. | |
69 | ||
70 | OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate. | |
71 | ||
72 | OSSL_CMP_exec_KUR_ses() obtains an updated certificate. | |
73 | ||
299e0f1e DDO |
74 | These four types of certificate enrollment are implemented as macros |
75 | calling OSSL_CMP_exec_certreq(). | |
76 | ||
77 | OSSL_CMP_exec_certreq() performs a certificate request of the type specified | |
f5f4fbaa | 78 | by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR. |
299e0f1e | 79 | For IR, CR, and KUR, the certificate template to be used in the request |
f5f4fbaa RL |
80 | may be supplied via the I<crm> parameter pointing to a CRMF structure. |
81 | Typically I<crm> is NULL, then the template ingredients are taken from I<ctx> | |
299e0f1e DDO |
82 | and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>, |
83 | L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc. | |
84 | For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead. | |
bedffe17 DDO |
85 | The enrollment session may be blocked (with polling and sleeping in between) |
86 | until the server side can fully process and ultimately answer the request. | |
299e0f1e DDO |
87 | |
88 | OSSL_CMP_try_certreq() is an alternative to the above functions that is | |
7e765f46 DDO |
89 | more flexible regarding what to do after receiving a checkAfter value. |
90 | When called for the first time (with no certificate request in progress for | |
f5f4fbaa RL |
91 | the given I<ctx>) it starts a new transaction by sending a certificate request |
92 | constructed as stated above using the I<req_type> and optional I<crm> parameter. | |
93 | Otherwise (when according to I<ctx> a 'waiting' status has been received before) | |
7e765f46 | 94 | it continues polling for the pending request |
f5f4fbaa | 95 | unless the I<req_type> argument is < 0, which aborts the request. |
7e765f46 | 96 | If the requested certificate is available the function returns 1 and the |
299e0f1e | 97 | caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate. |
7e765f46 DDO |
98 | If no error occurred but no certificate is available yet then |
99 | OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried | |
100 | and returns -1 after assigning the received checkAfter value | |
101 | via the output pointer argument (unless it is NULL). | |
102 | The checkAfter value indicates the number of seconds the caller should let pass | |
103 | before trying again. The caller is free to sleep for the given number of seconds | |
104 | or for some other time and/or to do anything else before retrying by calling | |
105 | OSSL_CMP_try_certreq() again with the same parameter values as before. | |
106 | OSSL_CMP_try_certreq() then polls | |
107 | to see whether meanwhile the requested certificate is available. | |
108 | If the caller decides to abort the pending certificate request and provides | |
f5f4fbaa | 109 | a negative value as the I<req_type> argument then OSSL_CMP_try_certreq() |
7e765f46 DDO |
110 | aborts the CMP transaction by sending an error message to the server. |
111 | ||
7e765f46 | 112 | OSSL_CMP_exec_RR_ses() requests the revocation of the certificate |
1d32ec20 RR |
113 | specified in the I<ctx> using the issuer DN and serial number set by |
114 | OSSL_CMP_CTX_set1_issuer(3) and OSSL_CMP_CTX_set1_serialNumber(3), respectively, | |
115 | otherwise the issuer DN and serial number | |
116 | of the certificate set by L<OSSL_CMP_CTX_set1_oldCert(3)>, | |
117 | otherwise the subject DN and public key | |
118 | of the certificate signing request set by L<OSSL_CMP_CTX_set1_p10CSR(3)>. | |
7e765f46 DDO |
119 | RFC 4210 is vague in which PKIStatus should be returned by the server. |
120 | We take "accepted" and "grantedWithMods" as clear success and handle | |
121 | "revocationWarning" and "revocationNotification" just as warnings because CAs | |
122 | typically return them as an indication that the certificate was already revoked. | |
123 | "rejection" is a clear error. The values "waiting" and "keyUpdateWarning" | |
124 | make no sense for revocation and thus are treated as an error as well. | |
bedffe17 DDO |
125 | The revocation session may be blocked (with polling and sleeping in between) |
126 | until the server can fully process and ultimately answer the request. | |
7e765f46 | 127 | |
ec5a9cd1 | 128 | OSSL_CMP_exec_GENM_ses() sends a genm general message containing the sequence of |
7e765f46 | 129 | infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>) |
19ddcc4c | 130 | optionally provided in the I<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>. |
bedffe17 DDO |
131 | The message exchange may be blocked (with polling and sleeping in between) |
132 | until the server can fully process and ultimately answer the request. | |
133 | On success the function records in I<ctx> status B<OSSL_CMP_PKISTATUS_accepted> | |
ec5a9cd1 DDO |
134 | and returns the list of B<ITAV>s received in a genp response message. |
135 | This can be used, for instance, | |
136 | with infoType C<signKeyPairTypes> to obtain the set of signature | |
137 | algorithm identifiers that the CA will certify for subject public keys. | |
7e765f46 | 138 | See RFC 4210 section 5.3.19 and appendix E.5 for details. |
ec5a9cd1 | 139 | Functions implementing more specific genm/genp exchanges are described next. |
7e765f46 | 140 | |
ec5a9cd1 | 141 | OSSL_CMP_get1_caCerts() uses a genm/genp message exchange with infoType caCerts |
d477484d DDO |
142 | to obtain a list of CA certificates from the CMP server referenced by I<ctx>. |
143 | On success it assigns to I<*out> the list of certificates received, | |
144 | which must be freed by the caller. | |
ec5a9cd1 | 145 | NULL output means that no CA certificates were provided by the server. |
d477484d | 146 | |
01b04851 DDO |
147 | OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message |
148 | with infoType rootCaCert to obtain from the CMP server referenced by I<ctx> | |
149 | in a genp response message with infoType rootCaKeyUpdate any update of the | |
150 | given root CA certificate I<oldWithOld> and verifies it as far as possible. | |
151 | See RFC 4210 section 4.4 for details. | |
152 | On success it assigns to I<*newWithNew> the root certificate received. | |
153 | When the I<newWithOld> and I<oldWithNew> output parameters are not NULL, | |
154 | it assigns to them the corresponding transition certificates. | |
155 | NULL means that the respective certificate was not provided by the server. | |
156 | All certificates obtained this way must be freed by the caller. | |
157 | ||
158 | B<WARNING:> | |
159 | The I<newWithNew> certificate is meant to be a certificate that will be trusted. | |
160 | The trust placed in it cannot be stronger than the trust placed in | |
161 | the I<oldwithold> certificate if present, otherwise it cannot be stronger than | |
162 | the weakest trust in any of the certificates in the trust store of I<ctx>. | |
163 | ||
40a200f9 DDO |
164 | OSSL_CMP_get1_crlUpdate() uses a genm request message with infoType crlStatusList |
165 | to obtain CRL from the CMP server referenced by I<ctx> in a genp response message | |
166 | with infoType crls. It uses I<last_crl> and I<crlcert> to create | |
167 | a request with a status field as described for L<OSSL_CMP_CRLSTATUS_create(3)>. | |
168 | On success it assigns to I<*crl> the CRL received. | |
169 | NULL means that no CRL was provided by the server. | |
170 | The CRL obtained this way must be freed by the caller. | |
171 | ||
7e765f46 DDO |
172 | =head1 NOTES |
173 | ||
174 | CMP is defined in RFC 4210 (and CRMF in RFC 4211). | |
175 | ||
89ed128d | 176 | The CMP client implementation is limited to one request per CMP message |
7e765f46 DDO |
177 | (and consequently to at most one response component per CMP message). |
178 | ||
1a9e2860 | 179 | When a client obtains from a CMP server CA certificates that it is going to |
01b04851 DDO |
180 | trust, for instance via the caPubs field of a certificate response or using |
181 | functions like OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate(), | |
1a9e2860 DDO |
182 | authentication of the CMP server is particularly critical. |
183 | So special care must be taken setting up server authentication in I<ctx> | |
184 | using functions such as | |
185 | L<OSSL_CMP_CTX_set0_trusted(3)> (for certificate-based authentication) or | |
186 | L<OSSL_CMP_CTX_set1_secretValue(3)> (for MAC-based protection). | |
187 | If authentication is certificate-based, L<OSSL_CMP_CTX_get0_validatedSrvCert(3)> | |
188 | should be used to obtain the server validated certificate | |
189 | and perform an authorization check based on it. | |
190 | ||
7e765f46 DDO |
191 | =head1 RETURN VALUES |
192 | ||
299e0f1e | 193 | OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(), |
7e765f46 | 194 | OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a |
f5f4fbaa | 195 | pointer to the newly obtained X509 certificate on success, NULL on error. |
7e765f46 DDO |
196 | This pointer will be freed implicitly by OSSL_CMP_CTX_free() or |
197 | CSSL_CMP_CTX_reinit(). | |
198 | ||
199 | OSSL_CMP_try_certreq() returns 1 if the requested certificate is available | |
299e0f1e | 200 | via L<OSSL_CMP_CTX_get0_newCert(3)> |
7e765f46 DDO |
201 | or on successfully aborting a pending certificate request, 0 on error, and -1 |
202 | in case a 'waiting' status has been received and checkAfter value is available. | |
299e0f1e | 203 | In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL |
f5f4fbaa RL |
204 | and the output parameter I<checkAfter> has been used to |
205 | assign the received value unless I<checkAfter> is NULL. | |
7e765f46 | 206 | |
01b04851 | 207 | OSSL_CMP_exec_RR_ses(), OSSL_CMP_get1_caCerts(), |
40a200f9 | 208 | OSSL_CMP_get1_rootCaKeyUpdate() and OSSL_CMP_get1_crlUpdate() |
d477484d | 209 | return 1 on success, 0 on error. |
7e765f46 | 210 | |
19ddcc4c DDO |
211 | OSSL_CMP_exec_GENM_ses() returns NULL on error, |
212 | otherwise a pointer to the sequence of B<ITAV> received, which may be empty. | |
7e765f46 DDO |
213 | This pointer must be freed by the caller. |
214 | ||
215 | =head1 EXAMPLES | |
216 | ||
217 | See OSSL_CMP_CTX for examples on how to prepare the context for these | |
218 | functions. | |
219 | ||
220 | =head1 SEE ALSO | |
221 | ||
299e0f1e DDO |
222 | L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>, |
223 | L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>, | |
224 | L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, | |
225 | L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>, | |
40a200f9 | 226 | L<OSSL_CMP_MSG_http_perform(3)>, L<OSSL_CMP_CRLSTATUS_create(3)> |
7e765f46 DDO |
227 | |
228 | =head1 HISTORY | |
229 | ||
230 | The OpenSSL CMP support was added in OpenSSL 3.0. | |
231 | ||
01b04851 DDO |
232 | OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate() |
233 | were added in OpenSSL 3.2. | |
d477484d | 234 | |
40a200f9 DDO |
235 | OSSL_CMP_get1_crlUpdate() and support for delayed delivery |
236 | of all types of response messages was added in OpenSSL 3.3. | |
bedffe17 | 237 | |
7e765f46 DDO |
238 | =head1 COPYRIGHT |
239 | ||
da1c088f | 240 | Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. |
7e765f46 DDO |
241 | |
242 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
243 | this file except in compliance with the License. You can obtain a copy | |
244 | in the file LICENSE in the source distribution or at | |
245 | L<https://www.openssl.org/source/license.html>. | |
246 | ||
247 | =cut |