1SSL_READ_EARLY_DATA(3)              OpenSSL             SSL_READ_EARLY_DATA(3)
2
3
4

NAME

6       SSL_set_max_early_data, SSL_CTX_set_max_early_data,
7       SSL_get_max_early_data, SSL_CTX_get_max_early_data,
8       SSL_set_recv_max_early_data, SSL_CTX_set_recv_max_early_data,
9       SSL_get_recv_max_early_data, SSL_CTX_get_recv_max_early_data,
10       SSL_SESSION_get_max_early_data, SSL_SESSION_set_max_early_data,
11       SSL_write_early_data, SSL_read_early_data, SSL_get_early_data_status,
12       SSL_allow_early_data_cb_fn, SSL_CTX_set_allow_early_data_cb,
13       SSL_set_allow_early_data_cb - functions for sending and receiving early
14       data
15

SYNOPSIS

17        #include <openssl/ssl.h>
18
19        int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data);
20        uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx);
21        int SSL_set_max_early_data(SSL *s, uint32_t max_early_data);
22        uint32_t SSL_get_max_early_data(const SSL *s);
23
24        int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data);
25        uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx);
26        int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data);
27        uint32_t SSL_get_recv_max_early_data(const SSL *s);
28
29        uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
30        int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data);
31
32        int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written);
33
34        int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
35
36        int SSL_get_early_data_status(const SSL *s);
37
38
39        typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg);
40
41        void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx,
42                                             SSL_allow_early_data_cb_fn cb,
43                                             void *arg);
44        void SSL_set_allow_early_data_cb(SSL *s,
45                                         SSL_allow_early_data_cb_fn cb,
46                                         void *arg);
47

DESCRIPTION

