488 lines
24 KiB
Groff
Executable File
488 lines
24 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "SSL_READ_EARLY_DATA 3"
|
|
.TH SSL_READ_EARLY_DATA 3 "2020-03-02" "3.0.0-dev" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
SSL_set_max_early_data,
|
|
SSL_CTX_set_max_early_data,
|
|
SSL_get_max_early_data,
|
|
SSL_CTX_get_max_early_data,
|
|
SSL_set_recv_max_early_data,
|
|
SSL_CTX_set_recv_max_early_data,
|
|
SSL_get_recv_max_early_data,
|
|
SSL_CTX_get_recv_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,
|
|
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
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #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);
|
|
\&
|
|
\& int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data);
|
|
\& uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx);
|
|
\& int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data);
|
|
\& uint32_t SSL_get_recv_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);
|
|
\&
|
|
\&
|
|
\& 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);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "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.
|
|
.PP
|
|
Early data has weaker security properties than other data sent over an \s-1SSL/TLS\s0
|
|
connection. In particular the data does not have forward secrecy. There are also
|
|
additional considerations around replay attacks (see \*(L"\s-1REPLAY\s0 \s-1PROTECTION\s0\*(R"
|
|
below). For these reasons extreme care should be exercised when using early
|
|
data. For specific details, consult the \s-1TLS\s0 1.3 specification.
|
|
.PP
|
|
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.
|
|
.PP
|
|
A server or client can determine whether the full handshake has been completed
|
|
or not by calling \fISSL_is_init_finished\fR\|(3).
|
|
.PP
|
|
On the client side, the function \fISSL_SESSION_get_max_early_data()\fR 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.
|
|
.PP
|
|
The function \fISSL_SESSION_set_max_early_data()\fR sets the maximum number of early
|
|
data bytes that can be sent for a session. This would typically be used when
|
|
creating a \s-1PSK\s0 session file (see \fISSL_CTX_set_psk_use_session_callback\fR\|(3)). If
|
|
using a ticket based \s-1PSK\s0 then this is set automatically to the value provided by
|
|
the server.
|
|
.PP
|
|
A client uses the function \fISSL_write_early_data()\fR to send early data. This
|
|
function is similar to the \fISSL_write_ex\fR\|(3) function, but with the following
|
|
differences. See \fISSL_write_ex\fR\|(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 \fISSL_write_early_data()\fR and
|
|
\&\fISSL_write_ex\fR\|(3).
|
|
.PP
|
|
When called by a client, \fISSL_write_early_data()\fR must be the first \s-1IO\s0 function
|
|
called on a new connection, i.e. it must occur before any calls to
|
|
\&\fISSL_write_ex\fR\|(3), \fISSL_read_ex\fR\|(3), \fISSL_connect\fR\|(3), \fISSL_do_handshake\fR\|(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 \fISSL_SESSION_get_max_early_data()\fR. Once the initial
|
|
\&\fISSL_write_early_data()\fR call has completed successfully the client may interleave
|
|
calls to \fISSL_read_ex\fR\|(3) and \fISSL_read\fR\|(3) with calls to
|
|
\&\fISSL_write_early_data()\fR as required.
|
|
.PP
|
|
If \fISSL_write_early_data()\fR fails you should call \fISSL_get_error\fR\|(3) to determine
|
|
the correct course of action, as for \fISSL_write_ex\fR\|(3).
|
|
.PP
|
|
When the client no longer wishes to send any more early data then it should
|
|
complete the handshake by calling a function such as \fISSL_connect\fR\|(3) or
|
|
\&\fISSL_do_handshake\fR\|(3). Alternatively you can call a standard write function
|
|
such as \fISSL_write_ex\fR\|(3), which will transparently complete the connection and
|
|
write the requested data.
|
|
.PP
|
|
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 \fISSL_get_early_data_status()\fR. This will return
|
|
\&\s-1SSL_EARLY_DATA_ACCEPTED\s0 if the data was accepted, \s-1SSL_EARLY_DATA_REJECTED\s0 if it
|
|
was rejected or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent. This function
|
|
may be called by either the client or the server.
|
|
.PP
|
|
A server uses the \fISSL_read_early_data()\fR function to receive early data on a
|
|
connection for which early data has been enabled using
|
|
\&\fISSL_CTX_set_max_early_data()\fR or \fISSL_set_max_early_data()\fR. As for
|
|
\&\fISSL_write_early_data()\fR, this must be the first \s-1IO\s0 function
|
|
called on a connection, i.e. it must occur before any calls to
|
|
\&\fISSL_write_ex\fR\|(3), \fISSL_read_ex\fR\|(3), \fISSL_accept\fR\|(3), \fISSL_do_handshake\fR\|(3),
|
|
or other similar functions.
|
|
.PP
|
|
\&\fISSL_read_early_data()\fR is similar to \fISSL_read_ex\fR\|(3) with the following
|
|
differences. Refer to \fISSL_read_ex\fR\|(3) for full details.
|
|
.PP
|
|
\&\fISSL_read_early_data()\fR may return 3 possible values:
|
|
.IP "\s-1SSL_READ_EARLY_DATA_ERROR\s0" 4
|
|
.IX Item "SSL_READ_EARLY_DATA_ERROR"
|
|
This indicates an \s-1IO\s0 or some other error occurred. This should be treated in the
|
|
same way as a 0 return value from \fISSL_read_ex\fR\|(3).
|
|
.IP "\s-1SSL_READ_EARLY_DATA_SUCCESS\s0" 4
|
|
.IX 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 \fISSL_read_ex\fR\|(3). You should continue to
|
|
call \fISSL_read_early_data()\fR to read more data.
|
|
.IP "\s-1SSL_READ_EARLY_DATA_FINISH\s0" 4
|
|
.IX 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 \fISSL_read_early_data()\fR if the client has not sent any early data,
|
|
or if the early data was rejected.
|
|
.PP
|
|
Once the initial \fISSL_read_early_data()\fR call has completed successfully (i.e. it
|
|
has returned \s-1SSL_READ_EARLY_DATA_SUCCESS\s0 or \s-1SSL_READ_EARLY_DATA_FINISH\s0) then the
|
|
server may choose to write data immediately to the unauthenticated client using
|
|
\&\fISSL_write_early_data()\fR. If \fISSL_read_early_data()\fR returned
|
|
\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 then in some situations (e.g. if the client only
|
|
supports TLSv1.2) the handshake may have already been completed and calls
|
|
to \fISSL_write_early_data()\fR are not allowed. Call \fISSL_is_init_finished\fR\|(3) to
|
|
determine whether the handshake has completed or not. If the handshake is still
|
|
in progress then the server may interleave calls to \fISSL_write_early_data()\fR with
|
|
calls to \fISSL_read_early_data()\fR as required.
|
|
.PP
|
|
Servers must not call \fISSL_read_ex\fR\|(3), \fISSL_read\fR\|(3), \fISSL_write_ex\fR\|(3) or
|
|
\&\fISSL_write\fR\|(3) until \fISSL_read_early_data()\fR has returned with
|
|
\&\s-1SSL_READ_EARLY_DATA_FINISH\s0. Once it has done so the connection to the client
|
|
still needs to be completed. Complete the connection by calling a function such
|
|
as \fISSL_accept\fR\|(3) or \fISSL_do_handshake\fR\|(3). Alternatively you can call a
|
|
standard read function such as \fISSL_read_ex\fR\|(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 \fISSL_read_early_data()\fR has returned
|
|
\&\s-1SSL_READ_EARLY_DATA_FINISH\s0.
|
|
.PP
|
|
Only servers may call \fISSL_read_early_data()\fR.
|
|
.PP
|
|
Calls to \fISSL_read_early_data()\fR may, in certain circumstances, complete the
|
|
connection immediately without further need to call a function such as
|
|
\&\fISSL_accept\fR\|(3). This can happen if the client is using a protocol version less
|
|
than TLSv1.3. Applications can test for this by calling
|
|
\&\fISSL_is_init_finished\fR\|(3). Alternatively, applications may choose to call
|
|
\&\fISSL_accept\fR\|(3) anyway. Such a call will successfully return immediately with no
|
|
further action taken.
|
|
.PP
|
|
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 the server does not accept early data; a
|
|
server may indicate support for early data by calling
|
|
\&\fISSL_CTX_set_max_early_data()\fR or
|
|
\&\fISSL_set_max_early_data()\fR to set it for the whole \s-1SSL_CTX\s0 or an individual \s-1SSL\s0
|
|
object respectively. The \fBmax_early_data\fR parameter specifies the maximum
|
|
amount of early data in bytes that is permitted to be sent on a single
|
|
connection. Similarly the \fISSL_CTX_get_max_early_data()\fR and
|
|
\&\fISSL_get_max_early_data()\fR functions can be used to obtain the current maximum
|
|
early data settings for the \s-1SSL_CTX\s0 and \s-1SSL\s0 objects respectively. Generally a
|
|
server application will either use both of \fISSL_read_early_data()\fR and
|
|
\&\fISSL_CTX_set_max_early_data()\fR (or \fISSL_set_max_early_data()\fR), 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 nonzero then replay protection is
|
|
automatically enabled (see \*(L"\s-1REPLAY\s0 \s-1PROTECTION\s0\*(R" below).
|
|
.PP
|
|
If the server rejects the early data sent by a client then it will skip over
|
|
the data that is sent. The maximum amount of received early data that is skipped
|
|
is controlled by the recv_max_early_data setting. If a client sends more than
|
|
this then the connection will abort. This value can be set by calling
|
|
\&\fISSL_CTX_set_recv_max_early_data()\fR or \fISSL_set_recv_max_early_data()\fR. The current
|
|
value for this setting can be obtained by calling
|
|
\&\fISSL_CTX_get_recv_max_early_data()\fR or \fISSL_get_recv_max_early_data()\fR. The default
|
|
value for this setting is 16,384 bytes.
|
|
.PP
|
|
The recv_max_early_data value also has an impact on early data that is accepted.
|
|
The amount of data that is accepted will always be the lower of the
|
|
max_early_data for the session and the recv_max_early_data setting for the
|
|
server. If a client sends more data than this then the connection will abort.
|
|
.PP
|
|
The configured value for max_early_data on a server may change over time as
|
|
required. However clients may have tickets containing the previously configured
|
|
max_early_data value. The recv_max_early_data should always be equal to or
|
|
higher than any recently configured max_early_data value in order to avoid
|
|
aborted connections. The recv_max_early_data should never be set to less than
|
|
the current configured max_early_data value.
|
|
.PP
|
|
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"\s-1REPLAY\s0 \s-1PROTECTION\s0\*(R"
|
|
below) or to decline early_data when the server is heavily loaded. The functions
|
|
\&\fISSL_CTX_set_allow_early_data_cb()\fR and \fISSL_set_allow_early_data_cb()\fR 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 \s-1SSL_OP_NO_ANTI_REPLAY\s0 option. See
|
|
\&\*(L"\s-1REPLAY\s0 \s-1PROTECTION\s0\*(R" below.
|
|
.SH "NOTES"
|
|
.IX Header "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 \s-1TCP\s0 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 \s-1TCP\s0 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 \s-1OS\s0 will
|
|
buffer outgoing \s-1TCP\s0 data if a \s-1TCP\s0 packet has already been sent which we have not
|
|
yet received an \s-1ACK\s0 for from the peer. The buffered data will only be
|
|
transmitted if enough data to fill an entire \s-1TCP\s0 packet is accumulated, or if
|
|
the \s-1ACK\s0 is received from the peer. The initial ClientHello will be sent in the
|
|
first \s-1TCP\s0 packet along with any data from the first call to
|
|
\&\fISSL_write_early_data()\fR. If the amount of data written will exceed the size of a
|
|
single \s-1TCP\s0 packet, or if there are more calls to \fISSL_write_early_data()\fR then
|
|
that additional data will be sent in subsequent \s-1TCP\s0 packets which will be
|
|
buffered by the \s-1OS\s0 and not sent until an \s-1ACK\s0 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.
|
|
.PP
|
|
In many operating systems the \s-1TCP_NODELAY\s0 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.
|
|
.PP
|
|
In rare circumstances, it may be possible for a client to have a session that
|
|
reports a max early data value greater than 0, but where the server does not
|
|
support this. For example, this can occur if a server has had its configuration
|
|
changed to accept a lower max early data value such as by calling
|
|
\&\fISSL_CTX_set_recv_max_early_data()\fR. Another example is if a server used to
|
|
support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such
|
|
a server will cause the connection to abort. Clients that encounter an aborted
|
|
connection while sending early data may want to retry the connection without
|
|
sending early data as this does not happen automatically. A client will have to
|
|
establish a new transport layer connection to the server and attempt the \s-1SSL/TLS\s0
|
|
connection again but without sending early data. Note that it is inadvisable to
|
|
retry with a lower maximum protocol version.
|
|
.SH "REPLAY PROTECTION"
|
|
.IX Header "REPLAY PROTECTION"
|
|
When early data is in use the \s-1TLS\s0 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 nonzero 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.
|
|
.PP
|
|
The replay protection mechanism relies on the internal OpenSSL server session
|
|
cache (see \fISSL_CTX_set_session_cache_mode\fR\|(3)). When replay protection is
|
|
being used the server will operate as if the \s-1SSL_OP_NO_TICKET\s0 option had been
|
|
selected (see \fISSL_CTX_set_options\fR\|(3)). 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.
|
|
.PP
|
|
Note that some applications may maintain an external cache of sessions (see
|
|
\&\fISSL_CTX_sess_set_new_cb\fR\|(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 \fISSL_CTX_sess_set_remove_cb\fR\|(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.
|
|
.PP
|
|
The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs)
|
|
(e.g. see \fISSL_CTX_set_psk_find_session_callback\fR\|(3)). Therefore extreme caution
|
|
should be applied when combining external PSKs with early data.
|
|
.PP
|
|
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 \fB\s-1SSL_OP_NO_ANTI_REPLAY\s0\fR option. See \fISSL_CTX_set_options\fR\|(3) for
|
|
details. Applications can also set a callback to make decisions about accepting
|
|
early data or not. See \fISSL_CTX_set_allow_early_data_cb()\fR above for details.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fISSL_write_early_data()\fR returns 1 for success or 0 for failure. In the event of a
|
|
failure call \fISSL_get_error\fR\|(3) to determine the correct course of action.
|
|
.PP
|
|
\&\fISSL_read_early_data()\fR returns \s-1SSL_READ_EARLY_DATA_ERROR\s0 for failure,
|
|
\&\s-1SSL_READ_EARLY_DATA_SUCCESS\s0 for success with more data to read and
|
|
\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 for success with no more to data be read. In the
|
|
event of a failure call \fISSL_get_error\fR\|(3) to determine the correct course of
|
|
action.
|
|
.PP
|
|
\&\fISSL_get_max_early_data()\fR, \fISSL_CTX_get_max_early_data()\fR and
|
|
\&\fISSL_SESSION_get_max_early_data()\fR return the maximum number of early data bytes
|
|
that may be sent.
|
|
.PP
|
|
\&\fISSL_set_max_early_data()\fR, \fISSL_CTX_set_max_early_data()\fR and
|
|
\&\fISSL_SESSION_set_max_early_data()\fR return 1 for success or 0 for failure.
|
|
.PP
|
|
\&\fISSL_get_early_data_status()\fR returns \s-1SSL_EARLY_DATA_ACCEPTED\s0 if early data was
|
|
accepted by the server, \s-1SSL_EARLY_DATA_REJECTED\s0 if early data was rejected by
|
|
the server, or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fISSL_get_error\fR\|(3),
|
|
\&\fISSL_write_ex\fR\|(3),
|
|
\&\fISSL_read_ex\fR\|(3),
|
|
\&\fISSL_connect\fR\|(3),
|
|
\&\fISSL_accept\fR\|(3),
|
|
\&\fISSL_do_handshake\fR\|(3),
|
|
\&\fISSL_CTX_set_psk_use_session_callback\fR\|(3),
|
|
\&\fIssl\fR\|(7)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
All of the functions described above were added in OpenSSL 1.1.1.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|