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 e8428e1c570a142dc8f8c56a4ae7baf10bfec039..61b52efeea84f05c4d1e4cd11890611482731c6e 100644 (file)
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -11,7 +11,9 @@ 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_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_get0_peername,
+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
 X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip,
 X509_VERIFY_PARAM_set1_ip_asc
 - X509 verification parameters


@@ -54,6 +56,7 @@ X509_VERIFY_PARAM_set1_ip_asc
                                  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,
                                   const char *email, size_t emaillen);
  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);


@@ -130,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


@@ -186,6 +207,8 @@ 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
 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


@@ -248,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.


@@ -263,6 +290,19 @@ 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.


@@ -292,8 +332,9 @@ 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
 


@@ -322,17 +363,20 @@ connections associated with an B<SSL_CTX> structure B<ctx>:
 L<X509_verify_cert(3)>,
 L<X509_check_host(3)>,
 L<X509_check_email(3)>,
 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