Commit 069181d7f3 for openssl.org

commit 069181d7f39beaae22bfa67bcba3c5fe93acafd4
Author: David Benjamin <davidben@google.com>
Date:   Mon Oct 20 17:38:14 2025 -0400

    doc: Discuss calling X509_verify_cert in cert_verify_callback

    Using SSL_CTX_set_cert_verify_callback but still calling
    X509_verify_cert is useful if applications want to dynamically
    configure the X509_STORE_CTX, or postprocess the result, in a way that
    does not quite fit the somewhat unpredictable behavior of the
    SSL_CTX_set_verify callback. (In my experience, applications rarely
    realize it is called multiple times. It's also too late at that point to
    reconfigure the X509_STORE_CTX as verification has already started.)

    There is one note in the docs that the callback needs to stash the
    verify result with X509_STORE_CTX_set_error, but it is not immediately
    obvious that X509_verify_cert will do so, or that it is the built-in
    behavior. Add a paragraph discussing this.

    Reviewed-by: Tim Hudson <tjh@openssl.org>
    Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
    Reviewed-by: Tomas Mraz <tomas@openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/28960)

diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
index 4d510f3041..d93916f3b2 100644
--- a/doc/man3/SSL_CTX_set_cert_verify_callback.pod
+++ b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
@@ -63,6 +63,11 @@ on resumption, even though no chain is presented int that case.
 Moreover, the calling application will be informed about the detailed result of
 the verification procedure and may elect to base further decisions on it.

+I<callback> may call L<X509_verify_cert(3)> to run the built-in verification
+function. This may be useful if application wishes to dynamically reconfigure
+I<x509_store_ctx> before verification, or postprocess the result. In this case,
+L<X509_verify_cert(3)> will set the B<error> member as described above.
+
 Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
 function set using L<SSL_CTX_set_verify(3)>.