When strict SCT fails record verification failure

[openssl.git] / doc / ssl / SSL_CTX_set_ct_validation_callback.pod

diff --git a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod
index ec51c75eb4d6de9765cc08fc7ef0b851caebccbf..bcd68d3393be08d6a4fa91ead5de30ca08c1dd95 100644 (file)
--- a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod
+++ b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod
@@ -33,21 +33,29 @@ The behaviour of the callback is determined by the B<validation_mode> argument,
 which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or
 B<SSL_CT_VALIDATION_STRICT> as described below.
 
+If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full
+TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer
+presents no valid SCTs the handshake will be aborted.
+If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue
+despite lack of valid SCTs.
+However, in that case if the verification status before the built-in callback
+was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the
+callback.
+Applications can call L<SSL_get_verify_result(3)> to check the status at
+handshake completion, even after session resumption since the verification
+status is part of the saved session state.
+See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>.
+
 If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the
-handshake continues regardless of the validation status of any SCTs.
-The application can inspect the validation status of the SCTs at handshake
-completion.
+handshake continues, and the verification status is not modified, regardless of
+the validation status of any SCTs.
+The application can still inspect the validation status of the SCTs at
+handshake completion.
 Note that with session resumption there will not be any SCTs presented during
 the handshake.
 Therefore, in applications that delay SCT policy enforcement until after
-handshake completion, SCT checks should only be performed when the session is
-not reused.
-See L<SSL_session_reused(3)>.
-
-If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full
-TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer
-presents no valid SCTs the handshake will be aborted.
-See L<SSL_set_verify(3)>.
+handshake completion, such delayed SCT checks should only be performed when the
+session is not resumed.
 
 SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback()
 register a custom callback that may implement a different policy than either of
@@ -112,6 +120,7 @@ callback) is set.
 =head1 SEE ALSO
 
 L<ssl(3)>,
+<SSL_get_verify_result(3)>,
 L<SSL_session_reused(3)>,
 L<SSL_set_verify(3)>,
 L<SSL_CTX_set_verify(3)>,