NAME

ssl_ct_validation_cb, SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - control Certificate Transparency policy

SYNOPSIS

 #include <openssl/ssl.h>

 typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx,
                                    const STACK_OF(SCT) *scts, void *arg);

 int SSL_enable_ct(SSL *s, int validation_mode);
 int SSL_CTX_enable_ct(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_disable_ct(SSL *s);
 void SSL_CTX_disable_ct(SSL_CTX *ctx);
 int SSL_ct_is_enabled(const SSL *s);
 int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx);

DESCRIPTION

SSL_enable_ct() and SSL_CTX_enable_ct() 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 validation_mode argument, which can be either of SSL_CT_VALIDATION_PERMISSIVE or SSL_CT_VALIDATION_STRICT as described below.

If validation_mode is equal to SSL_CT_VALIDATION_STRICT, then in a full TLS handshake with the verification mode set to SSL_VERIFY_PEER, if the peer presents no valid SCTs the handshake will be aborted. If the verification mode is 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 X509_V_OK it will be set to X509_V_ERR_NO_VALID_SCTS after the callback. Applications can call SSL_set_verify(3), <SSL_get_verify_result(3)>, NOTES

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.

The time returned by SSL_SESSION_get_time() will be used to evaluate whether any presented SCTs have timestamps that are in the future (and therefore invalid).

RESTRICTIONS

Certificate Transparency validation cannot be enabled and so a callback cannot be set if a custom client extension handler has been registered to handle SCT extensions (TLSEXT_TYPE_signed_certificate_timestamp).

RETURN VALUES

SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback() return 1 if the 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_disable_ct() and SSL_CTX_disable_ct() do not return a result.

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.

SEE ALSO

SSL_session_reused(3), SSL_CTX_set_verify(3), COPYRIGHT

Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (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 https://www.openssl.org/source/license.html.