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