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