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