1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk Kimssl_ct_validation_cb, 6e71b7053SJung-uk KimSSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, 7e71b7053SJung-uk KimSSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, 8e71b7053SJung-uk KimSSL_ct_is_enabled, SSL_CTX_ct_is_enabled - 9e71b7053SJung-uk Kimcontrol Certificate Transparency policy 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim=head1 SYNOPSIS 12e71b7053SJung-uk Kim 13e71b7053SJung-uk Kim #include <openssl/ssl.h> 14e71b7053SJung-uk Kim 15e71b7053SJung-uk Kim typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, 16e71b7053SJung-uk Kim const STACK_OF(SCT) *scts, void *arg); 17e71b7053SJung-uk Kim 18e71b7053SJung-uk Kim int SSL_enable_ct(SSL *s, int validation_mode); 19e71b7053SJung-uk Kim int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); 20e71b7053SJung-uk Kim int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, 21e71b7053SJung-uk Kim void *arg); 22e71b7053SJung-uk Kim int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, 23e71b7053SJung-uk Kim ssl_ct_validation_cb callback, 24e71b7053SJung-uk Kim void *arg); 25e71b7053SJung-uk Kim void SSL_disable_ct(SSL *s); 26e71b7053SJung-uk Kim void SSL_CTX_disable_ct(SSL_CTX *ctx); 27e71b7053SJung-uk Kim int SSL_ct_is_enabled(const SSL *s); 28e71b7053SJung-uk Kim int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); 29e71b7053SJung-uk Kim 30e71b7053SJung-uk Kim=head1 DESCRIPTION 31e71b7053SJung-uk Kim 32e71b7053SJung-uk KimSSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed 33e71b7053SJung-uk Kimcertificate timestamps (SCTs) either for a given SSL connection or for all 34e71b7053SJung-uk Kimconnections that share the given SSL context, respectively. 35e71b7053SJung-uk KimThis is accomplished by setting a built-in CT validation callback. 36e71b7053SJung-uk KimThe behaviour of the callback is determined by the B<validation_mode> argument, 37e71b7053SJung-uk Kimwhich can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or 38e71b7053SJung-uk KimB<SSL_CT_VALIDATION_STRICT> as described below. 39e71b7053SJung-uk Kim 40e71b7053SJung-uk KimIf B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full 41e71b7053SJung-uk KimTLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer 42e71b7053SJung-uk Kimpresents no valid SCTs the handshake will be aborted. 43e71b7053SJung-uk KimIf the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue 44e71b7053SJung-uk Kimdespite lack of valid SCTs. 45e71b7053SJung-uk KimHowever, in that case if the verification status before the built-in callback 46e71b7053SJung-uk Kimwas B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the 47e71b7053SJung-uk Kimcallback. 48e71b7053SJung-uk KimApplications can call L<SSL_get_verify_result(3)> to check the status at 49e71b7053SJung-uk Kimhandshake completion, even after session resumption since the verification 50e71b7053SJung-uk Kimstatus is part of the saved session state. 51e71b7053SJung-uk KimSee L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>. 52e71b7053SJung-uk Kim 53e71b7053SJung-uk KimIf B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the 54e71b7053SJung-uk Kimhandshake continues, and the verification status is not modified, regardless of 55e71b7053SJung-uk Kimthe validation status of any SCTs. 56e71b7053SJung-uk KimThe application can still inspect the validation status of the SCTs at 57e71b7053SJung-uk Kimhandshake completion. 58e71b7053SJung-uk KimNote that with session resumption there will not be any SCTs presented during 59e71b7053SJung-uk Kimthe handshake. 60e71b7053SJung-uk KimTherefore, in applications that delay SCT policy enforcement until after 61e71b7053SJung-uk Kimhandshake completion, such delayed SCT checks should only be performed when the 62e71b7053SJung-uk Kimsession is not resumed. 63e71b7053SJung-uk Kim 64e71b7053SJung-uk KimSSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() 65e71b7053SJung-uk Kimregister a custom callback that may implement a different policy than either of 66e71b7053SJung-uk Kimthe above. 67e71b7053SJung-uk KimThis callback can examine the peer's SCTs and determine whether they are 68e71b7053SJung-uk Kimsufficient to allow the connection to continue. 69e71b7053SJung-uk KimThe TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> 70e71b7053SJung-uk Kimand the callback returns a non-positive result. 71e71b7053SJung-uk Kim 72*b077aed3SPierre ProncheryAn arbitrary callback data argument, B<arg>, can be passed in when setting 73e71b7053SJung-uk Kimthe callback. 74e71b7053SJung-uk KimThis will be passed to the callback whenever it is invoked. 75e71b7053SJung-uk KimOwnership of this context remains with the caller. 76e71b7053SJung-uk Kim 77e71b7053SJung-uk KimIf no callback is set, SCTs will not be requested and Certificate Transparency 78e71b7053SJung-uk Kimvalidation will not occur. 79e71b7053SJung-uk Kim 80e71b7053SJung-uk KimNo callback will be invoked when the peer presents no certificate, e.g. by 81e71b7053SJung-uk Kimemploying an anonymous (aNULL) cipher suite. 82e71b7053SJung-uk KimIn that case the handshake continues as it would had no callback been 83e71b7053SJung-uk Kimrequested. 84e71b7053SJung-uk KimCallbacks are also not invoked when the peer certificate chain is invalid or 85e71b7053SJung-uk Kimvalidated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 86e71b7053SJung-uk KimPKI, or no X.509 PKI at all, respectively. 87e71b7053SJung-uk KimClients that require SCTs are expected to not have enabled any aNULL ciphers 88e71b7053SJung-uk Kimnor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA 89e71b7053SJung-uk Kimrecords. 90e71b7053SJung-uk Kim 91e71b7053SJung-uk KimSSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether 92e71b7053SJung-uk Kimenabled via the built-in or the custom callbacks, by setting a NULL callback. 93e71b7053SJung-uk KimThese may be implemented as macros. 94e71b7053SJung-uk Kim 95e71b7053SJung-uk KimSSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is 96e71b7053SJung-uk Kimenabled via either SSL_enable_ct() or a non-null custom callback, and 0 97e71b7053SJung-uk Kimotherwise. 98e71b7053SJung-uk Kim 99e71b7053SJung-uk Kim=head1 NOTES 100e71b7053SJung-uk Kim 101e71b7053SJung-uk KimWhen SCT processing is enabled, OCSP stapling will be enabled. This is because 102e71b7053SJung-uk Kimone possible source of SCTs is the OCSP response from a server. 103e71b7053SJung-uk Kim 104e71b7053SJung-uk KimThe time returned by SSL_SESSION_get_time() will be used to evaluate whether any 105e71b7053SJung-uk Kimpresented SCTs have timestamps that are in the future (and therefore invalid). 106e71b7053SJung-uk Kim 107e71b7053SJung-uk Kim=head1 RESTRICTIONS 108e71b7053SJung-uk Kim 109e71b7053SJung-uk KimCertificate Transparency validation cannot be enabled and so a callback cannot 110e71b7053SJung-uk Kimbe set if a custom client extension handler has been registered to handle SCT 111e71b7053SJung-uk Kimextensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). 112e71b7053SJung-uk Kim 113e71b7053SJung-uk Kim=head1 RETURN VALUES 114e71b7053SJung-uk Kim 115e71b7053SJung-uk KimSSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and 116e71b7053SJung-uk KimSSL_set_ct_validation_callback() return 1 if the B<callback> is successfully 117e71b7053SJung-uk Kimset. 118e71b7053SJung-uk KimThey return 0 if an error occurs, e.g. a custom client extension handler has 119e71b7053SJung-uk Kimbeen setup to handle SCTs. 120e71b7053SJung-uk Kim 121e71b7053SJung-uk KimSSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. 122e71b7053SJung-uk Kim 123e71b7053SJung-uk KimSSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT 124e71b7053SJung-uk Kimvalidation callback is set, or 0 if no callback (or equivalently a NULL 125e71b7053SJung-uk Kimcallback) is set. 126e71b7053SJung-uk Kim 127e71b7053SJung-uk Kim=head1 SEE ALSO 128e71b7053SJung-uk Kim 129e71b7053SJung-uk KimL<ssl(7)>, 130e71b7053SJung-uk Kim<SSL_get_verify_result(3)>, 131e71b7053SJung-uk KimL<SSL_session_reused(3)>, 132e71b7053SJung-uk KimL<SSL_set_verify(3)>, 133e71b7053SJung-uk KimL<SSL_CTX_set_verify(3)>, 134e71b7053SJung-uk KimL<SSL_SESSION_get_time(3)> 135e71b7053SJung-uk Kim 136e71b7053SJung-uk Kim=head1 COPYRIGHT 137e71b7053SJung-uk Kim 138*b077aed3SPierre ProncheryCopyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 139e71b7053SJung-uk Kim 140*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 141e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 142e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 143e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 144e71b7053SJung-uk Kim 145e71b7053SJung-uk Kim=cut 146