mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
ef466accdc
Following on from the latest API changes. Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2737)
210 lines
8.9 KiB
Plaintext
210 lines
8.9 KiB
Plaintext
=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_write_early,
|
|
SSL_read_early,
|
|
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_CTX *s);
|
|
uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
|
|
|
|
int SSL_write_early(SSL *s, const void *buf, size_t num, size_t *written);
|
|
|
|
int SSL_read_early(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 recieve early data. 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.
|
|
|
|
Early data has weaker security properties than other data sent over an SSL/TLS
|
|
connection. In particular the data is not forward secret and the server has 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.
|
|
|
|
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.
|
|
|
|
A server or client can determine whether the full handshake has been completed
|
|
or not by calling L<SSL_is_init_finished(3)>.
|
|
|
|
[[TODO(TLS1.3): The server uses SSL_write_ex()/SSL_write() to send data to an
|
|
unauthenticated client. Should we create a separate function for this to avoid
|
|
accidents??]]
|
|
|
|
On the client side the function SSL_SESSION_get_max_early_data() can be used to
|
|
determine whether 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.
|
|
|
|
A client uses the function SSL_write_early() to send early data. This function
|
|
works in the same way as the L<SSL_write_ex(3)> function, but with a few
|
|
differences. Refer to the L<SSL_write_ex(3)> documentation for
|
|
information on how to write bytes to the underlying connection, and how to
|
|
handle any errors that may arise. This page will detail the differences between
|
|
SSL_write_early() and L<SSL_write_ex(3)>.
|
|
|
|
SSL_write_early() 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() 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() as required.
|
|
|
|
If SSL_write_early() 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.
|
|
|
|
Only clients may call SSL_write_early().
|
|
|
|
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() function to receive early data on a
|
|
connection. As for SSL_write_early() 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() works in the same way as L<SSL_read_ex(3)> except for the
|
|
differences noted here. Refer to the L<SSL_read_ex(3)> documentation for full
|
|
details.
|
|
|
|
SSL_read_early() may return 3 possible values:
|
|
|
|
=over 4
|
|
|
|
=item SSL_READ_EARLY_ERROR
|
|
|
|
This indicates an IO or some other error occured. This should be treated in the
|
|
same way as a 0 return value from L<SSL_read_ex(3)>.
|
|
|
|
=item SSL_READ_EARLY_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() to read more data.
|
|
|
|
=item SSL_READ_EARLY_FINISH
|
|
|
|
This indicates that no more early data can be read. It may be returned on the
|
|
first call to SSL_read_early() if the client has not sent any early data, or
|
|
if the early data was rejected.
|
|
|
|
=back
|
|
|
|
Once the initial SSL_write_early() call has completed successfully the client
|
|
may interleave calls to L<SSL_write_ex(3)> and L<SSL_write(3)> with calls to
|
|
SSL_read_early() as required. As noted above data sent via L<SSL_write_ex(3)> or
|
|
L<SSL_write(3)> in this way is sent to an unauthenticated client.
|
|
|
|
Servers must not call L<SSL_read_ex(3)> or L<SSL_read(3)> until SSL_read_early()
|
|
has returned with SSL_READ_EARLY_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() has
|
|
returned SSL_READ_EARLY_FINISH.
|
|
|
|
Only servers may call SSL_read_early().
|
|
|
|
Calls to SSL_read_early() may, in certain circumstances, complete the connection
|
|
immediately without further need to call a function such as L<SSL_accept(3)>.
|
|
Applications can test for this by calling L<SSL_is_init_finished(3)>.
|
|
Alternatively, applications may choose to call L<SSL_accept(3)> anway. 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 RETURN VALUES
|
|
|
|
SSL_write_early() 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() returns SSL_READ_EARLY_ERROR for failure,
|
|
SSL_READ_EARLY_SUCCESS for success with more data to read and
|
|
SSL_READ_EARLY_FINISH for 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() and SSL_CTX_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(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
|