Commit fc2668e0b3 for openssl.org

commit fc2668e0b33f02a076bc7e356ad6c754f7b39e93
Author: Bob Beck <beck@openssl.org>
Date:   Thu Jul 16 12:47:12 2026 +0200

    Clarify the X509_VERIFY_PARAM_set_trust() documentation

    Spell out that the X509_TRUST_* selectors do not check the extKeyUsage
    extension they appear to name: they match only auxiliary trust
    information attached to the in-memory certificate from outside, so absent
    that they have no effect. Mark the selector as a legacy mechanism and
    point callers at X509_VERIFY_PARAM_set_purpose() instead.

    Documentation only; no behavioural change.

    Reviewed-by: Neil Horman <nhorman@openssl.org>
    Reviewed-by: Andrew Dinh <andrewd@openssl.org>
    MergeDate: Tue Aug 18 15:17:16 2026
    (Merged from https://github.com/openssl/openssl/pull/31972)

diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index a5c4d60a17..7f953f9a9f 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -88,12 +88,9 @@ X509_VERIFY_PARAM_get_purpose() returns the purpose in I<param>.

 X509_VERIFY_PARAM_set_trust() sets the trust selector in I<param> to
 I<trust>, which must be one of the B<X509_TRUST_*> identifiers defined
-in F<openssl/x509_vfy.h> (such as B<X509_TRUST_SSL_SERVER>,
-B<X509_TRUST_SSL_CLIENT>, B<X509_TRUST_EMAIL>, or B<X509_TRUST_OBJECT_SIGN>).
-The trust selector determines how explicit trust settings recorded on
-trust-anchor certificates are matched against the verification operation;
-see the TRUST SETTINGS section of L<openssl-x509(1)>. There is no
-public getter for the trust selector.
+in F<openssl/x509_vfy.h>. This is a legacy mechanism that most
+applications should not use; see L</BUGS>. There is no public getter
+for the trust selector.

 X509_VERIFY_PARAM_set_time() sets the verification time in I<param> to
 I<t>, which is then used as the reference time for certificate and CRL
@@ -374,6 +371,15 @@ If CRL checking is enabled, CRLs are expected to be available in the
 corresponding B<X509_STORE> structure. No attempt is made to download
 CRLs from the CRL distribution points extension.

+The B<X509_TRUST_*> selectors used by X509_VERIFY_PARAM_set_trust() are
+deceptively named: although each mirrors a PKIX extended key usage, the
+selector does not check that B<extKeyUsage>. It matches only auxiliary
+trust information that is never carried in the certificate itself but
+must be attached to the in-memory B<X509> object by the application;
+absent that, the selector has no effect. Use
+X509_VERIFY_PARAM_set_purpose() to constrain a certificate by its
+extended key usage instead.
+
 =head1 EXAMPLES

 Enable CRL checking when performing certificate verification during SSL
diff --git a/doc/man3/X509_VERIFY_PARAM_set_hostflags.pod b/doc/man3/X509_VERIFY_PARAM_set_hostflags.pod
index 9b8fe6ba35..714334d886 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_hostflags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_hostflags.pod
@@ -99,7 +99,7 @@ X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i.

 =head1 COPYRIGHT

-Copyright 2012-2026 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2026 The OpenSSL Project Authors. All Rights Reserved.

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