Standard preamble:
========================================================================
..
.... 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 -- \(*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\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, 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.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
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 . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . 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 . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . 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 .\} ========================================================================
Title "SSL_READ_EARLY_DATA 3"
way too many mistakes in technical documents.
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 PROTECTION\*(R"\s0 below). For these reasons extreme care should be exercised when using early data. For specific details, consult the \s-1TLS 1.3\s0 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 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 \s-1PSK\s0 session file (see SSL_CTX_set_psk_use_session_callback\|(3)). If using a ticket based \s-1PSK\s0 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 SSL_write_ex\|(3) function, but with the following differences. See 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 \fBSSL_write_ex\|(3).
When called by a client, SSL_write_early_data() must be the first \s-1IO\s0 function called on a new connection, i.e. it must occur before any calls to \fBSSL_write_ex\|(3), SSL_read_ex\|(3), SSL_connect\|(3), 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 \fBSSL_write_early_data() call has completed successfully the client may interleave calls to SSL_read_ex\|(3) and SSL_read\|(3) with calls to \fBSSL_write_early_data() as required.
If SSL_write_early_data() fails you should call SSL_get_error\|(3) to determine the correct course of action, as for 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 SSL_connect\|(3) or \fBSSL_do_handshake\|(3). Alternatively you can call a standard write function such as 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 \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.
A server uses the SSL_read_early_data() function to receive early data on a connection for which early data has been enabled using \fBSSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for \fBSSL_write_early_data(), this must be the first \s-1IO\s0 function called on a connection, i.e. it must occur before any calls to \fBSSL_write_ex\|(3), SSL_read_ex\|(3), SSL_accept\|(3), SSL_do_handshake\|(3), or other similar functions.
\fBSSL_read_early_data() is similar to SSL_read_ex\|(3) with the following differences. Refer to SSL_read_ex\|(3) for full details.
\fBSSL_read_early_data() may return 3 possible values:
Once the initial SSL_read_early_data() 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 \fBSSL_write_early_data(). If SSL_read_early_data() 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 SSL_write_early_data() are not allowed. Call 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 SSL_read_ex\|(3), SSL_read\|(3), SSL_write_ex\|(3) or \fBSSL_write\|(3) until SSL_read_early_data() 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 SSL_accept\|(3) or SSL_do_handshake\|(3). Alternatively you can call a standard read function such as 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 \s-1SSL_READ_EARLY_DATA_FINISH.\s0
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 \fBSSL_accept\|(3). This can happen if the client is using a protocol version less than TLSv1.3. Applications can test for this by calling \fBSSL_is_init_finished\|(3). Alternatively, applications may choose to call \fBSSL_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 the server does not accept early data; a server may indicate support for early data by calling \fBSSL_CTX_set_max_early_data() or \fBSSL_set_max_early_data() to set it for the whole \s-1SSL_CTX\s0 or an individual \s-1SSL\s0 object respectively. The max_early_data parameter specifies the maximum amount of early data in bytes that is permitted to be sent on a single connection. Similarly the SSL_CTX_get_max_early_data() and \fBSSL_get_max_early_data() 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 SSL_read_early_data() and \fBSSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), 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 PROTECTION\*(R"\s0 below).
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 \fBSSL_CTX_set_recv_max_early_data() or SSL_set_recv_max_early_data(). The current value for this setting can be obtained by calling \fBSSL_CTX_get_recv_max_early_data() or SSL_get_recv_max_early_data(). The default value for this setting is 16,384 bytes.
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.
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.
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 PROTECTION\*(R"\s0 below) or to decline early_data when the server is heavily loaded. The functions \fBSSL_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 \s-1SSL_OP_NO_ANTI_REPLAY\s0 option. See \*(L"\s-1REPLAY PROTECTION\*(R"\s0 below.
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.
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 \fBSSL_CTX_set_recv_max_early_data(). 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.
The replay protection mechanism relies on the internal OpenSSL server session cache (see SSL_CTX_set_session_cache_mode\|(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 SSL_CTX_set_options\|(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.
Note that some applications may maintain an external cache of sessions (see \fBSSL_CTX_sess_set_new_cb\|(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 SSL_CTX_sess_set_remove_cb\|(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.
The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs) (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 \s-1SSL_OP_NO_ANTI_REPLAY\s0 option. See 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.
\fBSSL_read_early_data() 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 SSL_get_error\|(3) to determine the correct course of action.
\fBSSL_get_max_early_data(), SSL_CTX_get_max_early_data() and \fBSSL_SESSION_get_max_early_data() return the maximum number of early data bytes that may be sent.
\fBSSL_set_max_early_data(), SSL_CTX_set_max_early_data() and \fBSSL_SESSION_set_max_early_data() return 1 for success or 0 for failure.
\fBSSL_get_early_data_status() 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.
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>.