X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fssl%2FSSL_CTX_set_ct_validation_callback.pod;h=c481ecbc87b2b0222403b0289b350cacf4d91da1;hp=167a0445363ad72688ade89c784198e1c795774c;hb=9d8c2dfe14cb371d242c04a52182aa0aee25ed18;hpb=36cc1390f265ce5f07a8841c106a6e1e7e021678 diff --git a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod index 167a044536..c481ecbc87 100644 --- a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod +++ b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -2,39 +2,100 @@ =head1 NAME +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_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 - 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_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); =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, 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_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 B argument, +which can be either of B or +B as described below. + +If B is equal to B, then in a full +TLS handshake with the verification mode set to B, if the peer +presents no valid SCTs the handshake will be aborted. +If the verification mode is B, the handshake will continue +despite lack of valid SCTs. +However, in that case if the verification status before the built-in callback +was B it will be set to B after the +callback. +Applications can call L to check the status at +handshake completion, even after session resumption since the verification +status is part of the saved session state. +See L, , L. + +If B is equal to B, 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 +and the callback returns a non-positive result. + +An arbitrary callback context argument, B, 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_disable_ct() and SSL_CTX_disable_ct() 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_enable_ct() 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 @@ -42,24 +103,36 @@ 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 (B). -If an SCT callback is enabled, a handshake may fail if the peer does -not provide a certificate, which can happen when using opportunistic -encryption with anonymous (B) cipher-suites enabled on both ends. -SCTs should only be used when the application requires an authenticated -connection, and wishes to perform additional validation on that identity. - =head1 RETURN VALUES -SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback() -return 1 if the B is successfully set. They return 0 if an error -occurs, e.g. a custom client extension handler has been setup to handle SCTs. +SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and +SSL_set_ct_validation_callback() return 1 if the B 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_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, -L +, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016 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 +L. =cut