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