DOC: improve `X509_VERIFY_PARAM_set_flags.pod` by DDvO · Pull Request #29150 · openssl/openssl

DDvO · 2025-11-14T19:04:49Z

Three doc-only commits carved out from #27357.

Add recommendation that TLS clients should use SSL_set_tlsext_host_name() for SNI
and that this should be done jointly with using {SSL,X509_VERIFY_PARAM}_{set1,add1}_host().
fix doc of NULL param to X509_VERIFY_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()
remove heavily outdated texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes

Copilot

Pull Request Overview

This PR improves the documentation for X509_VERIFY_PARAM_set_flags.pod with three main enhancements:

Adds guidance on using X509_VERIFY_PARAM_set1_host() with SSL_set_tlsext_host_name() for TLS clients
Clarifies NULL parameter behavior for email, IP address, and hostname validation functions
Removes outdated information about X509_V_FLAG_NO_ALT_CHAINS from pre-OpenSSL 1.1.0

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

esyr

Please review the notes about empty strings for email/ip/ipasc; the rest is just formatting nits and can be ignored.

esyr · 2025-11-23T12:47:42Z

-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.


I would move this to a history section, so it's still possible to figure out what the code written against ancient OpenSSL version was trying to do.

Good point, done.

And restored the original doc line for X509_V_FLAG_NO_ALT_CHAINS, which I had changed in a wrong way due to a misunderstanding when doing commit ade0873.

esyr · 2025-11-23T12:56:30Z

 X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
-I<email>.  If I<email> is NUL-terminated, I<emaillen> may be zero, otherwise
+I<email>.
+If I<email> is NULL or the empty string, email checking is disabled.


It doesn't seem to me that the current code sets the email field to NULL if an empty string is passed, and I don't see where a check is skipped against an empty e-mail, are you sure about this statement?

Oh, right, email checking is disabled (by int_x509_param_set1() in crypto/x509/x509_vpn.c) only if email is NULL.

On this occasion, found and fixed a bug in the doc of the emaillen parameter
and for the namelen parameter of X509_VERIFY_PARAM_set1_host() .

esyr · 2025-11-23T13:00:27Z


 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
+If I<ip> is NULL or the empty string, IP address checking is disabled. Otherwise,


Ditto here wrt empty string case.

Yep, did the same fixes as above.

esyr · 2025-11-23T13:14:10Z

-X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
-I<ipasc>.  The I<ipasc> argument is a NUL-terminal ASCII string:
+X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to I<ipasc>.
+If I<ipasc> is NULL or the empty string, IP address checking is disabled.


Ditto here; moreover, it is impossible to specify an incorrectly-formatted IP-address here (which, in accordance with ossl_a2i_ipadd(), empty string is).

Very true - here ipasc must not be NULL nor the empty string. Sorry for my mistakes.
Removed again the new sentence.

DDvO · 2025-12-05T11:50:09Z

@esyr thank you for your helpful review.
I've recently handled all your comments.

t8m · 2025-12-05T16:50:18Z

+Until OpenSSL 1.1.0, 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 X509_V_FLAG_TRUSTED_FIRST can be still cleared, cannot it?

Suggested change

Until OpenSSL 1.1.0, 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.

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.

Good point - here I did not question the contents of the existing doc but just aimed at handling outdated version references, moving text to the history section where appropriate.

Yet I just had a look at the commit history:
Since commit 0daccd4, X509_V_FLAG_TRUSTED_FIRST is on by default, and it was documented that it cannot be disabled, but in commit f517911 this latter part was removed. I also see no reason why it should be impossible to clear it.

So changed this part as you suggested, and also did a similar change further up,
from
When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is always the case
to
When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is the default

…_PARAM_set1_host() and SSL_set_tlsext_host_name()

…9_V_FLAG_NO_ALT_CHAINS; other small fixes

… on X509_V_FLAG_NO_ALT_CHAINS; other small fixes

…d texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes

…_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

…_VERIFY_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

DDvO · 2025-12-22T18:25:42Z

Rebased on latest master

DDvO · 2026-01-02T12:30:34Z

@esyr @t8m ok now?

esyr

LGTM, thank you!

…to X509_VERIFY_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

openssl-machine · 2026-01-07T13:00:54Z

This pull request is ready to merge

