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