c6a623adaa
Now that we attempt to send early data in the first TCP packet along with the ClientHello, the documentation for SSL_write_early_data() needed a tweak. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4802)
252 lines
12 KiB
Text
252 lines
12 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_set_max_early_data,
|
|
SSL_CTX_set_max_early_data,
|
|
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
|
|
- functions for sending and receiving early data
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data);
|
|
uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx);
|
|
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);
|
|
|
|
int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
|
|
|
|
int SSL_get_early_data_status(const SSL *s);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
These functions are used to send and receive early data where TLSv1.3 has been
|
|
negotiated. Early data can be sent by the client immediately after its initial
|
|
ClientHello without having to wait for the server to complete the handshake.
|
|
Early data can only be sent if a session has previously been established with
|
|
the server, and the server is known to support it. Additionally these functions
|
|
can be used to send data from the server to the client when the client has not
|
|
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
|
|
data. For specific details, consult the TLS 1.3 specification.
|
|
|
|
When a server receives early data it may opt to immediately respond by sending
|
|
application data back to the client. Data sent by the server at this stage is
|
|
done before the full handshake has been completed. Specifically the client's
|
|
authentication messages have not yet been received, i.e. the client is
|
|
unauthenticated at this point and care should be taken when using this
|
|
capability.
|
|
|
|
A server or client can determine whether the full handshake has been completed
|
|
or not by calling L<SSL_is_init_finished(3)>.
|
|
|
|
On the client side, the function SSL_SESSION_get_max_early_data() can be used to
|
|
determine if a session established with a server can be used to send early data.
|
|
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
|
|
the underlying connection, and how to handle any errors that may arise. This
|
|
page describes the differences between SSL_write_early_data() and
|
|
L<SSL_write_ex(3)>.
|
|
|
|
When called by a client, SSL_write_early_data() must be the first IO function
|
|
called on a new connection, i.e. it must occur before any calls to
|
|
L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_connect(3)>, L<SSL_do_handshake(3)>
|
|
or other similar functions. It may be called multiple times to stream data to
|
|
the server, but the total number of bytes written must not exceed the value
|
|
returned from SSL_SESSION_get_max_early_data(). Once the initial
|
|
SSL_write_early_data() call has completed successfully the client may interleave
|
|
calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to
|
|
SSL_write_early_data() as required.
|
|
|
|
If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine
|
|
the correct course of action, as for L<SSL_write_ex(3)>.
|
|
|
|
When the client no longer wishes to send any more early data then it should
|
|
complete the handshake by calling a function such as L<SSL_connect(3)> or
|
|
L<SSL_do_handshake(3)>. Alternatively you can call a standard write function
|
|
such as L<SSL_write_ex(3)>, which will transparently complete the connection and
|
|
write the requested data.
|
|
|
|
A server may choose to ignore early data that has been sent to it. Once the
|
|
connection has been completed you can determine whether the server accepted or
|
|
rejected the early data by calling SSL_get_early_data_status(). This will return
|
|
SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it
|
|
was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function
|
|
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
|
|
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.
|
|
|
|
SSL_read_early_data() is similar to L<SSL_read_ex(3)> with the following
|
|
differences. Refer to L<SSL_read_ex(3)> for full details.
|
|
|
|
SSL_read_early_data() may return 3 possible values:
|
|
|
|
=over 4
|
|
|
|
=item SSL_READ_EARLY_DATA_ERROR
|
|
|
|
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
|
|
|
|
This indicates that early data was successfully read. This should be treated in
|
|
the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to
|
|
call SSL_read_early_data() to read more data.
|
|
|
|
=item SSL_READ_EARLY_DATA_FINISH
|
|
|
|
This indicates that no more early data can be read. It may be returned on the
|
|
first call to SSL_read_early_data() if the client has not sent any early data,
|
|
or if the early data was rejected.
|
|
|
|
=back
|
|
|
|
Once the initial SSL_read_early_data() call has completed successfully (i.e. it
|
|
has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the
|
|
server may choose to write data immediately to the unauthenticated client using
|
|
SSL_write_early_data(). If SSL_read_early_data() returned
|
|
SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only
|
|
supports TLSv1.2) the handshake may have already been completed and calls
|
|
to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to
|
|
determine whether the handshake has completed or not. If the handshake is still
|
|
in progress then the server may interleave calls to SSL_write_early_data() with
|
|
calls to SSL_read_early_data() as required.
|
|
|
|
Servers must not call L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or
|
|
L<SSL_write(3)> until SSL_read_early_data() has returned with
|
|
SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client
|
|
still needs to be completed. Complete the connection by calling a function such
|
|
as L<SSL_accept(3)> or L<SSL_do_handshake(3)>. Alternatively you can call a
|
|
standard read function such as L<SSL_read_ex(3)>, which will transparently
|
|
complete the connection and read the requested data. Note that it is an error to
|
|
attempt to complete the connection before SSL_read_early_data() has returned
|
|
SSL_READ_EARLY_DATA_FINISH.
|
|
|
|
Only servers may call SSL_read_early_data().
|
|
|
|
Calls to SSL_read_early_data() may, in certain circumstances, complete the
|
|
connection immediately without further need to call a function such as
|
|
L<SSL_accept(3)>. This can happen if the client is using a protocol version less
|
|
than TLSv1.3. Applications can test for this by calling
|
|
L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call
|
|
L<SSL_accept(3)> anyway. Such a call will successfully return immediately with no
|
|
further action taken.
|
|
|
|
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
|
|
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
|
|
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.
|
|
|
|
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.
|
|
|
|
=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
|
|
failure call L<SSL_get_error(3)> to determine the correct course of action.
|
|
|
|
SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
|
|
SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
|
|
SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the
|
|
event of a failure call L<SSL_get_error(3)> to determine the correct course of
|
|
action.
|
|
|
|
SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
|
|
SSL_SESSION_get_max_early_data() return the maximum number of early data bytes
|
|
that may be sent.
|
|
|
|
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
|
|
the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<SSL_get_error(3)>,
|
|
L<SSL_write_ex(3)>,
|
|
L<SSL_read_ex(3)>,
|
|
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
|
|
|
|
All of the functions described above were added in OpenSSL 1.1.1.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|