…_PARAM_set1_host() and SSL_set_tlsext_host_name() Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:12 2026 (Merged from #29150)

…9_V_FLAG_NO_ALT_CHAINS; other small fixes Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:14 2026 (Merged from #29150)

…_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}() Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:15 2026 (Merged from #29150)

t8m · 2026-01-08T09:59:18Z

Merged to the master branch. Thank you for your contribution.

…_PARAM_set1_host() and SSL_set_tlsext_host_name() Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:12 2026 (Merged from openssl#29150)

…9_V_FLAG_NO_ALT_CHAINS; other small fixes Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:14 2026 (Merged from openssl#29150)

…_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}() Reviewed-by: Eugene Syromiatnikov <[email protected]> Reviewed-by: Tomas Mraz <[email protected]> MergeDate: Thu Jan 8 09:56:15 2026 (Merged from openssl#29150)

DDvO requested a review from Copilot November 14, 2025 19:04

DDvO added branch: master Applies to master branch approval: review pending This pull request needs review by a committer triaged: documentation The issue/pr deals with documentation (errors) tests: exempted The PR is exempt from requirements for testing labels Nov 14, 2025

Copilot started reviewing on behalf of DDvO November 14, 2025 19:05 View session

Copilot finished reviewing on behalf of DDvO November 14, 2025 19:05

Copilot AI reviewed Nov 14, 2025

View reviewed changes

Comment thread doc/man3/X509_VERIFY_PARAM_set_flags.pod Outdated

DDvO mentioned this pull request Nov 14, 2025

Fix URL scheme parsing and TLS Server Name Indication (SNI) and its use in apps/ #27357

Closed

2 tasks

DDvO force-pushed the improve_X509_VERIFY_PARAM_set_flags.pod branch from 3758245 to b1e5982 Compare November 14, 2025 19:10

DajanaV mentioned this pull request Nov 15, 2025

UPSTREAM PR #29150: DOC: improve X509_VERIFY_PARAM_set_flags.pod auroralabs-loci/openssl#95

Open

DDvO requested a review from t8m November 19, 2025 16:18

esyr requested changes Nov 23, 2025

View reviewed changes

DDvO requested a review from esyr December 3, 2025 16:57

t8m requested changes Dec 5, 2025

View reviewed changes

DDvO requested a review from t8m December 5, 2025 21:22

DDvO added 6 commits December 22, 2025 19:25

X509_VERIFY_PARAM_set_flags.pod: add hint on joint use of X509_VERIFY…

8536ae4

…_PARAM_set1_host() and SSL_set_tlsext_host_name()

X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts on X50…

1add76d

…9_V_FLAG_NO_ALT_CHAINS; other small fixes

fixup! X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts…

963586a

… on X509_V_FLAG_NO_ALT_CHAINS; other small fixes

fixup! fixup! X509_VERIFY_PARAM_set_flags.pod: remove heavily outdate…

3266275

…d texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes

X509_VERIFY_PARAM_set_flags.pod: fix doc of NULL param to X509_VERIFY…

dee9b88

…_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

fixup! X509_VERIFY_PARAM_set_flags.pod: fix doc of NULL param to X509…

5b32bc1

…_VERIFY_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

DDvO force-pushed the improve_X509_VERIFY_PARAM_set_flags.pod branch from 7288aec to 5b32bc1 Compare December 22, 2025 18:25

esyr previously approved these changes Jan 5, 2026

View reviewed changes

Comment thread doc/man3/X509_VERIFY_PARAM_set_flags.pod Outdated

fixup! fixup! X509_VERIFY_PARAM_set_flags.pod: fix doc of NULL param …

f89672f

…to X509_VERIFY_PARAM_set1_email() and X509_VERIFY_PARAM_set1{,_ip}()

DDvO dismissed esyr’s stale review via f89672f January 5, 2026 17:11

DDvO requested a review from esyr January 5, 2026 17:13

esyr approved these changes Jan 6, 2026

View reviewed changes

t8m approved these changes Jan 6, 2026

View reviewed changes

t8m added approval: done This pull request has the required number of approvals and removed approval: review pending This pull request needs review by a committer labels Jan 6, 2026

openssl-machine added approval: ready to merge The 24 hour grace period has passed, ready to merge and removed approval: done This pull request has the required number of approvals labels Jan 7, 2026

t8m closed this Jan 8, 2026

esyr mentioned this pull request Apr 14, 2026

[4.0] CHANGES.md: updates for 4.0.0 final release #30817

Closed

Uh oh!

Uh oh!

Conversation

DDvO commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

esyr left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DDvO Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DDvO commented Dec 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DDvO Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DDvO commented Dec 22, 2025

Uh oh!

DDvO commented Jan 2, 2026

Uh oh!

esyr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

openssl-machine commented Jan 7, 2026

Uh oh!

t8m commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

DDvO commented Nov 14, 2025 •

edited

Loading

esyr left a comment •

edited

Loading

DDvO Dec 3, 2025 •

edited

Loading

DDvO Dec 5, 2025 •

edited

Loading