1SSL_READ_EARLY_DATA(3) OpenSSL SSL_READ_EARLY_DATA(3)
2
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
17 #include <openssl/ssl.h>
18 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 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 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 int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written);
33 int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
35 int SSL_get_early_data_status(const SSL *s);
37 typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg);
40 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
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 only be sent if a session has
53 previously been established with the server, and the server is known to
54 support it. Additionally these functions can be used to send data from
55 the server to the client when the client has not yet completed the
56 authentication stage of the handshake.
57 Early data has weaker security properties than other data sent over an
59 SSL/TLS connection. In particular the data does not have forward
60 secrecy. There are also additional considerations around replay attacks
61 (see "REPLAY PROTECTION" below). For these reasons extreme care should
62 be exercised when using early data. For specific details, consult the
63 TLS 1.3 specification.
64 When a server receives early data it may opt to immediately respond by
66 sending application data back to the client. Data sent by the server at
67 this stage is done before the full handshake has been completed.
68 Specifically the client's authentication messages have not yet been
69 received, i.e. the client is unauthenticated at this point and care
70 should be taken when using this capability.
71 A server or client can determine whether the full handshake has been
73 completed or not by calling SSL_is_init_finished(3).
74 On the client side, the function SSL_SESSION_get_max_early_data() can
76 be used to determine if a session established with a server can be used
77 to send early data. If the session cannot be used then this function
78 will return 0. Otherwise it will return the maximum number of early
79 data bytes that can be sent.
80 The function SSL_SESSION_set_max_early_data() sets the maximum number
82 of early data bytes that can be sent for a session. This would
83 typically be used when creating a PSK session file (see
84 SSL_CTX_set_psk_use_session_callback(3)). If using a ticket based PSK
85 then this is set automatically to the value provided by the server.
86 A client uses the function SSL_write_early_data() to send early data.
88 This function is similar to the SSL_write_ex(3) function, but with the
89 following differences. See SSL_write_ex(3) for information on how to
90 write bytes to the underlying connection, and how to handle any errors
91 that may arise. This page describes the differences between
92 SSL_write_early_data() and SSL_write_ex(3).
93 When called by a client, SSL_write_early_data() must be the first IO
95 function called on a new connection, i.e. it must occur before any
96 calls to SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
97 SSL_do_handshake(3) or other similar functions. It may be called
98 multiple times to stream data to the server, but the total number of
99 bytes written must not exceed the value returned from
100 SSL_SESSION_get_max_early_data(). Once the initial
101 SSL_write_early_data() call has completed successfully the client may
102 interleave calls to SSL_read_ex(3) and SSL_read(3) with calls to
103 SSL_write_early_data() as required.
104 If SSL_write_early_data() fails you should call SSL_get_error(3) to
106 determine the correct course of action, as for SSL_write_ex(3).
107 When the client no longer wishes to send any more early data then it
109 should complete the handshake by calling a function such as
110 SSL_connect(3) or SSL_do_handshake(3). Alternatively you can call a
111 standard write function such as SSL_write_ex(3), which will
112 transparently complete the connection and write the requested data.
113 A server may choose to ignore early data that has been sent to it. Once
115 the connection has been completed you can determine whether the server
116 accepted or rejected the early data by calling
117 SSL_get_early_data_status(). This will return SSL_EARLY_DATA_ACCEPTED
118 if the data was accepted, SSL_EARLY_DATA_REJECTED if it was rejected or
119 SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function may be
120 called by either the client or the server.
121 A server uses the SSL_read_early_data() function to receive early data
123 on a connection for which early data has been enabled using
124 SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for
125 SSL_write_early_data(), this must be the first IO function called on a
126 connection, i.e. it must occur before any calls to SSL_write_ex(3),
127 SSL_read_ex(3), SSL_accept(3), SSL_do_handshake(3), or other similar
128 functions.
129 SSL_read_early_data() is similar to SSL_read_ex(3) with the following
131 differences. Refer to SSL_read_ex(3) for full details.
132 SSL_read_early_data() may return 3 possible values:
134 SSL_READ_EARLY_DATA_ERROR
136 This indicates an IO or some other error occurred. This should be
137 treated in the same way as a 0 return value from SSL_read_ex(3).
138 SSL_READ_EARLY_DATA_SUCCESS
140 This indicates that early data was successfully read. This should
141 be treated in the same way as a 1 return value from SSL_read_ex(3).
142 You should continue to call SSL_read_early_data() to read more
143 data.
144 SSL_READ_EARLY_DATA_FINISH
146 This indicates that no more early data can be read. It may be
147 returned on the first call to SSL_read_early_data() if the client
148 has not sent any early data, or if the early data was rejected.
149 Once the initial SSL_read_early_data() call has completed successfully
151 (i.e. it has returned SSL_READ_EARLY_DATA_SUCCESS or
152 SSL_READ_EARLY_DATA_FINISH) then the server may choose to write data
153 immediately to the unauthenticated client using SSL_write_early_data().
154 If SSL_read_early_data() returned SSL_READ_EARLY_DATA_FINISH then in
155 some situations (e.g. if the client only supports TLSv1.2) the
156 handshake may have already been completed and calls to
157 SSL_write_early_data() are not allowed. Call SSL_is_init_finished(3) to
158 determine whether the handshake has completed or not. If the handshake
159 is still in progress then the server may interleave calls to
160 SSL_write_early_data() with calls to SSL_read_early_data() as required.
161 Servers must not call SSL_read_ex(3), SSL_read(3), SSL_write_ex(3) or
163 SSL_write(3) until SSL_read_early_data() has returned with
164 SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the
165 client still needs to be completed. Complete the connection by calling
166 a function such as SSL_accept(3) or SSL_do_handshake(3). Alternatively
167 you can call a standard read function such as SSL_read_ex(3), which
168 will transparently complete the connection and read the requested data.
169 Note that it is an error to attempt to complete the connection before
170 SSL_read_early_data() has returned SSL_READ_EARLY_DATA_FINISH.
171 Only servers may call SSL_read_early_data().
173 Calls to SSL_read_early_data() may, in certain circumstances, complete
175 the connection immediately without further need to call a function such
176 as SSL_accept(3). This can happen if the client is using a protocol
177 version less than TLSv1.3. Applications can test for this by calling
178 SSL_is_init_finished(3). Alternatively, applications may choose to call
179 SSL_accept(3) anyway. Such a call will successfully return immediately
180 with no further action taken.
181 When a session is created between a server and a client the server will
183 specify the maximum amount of any early data that it will accept on any
184 future connection attempt. By default the server does not accept early
185 data; a server may indicate support for early data by calling
186 SSL_CTX_set_max_early_data() or SSL_set_max_early_data() to set it for
187 the whole SSL_CTX or an individual SSL object respectively. The
188 max_early_data parameter specifies the maximum amount of early data in
189 bytes that is permitted to be sent on a single connection. Similarly
190 the SSL_CTX_get_max_early_data() and SSL_get_max_early_data() functions
191 can be used to obtain the current maximum early data settings for the
192 SSL_CTX and SSL objects respectively. Generally a server application
193 will either use both of SSL_read_early_data() and
194 SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither
195 of them, since there is no practical benefit from using only one of
196 them. If the maximum early data setting for a server is non-zero then
197 replay protection is automatically enabled (see "REPLAY PROTECTION"
198 below).
199 If the server rejects the early data sent by a client then it will skip
201 over the data that is sent. The maximum amount of received early data
202 that is skipped is controlled by the recv_max_early_data setting. If a
203 client sends more than this then the connection will abort. This value
204 can be set by calling SSL_CTX_set_recv_max_early_data() or
205 SSL_set_recv_max_early_data(). The current value for this setting can
206 be obtained by calling SSL_CTX_get_recv_max_early_data() or
207 SSL_get_recv_max_early_data(). The default value for this setting is
208 16,384 bytes.
209 The recv_max_early_data value also has an impact on early data that is
211 accepted. The amount of data that is accepted will always be the lower
212 of the max_early_data for the session and the recv_max_early_data
213 setting for the server. If a client sends more data than this then the
214 connection will abort.
215 The configured value for max_early_data on a server may change over
217 time as required. However clients may have tickets containing the
218 previously configured max_early_data value. The recv_max_early_data
219 should always be equal to or higher than any recently configured
220 max_early_data value in order to avoid aborted connections. The
221 recv_max_early_data should never be set to less than the current
222 configured max_early_data value.
223 Some server applications may wish to have more control over whether
225 early data is accepted or not, for example to mitigate replay risks
226 (see "REPLAY PROTECTION" below) or to decline early_data when the
227 server is heavily loaded. The functions
228 SSL_CTX_set_allow_early_data_cb() and SSL_set_allow_early_data_cb() set
229 a callback which is called at a point in the handshake immediately
230 before a decision is made to accept or reject early data. The callback
231 is provided with a pointer to the user data argument that was provided
232 when the callback was first set. Returning 1 from the callback will
233 allow early data and returning 0 will reject it. Note that the OpenSSL
234 library may reject early data for other reasons in which case this
235 callback will not get called. Notably, the built-in replay protection
236 feature will still be used even if a callback is present unless it has
237 been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See
238 "REPLAY PROTECTION" below.
239
241 The whole purpose of early data is to enable a client to start sending
242 data to the server before a full round trip of network traffic has
243 occurred. Application developers should ensure they consider
244 optimisation of the underlying TCP socket to obtain a performant
245 solution. For example Nagle's algorithm is commonly used by operating
246 systems in an attempt to avoid lots of small TCP packets. In many
247 scenarios this is beneficial for performance, but it does not work well
248 with the early data solution as implemented in OpenSSL. In Nagle's
249 algorithm the OS will buffer outgoing TCP data if a TCP packet has
250 already been sent which we have not yet received an ACK for from the
251 peer. The buffered data will only be transmitted if enough data to fill
252 an entire TCP packet is accumulated, or if the ACK is received from the
253 peer. The initial ClientHello will be sent in the first TCP packet
254 along with any data from the first call to SSL_write_early_data(). If
255 the amount of data written will exceed the size of a single TCP packet,
256 or if there are more calls to SSL_write_early_data() then that
257 additional data will be sent in subsequent TCP packets which will be
258 buffered by the OS and not sent until an ACK is received for the first
259 packet containing the ClientHello. This means the early data is not
260 actually sent until a complete round trip with the server has occurred
261 which defeats the objective of early data.
262 In many operating systems the TCP_NODELAY socket option is available to
264 disable Nagle's algorithm. If an application opts to disable Nagle's
265 algorithm consideration should be given to turning it back on again
266 after the handshake is complete if appropriate.
267 In rare circumstances, it may be possible for a client to have a
269 session that reports a max early data value greater than 0, but where
270 the server does not support this. For example, this can occur if a
271 server has had its configuration changed to accept a lower max early
272 data value such as by calling SSL_CTX_set_recv_max_early_data().
273 Another example is if a server used to support TLSv1.3 but was later
274 downgraded to TLSv1.2. Sending early data to such a server will cause
275 the connection to abort. Clients that encounter an aborted connection
276 while sending early data may want to retry the connection without
277 sending early data as this does not happen automatically. A client will
278 have to establish a new transport layer connection to the server and
279 attempt the SSL/TLS connection again but without sending early data.
280 Note that it is inadvisable to retry with a lower maximum protocol
281 version.
282
284 When early data is in use the TLS protocol provides no security
285 guarantees that the same early data was not replayed across multiple
286 connections. As a mitigation for this issue OpenSSL automatically
287 enables replay protection if the server is configured with a non-zero
288 max early data value. With replay protection enabled sessions are
289 forced to be single use only. If a client attempts to reuse a session
290 ticket more than once, then the second and subsequent attempts will
291 fall back to a full handshake (and any early data that was submitted
292 will be ignored). Note that single use tickets are enforced even if a
293 client does not send any early data.
294 The replay protection mechanism relies on the internal OpenSSL server
296 session cache (see SSL_CTX_set_session_cache_mode(3)). When replay
297 protection is being used the server will operate as if the
298 SSL_OP_NO_TICKET option had been selected (see SSL_CTX_set_options(3)).
299 Sessions will be added to the cache whenever a session ticket is
300 issued. When a client attempts to resume the session, OpenSSL will
301 check for its presence in the internal cache. If it exists then the
302 resumption is allowed and the session is removed from the cache. If it
303 does not exist then the resumption is not allowed and a full handshake
304 will occur.
305 Note that some applications may maintain an external cache of sessions
307 (see SSL_CTX_sess_set_new_cb(3) and similar functions). It is the
308 application's responsibility to ensure that any sessions in the
309 external cache are also populated in the internal cache and that once
310 removed from the internal cache they are similarly removed from the
311 external cache. Failing to do this could result in an application
312 becoming vulnerable to replay attacks. Note that OpenSSL will lock the
313 internal cache while a session is removed but that lock is not held
314 when the remove session callback (see SSL_CTX_sess_set_remove_cb(3)) is
315 called. This could result in a small amount of time where the session
316 has been removed from the internal cache but is still available in the
317 external cache. Applications should be designed with this in mind in
318 order to minimise the possibility of replay attacks.
319 The OpenSSL replay protection does not apply to external Pre Shared
321 Keys (PSKs) (e.g. see SSL_CTX_set_psk_find_session_callback(3)).
322 Therefore extreme caution should be applied when combining external
323 PSKs with early data.
324 Some applications may mitigate the replay risks in other ways. For
326 those applications it is possible to turn off the built-in replay
327 protection feature using the SSL_OP_NO_ANTI_REPLAY option. See
328 SSL_CTX_set_options(3) for details. Applications can also set a
329 callback to make decisions about accepting early data or not. See
330 SSL_CTX_set_allow_early_data_cb() above for details.
331
333 SSL_write_early_data() returns 1 for success or 0 for failure. In the
334 event of a failure call SSL_get_error(3) to determine the correct
335 course of action.
336 SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
338 SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
339 SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In
340 the event of a failure call SSL_get_error(3) to determine the correct
341 course of action.
342 SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
344 SSL_SESSION_get_max_early_data() return the maximum number of early
345 data bytes that may be sent.
346 SSL_set_max_early_data(), SSL_CTX_set_max_early_data() and
348 SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure.
349 SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early
351 data was accepted by the server, SSL_EARLY_DATA_REJECTED if early data
352 was rejected by the server, or SSL_EARLY_DATA_NOT_SENT if no early data
353 was sent.
354
356 SSL_get_error(3), SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
357 SSL_accept(3), SSL_do_handshake(3),
358 SSL_CTX_set_psk_use_session_callback(3), ssl(7)
359
361 All of the functions described above were added in OpenSSL 1.1.1.
362
364 Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
365 Licensed under the OpenSSL license (the "License"). You may not use
367 this file except in compliance with the License. You can obtain a copy
368 in the file LICENSE in the source distribution or at
369 <https://www.openssl.org/source/license.html>.
3701.1.1c 2019-05-28 SSL_READ_EARLY_DATA(3)