49       These functions are used to send and receive early data where TLSv1.3
50       has been negotiated. Early data can be sent by the client immediately
51       after its initial ClientHello without having to wait for the server to
52       complete the handshake.  Early data can be sent if a session has
53       previously been established with the server or when establishing a new
54       session using an out-of-band PSK, and only when the server is known to
55       support it. Additionally these functions can be used to send data from
56       the server to the client when the client has not yet completed the
57       authentication stage of the handshake.
58
59       Early data has weaker security properties than other data sent over an
60       SSL/TLS connection. In particular the data does not have forward
61       secrecy. There are also additional considerations around replay attacks
62       (see "REPLAY PROTECTION" below). For these reasons extreme care should
63       be exercised when using early data. For specific details, consult the
64       TLS 1.3 specification.
65
66       When a server receives early data it may opt to immediately respond by
67       sending application data back to the client. Data sent by the server at
68       this stage is done before the full handshake has been completed.
69       Specifically the client's authentication messages have not yet been
70       received, i.e. the client is unauthenticated at this point and care
71       should be taken when using this capability.
72
73       A server or client can determine whether the full handshake has been
74       completed or not by calling SSL_is_init_finished(3).
75
76       On the client side, the function SSL_SESSION_get_max_early_data() can
77       be used to determine if a session established with a server can be used
78       to send early data.  If the session cannot be used then this function
79       will return 0. Otherwise it will return the maximum number of early
80       data bytes that can be sent.
81
82       The function SSL_SESSION_set_max_early_data() sets the maximum number
83       of early data bytes that can be sent for a session. This would
84       typically be used when creating a PSK session file (see
85       SSL_CTX_set_psk_use_session_callback(3)). If using a ticket based PSK
86       then this is set automatically to the value provided by the server.
87
88       A client uses the function SSL_write_early_data() to send early data.
89       This function is similar to the SSL_write_ex(3) function, but with the
90       following differences. See SSL_write_ex(3) for information on how to
91       write bytes to the underlying connection, and how to handle any errors
92       that may arise. This page describes the differences between
93       SSL_write_early_data() and SSL_write_ex(3).
94
95       When called by a client, SSL_write_early_data() must be the first IO
96       function called on a new connection, i.e. it must occur before any
97       calls to SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
98       SSL_do_handshake(3) or other similar functions. It may be called
99       multiple times to stream data to the server, but the total number of
100       bytes written must not exceed the value returned from
101       SSL_SESSION_get_max_early_data(). Once the initial
102       SSL_write_early_data() call has completed successfully the client may
103       interleave calls to SSL_read_ex(3) and SSL_read(3) with calls to
104       SSL_write_early_data() as required.
105
106       If SSL_write_early_data() fails you should call SSL_get_error(3) to
107       determine the correct course of action, as for SSL_write_ex(3).
108
109       When the client no longer wishes to send any more early data then it
110       should complete the handshake by calling a function such as
111       SSL_connect(3) or SSL_do_handshake(3). Alternatively you can call a
112       standard write function such as SSL_write_ex(3), which will
113       transparently complete the connection and write the requested data.
114
115       A server may choose to ignore early data that has been sent to it. Once
116       the connection has been completed you can determine whether the server
117       accepted or rejected the early data by calling
118       SSL_get_early_data_status(). This will return SSL_EARLY_DATA_ACCEPTED
119       if the data was accepted, SSL_EARLY_DATA_REJECTED if it was rejected or
120       SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function may be
121       called by either the client or the server.
122
123       A server uses the SSL_read_early_data() function to receive early data
124       on a connection for which early data has been enabled using
125       SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for
126       SSL_write_early_data(), this must be the first IO function called on a
127       connection, i.e. it must occur before any calls to SSL_write_ex(3),
128       SSL_read_ex(3), SSL_accept(3), SSL_do_handshake(3), or other similar
129       functions.
130
131       SSL_read_early_data() is similar to SSL_read_ex(3) with the following
132       differences. Refer to SSL_read_ex(3) for full details.
133
134       SSL_read_early_data() may return 3 possible values:
135
136       SSL_READ_EARLY_DATA_ERROR
137           This indicates an IO or some other error occurred. This should be
138           treated in the same way as a 0 return value from SSL_read_ex(3).
139
140       SSL_READ_EARLY_DATA_SUCCESS
141           This indicates that early data was successfully read. This should
142           be treated in the same way as a 1 return value from SSL_read_ex(3).
143           You should continue to call SSL_read_early_data() to read more
144           data.
145
146       SSL_READ_EARLY_DATA_FINISH
147           This indicates that no more early data can be read. It may be
148           returned on the first call to SSL_read_early_data() if the client
149           has not sent any early data, or if the early data was rejected.
150
151       Once the initial SSL_read_early_data() call has completed successfully
152       (i.e. it has returned SSL_READ_EARLY_DATA_SUCCESS or
153       SSL_READ_EARLY_DATA_FINISH) then the server may choose to write data
154       immediately to the unauthenticated client using SSL_write_early_data().
155       If SSL_read_early_data() returned SSL_READ_EARLY_DATA_FINISH then in
156       some situations (e.g. if the client only supports TLSv1.2) the
157       handshake may have already been completed and calls to
158       SSL_write_early_data() are not allowed. Call SSL_is_init_finished(3) to
159       determine whether the handshake has completed or not. If the handshake
160       is still in progress then the server may interleave calls to
161       SSL_write_early_data() with calls to SSL_read_early_data() as required.
162
163       Servers must not call SSL_read_ex(3), SSL_read(3), SSL_write_ex(3) or
164       SSL_write(3)  until SSL_read_early_data() has returned with
165       SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the
166       client still needs to be completed. Complete the connection by calling
167       a function such as SSL_accept(3) or SSL_do_handshake(3). Alternatively
168       you can call a standard read function such as SSL_read_ex(3), which
169       will transparently complete the connection and read the requested data.
170       Note that it is an error to attempt to complete the connection before
171       SSL_read_early_data() has returned SSL_READ_EARLY_DATA_FINISH.
172
173       Only servers may call SSL_read_early_data().
174
175       Calls to SSL_read_early_data() may, in certain circumstances, complete
176       the connection immediately without further need to call a function such
177       as SSL_accept(3). This can happen if the client is using a protocol
178       version less than TLSv1.3. Applications can test for this by calling
179       SSL_is_init_finished(3). Alternatively, applications may choose to call
180       SSL_accept(3) anyway. Such a call will successfully return immediately
181       with no further action taken.
182
183       When a session is created between a server and a client the server will
184       specify the maximum amount of any early data that it will accept on any
185       future connection attempt. By default the server does not accept early
186       data; a server may indicate support for early data by calling
187       SSL_CTX_set_max_early_data() or SSL_set_max_early_data() to set it for
188       the whole SSL_CTX or an individual SSL object respectively. The
189       max_early_data parameter specifies the maximum amount of early data in
190       bytes that is permitted to be sent on a single connection. Similarly
191       the SSL_CTX_get_max_early_data() and SSL_get_max_early_data() functions
192       can be used to obtain the current maximum early data settings for the
193       SSL_CTX and SSL objects respectively. Generally a server application
194       will either use both of SSL_read_early_data() and
195       SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither
196       of them, since there is no practical benefit from using only one of
197       them. If the maximum early data setting for a server is nonzero then
198       replay protection is automatically enabled (see "REPLAY PROTECTION"
199       below).
200
201       If the server rejects the early data sent by a client then it will skip
202       over the data that is sent. The maximum amount of received early data
203       that is skipped is controlled by the recv_max_early_data setting. If a
204       client sends more than this then the connection will abort. This value
205       can be set by calling SSL_CTX_set_recv_max_early_data() or
206       SSL_set_recv_max_early_data(). The current value for this setting can
207       be obtained by calling SSL_CTX_get_recv_max_early_data() or
208       SSL_get_recv_max_early_data(). The default value for this setting is
209       16,384 bytes.
210
211       The recv_max_early_data value also has an impact on early data that is
212       accepted.  The amount of data that is accepted will always be the lower
213       of the max_early_data for the session and the recv_max_early_data
214       setting for the server. If a client sends more data than this then the
215       connection will abort.
216
217       The configured value for max_early_data on a server may change over
218       time as required. However, clients may have tickets containing the
219       previously configured max_early_data value. The recv_max_early_data
220       should always be equal to or higher than any recently configured
221       max_early_data value in order to avoid aborted connections. The
222       recv_max_early_data should never be set to less than the current
223       configured max_early_data value.
224
225       Some server applications may wish to have more control over whether
226       early data is accepted or not, for example to mitigate replay risks
227       (see "REPLAY PROTECTION" below) or to decline early_data when the
228       server is heavily loaded. The functions
229       SSL_CTX_set_allow_early_data_cb() and SSL_set_allow_early_data_cb() set
230       a callback which is called at a point in the handshake immediately
231       before a decision is made to accept or reject early data. The callback
232       is provided with a pointer to the user data argument that was provided
233       when the callback was first set. Returning 1 from the callback will
234       allow early data and returning 0 will reject it. Note that the OpenSSL
235       library may reject early data for other reasons in which case this
236       callback will not get called. Notably, the built-in replay protection
237       feature will still be used even if a callback is present unless it has
238       been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See
239       "REPLAY PROTECTION" below.
240

