doc/man3/X509_VERIFY_PARAM_set_flags.pod

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