Also SLS_set_bio.pod got copied, remove the clone.
[skip ci]
Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2828)
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
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
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 signature must be verified. This requires:
+determine this, an SCT's timestamp and signature must be verified.
+This requires:
=over
=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.
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.
=head1 SEE ALSO
-L<ct(3)>
+L<ct(7)>
=head1 HISTORY
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
=head1 SEE ALSO
-L<ct(3)>
+L<ct(7)>
=head1 HISTORY
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- 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<rbio> for the read operations of the B<ssl>
-object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is
-non-blocking then the B<ssl> object will also have non-blocking behaviour. This
-function transfers ownership of B<rbio> to B<ssl>. It will be automatically
-freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this
-function, any existing B<rbio> that was previously set will also be freed via a
-call to L<BIO_free_all(3)> (this includes the case where the B<rbio> 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<wbio> for the write operations of the B<ssl> 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<BIO_up_ref(3)> 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<rbio> and the B<wbio> at the same time. This
-function transfers the ownership of B<rbio> and B<wbio> to B<ssl> 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<SSL_get_rbio(7)>,
-L<SSL_connect(3)>, L<SSL_accept(3)>,
-L<SSL_shutdown(3)>, L<ssl(7)>, L<bio(7)>
-
-=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<https://www.openssl.org/source/license.html>.
-
-=cut
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
=head1 SEE ALSO
-L<ssl(3)>,
+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_ct_validation_cb(3)>,
+L<SSL_SESSION_get_time(3)>
=head1 COPYRIGHT
projects / oweals / openssl.git / commitdiff