yet completed the authentication stage of the handshake.
Early data has weaker security properties than other data sent over an SSL/TLS
-connection. In particular the data does not have forward secrecy and there are
-no guarantees that the same early data was not replayed across multiple
-connections. For this reason extreme care should be exercised when using early
+connection. In particular the data does not have forward secrecy. There are also
+additional considerations around replay attacks (see L<REPLAY PROTECTION>
+below). For these reasons extreme care should be exercised when using early
data. For specific details, consult the TLS 1.3 specification.
When a server receives early data it may opt to immediately respond by sending
may be called by either the client or the server.
A server uses the SSL_read_early_data() function to receive early data on a
-connection. As for SSL_write_early_data() this must be the first IO function
+connection for which early data has been enabled using
+SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for
+SSL_write_early_data(), this must be the first IO function
called on a connection, i.e. it must occur before any calls to
L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>,
or other similar functions.
When a session is created between a server and a client the server will specify
the maximum amount of any early data that it will accept on any future
-connection attempt. By default this is approximately 16k. A server may override
-this default value by calling SSL_CTX_set_max_early_data() or
+connection attempt. By default the server does not accept early data; a
+server may indicate support for early data by calling
+SSL_CTX_set_max_early_data() or
SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL
-object respectively. Similarly the SSL_CTX_get_max_early_data() and
+object respectively. The B<max_early_data> parameter specifies the maximum
+amount of early data in bytes that is permitted to be sent on a single
+connection. Similarly the SSL_CTX_get_max_early_data() and
SSL_get_max_early_data() functions can be used to obtain the current maximum
-early data settings for the SSL_CTX and SSL objects respectively.
+early data settings for the SSL_CTX and SSL objects respectively. Generally a
+server application will either use both of SSL_read_early_data() and
+SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither of them,
+since there is no practical benefit from using only one of them. If the maximum
+early data setting for a server is non-zero then replay protection is
+automatically enabled (see L</REPLAY PROTECTION> below).
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
consideration should be given to turning it back on again after the handshake is
complete if appropriate.
+=head1 REPLAY PROTECTION
+
+When early data is in use the TLS protocol provides no security guarantees that
+the same early data was not replayed across multiple connections. As a
+mitigation for this issue OpenSSL automatically enables replay protection if the
+server is configured with a non-zero max early data value. With replay
+protection enabled sessions are forced to be single use only. If a client
+attempts to reuse a session ticket more than once, then the second and
+subsequent attempts will fall back to a full handshake (and any early data that
+was submitted will be ignored). Note that single use tickets are enforced even
+if a client does not send any early data.
+
+The replay protection mechanism relies on the internal OpenSSL server session
+cache (see L<SSL_CTX_set_session_cache_mode(3)>). By default sessions will be
+added to the cache whenever a session ticket is issued. When a client attempts
+to resume the session OpenSSL will check for its presence in the internal cache.
+If it exists then the resumption is allowed and the session is removed from the
+cache. If it does not exist then the resumption is not allowed and a full
+handshake will occur.
+
+Note that some applications may maintain an external cache of sessions (see
+L<SSL_CTX_sess_set_new_cb(3)> and similar functions). It is the application's
+responsibility to ensure that any sessions in the external cache are also
+populated in the internal cache and that once removed from the internal cache
+they are similarly removed from the external cache. Failing to do this could
+result in an application becoming vulnerable to replay attacks. Note that
+OpenSSL will lock the internal cache while a session is removed but that lock is
+not held when the remove session callback (see L<SSL_CTX_sess_set_remove_cb(3)>)
+is called. This could result in a small amount of time where the session has
+been removed from the internal cache but is still available in the external
+cache. Applications should be designed with this in mind in order to minimise
+the possibility of replay attacks.
+
+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.
+
=head1 RETURN VALUES
SSL_write_early_data() returns 1 for success or 0 for failure. In the event of a
projects / openssl.git / blobdiff