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