Document the X509_V_FLAG_PARTIAL_CHAIN flag

[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 2ea4895338c94f8569d609b6490ce7ccf3c349a4..947bd8a232af0e00ad14b72582cfaf313fea6daf 100644 (file)
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -37,15 +37,15 @@ X509_VERIFY_PARAM_set1_ip_asc
  time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param);
 
  int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,
  time_t X509_VERIFY_PARAM_get_time(const 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,


@@ -56,7 +56,7 @@ X509_VERIFY_PARAM_set1_ip_asc
                                       unsigned int flags);
  char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
  int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
                                       unsigned int flags);
  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);


@@ -248,10 +248,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 +267,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 +309,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
 


@@ -311,6 +329,7 @@ Enable CRL checking when performing certificate verification during SSL
 connections associated with an B<SSL_CTX> structure B<ctx>:
 
  X509_VERIFY_PARAM *param;
 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);
  param = X509_VERIFY_PARAM_new();
  X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
  SSL_CTX_set1_param(ctx, param);


@@ -326,7 +345,7 @@ L<X509_check_ip(3)>
 =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.
 
 =head1 COPYRIGHT
 OpenSSL 1.1.0, and has no effect.
 
 =head1 COPYRIGHT