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