]>
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, | |
9 | SSL_SESSION_get_max_early_data, | |
e17e1df7 | 10 | SSL_SESSION_set_max_early_data, |
0665b4ed | 11 | SSL_write_early_data, |
f533fbd4 | 12 | SSL_read_early_data, |
fd6c1025 MC |
13 | SSL_get_early_data_status |
14 | - functions for sending and receiving early data | |
15 | ||
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/ssl.h> | |
19 | ||
20 | int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data); | |
21 | uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx); | |
22 | int SSL_set_max_early_data(SSL *s, uint32_t max_early_data); | |
a8e75d56 | 23 | uint32_t SSL_get_max_early_data(const SSL *s); |
fd6c1025 | 24 | uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s); |
e17e1df7 | 25 | int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data); |
fd6c1025 | 26 | |
0665b4ed | 27 | int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written); |
fd6c1025 | 28 | |
f533fbd4 | 29 | int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes); |
fd6c1025 MC |
30 | |
31 | int SSL_get_early_data_status(const SSL *s); | |
32 | ||
33 | =head1 DESCRIPTION | |
34 | ||
27b138e9 | 35 | These functions are used to send and receive early data where TLSv1.3 has been |
cd9f7f62 MC |
36 | negotiated. Early data can be sent by the client immediately after its initial |
37 | ClientHello without having to wait for the server to complete the handshake. | |
38 | Early data can only be sent if a session has previously been established with | |
39 | the server, and the server is known to support it. Additionally these functions | |
40 | can be used to send data from the server to the client when the client has not | |
41 | yet completed the authentication stage of the handshake. | |
fd6c1025 MC |
42 | |
43 | Early data has weaker security properties than other data sent over an SSL/TLS | |
cd9f7f62 MC |
44 | connection. In particular the data does not have forward secrecy and there are |
45 | no guarantees that the same early data was not replayed across multiple | |
fd6c1025 | 46 | connections. For this reason extreme care should be exercised when using early |
83750d9b | 47 | data. For specific details, consult the TLS 1.3 specification. |
fd6c1025 | 48 | |
ef466acc MC |
49 | When a server receives early data it may opt to immediately respond by sending |
50 | application data back to the client. Data sent by the server at this stage is | |
51 | done before the full handshake has been completed. Specifically the client's | |
52 | authentication messages have not yet been received, i.e. the client is | |
cd9f7f62 MC |
53 | unauthenticated at this point and care should be taken when using this |
54 | capability. | |
ef466acc MC |
55 | |
56 | A server or client can determine whether the full handshake has been completed | |
57 | or not by calling L<SSL_is_init_finished(3)>. | |
58 | ||
cd9f7f62 MC |
59 | On the client side, the function SSL_SESSION_get_max_early_data() can be used to |
60 | determine if a session established with a server can be used to send early data. | |
61 | If the session cannot be used then this function will return 0. Otherwise it | |
62 | will return the maximum number of early data bytes that can be sent. | |
fd6c1025 | 63 | |
e17e1df7 MC |
64 | The function SSL_SESSION_set_max_early_data() sets the maximum number of early |
65 | data bytes that can be sent for a session. This would typically be used when | |
0ef28021 MC |
66 | creating a PSK session file (see L<SSL_CTX_set_psk_use_session_callback(3)>). If |
67 | using a ticket based PSK then this is set automatically to the value provided by | |
68 | the server. | |
e17e1df7 | 69 | |
0665b4ed | 70 | A client uses the function SSL_write_early_data() to send early data. This |
cd9f7f62 MC |
71 | function is similar to the L<SSL_write_ex(3)> function, but with the following |
72 | differences. See L<SSL_write_ex(3)> for information on how to write bytes to | |
73 | the underlying connection, and how to handle any errors that may arise. This | |
74 | page describes the differences between SSL_write_early_data() and | |
75 | L<SSL_write_ex(3)>. | |
fd6c1025 | 76 | |
09f28874 MC |
77 | When called by a client, SSL_write_early_data() must be the first IO function |
78 | called on a new connection, i.e. it must occur before any calls to | |
79 | L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_connect(3)>, L<SSL_do_handshake(3)> | |
80 | or other similar functions. It may be called multiple times to stream data to | |
81 | the server, but the total number of bytes written must not exceed the value | |
82 | returned from SSL_SESSION_get_max_early_data(). Once the initial | |
83 | SSL_write_early_data() call has completed successfully the client may interleave | |
84 | calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to | |
85 | SSL_write_early_data() as required. | |
fd6c1025 | 86 | |
0665b4ed MC |
87 | If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine |
88 | the correct course of action, as for L<SSL_write_ex(3)>. | |
fd6c1025 | 89 | |
ef466acc MC |
90 | When the client no longer wishes to send any more early data then it should |
91 | complete the handshake by calling a function such as L<SSL_connect(3)> or | |
92 | L<SSL_do_handshake(3)>. Alternatively you can call a standard write function | |
93 | such as L<SSL_write_ex(3)>, which will transparently complete the connection and | |
94 | write the requested data. | |
fd6c1025 | 95 | |
fd6c1025 MC |
96 | A server may choose to ignore early data that has been sent to it. Once the |
97 | connection has been completed you can determine whether the server accepted or | |
98 | rejected the early data by calling SSL_get_early_data_status(). This will return | |
99 | SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it | |
100 | was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function | |
101 | may be called by either the client or the server. | |
102 | ||
f533fbd4 | 103 | A server uses the SSL_read_early_data() function to receive early data on a |
c39e4048 BK |
104 | connection for which early data has been enabled using |
105 | SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for | |
106 | SSL_write_early_data(), this must be the first IO function | |
0665b4ed MC |
107 | called on a connection, i.e. it must occur before any calls to |
108 | L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>, | |
109 | or other similar functions. | |
fd6c1025 | 110 | |
cd9f7f62 MC |
111 | SSL_read_early_data() is similar to L<SSL_read_ex(3)> with the following |
112 | differences. Refer to L<SSL_read_ex(3)> for full details. | |
fd6c1025 | 113 | |
f533fbd4 | 114 | SSL_read_early_data() may return 3 possible values: |
fd6c1025 MC |
115 | |
116 | =over 4 | |
117 | ||
f533fbd4 | 118 | =item SSL_READ_EARLY_DATA_ERROR |
fd6c1025 | 119 | |
f4411faa | 120 | This indicates an IO or some other error occurred. This should be treated in the |
fd6c1025 MC |
121 | same way as a 0 return value from L<SSL_read_ex(3)>. |
122 | ||
f533fbd4 | 123 | =item SSL_READ_EARLY_DATA_SUCCESS |
fd6c1025 MC |
124 | |
125 | This indicates that early data was successfully read. This should be treated in | |
126 | the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to | |
f533fbd4 | 127 | call SSL_read_early_data() to read more data. |
fd6c1025 | 128 | |
f533fbd4 | 129 | =item SSL_READ_EARLY_DATA_FINISH |
fd6c1025 MC |
130 | |
131 | This indicates that no more early data can be read. It may be returned on the | |
f533fbd4 MC |
132 | first call to SSL_read_early_data() if the client has not sent any early data, |
133 | or if the early data was rejected. | |
fd6c1025 MC |
134 | |
135 | =back | |
136 | ||
09f28874 MC |
137 | Once the initial SSL_read_early_data() call has completed successfully (i.e. it |
138 | has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the | |
139 | server may choose to write data immediately to the unauthenticated client using | |
140 | SSL_write_early_data(). If SSL_read_early_data() returned | |
141 | SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only | |
cd9f7f62 | 142 | supports TLSv1.2) the handshake may have already been completed and calls |
09f28874 MC |
143 | to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to |
144 | determine whether the handshake has completed or not. If the handshake is still | |
145 | in progress then the server may interleave calls to SSL_write_early_data() with | |
146 | calls to SSL_read_early_data() as required. | |
147 | ||
148 | Servers must not call L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or | |
149 | L<SSL_write(3)> until SSL_read_early_data() has returned with | |
150 | SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client | |
151 | still needs to be completed. Complete the connection by calling a function such | |
152 | as L<SSL_accept(3)> or L<SSL_do_handshake(3)>. Alternatively you can call a | |
153 | standard read function such as L<SSL_read_ex(3)>, which will transparently | |
154 | complete the connection and read the requested data. Note that it is an error to | |
155 | attempt to complete the connection before SSL_read_early_data() has returned | |
156 | SSL_READ_EARLY_DATA_FINISH. | |
f533fbd4 MC |
157 | |
158 | Only servers may call SSL_read_early_data(). | |
159 | ||
160 | Calls to SSL_read_early_data() may, in certain circumstances, complete the | |
161 | connection immediately without further need to call a function such as | |
cd9f7f62 MC |
162 | L<SSL_accept(3)>. This can happen if the client is using a protocol version less |
163 | than TLSv1.3. Applications can test for this by calling | |
f533fbd4 | 164 | L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call |
27b138e9 | 165 | L<SSL_accept(3)> anyway. Such a call will successfully return immediately with no |
f533fbd4 | 166 | further action taken. |
ef466acc | 167 | |
fd6c1025 MC |
168 | When a session is created between a server and a client the server will specify |
169 | the maximum amount of any early data that it will accept on any future | |
c39e4048 BK |
170 | connection attempt. By default the server does not accept early data; a |
171 | server may indicate support for early data by calling | |
172 | SSL_CTX_set_max_early_data() or | |
fd6c1025 MC |
173 | SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL |
174 | object respectively. Similarly the SSL_CTX_get_max_early_data() and | |
175 | SSL_get_max_early_data() functions can be used to obtain the current maximum | |
176 | early data settings for the SSL_CTX and SSL objects respectively. | |
c39e4048 BK |
177 | Generally a server application will either use both of SSL_read_early_data() |
178 | and SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither | |
179 | of them, since there is no practical benefit from using only one of them. | |
fd6c1025 MC |
180 | |
181 | In the event that the current maximum early data setting for the server is | |
182 | different to that originally specified in a session that a client is resuming | |
183 | with then the lower of the two values will apply. | |
184 | ||
0299f3f7 MC |
185 | =head1 NOTES |
186 | ||
187 | The whole purpose of early data is to enable a client to start sending data to | |
188 | the server before a full round trip of network traffic has occurred. Application | |
189 | developers should ensure they consider optimisation of the underlying TCP socket | |
190 | to obtain a performant solution. For example Nagle's algorithm is commonly used | |
191 | by operating systems in an attempt to avoid lots of small TCP packets. In many | |
192 | scenarios this is beneficial for performance, but it does not work well with the | |
193 | early data solution as implemented in OpenSSL. In Nagle's algorithm the OS will | |
194 | buffer outgoing TCP data if a TCP packet has already been sent which we have not | |
195 | yet received an ACK for from the peer. The buffered data will only be | |
196 | transmitted if enough data to fill an entire TCP packet is accumulated, or if | |
c6a623ad MC |
197 | the ACK is received from the peer. The initial ClientHello will be sent in the |
198 | first TCP packet along with any data from the first call to | |
199 | SSL_write_early_data(). If the amount of data written will exceed the size of a | |
200 | single TCP packet, or if there are more calls to SSL_write_early_data() then | |
201 | that additional data will be sent in subsequent TCP packets which will be | |
202 | buffered by the OS and not sent until an ACK is received for the first packet | |
203 | containing the ClientHello. This means the early data is not actually | |
0299f3f7 MC |
204 | sent until a complete round trip with the server has occurred which defeats the |
205 | objective of early data. | |
206 | ||
207 | In many operating systems the TCP_NODELAY socket option is available to disable | |
208 | Nagle's algorithm. If an application opts to disable Nagle's algorithm | |
209 | consideration should be given to turning it back on again after the handshake is | |
210 | complete if appropriate. | |
211 | ||
fd6c1025 MC |
212 | =head1 RETURN VALUES |
213 | ||
0665b4ed | 214 | SSL_write_early_data() returns 1 for success or 0 for failure. In the event of a |
ef466acc | 215 | failure call L<SSL_get_error(3)> to determine the correct course of action. |
fd6c1025 | 216 | |
f533fbd4 MC |
217 | SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure, |
218 | SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and | |
cd9f7f62 MC |
219 | SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the |
220 | event of a failure call L<SSL_get_error(3)> to determine the correct course of | |
221 | action. | |
fd6c1025 MC |
222 | |
223 | SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and | |
224 | SSL_SESSION_get_max_early_data() return the maximum number of early data bytes | |
225 | that may be sent. | |
226 | ||
e17e1df7 MC |
227 | SSL_set_max_early_data(), SSL_CTX_set_max_early_data() and |
228 | SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure. | |
fd6c1025 MC |
229 | |
230 | SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early data was | |
231 | accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by | |
232 | the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent. | |
233 | ||
234 | =head1 SEE ALSO | |
235 | ||
236 | L<SSL_get_error(3)>, | |
237 | L<SSL_write_ex(3)>, | |
238 | L<SSL_read_ex(3)>, | |
239 | L<SSL_connect(3)>, | |
240 | L<SSL_accept(3)>, | |
241 | L<SSL_do_handshake(3)>, | |
e17e1df7 | 242 | L<SSL_CTX_set_psk_use_session_callback(3)>, |
fd6c1025 MC |
243 | L<ssl(7)> |
244 | ||
245 | =head1 HISTORY | |
246 | ||
247 | All of the functions described above were added in OpenSSL 1.1.1. | |
248 | ||
249 | =head1 COPYRIGHT | |
250 | ||
251 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
252 | ||
253 | Licensed under the OpenSSL license (the "License"). You may not use | |
254 | this file except in compliance with the License. You can obtain a copy | |
255 | in the file LICENSE in the source distribution or at | |
256 | L<https://www.openssl.org/source/license.html>. | |
257 | ||
258 | =cut |