]>
Commit | Line | Data |
---|---|---|
1 | =pod | |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup, | |
6 | X509_STORE_CTX_free, X509_STORE_CTX_init, | |
7 | X509_STORE_CTX_init_rpk, | |
8 | X509_STORE_CTX_set0_trusted_stack, | |
9 | X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, | |
10 | X509_STORE_CTX_set0_rpk, | |
11 | X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, | |
12 | X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, | |
13 | X509_STORE_CTX_get_num_untrusted, | |
14 | X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, | |
15 | X509_STORE_CTX_get0_rpk, | |
16 | X509_STORE_CTX_set_default, | |
17 | X509_STORE_CTX_set_verify, | |
18 | X509_STORE_CTX_verify_fn, | |
19 | X509_STORE_CTX_set_purpose, | |
20 | X509_STORE_CTX_set_trust, | |
21 | X509_STORE_CTX_purpose_inherit | |
22 | - X509_STORE_CTX initialisation | |
23 | ||
24 | =head1 SYNOPSIS | |
25 | ||
26 | #include <openssl/x509_vfy.h> | |
27 | ||
28 | X509_STORE_CTX *X509_STORE_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq); | |
29 | X509_STORE_CTX *X509_STORE_CTX_new(void); | |
30 | void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); | |
31 | void X509_STORE_CTX_free(X509_STORE_CTX *ctx); | |
32 | ||
33 | int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store, | |
34 | X509 *target, STACK_OF(X509) *untrusted); | |
35 | int X509_STORE_CTX_init_rpk(X509_STORE_CTX *ctx, X509_STORE *trust_store, | |
36 | EVP_PKEY *rpk); | |
37 | ||
38 | void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); | |
39 | ||
40 | void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target); | |
41 | void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); | |
42 | void X509_STORE_CTX_set0_rpk(X509_STORE_CTX *ctx, EVP_PKEY *target); | |
43 | ||
44 | X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx); | |
45 | void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); | |
46 | ||
47 | STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx); | |
48 | void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); | |
49 | ||
50 | int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx); | |
51 | STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx); | |
52 | void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain); | |
53 | EVP_PKEY *X509_STORE_CTX_get0_rpk(const X509_STORE_CTX *ctx); | |
54 | ||
55 | int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); | |
56 | typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *); | |
57 | void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); | |
58 | ||
59 | int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose); | |
60 | int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust); | |
61 | int X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose, | |
62 | int purpose, int trust); | |
63 | ||
64 | =head1 DESCRIPTION | |
65 | ||
66 | These functions initialise an B<X509_STORE_CTX> structure for subsequent use | |
67 | by L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)>. | |
68 | ||
69 | X509_STORE_CTX_new_ex() returns a newly initialised B<X509_STORE_CTX> | |
70 | structure associated with the specified library context I<libctx> and property | |
71 | query string I<propq>. Any cryptographic algorithms fetched while performing | |
72 | processing with the X509_STORE_CTX will use that library context and property | |
73 | query string. | |
74 | ||
75 | X509_STORE_CTX_new() is the same as X509_STORE_CTX_new_ex() except that | |
76 | the default library context and a NULL property query string are used. | |
77 | ||
78 | X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. | |
79 | It is used by X509_STORE_CTX_init() and X509_STORE_CTX_free(). | |
80 | ||
81 | X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx> | |
82 | is no longer valid. | |
83 | If I<ctx> is NULL nothing is done. | |
84 | ||
85 | X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation. | |
86 | ||
87 | X509_STORE_CTX_init() initializes the internal state and resources of the | |
88 | X509_STORE_CTX, and must be called before each call to L<X509_verify_cert(3)> or | |
89 | L<X509_STORE_CTX_verify(3)>, i.e., a context is only good for one verification. | |
90 | If you want to verify a further certificate or chain with the same I<ctx> | |
91 | then you must call X509_STORE_CTX_init() again. | |
92 | The trusted certificate store is set to I<trust_store> of type B<X509_STORE>. | |
93 | This may be NULL because there are no trusted certificates or because | |
94 | they are provided simply as a list using X509_STORE_CTX_set0_trusted_stack(). | |
95 | The certificate to be verified is set to I<target>, | |
96 | and a list of additional certificates may be provided in I<untrusted>, | |
97 | which will be untrusted but may be used to build the chain. | |
98 | The I<target> certificate is not copied (its reference count is not updated), | |
99 | and the caller must not free it before verification is complete. | |
100 | Each of the I<trust_store>, I<target> and I<untrusted> parameters can be NULL. | |
101 | Yet note that L<X509_verify_cert(3)> and L<X509_STORE_CTX_verify(3)> | |
102 | will need a verification target. | |
103 | This can also be set using X509_STORE_CTX_set_cert(). | |
104 | For L<X509_STORE_CTX_verify(3)>, which takes by default the first element of the | |
105 | list of untrusted certificates as its verification target, | |
106 | this can be also set indirectly using X509_STORE_CTX_set0_untrusted(). | |
107 | ||
108 | X509_STORE_CTX_init_rpk() sets up I<ctx> for a subsequent verification | |
109 | operation for the I<target> raw public key. | |
110 | It behaves similarly to X509_STORE_CTX_init(). | |
111 | The I<target> raw public key can also be supplied separately, via | |
112 | X509_STORE_CTX_set0_rpk(). | |
113 | The I<target> public key is not copied (its reference count is not updated), | |
114 | and the caller must not free it before verification is complete. | |
115 | ||
116 | X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of | |
117 | I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates | |
118 | instead of using an B<X509_STORE> where its complexity is not needed | |
119 | or to make sure that only the given set I<sk> of certificates are trusted. | |
120 | ||
121 | X509_STORE_CTX_set_cert() sets the target certificate to be verified in I<ctx> | |
122 | to I<target>. | |
123 | The target certificate is not copied (its reference count is not updated), | |
124 | and the caller must not free it before verification is complete. | |
125 | ||
126 | X509_STORE_CTX_set0_rpk() sets the target raw public key to be verified in I<ctx> | |
127 | to I<target>, a non-NULL raw public key preempts any target certificate, which | |
128 | is then ignored. | |
129 | The I<target> public key is not copied (its reference count is not updated), | |
130 | and the caller must not free it before verification is complete. | |
131 | ||
132 | X509_STORE_CTX_set0_verified_chain() sets the validated chain to I<chain>. | |
133 | Ownership of the chain is transferred to I<ctx>, | |
134 | and so it should not be free'd by the caller. | |
135 | ||
136 | X509_STORE_CTX_get0_chain() returns the internal pointer used by the | |
137 | I<ctx> that contains the constructed (output) chain. | |
138 | ||
139 | X509_STORE_CTX_get0_rpk() returns the internal pointer used by the | |
140 | I<ctx> that contains the raw public key. | |
141 | ||
142 | X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate | |
143 | verification to I<sk>. These CRLs will only be used if CRL verification is | |
144 | enabled in the associated B<X509_VERIFY_PARAM> structure. This might be | |
145 | used where additional "useful" CRLs are supplied as part of a protocol, | |
146 | for example in a PKCS#7 structure. | |
147 | ||
148 | X509_STORE_CTX_get0_param() retrieves an internal pointer | |
149 | to the verification parameters associated with I<ctx>. | |
150 | ||
151 | X509_STORE_CTX_set0_param() sets the internal verification parameter pointer | |
152 | to I<param>. After this call B<param> should not be used. | |
153 | ||
154 | X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the | |
155 | stack of untrusted certificates associated with I<ctx>. | |
156 | ||
157 | X509_STORE_CTX_set0_untrusted() sets the internal pointer to the stack | |
158 | of untrusted certificates associated with I<ctx> to I<sk>. | |
159 | X509_STORE_CTX_verify() will take the first element, if any, | |
160 | as its default target if the target certificate is not set explicitly. | |
161 | ||
162 | X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates | |
163 | that were used in building the chain. | |
164 | This is can be used after calling L<X509_verify_cert(3)> and similar functions. | |
165 | With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element. | |
166 | ||
167 | X509_STORE_CTX_get0_chain() returns the internal pointer used by the | |
168 | I<ctx> that contains the validated chain. | |
169 | ||
170 | Details of the chain building and checking process are described in | |
171 | L<openssl-verification-options(1)/Certification Path Building> and | |
172 | L<openssl-verification-options(1)/Certification Path Validation>. | |
173 | ||
174 | X509_STORE_CTX_set0_verified_chain() sets the validated chain used | |
175 | by I<ctx> to be I<chain>. | |
176 | Ownership of the chain is transferred to I<ctx>, | |
177 | and so it should not be free'd by the caller. | |
178 | ||
179 | X509_STORE_CTX_set_default() looks up and sets the default verification | |
180 | method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to | |
181 | find an appropriate set of parameters from the purpose identifier I<name>. | |
182 | Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>, | |
183 | C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>, | |
184 | and C<any>. | |
185 | ||
186 | X509_STORE_CTX_set_verify() provides the capability for overriding the default | |
187 | verify function. This function is responsible for verifying chain signatures and | |
188 | expiration times. | |
189 | ||
190 | A verify function is defined as an X509_STORE_CTX_verify type which has the | |
191 | following signature: | |
192 | ||
193 | int (*verify)(X509_STORE_CTX *); | |
194 | ||
195 | This function should receive the current X509_STORE_CTX as a parameter and | |
196 | return 1 on success or 0 on failure. | |
197 | ||
198 | X509 certificates may contain information about what purposes keys contained | |
199 | within them can be used for. For example "TLS WWW Server Authentication" or | |
200 | "Email Protection". This "key usage" information is held internally to the | |
201 | certificate itself. In addition the trust store containing trusted certificates | |
202 | can declare what purposes we trust different certificates for. This "trust" | |
203 | information is not held within the certificate itself but is "meta" information | |
204 | held alongside it. This "meta" information is associated with the certificate | |
205 | after it is issued and could be determined by a system administrator. For | |
206 | example a certificate might declare that it is suitable for use for both | |
207 | "TLS WWW Server Authentication" and "TLS Client Authentication", but a system | |
208 | administrator might only trust it for the former. An X.509 certificate extension | |
209 | exists that can record extended key usage information to supplement the purpose | |
210 | information described above. This extended mechanism is arbitrarily extensible | |
211 | and not well suited for a generic library API; applications that need to | |
212 | validate extended key usage information in certificates will need to define a | |
213 | custom "purpose" (see below) or supply a nondefault verification callback | |
214 | (L<X509_STORE_set_verify_cb_func(3)>). | |
215 | ||
216 | X509_STORE_CTX_set_purpose() sets the purpose for the target certificate being | |
217 | verified in the I<ctx>. Built-in available values for the I<purpose> argument | |
218 | are B<X509_PURPOSE_SSL_CLIENT>, B<X509_PURPOSE_SSL_SERVER>, | |
219 | B<X509_PURPOSE_NS_SSL_SERVER>, B<X509_PURPOSE_SMIME_SIGN>, | |
220 | B<X509_PURPOSE_SMIME_ENCRYPT>, B<X509_PURPOSE_CRL_SIGN>, B<X509_PURPOSE_ANY>, | |
221 | B<X509_PURPOSE_OCSP_HELPER>, B<X509_PURPOSE_TIMESTAMP_SIGN> and | |
222 | B<X509_PURPOSE_CODE_SIGN>. It is also | |
223 | possible to create a custom purpose value. Setting a purpose requests that | |
224 | the key usage and extended key usage (EKU) extensions optionally declared within | |
225 | the certificate and its chain are verified to be consistent with that purpose. | |
226 | For SSL client, SSL server, and S/MIME purposes, the EKU is checked also for the | |
227 | CA certificates along the chain, including any given trust anchor certificate. | |
228 | Potentially also further checks are done (depending on the purpose given). | |
229 | Every purpose also has an associated default trust value, which will also be set | |
230 | at the same time. During verification, this trust setting will be verified | |
231 | to check whether it is consistent with the trust set by the system administrator | |
232 | for certificates in the chain. | |
233 | ||
234 | X509_STORE_CTX_set_trust() sets the trust value for the target certificate | |
235 | being verified in the I<ctx>. Built-in available values for the I<trust> | |
236 | argument are B<X509_TRUST_COMPAT>, B<X509_TRUST_SSL_CLIENT>, | |
237 | B<X509_TRUST_SSL_SERVER>, B<X509_TRUST_EMAIL>, B<X509_TRUST_OBJECT_SIGN>, | |
238 | B<X509_TRUST_OCSP_SIGN>, B<X509_TRUST_OCSP_REQUEST> and B<X509_TRUST_TSA>. It is | |
239 | also possible to create a custom trust value. Since X509_STORE_CTX_set_purpose() | |
240 | also sets the trust value it is normally sufficient to only call that function. | |
241 | If both are called then X509_STORE_CTX_set_trust() should be called after | |
242 | X509_STORE_CTX_set_purpose() since the trust setting of the last call will be | |
243 | used. | |
244 | ||
245 | It should not normally be necessary for end user applications to call | |
246 | X509_STORE_CTX_purpose_inherit() directly. Typically applications should call | |
247 | X509_STORE_CTX_set_purpose() or X509_STORE_CTX_set_trust() instead. Using this | |
248 | function it is possible to set the purpose and trust values for the I<ctx> at | |
249 | the same time. | |
250 | Both I<ctx> and its internal verification parameter pointer must not be NULL. | |
251 | The I<def_purpose> and I<purpose> arguments can have the same | |
252 | purpose values as described for X509_STORE_CTX_set_purpose() above. The I<trust> | |
253 | argument can have the same trust values as described in | |
254 | X509_STORE_CTX_set_trust() above. Any of the I<def_purpose>, I<purpose> or | |
255 | I<trust> values may also have the value 0 to indicate that the supplied | |
256 | parameter should be ignored. After calling this function the purpose to be used | |
257 | for verification is set from the I<purpose> argument unless the purpose was | |
258 | already set in I<ctx> before, and the trust is set from the I<trust> argument | |
259 | unless the trust was already set in I<ctx> before. | |
260 | If I<trust> is 0 then the trust value will be set from | |
261 | the default trust value for I<purpose>. If the default trust value for the | |
262 | purpose is I<X509_TRUST_DEFAULT> and I<trust> is 0 then the default trust value | |
263 | associated with the I<def_purpose> value is used for the trust setting instead. | |
264 | ||
265 | =head1 NOTES | |
266 | ||
267 | The certificates and CRLs in a store are used internally and should B<not> | |
268 | be freed up until after the associated B<X509_STORE_CTX> is freed. | |
269 | ||
270 | =head1 BUGS | |
271 | ||
272 | The certificates and CRLs in a context are used internally and should B<not> | |
273 | be freed up until after the associated B<X509_STORE_CTX> is freed. Copies | |
274 | should be made or reference counts increased instead. | |
275 | ||
276 | =head1 RETURN VALUES | |
277 | ||
278 | X509_STORE_CTX_new() returns a newly allocated context or NULL if an | |
279 | error occurred. | |
280 | ||
281 | X509_STORE_CTX_init() and X509_STORE_CTX_init_rpk() return 1 for success | |
282 | or 0 if an error occurred. | |
283 | ||
284 | X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> | |
285 | structure or NULL if an error occurred. | |
286 | ||
287 | X509_STORE_CTX_get0_rpk() returns a pointer to an B<EVP_PKEY> structure if | |
288 | present, or NULL if absent. | |
289 | ||
290 | X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), | |
291 | X509_STORE_CTX_set0_trusted_stack(), | |
292 | X509_STORE_CTX_set_cert(), | |
293 | X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return | |
294 | values. | |
295 | ||
296 | X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. | |
297 | ||
298 | X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates | |
299 | used. | |
300 | ||
301 | =head1 SEE ALSO | |
302 | ||
303 | L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>, | |
304 | L<X509_VERIFY_PARAM_set_flags(3)> | |
305 | ||
306 | =head1 HISTORY | |
307 | ||
308 | The X509_STORE_CTX_set0_crls() function was added in OpenSSL 1.0.0. | |
309 | The X509_STORE_CTX_get_num_untrusted() function was added in OpenSSL 1.1.0. | |
310 | The X509_STORE_CTX_new_ex() function was added in OpenSSL 3.0. | |
311 | The X509_STORE_CTX_init_rpk(), X509_STORE_CTX_get0_rpk(), and | |
312 | X509_STORE_CTX_set0_rpk() functions were added in OpenSSL 3.2. | |
313 | ||
314 | There is no need to call X509_STORE_CTX_cleanup() explicitly since OpenSSL 3.0. | |
315 | ||
316 | =head1 COPYRIGHT | |
317 | ||
318 | Copyright 2009-2024 The OpenSSL Project Authors. All Rights Reserved. | |
319 | ||
320 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
321 | this file except in compliance with the License. You can obtain a copy | |
322 | in the file LICENSE in the source distribution or at | |
323 | L<https://www.openssl.org/source/license.html>. | |
324 | ||
325 | =cut |