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