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)

(cherry picked from commit 069181d7f39beaae22bfa67bcba3c5fe93acafd4)

diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
index 4d510f3041d4593d5ffa0c8194bda868b9651750..d93916f3b2482ec31f3a0b69f4b731bd585b89af 100644 (file)
--- 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)>.