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