doc: Discuss calling X509_verify_cert in cert_verify_callbackopenssl-3.2

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 <[email protected]>
Reviewed-by: Viktor Dukhovni <[email protected]>
Reviewed-by: Tomas Mraz <[email protected]>
(Merged from https://github.com/openssl/openssl/pull/28960)

(cherry picked from commit 069181d7f39beaae22bfa67bcba3c5fe93acafd4)

1 files changed, 5 insertions, 0 deletions

diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
index be59a548cbd..9e8b524a7df 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)>.