58 These functions are used to send and receive early data where TLSv1.3 has been
60 ClientHello without having to wait for the server to complete the handshake.
63 when the server is known to support it. Additionally these functions can be used
64 to send data from the server to the client when the client has not yet completed
73 When a server receives early data it may opt to immediately respond by sending
74 application data back to the client. Data sent by the server at this stage is
83 On the client side, the function SSL_SESSION_get_max_early_data() can be used to
84 determine if a session established with a server can be used to send early data.
91 using a ticket based PSK then this is set automatically to the value provided by
94 A client uses the function SSL_write_early_data() to send early data. This
95 function is similar to the L<SSL_write_ex(3)> function, but with the following
96 differences. See L<SSL_write_ex(3)> for information on how to write bytes to
97 the underlying connection, and how to handle any errors that may arise. This
102 called on a new connection, i.e. it must occur before any calls to
104 or other similar functions. It may be called multiple times to stream data to
108 calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to
111 If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine
114 When the client no longer wishes to send any more early data then it should
120 A server may choose to ignore early data that has been sent to it. Once the
127 A server uses the SSL_read_early_data() function to receive early data on a
131 called on a connection, i.e. it must occur before any calls to
135 SSL_read_early_data() is similar to L<SSL_read_ex(3)> with the following
136 differences. Refer to L<SSL_read_ex(3)> for full details.
150 the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to
151 call SSL_read_early_data() to read more data.
156 first call to SSL_read_early_data() if the client has not sent any early data,
163 server may choose to write data immediately to the unauthenticated client using
167 to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to
169 in progress then the server may interleave calls to SSL_write_early_data() with
170 calls to SSL_read_early_data() as required.
174 SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client
175 still needs to be completed. Complete the connection by calling a function such
178 complete the connection and read the requested data. Note that it is an error to
179 attempt to complete the connection before SSL_read_early_data() has returned
184 Calls to SSL_read_early_data() may, in certain circumstances, complete the
185 connection immediately without further need to call a function such as
188 L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call
197 SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL
199 amount of early data in bytes that is permitted to be sent on a single
201 SSL_get_max_early_data() functions can be used to obtain the current maximum
225 max_early_data value. The recv_max_early_data should always be equal to or
226 higher than any recently configured max_early_data value in order to avoid
227 aborted connections. The recv_max_early_data should never be set to less than
230 Some server applications may wish to have more control over whether early data
231 is accepted or not, for example to mitigate replay risks (see L</REPLAY PROTECTION>
232 below) or to decline early_data when the server is heavily loaded. The functions
235 decision is made to accept or reject early data. The callback is provided with a
236 pointer to the user data argument that was provided when the callback was first
251 The whole purpose of early data is to enable a client to start sending data to
254 to obtain a performant solution. For example Nagle's algorithm is commonly used
255 by operating systems in an attempt to avoid lots of small TCP packets. In many
260 transmitted if enough data to fill an entire TCP packet is accumulated, or if
262 first TCP packet along with any data from the first call to
264 single TCP packet, or if there are more calls to SSL_write_early_data() then
271 In many operating systems the TCP_NODELAY socket option is available to disable
272 Nagle's algorithm. If an application opts to disable Nagle's algorithm
273 consideration should be given to turning it back on again after the handshake is
276 In rare circumstances, it may be possible for a client to have a session that
279 changed to accept a lower max early data value such as by calling
280 SSL_CTX_set_recv_max_early_data(). Another example is if a server used to
281 support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such
282 a server will cause the connection to abort. Clients that encounter an aborted
283 connection while sending early data may want to retry the connection without
284 sending early data as this does not happen automatically. A client will have to
285 establish a new transport layer connection to the server and attempt the SSL/TLS
286 connection again but without sending early data. Note that it is inadvisable to
295 protection enabled sessions are forced to be single use only. If a client
296 attempts to reuse a session ticket more than once, then the second and
297 subsequent attempts will fall back to a full handshake (and any early data that
304 selected (see L<SSL_CTX_set_options(3)>). Sessions will be added to the cache
305 whenever a session ticket is issued. When a client attempts to resume the
313 responsibility to ensure that any sessions in the external cache are also
315 they are similarly removed from the external cache. Failing to do this could
316 result in an application becoming vulnerable to replay attacks. Note that
321 cache. Applications should be designed with this in mind in order to minimise
324 The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs)
329 applications it is possible to turn off the built-in replay protection feature
331 details. Applications can also set a callback to make decisions about accepting
337 failure call L<SSL_get_error(3)> to determine the correct course of action.
340 SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
341 SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the
342 event of a failure call L<SSL_get_error(3)> to determine the correct course of

Last Index update Fri Nov 22 14:03:13 UTC 2024

Dedicated to & Maintained by Room-11