=head1 NAME
+SSL_ct_enable, SSL_CTX_ct_enable, SSL_ct_disable, SSL_CTX_ct_disable,
SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,
-SSL_get_ct_validation_callback, SSL_CTX_get_ct_validation_callback -
+SSL_ct_is_enabled, SSL_CTX_ct_is_enabled -
control Certificate Transparency policy
=head1 SYNOPSIS
#include <openssl/ssl.h>
- int SSL_set_ct_validation_callback(SSL *s, ct_validation_cb callback, void *arg);
- int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, ct_validation_cb callback, void *arg);
- ct_validation_cb SSL_get_ct_validation_callback(const SSL *s);
- ct_validation_cb SSL_CTX_get_ct_validation_callback(const SSL_CTX *ctx);
+ int SSL_ct_enable(SSL *s, int validation_mode);
+ int SSL_CTX_ct_enable(SSL_CTX *ctx, int validation_mode);
+ int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback,
+ void *arg);
+ int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx,
+ ssl_ct_validation_cb callback,
+ void *arg);
+ void SSL_ct_disable(SSL *s);
+ void SSL_CTX_ct_disable(SSL_CTX *ctx);
+ int SSL_ct_is_enabled(const SSL *s);
+ int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx);
=head1 DESCRIPTION
-SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() set
-the function that is called when Certificate Transparency validation needs to
-occur. It is the responsibility of this function to examine the signed
-certificate timestamps (SCTs) that are passed to it and determine whether they
-are sufficient to allow the connection to continue. If they are, the function
-must return 1, otherwise it must return 0.
-
-An arbitrary piece of user data, B<arg>, can be passed in when setting the
-callback. This will be passed to the callback whenever it is invoked. Ownership
-of this userdata remains with the caller.
+SSL_ct_enable() and SSL_CTX_ct_enable() enable the processing of signed
+certificate timestamps (SCTs) either for a given SSL connection or for all
+connections that share the given SSL context, respectively.
+This is accomplished by setting a built-in CT validation callback.
+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, 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, 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
+the above.
+This callback can examine the peer's SCTs and determine whether they are
+sufficient to allow the connection to continue.
+The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE>
+and the callback returns a non-positive result.
+
+An arbitrary callback context argument, B<arg>, can be passed in when setting
+the callback.
+This will be passed to the callback whenever it is invoked.
+Ownership of this context remains with the caller.
If no callback is set, SCTs will not be requested and Certificate Transparency
validation will not occur.
+No callback will be invoked when the peer presents no certificate, e.g. by
+employing an anonymous (aNULL) ciphersuite.
+In that case the handshake continues as it would had no callback been
+requested.
+Callbacks are also not invoked when the peer certificate chain is invalid or
+validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509
+PKI, or no X.509 PKI at all, respectively.
+Clients that require SCTs are expected to not have enabled any aNULL ciphers
+nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA
+records.
+
+SSL_ct_disable() and SSL_CTX_ct_disable() turn off CT processing, whether
+enabled via the built-in or the custom callbacks, by setting a NULL callback.
+These may be implemented as macros.
+
+SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is
+enabled via either SSL_ct_enable() or a non-null custom callback, and 0
+otherwise.
+
=head1 NOTES
-If a callback is set, OCSP stapling will be enabled. This is because one
-possible source of SCTs is the OCSP response from a server.
+When SCT processing is enabled, OCSP stapling will be enabled. This is because
+one possible source of SCTs is the OCSP response from a server.
=head1 RESTRICTIONS
=head1 RETURN VALUES
-SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback()
-return 1 if the B<callback> is successfully set. They return 0 if an error
-occurs, e.g. a custom client extension handler has been setup to handle SCTs.
+SSL_ct_enable(), SSL_CTX_ct_enable(), SSL_CTX_set_ct_validation_callback() and
+SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully
+set.
+They return 0 if an error occurs, e.g. a custom client extension handler has
+been setup to handle SCTs.
+
+SSL_ct_disable() and SSL_CTX_ct_disable() do not return a result.
-SSL_CTX_get_ct_validation_callback() and SSL_get_ct_validation_callback()
-return the current callback, or NULL if no callback is set.
+SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT
+validation callback is set, or 0 if no callback (or equivalently a NULL
+callback) is set.
=head1 SEE ALSO
L<ssl(3)>,
-L<ct_validation_cb(3)>
+<SSL_get_verify_result(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_set_verify(3)>,
+L<SSL_CTX_set_verify(3)>,
+L<ssl_ct_validation_cb(3)>
=cut
projects / openssl.git / blobdiff