From: Dr. David von Oheimb Date: Fri, 11 Apr 2025 18:01:38 +0000 (+0200) Subject: X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts on X509_V_FLAG_NO_ALT_... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ac5e2d22afdb11ba1a2d6a51005433b2e686a0d5;p=thirdparty%2Fopenssl.git X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes Reviewed-by: Eugene Syromiatnikov Reviewed-by: Tomas Mraz 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 022aa733f29..81f4af3a817 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 structure associated with a certificate verification operation. -The X509_VERIFY_PARAM_set_flags() function sets the flags in B by oring -it with B. See L for a complete -description of values the B parameter can take. +The X509_VERIFY_PARAM_set_flags() function sets the flags in I by oring +it with I. See L for a complete +description of values the I parameter can take. -X509_VERIFY_PARAM_get_flags() returns the flags in B. +X509_VERIFY_PARAM_get_flags() returns the flags in I. -X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B +X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in I 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 section for a description of these bits. +See the L section for a description of these bits. -X509_VERIFY_PARAM_clear_flags() clears the flags B in B. +X509_VERIFY_PARAM_clear_flags() clears the flags I in I. -X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B -to B. This determines the acceptable purpose of the certificate +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in I +to I. This determines the acceptable purpose of the certificate chain, for example B. -The purpose requirement is cleared if B is X509_PURPOSE_DEFAULT_ANY. +The purpose requirement is cleared if I is B. -X509_VERIFY_PARAM_get_purpose() returns the purpose in B. +X509_VERIFY_PARAM_get_purpose() returns the purpose in I. -X509_VERIFY_PARAM_set_trust() sets the trust setting in B to -B. +X509_VERIFY_PARAM_set_trust() sets the trust setting in I to +I. -X509_VERIFY_PARAM_set_time() sets the verification time in B to -B. Normally the current time is used. +X509_VERIFY_PARAM_set_time() sets the verification time in I to +I. Normally the current time is used. -X509_VERIFY_PARAM_add0_policy() adds B to the acceptable policy set. +X509_VERIFY_PARAM_add0_policy() adds I 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. Any existing -policy set is cleared. The B parameter can be B to clear +by default) and sets the acceptable policy set to I. Any existing +policy set is cleared. The I parameter can be NULL to clear an existing policy set. -X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B. +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to I. 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 limit of 0 only allows the end-entity certificate to be signed -directly by the trust anchor, while with a B limit of 1 there can be one +Thus a I limit of 0 only allows the end-entity certificate to be signed +directly by the trust anchor, while with a I 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. +I. 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 Bth expected DNS hostname that has +X509_VERIFY_PARAM_get0_host() returns the Ith 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 = 0 and increment B as long as no NULL +To obtain all names start with I = 0 and increment I as long as no NULL pointer is returned. -X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to -B clearing any previously specified hostname. If -B is NULL, or empty the list of hostnames is cleared, and -name checks are not performed on the peer certificate. If B -is NUL-terminated, B may be zero, otherwise B -must be set to the length of B. +X509_VERIFY_PARAM_set1_host() sets in I the expected +DNS hostname to I, clearing any previously specified hostname. +If I is NULL or the empty string, the list of hostnames is cleared +and hostname checks are not performed on the peer certificate. +If I is NUL-terminated, I may be zero, +otherwise I must be set to the length of I. When a hostname is specified, certificate verification automatically invokes L -with flags equal to the B argument given to +with flags equal to the I argument given to X509_VERIFY_PARAM_set_hostflags() (default zero). Applications are strongly advised to use this interface in preference to explicitly calling L, hostname checks may be out of scope @@ -176,10 +176,10 @@ flag takes precedence over the B 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 as an additional reference +X509_VERIFY_PARAM_add1_host() adds I 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 is NULL or empty. When +are retained, no change is made if I 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 argument is freed. Applications must not free +associated I 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. If B is NUL-terminated, B may be zero, otherwise -B must be set to the length of B. When an email address +I. If I is NUL-terminated, I may be zero, otherwise +I must be set to the length of I. When an email address is specified, certificate verification automatically invokes L. 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. -The B argument is in binary format, in network byte-order and -B 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. +The I argument is in binary format, in network byte-order and +I must be set to 4 for IPv4 and 16 for IPv6. When an IP address is specified, certificate verification automatically invokes L. X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to -B. The B argument is a NUL-terminal ASCII string: +I. The I 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, B and -B set the B, B and B flags respectively as defined in -B. Policy checking is automatically enabled if any of these flags +B set the C, C and C flags respectively as defined in +RFC 5280. Policy checking is automatically enabled if any of these flags are set. If B 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 is set, which is always the case since +When B is set, which is the default since OpenSSL 1.1.0, construction of the certificate chain in L 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). -The B flag could have been used before OpenSSL 1.1.0 -to suppress checking for alternative chains. -By default, unless B 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 always set, this option -has no effect. +The B flag suppresses checking for alternative chains. The B 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 set, chain +With B 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 structure B: +connections associated with an B structure I: X509_VERIFY_PARAM *param; @@ -405,6 +397,7 @@ connections associated with an B structure B: =head1 SEE ALSO +L, L, L, L, @@ -414,6 +407,13 @@ L =head1 HISTORY +Until OpenSSL 1.1.0, by default (unless B 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 is set by default. + The B flag was added in OpenSSL 1.1.0. The flag B was deprecated in OpenSSL 1.1.0 and has no effect.