Commit ac5e2d22af for openssl.org
commit ac5e2d22afdb11ba1a2d6a51005433b2e686a0d5
Author: Dr. David von Oheimb <dev@ddvo.net>
Date: Fri Apr 11 20:01:38 2025 +0200
X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
MergeDate: Thu Jan 8 09:56:14 2026
(Merged from https://github.com/openssl/openssl/pull/29150)
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index 022aa733f2..81f4af3a81 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -76,54 +76,54 @@ X509_VERIFY_PARAM_set1_ip_asc
These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
a certificate verification operation.
-The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring
-it with B<flags>. See L</VERIFICATION FLAGS> for a complete
-description of values the B<flags> parameter can take.
+The X509_VERIFY_PARAM_set_flags() function sets the flags in I<param> by oring
+it with I<flags>. See L</VERIFICATION FLAGS> for a complete
+description of values the I<flags> parameter can take.
-X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
+X509_VERIFY_PARAM_get_flags() returns the flags in I<param>.
-X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param>
+X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in I<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.
+See the L</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_clear_flags() clears the flags I<flags> in I<param>.
-X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
-to B<purpose>. This determines the acceptable purpose of the certificate
+X509_VERIFY_PARAM_set_purpose() sets the verification purpose in I<param>
+to I<purpose>. This determines the acceptable purpose of the certificate
chain, for example B<X509_PURPOSE_SSL_CLIENT>.
-The purpose requirement is cleared if B<purpose> is X509_PURPOSE_DEFAULT_ANY.
+The purpose requirement is cleared if I<purpose> is B<X509_PURPOSE_DEFAULT_ANY>.
-X509_VERIFY_PARAM_get_purpose() returns the purpose in B<param>.
+X509_VERIFY_PARAM_get_purpose() returns the purpose in I<param>.
-X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
-B<trust>.
+X509_VERIFY_PARAM_set_trust() sets the trust setting in I<param> to
+I<trust>.
-X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to
-B<t>. Normally the current time is used.
+X509_VERIFY_PARAM_set_time() sets the verification time in I<param> to
+I<t>. Normally the current time is used.
-X509_VERIFY_PARAM_add0_policy() adds B<policy> to the acceptable policy set.
+X509_VERIFY_PARAM_add0_policy() adds I<policy> to the acceptable policy set.
Contrary to preexisting documentation of this function it does not enable
policy checking.
X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled
-by default) and sets the acceptable policy set to B<policies>. Any existing
-policy set is cleared. The B<policies> parameter can be B<NULL> to clear
+by default) and sets the acceptable policy set to I<policies>. Any existing
+policy set is cleared. The I<policies> parameter can be NULL to clear
an existing policy set.
-X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
+X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to I<depth>.
That is the maximum number of intermediate CA certificates that can appear in a
chain.
A maximal depth chain contains 2 more certificates than the limit, since
neither the end-entity certificate nor the trust-anchor count against this
limit.
-Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed
-directly by the trust anchor, while with a B<depth> limit of 1 there can be one
+Thus a I<depth> limit of 0 only allows the end-entity certificate to be signed
+directly by the trust anchor, while with a I<depth> limit of 1 there can be one
intermediate CA certificate between the trust anchor and the end-entity
certificate.
X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to
-B<auth_level>.
+I<auth_level>.
The authentication security level determines the acceptable signature and public
key strength when verifying certificate chains.
For a certificate chain to validate, the public keys of all the certificates
@@ -139,21 +139,21 @@ Security level 1 requires at least 80-bit-equivalent security and is broadly
interoperable, though it will, for example, reject MD5 signatures or RSA keys
shorter than 1024 bits.
-X509_VERIFY_PARAM_get0_host() returns the B<n>th expected DNS hostname that has
+X509_VERIFY_PARAM_get0_host() returns the I<n>th expected DNS hostname that has
been set using X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host().
-To obtain all names start with B<n> = 0 and increment B<n> as long as no NULL
+To obtain all names start with I<n> = 0 and increment I<n> as long as no NULL
pointer is returned.
-X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
-B<name> clearing any previously specified hostname. 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>
-must be set to the length of B<name>.
+X509_VERIFY_PARAM_set1_host() sets in I<param> the expected
+DNS hostname to I<name>, clearing any previously specified hostname.
+If I<name> is NULL or the empty string, the list of hostnames is cleared
+and hostname checks are not performed on the peer certificate.
+If I<name> is NUL-terminated, I<namelen> may be zero,
+otherwise I<namelen> must be set to the length of I<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
+with flags equal to the I<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 may be out of scope
@@ -176,10 +176,10 @@ flag takes precedence 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
+X509_VERIFY_PARAM_add1_host() adds I<name> as an additional reference
identifier that can match the peer's certificate. Any previous names
set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
-are retained, no change is made if B<name> is NULL or empty. When
+are retained, no change is made if I<name> is NULL or the empty string. When
multiple names are configured, the peer is considered verified when
any name matches.
@@ -190,28 +190,28 @@ reference identifier specifies a parent domain (starts with ".")
rather than a hostname, the peer name may be a wildcard name or a
sub-domain of the reference identifier respectively. The return
string is allocated by the library and is no longer valid once the
-associated B<param> argument is freed. Applications must not free
+associated I<param> argument is freed. Applications must not free
the return value.
X509_VERIFY_PARAM_get0_email() returns the expected RFC822 email address.
X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
-B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
-B<emaillen> must be set to the length of B<email>. When an email address
+I<email>. If I<email> is NUL-terminated, I<emaillen> may be zero, otherwise
+I<emaillen> must be set to the length of I<email>. When an email address
is specified, certificate verification automatically invokes
L<X509_check_email(3)>.
X509_VERIFY_PARAM_get1_ip_asc() returns the expected IP address as a string.
The caller is responsible for freeing it.
-X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>.
-The B<ip> argument is in binary format, in network byte-order and
-B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
+X509_VERIFY_PARAM_set1_ip() sets the expected IP address to I<ip>.
+The I<ip> argument is in binary format, in network byte-order and
+I<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
address is specified, certificate verification automatically invokes
L<X509_check_ip(3)>.
X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
-B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
+I<ipasc>. The I<ipasc> argument is a NUL-terminal ASCII string:
dotted decimal quad for IPv4 and colon-separated hexadecimal for
IPv6. The condensed "::" notation is supported for IPv6 addresses.
@@ -283,9 +283,9 @@ no policy checking is performed. Additional information is sent to the
verification callback relating to policy checking.
B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
-B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any
-policy> and B<inhibit policy mapping> flags respectively as defined in
-B<RFC3280>. Policy checking is automatically enabled if any of these flags
+B<X509_V_FLAG_INHIBIT_MAP> set the C<require explicit policy>, C<inhibit any
+policy> and C<inhibit policy mapping> flags respectively as defined in
+RFC 5280. Policy checking is automatically enabled if any of these flags
are set.
If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful
@@ -310,7 +310,7 @@ check the signature anyway. A side effect of not checking the self-signature
of such a certificate is that disabled or unsupported message digests used for
the signature are not treated as fatal errors.
-When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is always the case since
+When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is the default since
OpenSSL 1.1.0, construction of the certificate chain
in L<X509_verify_cert(3)> searches the trust store for issuer certificates
before searching the provided untrusted certificates.
@@ -319,22 +319,14 @@ 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<openssl-x509(1)>).
-The B<X509_V_FLAG_NO_ALT_CHAINS> flag could have been used before OpenSSL 1.1.0
-to suppress checking for alternative chains.
-By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a
-certificate chain, if the first certificate chain found is not trusted, then
-OpenSSL will attempt to replace untrusted certificates supplied by the peer
-with certificates from the trust store to see if an alternative chain can be
-found that is trusted.
-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_NO_ALT_CHAINS> flag suppresses checking for alternative chains.
The B<X509_V_FLAG_PARTIAL_CHAIN> flag causes non-self-signed certificates in the
trust store to be treated as trust anchors, in the same way as self-signed
root CA certificates.
This makes it possible to trust self-issued certificates as well as certificates
issued by an intermediate CA without having to trust their ancestor root CA.
-With OpenSSL 1.1.0 and later and B<X509_V_FLAG_PARTIAL_CHAIN> set, chain
+With B<X509_V_FLAG_PARTIAL_CHAIN> set, chain
construction stops as soon as the first certificate contained in the trust store
is added to the chain, whether that certificate is a self-signed "root"
certificate or a not self-signed "intermediate" or self-issued certificate.
@@ -394,7 +386,7 @@ CRLs from the CRL distribution points extension.
=head1 EXAMPLES
Enable CRL checking when performing certificate verification during SSL
-connections associated with an B<SSL_CTX> structure B<ctx>:
+connections associated with an B<SSL_CTX> structure I<ctx>:
X509_VERIFY_PARAM *param;
@@ -405,6 +397,7 @@ connections associated with an B<SSL_CTX> structure B<ctx>:
=head1 SEE ALSO
+L<SSL_CTX_set_security_level(3)>,
L<X509_verify_cert(3)>,
L<X509_check_host(3)>,
L<X509_check_email(3)>,
@@ -414,6 +407,13 @@ L<openssl-x509(1)>
=head1 HISTORY
+Until OpenSSL 1.1.0, by default (unless B<X509_V_FLAG_TRUSTED_FIRST> was set), when building a
+certificate chain, if the first certificate chain found was not trusted,
+OpenSSL would attempt to replace untrusted certificates supplied by the peer
+with certificates from the trust store to see if an alternative chain can be
+found that is trusted.
+Since OpenSSL 1.1.0 version, the B<X509_V_FLAG_TRUSTED_FIRST> is set by default.
+
The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0.
The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in OpenSSL 1.1.0
and has no effect.