]>
Commit | Line | Data |
---|---|---|
6c17629f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a47bc283 RS |
5 | X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, |
6 | X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, | |
7 | X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, | |
8 | X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags, | |
9 | X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, | |
10 | X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, | |
11 | X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, | |
12 | X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, | |
13 | X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, | |
14 | X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, | |
15 | X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, | |
16 | X509_VERIFY_PARAM_set1_ip_asc | |
17 | - X509 verification parameters | |
6c17629f DSH |
18 | |
19 | =head1 SYNOPSIS | |
20 | ||
21 | #include <openssl/x509_vfy.h> | |
22 | ||
fbb82a60 | 23 | int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, |
a47bc283 | 24 | unsigned long flags); |
6c17629f | 25 | int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, |
a47bc283 | 26 | unsigned long flags); |
4588cb44 | 27 | unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); |
6c17629f | 28 | |
a47bc283 RS |
29 | int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, |
30 | uint32_t flags); | |
31 | uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param); | |
32 | ||
6c17629f DSH |
33 | int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); |
34 | int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); | |
35 | ||
36 | void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); | |
37 | ||
38 | int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, | |
1bc74519 RS |
39 | ASN1_OBJECT *policy); |
40 | int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, | |
41 | STACK_OF(ASN1_OBJECT) *policies); | |
6c17629f DSH |
42 | |
43 | void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); | |
44 | int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); | |
45 | ||
fbb82a60 VD |
46 | void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, |
47 | int auth_level); | |
48 | int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); | |
49 | ||
397a8e74 | 50 | int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, |
1bc74519 | 51 | const char *name, size_t namelen); |
8abffa4a | 52 | int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, |
297c67fc | 53 | const char *name, size_t namelen); |
397a8e74 | 54 | void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, |
1bc74519 | 55 | unsigned int flags); |
4588cb44 | 56 | char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param); |
397a8e74 | 57 | int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, |
1bc74519 | 58 | const char *email, size_t emaillen); |
397a8e74 | 59 | int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, |
1bc74519 | 60 | const unsigned char *ip, size_t iplen); |
297c67fc | 61 | int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); |
397a8e74 | 62 | |
6c17629f DSH |
63 | =head1 DESCRIPTION |
64 | ||
65 | These functions manipulate the B<X509_VERIFY_PARAM> structure associated with | |
1bc74519 | 66 | a certificate verification operation. |
6c17629f DSH |
67 | |
68 | The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring | |
69 | it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete | |
70 | description of values the B<flags> parameter can take. | |
71 | ||
72 | X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. | |
73 | ||
a47bc283 RS |
74 | X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param> |
75 | which specifies how verification flags are copied from one structure to | |
76 | another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags. | |
77 | See the B<INHERITANCE FLAGS> section for a description of these bits. | |
78 | ||
6c17629f DSH |
79 | X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. |
80 | ||
81 | X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> | |
82 | to B<purpose>. This determines the acceptable purpose of the certificate | |
83 | chain, for example SSL client or SSL server. | |
84 | ||
1bc74519 | 85 | X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to |
6c17629f DSH |
86 | B<trust>. |
87 | ||
88 | X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to | |
89 | B<t>. Normally the current time is used. | |
90 | ||
91 | X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled | |
92 | by default) and adds B<policy> to the acceptable policy set. | |
93 | ||
94 | X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled | |
95 | by default) and sets the acceptable policy set to B<policies>. Any existing | |
96 | policy set is cleared. The B<policies> parameter can be B<NULL> to clear | |
97 | an existing policy set. | |
98 | ||
99 | X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. | |
fbb82a60 | 100 | That is the maximum number of intermediate CA certificates that can appear in a |
6c17629f | 101 | chain. |
fbb82a60 | 102 | A maximal depth chain contains 2 more certificates than the limit, since |
0ad69cd6 | 103 | neither the end-entity certificate nor the trust-anchor count against this |
fbb82a60 VD |
104 | limit. |
105 | Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed | |
106 | directly by the trust-anchor, while with a B<depth> limit of 1 there can be one | |
107 | intermediate CA certificate between the trust-anchor and the end-entity | |
108 | certificate. | |
109 | ||
110 | X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to | |
111 | B<auth_level>. | |
112 | The authentication security level determines the acceptable signature and public | |
113 | key strength when verifying certificate chains. | |
114 | For a certificate chain to validate, the public keys of all the certificates | |
115 | must meet the specified security level. | |
116 | The signature algorithm security level is not enforced for the chain's I<trust | |
117 | anchor> certificate, which is either directly trusted or validated by means other | |
118 | than its signature. | |
119 | See L<SSL_CTX_set_security_level(3)> for the definitions of the available | |
120 | levels. | |
121 | The default security level is -1, or "not set". | |
122 | At security level 0 or lower all algorithms are acceptable. | |
123 | Security level 1 requires at least 80-bit-equivalent security and is broadly | |
124 | interoperable, though it will, for example, reject MD5 signatures or RSA keys | |
125 | shorter than 1024 bits. | |
6c17629f | 126 | |
8abffa4a VD |
127 | X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to |
128 | B<name> clearing any previously specified host name or names. If | |
129 | B<name> is NULL, or empty the list of hostnames is cleared, and | |
130 | name checks are not performed on the peer certificate. If B<name> | |
131 | is NUL-terminated, B<namelen> may be zero, otherwise B<namelen> | |
132 | must be set to the length of B<name>. When a hostname is specified, | |
133 | certificate verification automatically invokes L<X509_check_host(3)> | |
134 | with flags equal to the B<flags> argument given to | |
35cb565a | 135 | X509_VERIFY_PARAM_set_hostflags() (default zero). Applications |
8abffa4a VD |
136 | are strongly advised to use this interface in preference to explicitly |
137 | calling L<X509_check_host(3)>, hostname checks are out of scope | |
138 | with the DANE-EE(3) certificate usage, and the internal check will | |
139 | be suppressed as appropriate when DANE support is added to OpenSSL. | |
140 | ||
141 | X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference | |
186bb907 | 142 | identifier that can match the peer's certificate. Any previous names |
8abffa4a VD |
143 | set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host() |
144 | are retained, no change is made if B<name> is NULL or empty. When | |
145 | multiple names are configured, the peer is considered verified when | |
146 | any name matches. | |
397a8e74 | 147 | |
6e661d45 VD |
148 | X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject |
149 | CommonName from the peer certificate that matched one of the reference | |
150 | identifiers. When wildcard matching is not disabled, or when a | |
151 | reference identifier specifies a parent domain (starts with ".") | |
152 | rather than a hostname, the peer name may be a wildcard name or a | |
153 | sub-domain of the reference identifier respectively. The return | |
154 | string is allocated by the library and is no longer valid once the | |
155 | associated B<param> argument is freed. Applications must not free | |
156 | the return value. | |
157 | ||
397a8e74 | 158 | X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to |
df24f29a | 159 | B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise |
397a8e74 VD |
160 | B<emaillen> must be set to the length of B<email>. When an email address |
161 | is specified, certificate verification automatically invokes | |
162 | L<X509_check_email(3)>. | |
163 | ||
164 | X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>. | |
165 | The B<ip> argument is in binary format, in network byte-order and | |
166 | B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP | |
167 | address is specified, certificate verification automatically invokes | |
168 | L<X509_check_ip(3)>. | |
169 | ||
170 | X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to | |
171 | B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string: | |
172 | dotted decimal quad for IPv4 and colon-separated hexadecimal for | |
173 | IPv6. The condensed "::" notation is supported for IPv6 addresses. | |
174 | ||
6c17629f DSH |
175 | =head1 RETURN VALUES |
176 | ||
397a8e74 | 177 | X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), |
a47bc283 | 178 | X509_VERIFY_PARAM_set_inh_flags(), |
6c17629f | 179 | X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), |
397a8e74 | 180 | X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), |
919ba009 | 181 | X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(), |
397a8e74 VD |
182 | X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and |
183 | X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for | |
184 | failure. | |
6c17629f DSH |
185 | |
186 | X509_VERIFY_PARAM_get_flags() returns the current verification flags. | |
187 | ||
a47bc283 RS |
188 | X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags. |
189 | ||
6c17629f DSH |
190 | X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return |
191 | values. | |
192 | ||
193 | X509_VERIFY_PARAM_get_depth() returns the current verification depth. | |
194 | ||
fbb82a60 VD |
195 | X509_VERIFY_PARAM_get_auth_level() returns the current authentication security |
196 | level. | |
197 | ||
6c17629f DSH |
198 | =head1 VERIFICATION FLAGS |
199 | ||
200 | The verification flags consists of zero or more of the following flags | |
201 | ored together. | |
202 | ||
203 | B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf | |
1bc74519 | 204 | certificate. An error occurs if a suitable CRL cannot be found. |
6c17629f DSH |
205 | |
206 | B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate | |
207 | chain. | |
208 | ||
209 | B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default | |
210 | any unhandled critical extensions in certificates or (if checked) CRLs results | |
211 | in a fatal error. If this flag is set unhandled critical extensions are | |
212 | ignored. B<WARNING> setting this option for anything other than debugging | |
213 | purposes can be a security risk. Finer control over which extensions are | |
214 | supported can be performed in the verification callback. | |
215 | ||
186bb907 | 216 | The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken |
6c17629f DSH |
217 | certificates and makes the verification strictly apply B<X509> rules. |
218 | ||
219 | B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. | |
220 | ||
221 | B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default | |
186bb907 | 222 | no policy checking is performed. Additional information is sent to the |
6c17629f DSH |
223 | verification callback relating to policy checking. |
224 | ||
225 | B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and | |
226 | B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any | |
227 | policy> and B<inhibit policy mapping> flags respectively as defined in | |
228 | B<RFC3280>. Policy checking is automatically enabled if any of these flags | |
229 | are set. | |
230 | ||
231 | If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful | |
232 | a special status code is set to the verification callback. This permits it | |
233 | to examine the valid policy tree and perform additional checks or simply | |
234 | log it for debugging purposes. | |
235 | ||
2b4ffc65 | 236 | By default some additional features such as indirect CRLs and CRLs signed by |
6c17629f DSH |
237 | different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set |
238 | they are enabled. | |
239 | ||
186bb907 | 240 | If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to |
6c17629f DSH |
241 | determine certificate status. If not set deltas are ignored. |
242 | ||
243 | B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed | |
186bb907 | 244 | certificate signature. By default this check is disabled because it doesn't |
6c17629f DSH |
245 | add any additional security but in some cases applications might want to |
246 | check the signature anyway. A side effect of not checking the root CA | |
247 | signature is that disabled or unsupported message digests on the root CA | |
248 | are not treated as fatal errors. | |
249 | ||
0daccd4d VD |
250 | If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain, |
251 | L<X509_verify_cert(3)> will search the trust store for issuer certificates before | |
252 | searching the provided untrusted certificates. | |
253 | As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. | |
254 | ||
fa7b0111 | 255 | The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative |
0daccd4d VD |
256 | chains. |
257 | By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a | |
258 | certificate chain, if the first certificate chain found is not trusted, then | |
259 | OpenSSL will attempt to replace untrusted certificates supplied by the peer | |
260 | with certificates from the trust store to see if an alternative chain can be | |
261 | found that is trusted. | |
262 | As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option | |
263 | has no effect. | |
fa7b0111 | 264 | |
d35ff2c0 DW |
265 | The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period |
266 | of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time() | |
267 | is used to specify a verification time, the check is not suppressed. | |
268 | ||
a47bc283 RS |
269 | =head1 INHERITANCE FLAGS |
270 | ||
271 | These flags spevify how parameters are "inherited" from one structure to | |
272 | another. | |
273 | ||
274 | If B<X509_VP_FLAG_ONCE> is set then the current setting is zeroed | |
275 | after the next call. | |
276 | ||
277 | If B<X509_VP_FLAG_LOCKED> is set then no values are copied. This overrides | |
278 | all of the following flags. | |
279 | ||
280 | If B<X509_VP_FLAG_DEFAULT> is set then anything set in the source is copied | |
281 | to the destination. Effectively the values in "to" become default values | |
282 | which will be used only if nothing new is set in "from". This is the | |
283 | default. | |
284 | ||
285 | If B<X509_VP_FLAG_OVERWRITE> is set then all value are copied across whether | |
286 | they are set or not. Flags is still Ored though. | |
287 | ||
288 | If B<X509_VP_FLAG_RESET_FLAGS> is set then the flags value is copied instead | |
289 | of ORed. | |
290 | ||
6c17629f DSH |
291 | =head1 NOTES |
292 | ||
293 | The above functions should be used to manipulate verification parameters | |
294 | instead of legacy functions which work in specific structures such as | |
295 | X509_STORE_CTX_set_flags(). | |
296 | ||
297 | =head1 BUGS | |
298 | ||
299 | Delta CRL checking is currently primitive. Only a single delta can be used and | |
1bc74519 | 300 | (partly due to limitations of B<X509_STORE>) constructed CRLs are not |
6c17629f DSH |
301 | maintained. |
302 | ||
303 | If CRLs checking is enable CRLs are expected to be available in the | |
304 | corresponding B<X509_STORE> structure. No attempt is made to download | |
305 | CRLs from the CRL distribution points extension. | |
306 | ||
307 | =head1 EXAMPLE | |
308 | ||
1bc74519 | 309 | Enable CRL checking when performing certificate verification during SSL |
9074df86 | 310 | connections associated with an B<SSL_CTX> structure B<ctx>: |
6c17629f DSH |
311 | |
312 | X509_VERIFY_PARAM *param; | |
313 | param = X509_VERIFY_PARAM_new(); | |
314 | X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); | |
315 | SSL_CTX_set1_param(ctx, param); | |
316 | X509_VERIFY_PARAM_free(param); | |
317 | ||
318 | =head1 SEE ALSO | |
319 | ||
9b86974e RS |
320 | L<X509_verify_cert(3)>, |
321 | L<X509_check_host(3)>, | |
322 | L<X509_check_email(3)>, | |
323 | L<X509_check_ip(3)> | |
6c17629f DSH |
324 | |
325 | =head1 HISTORY | |
326 | ||
fa7b0111 | 327 | The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0 |
d33def66 VD |
328 | The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of |
329 | OpenSSL 1.1.0, and has no effect. | |
6c17629f | 330 | |
e2f92610 RS |
331 | =head1 COPYRIGHT |
332 | ||
333 | Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. | |
334 | ||
335 | Licensed under the OpenSSL license (the "License"). You may not use | |
336 | this file except in compliance with the License. You can obtain a copy | |
337 | in the file LICENSE in the source distribution or at | |
338 | L<https://www.openssl.org/source/license.html>. | |
339 | ||
340 | =cut |