]>
Commit | Line | Data |
---|---|---|
db576632 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d8652be0 | 5 | X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup, |
3c95ef22 TS |
6 | X509_STORE_CTX_free, X509_STORE_CTX_init, |
7 | X509_STORE_CTX_init_rpk, | |
8 | X509_STORE_CTX_set0_trusted_stack, | |
cc45a884 | 9 | X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, |
3c95ef22 | 10 | X509_STORE_CTX_set0_rpk, |
f0e0fd51 | 11 | X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, |
4dba585f | 12 | X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, |
f0e0fd51 | 13 | X509_STORE_CTX_get_num_untrusted, |
f9ac6f69 | 14 | X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, |
3c95ef22 | 15 | X509_STORE_CTX_get0_rpk, |
f0e0fd51 | 16 | X509_STORE_CTX_set_default, |
121677b4 | 17 | X509_STORE_CTX_set_verify, |
7b75b973 MC |
18 | X509_STORE_CTX_verify_fn, |
19 | X509_STORE_CTX_set_purpose, | |
20 | X509_STORE_CTX_set_trust, | |
21 | X509_STORE_CTX_purpose_inherit | |
99d63d46 | 22 | - X509_STORE_CTX initialisation |
db576632 DSH |
23 | |
24 | =head1 SYNOPSIS | |
25 | ||
26 | #include <openssl/x509_vfy.h> | |
27 | ||
b4250010 | 28 | X509_STORE_CTX *X509_STORE_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq); |
db576632 DSH |
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 | ||
11ddbf84 | 33 | int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store, |
2576b9c3 | 34 | X509 *target, STACK_OF(X509) *untrusted); |
3c95ef22 TS |
35 | int X509_STORE_CTX_init_rpk(X509_STORE_CTX *ctx, X509_STORE *trust_store, |
36 | EVP_PKEY *rpk); | |
db576632 | 37 | |
f0e0fd51 | 38 | void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); |
db576632 | 39 | |
2576b9c3 | 40 | void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target); |
f0e0fd51 | 41 | void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); |
3c95ef22 | 42 | void X509_STORE_CTX_set0_rpk(X509_STORE_CTX *ctx, EVP_PKEY *target); |
db576632 | 43 | |
8cc86b81 | 44 | X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx); |
db576632 | 45 | void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); |
db576632 | 46 | |
8cc86b81 | 47 | STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx); |
4dba585f | 48 | void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); |
f0e0fd51 | 49 | |
8cc86b81 | 50 | int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx); |
f9ac6f69 DDO |
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); | |
3c95ef22 | 53 | EVP_PKEY *X509_STORE_CTX_get0_rpk(const X509_STORE_CTX *ctx); |
7f3f41d8 | 54 | |
f9ac6f69 | 55 | int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); |
4a7b3a7b | 56 | typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *); |
4a7b3a7b | 57 | void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); |
f0e0fd51 | 58 | |
7b75b973 MC |
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 | ||
db576632 DSH |
64 | =head1 DESCRIPTION |
65 | ||
66 | These functions initialise an B<X509_STORE_CTX> structure for subsequent use | |
11ddbf84 | 67 | by L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)>. |
db576632 | 68 | |
d8652be0 | 69 | X509_STORE_CTX_new_ex() returns a newly initialised B<X509_STORE_CTX> |
cc45a884 MC |
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 | ||
d8652be0 | 75 | X509_STORE_CTX_new() is the same as X509_STORE_CTX_new_ex() except that |
cc45a884 | 76 | the default library context and a NULL property query string are used. |
db576632 DSH |
77 | |
78 | X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. | |
c926a5ec | 79 | It is used by X509_STORE_CTX_init() and X509_STORE_CTX_free(). |
db576632 | 80 | |
cc45a884 | 81 | X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx> |
db576632 | 82 | is no longer valid. |
cc45a884 | 83 | If I<ctx> is NULL nothing is done. |
db576632 | 84 | |
c34e7876 | 85 | X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation. |
22f82d45 SS |
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 | |
c926a5ec DDO |
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. | |
11ddbf84 DDO |
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(). | |
c926a5ec | 95 | The certificate to be verified is set to I<target>, |
2576b9c3 | 96 | and a list of additional certificates may be provided in I<untrusted>, |
c926a5ec | 97 | which will be untrusted but may be used to build the chain. |
3c95ef22 TS |
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. | |
2576b9c3 | 100 | Each of the I<trust_store>, I<target> and I<untrusted> parameters can be NULL. |
c926a5ec | 101 | Yet note that L<X509_verify_cert(3)> and L<X509_STORE_CTX_verify(3)> |
11ddbf84 DDO |
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(). | |
db576632 | 107 | |
3c95ef22 TS |
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(). | |
9a271795 | 111 | The I<target> raw public key can also be supplied separately, via |
3c95ef22 TS |
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 | ||
f0e0fd51 | 116 | X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of |
cc45a884 | 117 | I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates |
f9ac6f69 DDO |
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. | |
db576632 | 120 | |
11ddbf84 | 121 | X509_STORE_CTX_set_cert() sets the target certificate to be verified in I<ctx> |
2576b9c3 | 122 | to I<target>. |
3c95ef22 TS |
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. | |
db576632 | 131 | |
f9ac6f69 DDO |
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 | ||
8c1cbc72 | 136 | X509_STORE_CTX_get0_chain() returns the internal pointer used by the |
f9ac6f69 | 137 | I<ctx> that contains the constructed (output) chain. |
db576632 | 138 | |
3c95ef22 TS |
139 | X509_STORE_CTX_get0_rpk() returns the internal pointer used by the |
140 | I<ctx> that contains the raw public key. | |
141 | ||
db576632 | 142 | X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate |
cc45a884 | 143 | verification to I<sk>. These CRLs will only be used if CRL verification is |
db576632 DSH |
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 | ||
f0e0fd51 | 148 | X509_STORE_CTX_get0_param() retrieves an internal pointer |
cc45a884 | 149 | to the verification parameters associated with I<ctx>. |
db576632 | 150 | |
f9ac6f69 DDO |
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 | ||
f0e0fd51 | 154 | X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the |
cc45a884 | 155 | stack of untrusted certificates associated with I<ctx>. |
f0e0fd51 | 156 | |
11ddbf84 | 157 | X509_STORE_CTX_set0_untrusted() sets the internal pointer to the stack |
cc45a884 | 158 | of untrusted certificates associated with I<ctx> to I<sk>. |
11ddbf84 DDO |
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. | |
4dba585f | 161 | |
f9ac6f69 DDO |
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. | |
db576632 DSH |
178 | |
179 | X509_STORE_CTX_set_default() looks up and sets the default verification | |
cc45a884 | 180 | method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to |
4acda863 DDO |
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>. | |
db576632 | 185 | |
7cafbb4b MC |
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 | |
99d63d46 | 188 | expiration times. |
7cafbb4b MC |
189 | |
190 | A verify function is defined as an X509_STORE_CTX_verify type which has the | |
191 | following signature: | |
192 | ||
1bc74519 | 193 | int (*verify)(X509_STORE_CTX *); |
7cafbb4b MC |
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 | ||
7b75b973 MC |
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 | |
2d17290d | 212 | validate extended key usage information in certificates will need to define a |
7b75b973 MC |
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>, | |
178696d6 LJ |
221 | B<X509_PURPOSE_OCSP_HELPER>, B<X509_PURPOSE_TIMESTAMP_SIGN> and |
222 | B<X509_PURPOSE_CODE_SIGN>. It is also | |
3fa6dbd1 DDO |
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. | |
7b75b973 MC |
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 | |
c00fd2de DDO |
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 | |
7b75b973 MC |
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 | |
c00fd2de DDO |
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 | |
7b75b973 MC |
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 | ||
db576632 DSH |
265 | =head1 NOTES |
266 | ||
267 | The certificates and CRLs in a store are used internally and should B<not> | |
f0e0fd51 | 268 | be freed up until after the associated B<X509_STORE_CTX> is freed. |
db576632 DSH |
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 | ||
c926a5ec | 278 | X509_STORE_CTX_new() returns a newly allocated context or NULL if an |
db576632 DSH |
279 | error occurred. |
280 | ||
3c95ef22 TS |
281 | X509_STORE_CTX_init() and X509_STORE_CTX_init_rpk() return 1 for success |
282 | or 0 if an error occurred. | |
db576632 DSH |
283 | |
284 | X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> | |
c926a5ec | 285 | structure or NULL if an error occurred. |
db576632 | 286 | |
3c95ef22 TS |
287 | X509_STORE_CTX_get0_rpk() returns a pointer to an B<EVP_PKEY> structure if |
288 | present, or NULL if absent. | |
289 | ||
f0e0fd51 RS |
290 | X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), |
291 | X509_STORE_CTX_set0_trusted_stack(), | |
292 | X509_STORE_CTX_set_cert(), | |
db576632 DSH |
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 | ||
7f3f41d8 MC |
298 | X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates |
299 | used. | |
300 | ||
db576632 DSH |
301 | =head1 SEE ALSO |
302 | ||
11ddbf84 | 303 | L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>, |
9b86974e | 304 | L<X509_VERIFY_PARAM_set_flags(3)> |
db576632 DSH |
305 | |
306 | =head1 HISTORY | |
307 | ||
fc5ecadd DMSP |
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. | |
d8652be0 | 310 | The X509_STORE_CTX_new_ex() function was added in OpenSSL 3.0. |
3c95ef22 TS |
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. | |
db576632 | 313 | |
c926a5ec DDO |
314 | There is no need to call X509_STORE_CTX_cleanup() explicitly since OpenSSL 3.0. |
315 | ||
e2f92610 RS |
316 | =head1 COPYRIGHT |
317 | ||
b6461792 | 318 | Copyright 2009-2024 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 319 | |
4746f25a | 320 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |