From 18ad46297dcd44c1ac6c9f7f2f966e19c4d45e91 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Tue, 15 Nov 2016 16:34:18 -0500 Subject: [PATCH] Cherry-pick doc updates from PR 1554 Also fix version in libcrypto.num, from backporting new functions. Reviewed-by: Viktor Dukhovni Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/1554) (cherry picked from commit ebcb536858a271e8812fb9bbafbc0b825e5ece24) --- doc/CT_POLICY_EVAL_CTX_new.pod | 111 ++++++++++++++++ doc/SCT_validate.pod | 98 ++++++++++++++ doc/SSL_CTX_set_ct_validation_callback.pod | 142 +++++++++++++++++++++ util/libcrypto.num | 4 +- 4 files changed, 353 insertions(+), 2 deletions(-) create mode 100644 doc/CT_POLICY_EVAL_CTX_new.pod create mode 100644 doc/SCT_validate.pod create mode 100644 doc/SSL_CTX_set_ct_validation_callback.pod diff --git a/doc/CT_POLICY_EVAL_CTX_new.pod b/doc/CT_POLICY_EVAL_CTX_new.pod new file mode 100644 index 0000000000..fedc58d08a --- /dev/null +++ b/doc/CT_POLICY_EVAL_CTX_new.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, +CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, +CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, +CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, +CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - +Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy + +=head1 SYNOPSIS + + #include + + CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); + void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); + X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); + X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); + const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store); + uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); + +=head1 DESCRIPTION + +A B is used by functions that evaluate whether Signed +Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. +This policy may be, for example, that at least one valid SCT is available. To +determine this, an SCT's timestamp and signature must be verified. +This requires: + +=over + +=item * the public key of the log that issued the SCT + +=item * the certificate that the SCT was issued for + +=item * the issuer certificate (if the SCT was issued for a pre-certificate) + +=item * the current time + +=back + +The above requirements are met using the setters described below. + +CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This +should then be populated using: + +=over + +=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs + +Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the +CT_POLICY_EVAL_CTX. + +=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid + +The SCT timestamp will be compared to this time to check whether the SCT was +issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose +timestamp is in the future". By default, this will be set to 5 minutes in the +future (e.g. (time() + 300) * 1000), to allow for clock drift. + +The time should be in milliseconds since the Unix epoch. + +=back + +Each setter has a matching getter for accessing the current value. + +When no longer required, the B should be passed to +CT_POLICY_EVAL_CTX_free() to delete it. + +=head1 NOTES + +The issuer certificate only needs to be provided if at least one of the SCTs +was issued for a pre-certificate. This will be the case for SCTs embedded in a +certificate (i.e. those in an X.509 extension), but may not be the case for SCTs +found in the TLS SCT extension or OCSP response. + +=head1 RETURN VALUES + +CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=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 diff --git a/doc/SCT_validate.pod b/doc/SCT_validate.pod new file mode 100644 index 0000000000..9868a282b5 --- /dev/null +++ b/doc/SCT_validate.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +SCT_validate, SCT_LIST_validate, SCT_get_validation_status - +checks Signed Certificate Timestamps (SCTs) are valid + +=head1 SYNOPSIS + + #include + + typedef enum { + SCT_VALIDATION_STATUS_NOT_SET, + SCT_VALIDATION_STATUS_UNKNOWN_LOG, + SCT_VALIDATION_STATUS_VALID, + SCT_VALIDATION_STATUS_INVALID, + SCT_VALIDATION_STATUS_UNVERIFIED, + SCT_VALIDATION_STATUS_UNKNOWN_VERSION + } sct_validation_status_t; + + int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx); + int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx); + sct_validation_status_t SCT_get_validation_status(const SCT *sct); + +=head1 DESCRIPTION + +SCT_validate() will check that an SCT is valid and verify its signature. +SCT_LIST_validate() performs the same checks on an entire stack of SCTs. +The result of the validation checks can be obtained by passing the SCT to +SCT_get_validation_status(). + +A CT_POLICY_EVAL_CTX must be provided that specifies: + +=over + +=item * The certificate the SCT was issued for. + +Failure to provide the certificate will result in the validation status being +SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * The issuer of that certificate. + +This is only required if the SCT was issued for a pre-certificate +(see RFC 6962). If it is required but not provided, the validation status will +be SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * A CTLOG_STORE that contains the CT log that issued this SCT. + +If the SCT was issued by a log that is not in this CTLOG_STORE, the validation +status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. + +=back + +If the SCT is of an unsupported version (only v1 is currently supported), the +validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION. + +If the SCT's signature is incorrect, its timestamp is in the future (relative to +the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation +status will be SCT_VALIDATION_STATUS_INVALID. + +If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID. + +=head1 NOTES + +A return value of 0 from SCT_LIST_validate() should not be interpreted as a +failure. At a minimum, only one valid SCT may provide sufficient confidence +that a certificate has been publicly logged. + +=head1 RETURN VALUES + +SCT_validate() returns a negative integer if an internal error occurs, 0 if the +SCT fails validation, or 1 if the SCT passes validation. + +SCT_LIST_validate() returns a negative integer if an internal error occurs, 0 +if any of SCTs fails validation, or 1 if they all pass validation. + +SCT_get_validation_status() returns the validation status of the SCT. +If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the +returned value will be SCT_VALIDATION_STATUS_NOT_SET. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=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 diff --git a/doc/SSL_CTX_set_ct_validation_callback.pod b/doc/SSL_CTX_set_ct_validation_callback.pod new file mode 100644 index 0000000000..d818e00fc5 --- /dev/null +++ b/doc/SSL_CTX_set_ct_validation_callback.pod @@ -0,0 +1,142 @@ +=pod + +=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_ct_is_enabled, SSL_CTX_ct_is_enabled - +control Certificate Transparency policy + +=head1 SYNOPSIS + + #include + + 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_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 + +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). + +=head1 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 (B). + +=head1 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 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_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 diff --git a/util/libcrypto.num b/util/libcrypto.num index 46b549b328..15cf3f689b 100644 --- a/util/libcrypto.num +++ b/util/libcrypto.num @@ -4208,5 +4208,5 @@ OCSP_RESPID_set_by_key 4158 1_1_0a EXIST::FUNCTION:OCSP OCSP_RESPID_match 4159 1_1_0a EXIST::FUNCTION:OCSP DSO_pathbyaddr 4170 1_1_0c EXIST::FUNCTION: DSO_dsobyaddr 4171 1_1_0c EXIST::FUNCTION: -CT_POLICY_EVAL_CTX_get_time 4172 1_1_1 EXIST::FUNCTION:CT -CT_POLICY_EVAL_CTX_set_time 4173 1_1_1 EXIST::FUNCTION:CT +CT_POLICY_EVAL_CTX_get_time 4172 1_1_0d EXIST::FUNCTION:CT +CT_POLICY_EVAL_CTX_set_time 4173 1_1_0d EXIST::FUNCTION:CT -- 2.25.1