diff options
author | Matt Caswell <matt@openssl.org> | 2018-06-07 16:32:19 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2018-07-02 15:06:12 +0100 |
commit | dc7a3543e0244bfdb9cbca1408fb7a6aa5da34b5 (patch) | |
tree | bce641c13851102b7188bd56df664d72755cbfb0 /doc | |
parent | c9598459b6c797bd316e44834f5129bdf28add2b (diff) |
Document the new early data callback and option
Document SSL_OP_NO_ANTI_REPLAY and SSL_CTX_set_allow_early_data_cb()
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6469)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/SSL_CTX_set_options.pod | 11 | ||||
-rw-r--r-- | doc/man3/SSL_read_early_data.pod | 35 |
2 files changed, 45 insertions, 1 deletions
diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index f04de32f6c..ae5ca1bd5d 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -226,6 +226,17 @@ this option is set or not CCS messages received from the peer will always be ignored in TLSv1.3. This option is set by default. To switch it off use SSL_clear_options(). A future version of OpenSSL may not set this by default. +=item SSL_OP_NO_ANTI_REPLAY + +By default, when a server is configured for early data (i.e., max_early_data > 0), +OpenSSL will switch on replay protection. See L<SSL_read_early_data(3)> for a +description of the replay protection feature. Anti-replay measures are required +to comply with the TLSv1.3 specification. Some applications may be able to +mitigate the replay risks in other ways and in such cases the built in OpenSSL +functionality is not required. Those applications can turn this feature off by +setting this option. This is a server-side opton only. It is ignored by +clients. + =back The following options no longer have any effect but their identifiers are diff --git a/doc/man3/SSL_read_early_data.pod b/doc/man3/SSL_read_early_data.pod index 6a76ec2923..cf6f7579b5 100644 --- a/doc/man3/SSL_read_early_data.pod +++ b/doc/man3/SSL_read_early_data.pod @@ -10,7 +10,10 @@ SSL_SESSION_get_max_early_data, SSL_SESSION_set_max_early_data, SSL_write_early_data, SSL_read_early_data, -SSL_get_early_data_status +SSL_get_early_data_status, +SSL_allow_early_data_cb_fn, +SSL_CTX_set_allow_early_data_cb, +SSL_set_allow_early_data_cb - functions for sending and receiving early data =head1 SYNOPSIS @@ -30,6 +33,16 @@ SSL_get_early_data_status int SSL_get_early_data_status(const SSL *s); + + typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg); + + void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx, + SSL_allow_early_data_cb_fn cb, + void *arg); + void SSL_set_allow_early_data_cb(SSL *s, + SSL_allow_early_data_cb_fn cb, + void *arg); + =head1 DESCRIPTION These functions are used to send and receive early data where TLSv1.3 has been @@ -186,6 +199,20 @@ In the event that the current maximum early data setting for the server is different to that originally specified in a session that a client is resuming with then the lower of the two values will apply. +Some server applications may wish to have more control over whether early data +is accepted or not, for example to mitigate replay risks (see L</REPLAY PROTECTION> +below) or to decline early_data when the server is heavily loaded. The functions +SSL_CTX_set_allow_early_data_cb() and SSL_set_allow_early_data_cb() set a +callback which is called at a point in the handshake immediately before a +decision is made to accept or reject early data. The callback is provided with a +pointer to the user data argument that was provided when the callback was first +set. Returning 1 from the callback will allow early data and returning 0 will +reject it. Note that the OpenSSL library may reject early data for other reasons +in which case this callback will not get called. Notably, the built-in replay +protection feature will still be used even if a callback is present unless it +has been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See +L</REPLAY PROTECTION> below. + =head1 NOTES The whole purpose of early data is to enable a client to start sending data to @@ -252,6 +279,12 @@ The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs) (e.g. see SSL_CTX_set_psk_find_session_callback(3)). Therefore extreme caution should be applied when combining external PSKs with early data. +Some applications may mitigate the replay risks in other ways. For those +applications it is possible to turn off the built-in replay protection feature +using the B<SSL_OP_NO_ANTI_REPLAY> option. See L<SSL_CTX_set_options(3)> for +details. Applications can also set a callback to make decisions about accepting +early data or not. See SSL_CTX_set_allow_early_data_cb() above for details. + =head1 RETURN VALUES SSL_write_early_data() returns 1 for success or 0 for failure. In the event of a |