Fix typo in CONTRIBUTING.md

[openssl.git] / doc / man3 / SSL_CTX_set_cert_verify_callback.pod

diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
index 0c3378db660ec1ccec98a1737092dec6fae61f93..be59a548cbd9ea3f05d29eed293dbfc1bdda50c6 100644 (file)
--- a/doc/man3/SSL_CTX_set_cert_verify_callback.pod
+++ b/doc/man3/SSL_CTX_set_cert_verify_callback.pod
@@ -20,24 +20,48 @@ 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. 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!
+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 of 0 leads to handshake failure.
+In client mode, the behaviour is as follows.
+All values, including 0, are ignored
+if the verification mode is B<SSL_VERIFY_NONE>.
+Otherwise, when the return value is less than or equal to 0, the handshake will
+fail.
+
+In client mode I<callback> may also call the L<SSL_set_retry_verify(3)>
+function on the B<SSL> object set in the I<x509_store_ctx> ex data (see
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>) and return 1. This would be
+typically done in case the certificate verification was not yet able
+to succeed. This makes the handshake suspend and return control to the
+calling application with B<SSL_ERROR_WANT_RETRY_VERIFY>. The app can for
+instance fetch further certificates or cert status information needed for
+the verification. 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.
+
+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)>.
@@ -65,14 +89,16 @@ 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_set_retry_verify(3)>,
 L<SSL_CTX_load_verify_locations(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.