NOTES

242       The whole purpose of early data is to enable a client to start sending
243       data to the server before a full round trip of network traffic has
244       occurred. Application developers should ensure they consider
245       optimisation of the underlying TCP socket to obtain a performant
246       solution. For example Nagle's algorithm is commonly used by operating
247       systems in an attempt to avoid lots of small TCP packets. In many
248       scenarios this is beneficial for performance, but it does not work well
249       with the early data solution as implemented in OpenSSL. In Nagle's
250       algorithm the OS will buffer outgoing TCP data if a TCP packet has
251       already been sent which we have not yet received an ACK for from the
252       peer. The buffered data will only be transmitted if enough data to fill
253       an entire TCP packet is accumulated, or if the ACK is received from the
254       peer. The initial ClientHello will be sent in the first TCP packet
255       along with any data from the first call to SSL_write_early_data(). If
256       the amount of data written will exceed the size of a single TCP packet,
257       or if there are more calls to SSL_write_early_data() then that
258       additional data will be sent in subsequent TCP packets which will be
259       buffered by the OS and not sent until an ACK is received for the first
260       packet containing the ClientHello. This means the early data is not
261       actually sent until a complete round trip with the server has occurred
262       which defeats the objective of early data.
263
264       In many operating systems the TCP_NODELAY socket option is available to
265       disable Nagle's algorithm. If an application opts to disable Nagle's
266       algorithm consideration should be given to turning it back on again
267       after the handshake is complete if appropriate.
268
269       In rare circumstances, it may be possible for a client to have a
270       session that reports a max early data value greater than 0, but where
271       the server does not support this. For example, this can occur if a
272       server has had its configuration changed to accept a lower max early
273       data value such as by calling SSL_CTX_set_recv_max_early_data().
274       Another example is if a server used to support TLSv1.3 but was later
275       downgraded to TLSv1.2. Sending early data to such a server will cause
276       the connection to abort. Clients that encounter an aborted connection
277       while sending early data may want to retry the connection without
278       sending early data as this does not happen automatically. A client will
279       have to establish a new transport layer connection to the server and
280       attempt the SSL/TLS connection again but without sending early data.
281       Note that it is inadvisable to retry with a lower maximum protocol
282       version.
283

