Commit 18ad4629 authored by Rich Salz's avatar Rich Salz
Browse files

Cherry-pick doc updates from PR 1554 



Also fix version in libcrypto.num, from backporting new
functions.

Reviewed-by: default avatarViktor Dukhovni <viktor@openssl.org>
Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1554)
(cherry picked from commit ebcb5368)
parent 5229bbe7

doc/CT_POLICY_EVAL_CTX_new.pod

0 → 100644
+111 −0
Original line number Diff line number Diff line 
=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 <openssl/ct.h>



 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<CT_POLICY_EVAL_CTX> 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<CT_POLICY_EVAL_CTX> 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<ct(7)>



=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<https://www.openssl.org/source/license.html>.



=cut

doc/SCT_validate.pod

0 → 100644
+98 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



SCT_validate, SCT_LIST_validate, SCT_get_validation_status -

checks Signed Certificate Timestamps (SCTs) are valid



=head1 SYNOPSIS



 #include <openssl/ct.h>



 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<ct(7)>



=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<https://www.openssl.org/source/license.html>.



=cut

doc/SSL_CTX_set_ct_validation_callback.pod

0 → 100644
+142 −0
Original line number Diff line number Diff line 
=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 <openssl/ssl.h>



 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<validation_mode> argument,

which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or

B<SSL_CT_VALIDATION_STRICT> as described below.



If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full

TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer

presents no valid SCTs the handshake will be aborted.

If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue

despite lack of valid SCTs.

However, in that case if the verification status before the built-in callback

was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the

callback.

Applications can call L<SSL_get_verify_result(3)> to check the status at

handshake completion, even after session resumption since the verification

status is part of the saved session state.

See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>.



If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, 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<SSL_VERIFY_NONE>

and the callback returns a non-positive result.



An arbitrary callback context argument, B<arg>, 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<TLSEXT_TYPE_signed_certificate_timestamp>).



=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<callback> 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<ssl(7)>,

<SSL_get_verify_result(3)>,

L<SSL_session_reused(3)>,

L<SSL_set_verify(3)>,

L<SSL_CTX_set_verify(3)>,

L<ssl_ct_validation_cb(3)>,

L<SSL_SESSION_get_time(3)>



=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<https://www.openssl.org/source/license.html>.



=cut

util/libcrypto.num

+2 −2
Original line number Diff line number Diff line
@@ -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