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