SSL_CTX_set_cert_verify_callback.pod: various corrections and clarifications

- Make clear the callback is called whenever a peer certificate has been received,
  which is independent of the verification mode.
- Make clear that a return value > 1 always leads to handshake failure.
- Make clear that in server mode also return values <= 0 lead to handshake failure.
- For client mode replace the incorrect formulation "if B<SSL_VERIFY_PEER> is set"
  by what is actually implemented: "if the verification mode is not B<SSL_VERIFY_NONE>".
- Refer to X509_STORE_CTX_set_error() rather than to internal error variable.

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13937)

diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
index 6a482ece5a338f7b93bec3850a1ceb17cd95ce5b..87ea772fb73bcccee70434443497036289639293 100644 (file)
--- a/doc/man3/SSL_CTX_set_cert_verify_callback.pod
+++ b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
@@ -20,20 +20,23 @@ the time when L<SSL_new(3)> is called.
 
 =head1 NOTES
 
-Whenever a certificate is verified during a SSL/TLS handshake, a verification
-function is called. If the application does not explicitly specify a
-verification callback function, the built-in verification function is used.
+When a peer certificate has been received during a SSL/TLS handshake,
+a verification function is called regardless of the verification mode.
+If the application does not explicitly specify a verification callback function,
+the built-in verification function is used.
 If a verification callback I<callback> is specified via
 SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
-instead. By setting I<callback> to NULL, the default behaviour is restored.
-
-When the verification must be performed, I<callback> will be called with
-the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
-argument I<arg> is specified by the application when setting I<callback>.
-
-I<callback> should return 1 to indicate verification success and 0 to
-indicate verification failure. If SSL_VERIFY_PEER is set and I<callback>
-returns 0, the handshake will fail.
+instead with the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg).
+The argument I<arg> is specified by the application when setting I<callback>.
+By setting I<callback> to NULL, the default behaviour is restored.
+
+I<callback> should return 1 to indicate verification success
+and 0 to indicate verification failure.
+In server mode, a return value other than 1 leads to handshake failure.
+In client mode, the behaviour is as follows.
+A return value greater than 1 leads to handshake failure.
+Other values are ignored if the verification mode is B<SSL_VERIFY_NONE>.
+On return value 0 the handshake will fail.
 
 In client mode I<callback> may also return -1,
 typically on failure verifying the server certificate.
@@ -45,11 +48,18 @@ Calling L<SSL_connect(3)> again resumes the connection attempt
 by retrying the server certificate verification step.
 This process may even be repeated if need be.
 
-As the verification procedure may
-allow the connection to continue in the case of failure (by always
-returning 1) the verification result must be set in any case using the
-B<error> member of I<x509_store_ctx> so that the calling application
-will be informed about the detailed result of the verification procedure!
+In any case a viable verification result value must be reflected
+in the B<error> member of I<x509_store_ctx>,
+which can be done using L<X509_STORE_CTX_set_error(3)>.
+This is particularly important in case
+the I<callback> allows the connection to continue (by returning 1).
+Note that the verification status in the store context is a possibly durable
+indication of the chain's validity!
+This gets recorded in the SSL session (and thus also in session tickets)
+and the validity of the originally presented chain is then visible
+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.
 
 Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
 function set using L<SSL_CTX_set_verify(3)>.
@@ -77,6 +87,7 @@ SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_CTX_set_verify(3)>,
+L<X509_STORE_CTX_set_error(3)>,
 L<SSL_get_verify_result(3)>,
 L<SSL_CTX_load_verify_locations(3)>