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