REPLAY PROTECTION

285       When early data is in use the TLS protocol provides no security
286       guarantees that the same early data was not replayed across multiple
287       connections. As a mitigation for this issue OpenSSL automatically
288       enables replay protection if the server is configured with a nonzero
289       max early data value. With replay protection enabled sessions are
290       forced to be single use only. If a client attempts to reuse a session
291       ticket more than once, then the second and subsequent attempts will
292       fall back to a full handshake (and any early data that was submitted
293       will be ignored). Note that single use tickets are enforced even if a
294       client does not send any early data.
295
296       The replay protection mechanism relies on the internal OpenSSL server
297       session cache (see SSL_CTX_set_session_cache_mode(3)). When replay
298       protection is being used the server will operate as if the
299       SSL_OP_NO_TICKET option had been selected (see SSL_CTX_set_options(3)).
300       Sessions will be added to the cache whenever a session ticket is
301       issued. When a client attempts to resume the session, OpenSSL will
302       check for its presence in the internal cache. If it exists then the
303       resumption is allowed and the session is removed from the cache. If it
304       does not exist then the resumption is not allowed and a full handshake
305       will occur.
306
307       Note that some applications may maintain an external cache of sessions
308       (see SSL_CTX_sess_set_new_cb(3) and similar functions). It is the
309       application's responsibility to ensure that any sessions in the
310       external cache are also populated in the internal cache and that once
311       removed from the internal cache they are similarly removed from the
312       external cache. Failing to do this could result in an application
313       becoming vulnerable to replay attacks. Note that OpenSSL will lock the
314       internal cache while a session is removed but that lock is not held
315       when the remove session callback (see SSL_CTX_sess_set_remove_cb(3)) is
316       called. This could result in a small amount of time where the session
317       has been removed from the internal cache but is still available in the
318       external cache. Applications should be designed with this in mind in
319       order to minimise the possibility of replay attacks.
320
321       The OpenSSL replay protection does not apply to external Pre Shared
322       Keys (PSKs) (e.g. see SSL_CTX_set_psk_find_session_callback(3)).
323       Therefore, extreme caution should be applied when combining external
324       PSKs with early data.
325
326       Some applications may mitigate the replay risks in other ways. For
327       those applications it is possible to turn off the built-in replay
328       protection feature using the SSL_OP_NO_ANTI_REPLAY option. See
329       SSL_CTX_set_options(3) for details. Applications can also set a
330       callback to make decisions about accepting early data or not. See
331       SSL_CTX_set_allow_early_data_cb() above for details.
332

RETURN VALUES

334       SSL_write_early_data() returns 1 for success or 0 for failure. In the
335       event of a failure call SSL_get_error(3) to determine the correct
336       course of action.
337
338       SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
339       SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
340       SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In
341       the event of a failure call SSL_get_error(3) to determine the correct
342       course of action.
343
344       SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
345       SSL_SESSION_get_max_early_data() return the maximum number of early
346       data bytes that may be sent.
347
348       SSL_set_max_early_data(), SSL_CTX_set_max_early_data() and
349       SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure.
350
351       SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early
352       data was accepted by the server, SSL_EARLY_DATA_REJECTED if early data
353       was rejected by the server, or SSL_EARLY_DATA_NOT_SENT if no early data
354       was sent.
355

SEE ALSO

357       SSL_get_error(3), SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
358       SSL_accept(3), SSL_do_handshake(3),
359       SSL_CTX_set_psk_use_session_callback(3), ssl(7)
360

HISTORY

362       All of the functions described above were added in OpenSSL 1.1.1.
363
365       Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
366
367       Licensed under the OpenSSL license (the "License").  You may not use
368       this file except in compliance with the License.  You can obtain a copy
369       in the file LICENSE in the source distribution or at
370       <https://www.openssl.org/source/license.html>.
371
372
373
3741.1.1k                            2021-03-26            SSL_READ_EARLY_DATA(3)
Impressum