From 6c34c5f30bf528237cb15ed634dc338412b51a76 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 2 Mar 2017 12:59:43 -0500 Subject: [PATCH] Fix cherry-pick and put files in right place Also SLS_set_bio.pod got copied, remove the clone. [skip ci] Reviewed-by: Andy Polyakov (Merged from https://github.com/openssl/openssl/pull/2828) --- doc/CT_POLICY_EVAL_CTX_new.pod | 111 -------------- doc/SCT_validate.pod | 98 ------------ doc/SSL_CTX_set_ct_validation_callback.pod | 142 ------------------ doc/crypto/CT_POLICY_EVAL_CTX_new.pod | 21 ++- doc/crypto/SCT_validate.pod | 10 +- doc/crypto/SSL_set_bio.pod | 108 ------------- .../SSL_CTX_set_ct_validation_callback.pod | 8 +- 7 files changed, 30 insertions(+), 468 deletions(-) delete mode 100644 doc/CT_POLICY_EVAL_CTX_new.pod delete mode 100644 doc/SCT_validate.pod delete mode 100644 doc/SSL_CTX_set_ct_validation_callback.pod delete mode 100644 doc/crypto/SSL_set_bio.pod diff --git a/doc/CT_POLICY_EVAL_CTX_new.pod b/doc/CT_POLICY_EVAL_CTX_new.pod deleted file mode 100644 index fedc58d08a..0000000000 --- a/doc/CT_POLICY_EVAL_CTX_new.pod +++ /dev/null @@ -1,111 +0,0 @@ -=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 deleted file mode 100644 index 9868a282b5..0000000000 --- a/doc/SCT_validate.pod +++ /dev/null @@ -1,98 +0,0 @@ -=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 deleted file mode 100644 index d818e00fc5..0000000000 --- a/doc/SSL_CTX_set_ct_validation_callback.pod +++ /dev/null @@ -1,142 +0,0 @@ -=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/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod index 62792992e2..fedc58d08a 100644 --- a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod +++ b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod @@ -5,7 +5,8 @@ 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_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 @@ -20,13 +21,16 @@ Encapsulates the data required to evaluate whether SCTs meet a Certificate Trans 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 signature must be verified. This requires: +determine this, an SCT's timestamp and signature must be verified. +This requires: =over @@ -36,6 +40,8 @@ determine this, an SCT's signature must be verified. This requires: =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. @@ -58,6 +64,15 @@ Increments the reference count of the certificate. 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. @@ -78,7 +93,7 @@ CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod index 713bcd29d8..9868a282b5 100644 --- a/doc/crypto/SCT_validate.pod +++ b/doc/crypto/SCT_validate.pod @@ -54,9 +54,11 @@ status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. 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, the validation status will be -SCT_VALIDATION_STATUS_INVALID. Otherwise, if all checks have passed, the -validation status will be SCT_VALIDATION_STATUS_VALID. +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 @@ -78,7 +80,7 @@ returned value will be SCT_VALIDATION_STATUS_NOT_SET. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/crypto/SSL_set_bio.pod b/doc/crypto/SSL_set_bio.pod deleted file mode 100644 index 58d22b63d7..0000000000 --- a/doc/crypto/SSL_set_bio.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO - -=head1 SYNOPSIS - - #include - - void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); - void SSL_set0_rbio(SSL *s, BIO *rbio); - void SSL_set0_wbio(SSL *s, BIO *wbio); - -=head1 DESCRIPTION - -SSL_set0_rbio() connects the BIO B for the read operations of the B -object. The SSL engine inherits the behaviour of B. If the BIO is -non-blocking then the B object will also have non-blocking behaviour. This -function transfers ownership of B to B. It will be automatically -freed using L when the B is freed. On calling this -function, any existing B that was previously set will also be freed via a -call to L (this includes the case where the B is set to -the same value as previously). - -SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects -the BIO B for the write operations of the B object. Note that if the -rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take -ownership of one reference. Therefore it may be necessary to increment the -number of references available using L before calling the set0 -functions. - -SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except -that it connects both the B and the B at the same time. This -function transfers the ownership of B and B to B except that -the rules for this are much more complex. For this reason this function is -considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be -used in preference. The ownership rules are as follows: - -=over 4 - -=item * - -If neither the rbio or wbio have changed from their previous values then nothing -is done. - -=item * - -If the rbio and wbio parameters are different and both are different to their -previously set values then one reference is consumed for the rbio and one -reference is consumed for the wbio. - -=item * - -If the rbio and wbio parameters are the same and the rbio is not the same as the -previously set value then one reference is consumed. - -=item * - -If the rbio and wbio parameters are the same and the rbio is the same as the -previously set value, then no additional references are consumed. - -=item * - -If the rbio and wbio parameters are different and the rbio is the same as the -previously set value then one reference is consumbed for the wbio and no -references are consumed for the rbio. - -=item * - -If the rbio and wbio parameters are different and the wbio is the same as the -previously set value and the old rbio and wbio values were the same as each -other then one reference is consumed for the rbio and no references are consumed -for the wbio. - -=item * - -If the rbio and wbio parameters are different and the wbio is the same as the -previously set value and the old rbio and wbio values were different to each -other then one reference is consumed for the rbio and one reference is consumed -for the wbio. - -=back - -=head1 RETURN VALUES - -SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail. - -=head1 SEE ALSO - -L, -L, L, -L, L, L - -=head1 HISTORY - -SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2000-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/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod index c481ecbc87..d818e00fc5 100644 --- a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod +++ b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -97,6 +97,9 @@ otherwise. 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 @@ -119,12 +122,13 @@ callback) is set. =head1 SEE ALSO -L, +L, , L, L, L, -L +L, +L =head1 COPYRIGHT -- 2.25.1