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