Skip CN DNS name constraint checks when not needed

[oweals/openssl.git] / doc / man3 / X509_VERIFY_PARAM_set_flags.pod

diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index 2800cd441d74ade2bc49ae82613b918db60afcd8..61b52efeea84f05c4d1e4cd11890611482731c6e 100644 (file)
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -2,33 +2,52 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
+X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags,
+X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose,
+X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags,
+X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth,
+X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level,
+X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time,
+X509_VERIFY_PARAM_get_time,
+X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies,
+X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host,
+X509_VERIFY_PARAM_set_hostflags,
+X509_VERIFY_PARAM_get_hostflags,
+X509_VERIFY_PARAM_get0_peername,
+X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip,
+X509_VERIFY_PARAM_set1_ip_asc
+- X509 verification parameters

 
 =head1 SYNOPSIS
 
  #include <openssl/x509_vfy.h>
 
  int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param,
 
 =head1 SYNOPSIS
 
  #include <openssl/x509_vfy.h>
 
  int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param,

-                                        unsigned long flags);
+                                 unsigned long flags);

  int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param,
  int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param,

-                                        unsigned long flags);
+                                   unsigned long flags);

  unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param);
 
  unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param);
 

+ int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param,
+                                     uint32_t flags);
+ uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param);
+

  int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose);
  int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust);
 
  void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t);
  int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose);
  int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust);
 
  void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t);

+ time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param);

 
  int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,
 
  int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,

-                                        ASN1_OBJECT *policy);
+                                   ASN1_OBJECT *policy);

  int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param,
  int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param,

-                                        STACK_OF(ASN1_OBJECT) *policies);
+                                     STACK_OF(ASN1_OBJECT) *policies);

 
  void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
  int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
 
  void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param,
 
  void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
  int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
 
  void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param,

-                                        int auth_level);
+                                       int auth_level);

  int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param);
 
  int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
  int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param);
 
  int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,


@@ -37,9 +56,10 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge
                                  const char *name, size_t namelen);
  void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
                                       unsigned int flags);
                                  const char *name, size_t namelen);
  void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
                                       unsigned int flags);

+ unsigned int X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param);

  char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
  int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
  char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
  int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,

-                                 const char *email, size_t emaillen);
+                                  const char *email, size_t emaillen);

  int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
                                const unsigned char *ip, size_t iplen);
  int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
  int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
                                const unsigned char *ip, size_t iplen);
  int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);


@@ -55,6 +75,11 @@ description of values the B<flags> parameter can take.
 
 X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
 
 
 X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
 

+X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param>
+which specifies how verification flags are copied from one structure to
+another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags.
+See the B<INHERITANCE FLAGS> section for a description of these bits.
+

 X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
 
 X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
 X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
 
 X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>


@@ -108,14 +133,32 @@ B<name> clearing any previously specified host name or names.  If
 B<name> is NULL, or empty the list of hostnames is cleared, and
 name checks are not performed on the peer certificate.  If B<name>
 is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
 B<name> is NULL, or empty the list of hostnames is cleared, and
 name checks are not performed on the peer certificate.  If B<name>
 is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>

-must be set to the length of B<name>.  When a hostname is specified,
+must be set to the length of B<name>.
+
+When a hostname is specified,

 certificate verification automatically invokes L<X509_check_host(3)>
 with flags equal to the B<flags> argument given to
 X509_VERIFY_PARAM_set_hostflags() (default zero).  Applications
 are strongly advised to use this interface in preference to explicitly
 certificate verification automatically invokes L<X509_check_host(3)>
 with flags equal to the B<flags> argument given to
 X509_VERIFY_PARAM_set_hostflags() (default zero).  Applications
 are strongly advised to use this interface in preference to explicitly

-calling L<X509_check_host(3)>, hostname checks are out of scope
+calling L<X509_check_host(3)>, hostname checks may be out of scope

 with the DANE-EE(3) certificate usage, and the internal check will
 with the DANE-EE(3) certificate usage, and the internal check will

-be suppressed as appropriate when DANE support is added to OpenSSL.
+be suppressed as appropriate when DANE verification is enabled.
+
+When the subject CommonName will not be ignored, whether as a result of the
+B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> host flag, or because no DNS subject
+alternative names are present in the certificate, any DNS name constraints in
+issuer certificates apply to the subject CommonName as well as the subject
+alternative name extension.
+
+When the subject CommonName will be ignored, whether as a result of the
+B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> host flag, or because some DNS subject
+alternative names are present in the certificate, DNS name constraints in
+issuer certificates will not be applied to the subject DN.
+As described in X509_check_host(3) the B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>
+flag takes precendence over the B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag.
+
+X509_VERIFY_PARAM_get_hostflags() returns any host flags previously set via a
+call to X509_VERIFY_PARAM_set_hostflags().

 
 X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
 identifier that can match the peer's certificate.  Any previous names
 
 X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
 identifier that can match the peer's certificate.  Any previous names


@@ -154,6 +197,7 @@ IPv6.  The condensed "::" notation is supported for IPv6 addresses.
 =head1 RETURN VALUES
 
 X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
 =head1 RETURN VALUES
 
 X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),

+X509_VERIFY_PARAM_set_inh_flags(),

 X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
 X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
 X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),
 X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
 X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
 X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),


