SSL_get_max_early_data,
SSL_CTX_get_max_early_data,
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
int SSL_set_max_early_data(SSL *s, uint32_t max_early_data);
uint32_t SSL_get_max_early_data(const SSL *s);
uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
+ int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data);
int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written);
If the session cannot be used then this function will return 0. Otherwise it
will return the maximum number of early data bytes that can be sent.
+The function SSL_SESSION_set_max_early_data() sets the maximum number of early
+data bytes that can be sent for a session. This would typically be used when
+creating a PSK session file (see L<SSL_CTX_set_psk_use_session_callback(3)>). If
+using a ticket based PSK then this is set automatically to the value provided by
+the server.
+
A client uses the function SSL_write_early_data() to send early data. This
function is similar to the L<SSL_write_ex(3)> function, but with the following
differences. See L<SSL_write_ex(3)> for information on how to write bytes to
=item SSL_READ_EARLY_DATA_ERROR
-This indicates an IO or some other error occured. This should be treated in the
+This indicates an IO or some other error occurred. This should be treated in the
same way as a 0 return value from L<SSL_read_ex(3)>.
=item SSL_READ_EARLY_DATA_SUCCESS
different to that originally specified in a session that a client is resuming
with then the lower of the two values will apply.
+=head1 NOTES
+
+The whole purpose of early data is to enable a client to start sending data to
+the server before a full round trip of network traffic has occurred. Application
+developers should ensure they consider optimisation of the underlying TCP socket
+to obtain a performant solution. For example Nagle's algorithm is commonly used
+by operating systems in an attempt to avoid lots of small TCP packets. In many
+scenarios this is beneficial for performance, but it does not work well with the
+early data solution as implemented in OpenSSL. In Nagle's algorithm the OS will
+buffer outgoing TCP data if a TCP packet has already been sent which we have not
+yet received an ACK for from the peer. The buffered data will only be
+transmitted if enough data to fill an entire TCP packet is accumulated, or if
+the ACK is received from the peer. The initial ClientHello will be sent in the
+first TCP packet along with any data from the first call to
+SSL_write_early_data(). If the amount of data written will exceed the size of a
+single TCP packet, or if there are more calls to SSL_write_early_data() then
+that additional data will be sent in subsequent TCP packets which will be
+buffered by the OS and not sent until an ACK is received for the first packet
+containing the ClientHello. This means the early data is not actually
+sent until a complete round trip with the server has occurred which defeats the
+objective of early data.
+
+In many operating systems the TCP_NODELAY socket option is available to disable
+Nagle's algorithm. If an application opts to disable Nagle's algorithm
+consideration should be given to turning it back on again after the handshake is
+complete if appropriate.
+
=head1 RETURN VALUES
SSL_write_early_data() returns 1 for success or 0 for failure. In the event of a
SSL_SESSION_get_max_early_data() return the maximum number of early data bytes
that may be sent.
-SSL_set_max_early_data() and SSL_CTX_set_max_early_data() return 1 for success
-or 0 for failure.
+SSL_set_max_early_data(), SSL_CTX_set_max_early_data() and
+SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure.
SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early data was
accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by
L<SSL_connect(3)>,
L<SSL_accept(3)>,
L<SSL_do_handshake(3)>,
+L<SSL_CTX_set_psk_use_session_callback(3)>,
L<ssl(7)>
=head1 HISTORY