Document the new early data callback and option

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

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

 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

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

(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

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