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