@@ -163,6 +207,10 @@ failure.
 
 X509_VERIFY_PARAM_get_flags() returns the current verification flags.
 
 
 X509_VERIFY_PARAM_get_flags() returns the current verification flags.
 

+X509_VERIFY_PARAM_get_hostflags() returns any current host flags.
+
+X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags.
+

 X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return
 values.
 
 X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return
 values.
 


@@ -223,10 +271,14 @@ check the signature anyway. A side effect of not checking the root CA
 signature is that disabled or unsupported message digests on the root CA
 are not treated as fatal errors.
 
 signature is that disabled or unsupported message digests on the root CA
 are not treated as fatal errors.
 

-If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain,
-L<X509_verify_cert(3)> will search the trust store for issuer certificates before
-searching the provided untrusted certificates.
-As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
+When B<X509_V_FLAG_TRUSTED_FIRST> is set, construction of the certificate chain
+in L<X509_verify_cert(3)> will search the trust store for issuer certificates
+before searching the provided untrusted certificates.
+Local issuer certificates are often more likely to satisfy local security
+requirements and lead to a locally trusted root.
+This is especially important when some certificates in the trust store have
+explicit trust settings (see "TRUST SETTINGS" in L<x509(1)>).
+As of OpenSSL 1.1.0 this option is on by default.

 
 The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
 chains.
 
 The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
 chains.


@@ -238,15 +290,51 @@ found that is trusted.
 As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
 has no effect.
 
 As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
 has no effect.
 

+The B<X509_V_FLAG_PARTIAL_CHAIN> flag causes intermediate certificates in the
+trust store to be treated as trust-anchors, in the same way as the self-signed
+root CA certificates.
+This makes it possible to trust certificates issued by an intermediate CA
+without having to trust its ancestor root CA.
+With OpenSSL 1.1.0 and later and <X509_V_FLAG_PARTIAL_CHAIN> set, chain
+construction stops as soon as the first certificate from the trust store is
+added to the chain, whether that certificate is a self-signed "root"
+certificate or a not self-signed intermediate certificate.
+Thus, when an intermediate certificate is found in the trust store, the
+verified chain passed to callbacks may be shorter than it otherwise would
+be without the B<X509_V_FLAG_PARTIAL_CHAIN> flag.
+

 The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
 of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
 is used to specify a verification time, the check is not suppressed.
 
 The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
 of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
 is used to specify a verification time, the check is not suppressed.
 

+=head1 INHERITANCE FLAGS
+
+These flags specify how parameters are "inherited" from one structure to
+another.
+
+If B<X509_VP_FLAG_ONCE> is set then the current setting is zeroed
+after the next call.
+
+If B<X509_VP_FLAG_LOCKED> is set then no values are copied.  This overrides
+all of the following flags.
+
+If B<X509_VP_FLAG_DEFAULT> is set then anything set in the source is copied
+to the destination. Effectively the values in "to" become default values
+which will be used only if nothing new is set in "from".  This is the
+default.
+
+If B<X509_VP_FLAG_OVERWRITE> is set then all value are copied across whether
+they are set or not. Flags is still Ored though.
+
+If B<X509_VP_FLAG_RESET_FLAGS> is set then the flags value is copied instead
+of ORed.
+

 =head1 NOTES
 
 The above functions should be used to manipulate verification parameters
 =head1 NOTES
 
 The above functions should be used to manipulate verification parameters

-instead of legacy functions which work in specific structures such as
-X509_STORE_CTX_set_flags().
+instead of functions which work in specific structures such as
+X509_STORE_CTX_set_flags() which are likely to be deprecated in a future
+release.

 
 =head1 BUGS
 
 
 =head1 BUGS
 


@@ -263,28 +351,32 @@ CRLs from the CRL distribution points extension.
 Enable CRL checking when performing certificate verification during SSL
 connections associated with an B<SSL_CTX> structure B<ctx>:
 
 Enable CRL checking when performing certificate verification during SSL
 connections associated with an B<SSL_CTX> structure B<ctx>:
 

-  X509_VERIFY_PARAM *param;
-  param = X509_VERIFY_PARAM_new();
-  X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
-  SSL_CTX_set1_param(ctx, param);
-  X509_VERIFY_PARAM_free(param);
+ X509_VERIFY_PARAM *param;
+
+ param = X509_VERIFY_PARAM_new();
+ X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
+ SSL_CTX_set1_param(ctx, param);
+ X509_VERIFY_PARAM_free(param);

 
 =head1 SEE ALSO
 
 L<X509_verify_cert(3)>,
 L<X509_check_host(3)>,
 L<X509_check_email(3)>,
 
 =head1 SEE ALSO
 
 L<X509_verify_cert(3)>,
 L<X509_check_host(3)>,
 L<X509_check_email(3)>,

-L<X509_check_ip(3)>
+L<X509_check_ip(3)>,
+L<x509(1)>

 
 =head1 HISTORY
 
 The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
 
 =head1 HISTORY
 
 The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0

-The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of
+The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in

 OpenSSL 1.1.0, and has no effect.
 
 OpenSSL 1.1.0, and has no effect.
 

+X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i.
+

 =head1 COPYRIGHT
 
 =head1 COPYRIGHT
 

-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved.

 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy