Bite the bullet, and attempt something close to documentation for X509_verify_cert. - #31314

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from #31314)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from #31314)

(cherry picked from commit b2a133e)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from #31314)

(cherry picked from commit b2a133e)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from #31314)

(cherry picked from commit b2a133e)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from #31314)

(cherry picked from commit b2a133e)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from openssl#31314)

I am doing this because I have need to add information that really does
belong here, and the current stuff is less documentation than more or
less some hand waving about how it works without any details

So to summarize the changes:

1) This documents the current way that X509_verify_cert goes about
building and verifying a chain, identifying the relevant flags that
can affect how this happens today, and cross references the correct page
to find the rest of the exhaustive list of verification flags and what they do.

2) This documents the verification callback and how it can be used
to affect the verification outcome, This includes warning potential
users of the callback of what returning values from it means,
the common ways to end up unintentionaly doing things you did not expect
with the callback, and that it depends upon internals and should not be
relied upon.

Reviewed-by: Saša Nedvědický <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
MergeDate: Wed Jun 10 11:33:13 2026
(Merged from openssl#31314)