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)

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index f04de32f6c6e6ffde863fa94146cd0eeda1722e9..ae5ca1bd5d23c423a5552700478bdf6a2b4c67af 100644 (file)
--- 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 6a76ec29231f87dd5314dcc8e2de466fd57deff6..cf6f7579b5297992dc5fd4e0b80184d6ed83fe52 100644 (file)
--- 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

diff --git a/util/private.num b/util/private.num
index ac536a56aab052e6468396aa566feda31a607501..b90e33db800e0525b222f7a392dbaa7d5d1ddb3d 100644 (file)
--- a/util/private.num
+++ b/util/private.num
@@ -48,7 +48,9 @@ RAND_DRBG_cleanup_nonce_fn              datatype
 RAND_DRBG_get_entropy_fn                datatype
 RAND_DRBG_get_nonce_fn                  datatype
 RAND_poll_cb                            datatype
+SSL_CTX_allow_early_data_cb_fn          datatype
 SSL_CTX_keylog_cb_func                  datatype
+SSL_allow_early_data_cb_fn              datatype
 SSL_client_hello_cb_fn                  datatype
 SSL_psk_client_cb_func                  datatype
 SSL_psk_find_session_cb_func            datatype