5 X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags,
6 X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose,
7 X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags,
8 X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth,
9 X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level,
10 X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time,
11 X509_VERIFY_PARAM_get_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,
15 X509_VERIFY_PARAM_get_hostflags,
16 X509_VERIFY_PARAM_get0_peername,
17 X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip,
18 X509_VERIFY_PARAM_set1_ip_asc
19 - X509 verification parameters
23 #include <openssl/x509_vfy.h>
25 int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param,
27 int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param,
29 unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param);
31 int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param,
33 uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param);
35 int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose);
36 int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust);
38 void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t);
39 time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param);
41 int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,
43 int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param,
44 STACK_OF(ASN1_OBJECT) *policies);
46 void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
47 int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
49 void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param,
51 int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param);
53 int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
54 const char *name, size_t namelen);
55 int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param,
56 const char *name, size_t namelen);
57 void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
59 unsigned int X509_VERIFY_PARAM_get_hostflags(X509_VERIFY_PARAM *param);
60 char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
61 int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
62 const char *email, size_t emaillen);
63 int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
64 const unsigned char *ip, size_t iplen);
65 int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
69 These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
70 a certificate verification operation.
72 The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring
73 it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete
74 description of values the B<flags> parameter can take.
76 X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
78 X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param>
79 which specifies how verification flags are copied from one structure to
80 another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags.
81 See the B<INHERITANCE FLAGS> section for a description of these bits.
83 X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
85 X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
86 to B<purpose>. This determines the acceptable purpose of the certificate
87 chain, for example SSL client or SSL server.
89 X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
92 X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to
93 B<t>. Normally the current time is used.
95 X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled
96 by default) and adds B<policy> to the acceptable policy set.
98 X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled
99 by default) and sets the acceptable policy set to B<policies>. Any existing
100 policy set is cleared. The B<policies> parameter can be B<NULL> to clear
101 an existing policy set.
103 X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
104 That is the maximum number of intermediate CA certificates that can appear in a
106 A maximal depth chain contains 2 more certificates than the limit, since
107 neither the end-entity certificate nor the trust-anchor count against this
109 Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed
110 directly by the trust-anchor, while with a B<depth> limit of 1 there can be one
111 intermediate CA certificate between the trust-anchor and the end-entity
114 X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to
116 The authentication security level determines the acceptable signature and public
117 key strength when verifying certificate chains.
118 For a certificate chain to validate, the public keys of all the certificates
119 must meet the specified security level.
120 The signature algorithm security level is not enforced for the chain's I<trust
121 anchor> certificate, which is either directly trusted or validated by means other
123 See L<SSL_CTX_set_security_level(3)> for the definitions of the available
125 The default security level is -1, or "not set".
126 At security level 0 or lower all algorithms are acceptable.
127 Security level 1 requires at least 80-bit-equivalent security and is broadly
128 interoperable, though it will, for example, reject MD5 signatures or RSA keys
129 shorter than 1024 bits.
131 X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
132 B<name> clearing any previously specified host name or names. If
133 B<name> is NULL, or empty the list of hostnames is cleared, and
134 name checks are not performed on the peer certificate. If B<name>
135 is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
136 must be set to the length of B<name>. When a hostname is specified,
137 certificate verification automatically invokes L<X509_check_host(3)>
138 with flags equal to the B<flags> argument given to
139 X509_VERIFY_PARAM_set_hostflags() (default zero). Applications
140 are strongly advised to use this interface in preference to explicitly
141 calling L<X509_check_host(3)>, hostname checks are out of scope
142 with the DANE-EE(3) certificate usage, and the internal check will
143 be suppressed as appropriate when DANE support is added to OpenSSL.
145 X509_VERIFY_PARAM_get_hostflags() returns any host flags previously set via a
146 call to X509_VERIFY_PARAM_set_hostflags().
148 X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
149 identifier that can match the peer's certificate. Any previous names
150 set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
151 are retained, no change is made if B<name> is NULL or empty. When
152 multiple names are configured, the peer is considered verified when
155 X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject
156 CommonName from the peer certificate that matched one of the reference
157 identifiers. When wildcard matching is not disabled, or when a
158 reference identifier specifies a parent domain (starts with ".")
159 rather than a hostname, the peer name may be a wildcard name or a
160 sub-domain of the reference identifier respectively. The return
161 string is allocated by the library and is no longer valid once the
162 associated B<param> argument is freed. Applications must not free
165 X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
166 B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
167 B<emaillen> must be set to the length of B<email>. When an email address
168 is specified, certificate verification automatically invokes
169 L<X509_check_email(3)>.
171 X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>.
172 The B<ip> argument is in binary format, in network byte-order and
173 B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
174 address is specified, certificate verification automatically invokes
177 X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
178 B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
179 dotted decimal quad for IPv4 and colon-separated hexadecimal for
180 IPv6. The condensed "::" notation is supported for IPv6 addresses.
184 X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
185 X509_VERIFY_PARAM_set_inh_flags(),
186 X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
187 X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
188 X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),
189 X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and
190 X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for
193 X509_VERIFY_PARAM_get_flags() returns the current verification flags.
195 X509_VERIFY_PARAM_get_hostflags() returns any current host flags.
197 X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags.
199 X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return
202 X509_VERIFY_PARAM_get_depth() returns the current verification depth.
204 X509_VERIFY_PARAM_get_auth_level() returns the current authentication security
207 =head1 VERIFICATION FLAGS
209 The verification flags consists of zero or more of the following flags
212 B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf
213 certificate. An error occurs if a suitable CRL cannot be found.
215 B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate
218 B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default
219 any unhandled critical extensions in certificates or (if checked) CRLs results
220 in a fatal error. If this flag is set unhandled critical extensions are
221 ignored. B<WARNING> setting this option for anything other than debugging
222 purposes can be a security risk. Finer control over which extensions are
223 supported can be performed in the verification callback.
225 The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken
226 certificates and makes the verification strictly apply B<X509> rules.
228 B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification.
230 B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default
231 no policy checking is performed. Additional information is sent to the
232 verification callback relating to policy checking.
234 B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
235 B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any
236 policy> and B<inhibit policy mapping> flags respectively as defined in
237 B<RFC3280>. Policy checking is automatically enabled if any of these flags
240 If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful
241 a special status code is set to the verification callback. This permits it
242 to examine the valid policy tree and perform additional checks or simply
243 log it for debugging purposes.
245 By default some additional features such as indirect CRLs and CRLs signed by
246 different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set
249 If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to
250 determine certificate status. If not set deltas are ignored.
252 B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed
253 certificate signature. By default this check is disabled because it doesn't
254 add any additional security but in some cases applications might want to
255 check the signature anyway. A side effect of not checking the root CA
256 signature is that disabled or unsupported message digests on the root CA
257 are not treated as fatal errors.
259 When B<X509_V_FLAG_TRUSTED_FIRST> is set, construction of the certificate chain
260 in L<X509_verify_cert(3)> will search the trust store for issuer certificates
261 before searching the provided untrusted certificates.
262 Local issuer certificates are often more likely to satisfy local security
263 requirements and lead to a locally trusted root.
264 This is especially important when some certificates in the trust store have
265 explicit trust settings (see "TRUST SETTINGS" in L<x509(1)>).
266 As of OpenSSL 1.1.0 this option is on by default.
268 The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
270 By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a
271 certificate chain, if the first certificate chain found is not trusted, then
272 OpenSSL will attempt to replace untrusted certificates supplied by the peer
273 with certificates from the trust store to see if an alternative chain can be
274 found that is trusted.
275 As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
278 The B<X509_V_FLAG_PARTIAL_CHAIN> flag causes intermediate certificates in the
279 trust store to be treated as trust-anchors, in the same way as the self-signed
280 root CA certificates.
281 This makes it possible to trust certificates issued by an intermediate CA
282 without having to trust its ancestor root CA.
283 With OpenSSL 1.1.0 and later and <X509_V_FLAG_PARTIAL_CHAIN> set, chain
284 construction stops as soon as the first certificate from the trust store is
285 added to the chain, whether that certificate is a self-signed "root"
286 certificate or a not self-signed intermediate certificate.
287 Thus, when an intermediate certificate is found in the trust store, the
288 verified chain passed to callbacks may be shorter than it otherwise would
289 be without the B<X509_V_FLAG_PARTIAL_CHAIN> flag.
291 The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
292 of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
293 is used to specify a verification time, the check is not suppressed.
295 =head1 INHERITANCE FLAGS
297 These flags specify how parameters are "inherited" from one structure to
300 If B<X509_VP_FLAG_ONCE> is set then the current setting is zeroed
303 If B<X509_VP_FLAG_LOCKED> is set then no values are copied. This overrides
304 all of the following flags.
306 If B<X509_VP_FLAG_DEFAULT> is set then anything set in the source is copied
307 to the destination. Effectively the values in "to" become default values
308 which will be used only if nothing new is set in "from". This is the
311 If B<X509_VP_FLAG_OVERWRITE> is set then all value are copied across whether
312 they are set or not. Flags is still Ored though.
314 If B<X509_VP_FLAG_RESET_FLAGS> is set then the flags value is copied instead
319 The above functions should be used to manipulate verification parameters
320 instead of functions which work in specific structures such as
321 X509_STORE_CTX_set_flags() which are likely to be deprecated in a future
326 Delta CRL checking is currently primitive. Only a single delta can be used and
327 (partly due to limitations of B<X509_STORE>) constructed CRLs are not
330 If CRLs checking is enable CRLs are expected to be available in the
331 corresponding B<X509_STORE> structure. No attempt is made to download
332 CRLs from the CRL distribution points extension.
336 Enable CRL checking when performing certificate verification during SSL
337 connections associated with an B<SSL_CTX> structure B<ctx>:
339 X509_VERIFY_PARAM *param;
341 param = X509_VERIFY_PARAM_new();
342 X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
343 SSL_CTX_set1_param(ctx, param);
344 X509_VERIFY_PARAM_free(param);
348 L<X509_verify_cert(3)>,
349 L<X509_check_host(3)>,
350 L<X509_check_email(3)>,
356 The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
357 The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in
358 OpenSSL 1.1.0, and has no effect.
360 X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i.
364 Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved.
366 Licensed under the OpenSSL license (the "License"). You may not use
367 this file except in compliance with the License. You can obtain a copy
368 in the file LICENSE in the source distribution or at
369 L<https://www.openssl.org/source/license.html>.