]>
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, | |
0665b4ed | 10 | SSL_write_early_data, |
f533fbd4 | 11 | SSL_read_early_data, |
fd6c1025 MC |
12 | SSL_get_early_data_status |
13 | - functions for sending and receiving early data | |
14 | ||
15 | =head1 SYNOPSIS | |
16 | ||
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); | |
a8e75d56 | 22 | uint32_t SSL_get_max_early_data(const SSL *s); |
fd6c1025 MC |
23 | uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s); |
24 | ||
0665b4ed | 25 | int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written); |
fd6c1025 | 26 | |
f533fbd4 | 27 | int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes); |
fd6c1025 MC |
28 | |
29 | int SSL_get_early_data_status(const SSL *s); | |
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
cd9f7f62 MC |
33 | These functions are used to send and recieve early data where TLSv1.3 has been |
34 | negotiated. Early data can be sent by the client immediately after its initial | |
35 | ClientHello without having to wait for the server to complete the handshake. | |
36 | Early data can only be sent if a session has previously been established with | |
37 | the server, and the server is known to support it. Additionally these functions | |
38 | can be used to send data from the server to the client when the client has not | |
39 | yet completed the authentication stage of the handshake. | |
fd6c1025 MC |
40 | |
41 | Early data has weaker security properties than other data sent over an SSL/TLS | |
cd9f7f62 MC |
42 | connection. In particular the data does not have forward secrecy and there are |
43 | no guarantees that the same early data was not replayed across multiple | |
fd6c1025 | 44 | connections. For this reason extreme care should be exercised when using early |
83750d9b | 45 | data. For specific details, consult the TLS 1.3 specification. |
fd6c1025 | 46 | |
ef466acc MC |
47 | When a server receives early data it may opt to immediately respond by sending |
48 | application data back to the client. Data sent by the server at this stage is | |
49 | done before the full handshake has been completed. Specifically the client's | |
50 | authentication messages have not yet been received, i.e. the client is | |
cd9f7f62 MC |
51 | unauthenticated at this point and care should be taken when using this |
52 | capability. | |
ef466acc MC |
53 | |
54 | A server or client can determine whether the full handshake has been completed | |
55 | or not by calling L<SSL_is_init_finished(3)>. | |
56 | ||
cd9f7f62 MC |
57 | On the client side, the function SSL_SESSION_get_max_early_data() can be used to |
58 | determine if a session established with a server can be used to send early data. | |
59 | If the session cannot be used then this function will return 0. Otherwise it | |
60 | will return the maximum number of early data bytes that can be sent. | |
fd6c1025 | 61 | |
0665b4ed | 62 | A client uses the function SSL_write_early_data() to send early data. This |
cd9f7f62 MC |
63 | function is similar to the L<SSL_write_ex(3)> function, but with the following |
64 | differences. See L<SSL_write_ex(3)> for information on how to write bytes to | |
65 | the underlying connection, and how to handle any errors that may arise. This | |
66 | page describes the differences between SSL_write_early_data() and | |
67 | L<SSL_write_ex(3)>. | |
fd6c1025 | 68 | |
09f28874 MC |
69 | When called by a client, SSL_write_early_data() must be the first IO function |
70 | called on a new connection, i.e. it must occur before any calls to | |
71 | L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_connect(3)>, L<SSL_do_handshake(3)> | |
72 | or other similar functions. It may be called multiple times to stream data to | |
73 | the server, but the total number of bytes written must not exceed the value | |
74 | returned from SSL_SESSION_get_max_early_data(). Once the initial | |
75 | SSL_write_early_data() call has completed successfully the client may interleave | |
76 | calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to | |
77 | SSL_write_early_data() as required. | |
fd6c1025 | 78 | |
0665b4ed MC |
79 | If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine |
80 | the correct course of action, as for L<SSL_write_ex(3)>. | |
fd6c1025 | 81 | |
ef466acc MC |
82 | When the client no longer wishes to send any more early data then it should |
83 | complete the handshake by calling a function such as L<SSL_connect(3)> or | |
84 | L<SSL_do_handshake(3)>. Alternatively you can call a standard write function | |
85 | such as L<SSL_write_ex(3)>, which will transparently complete the connection and | |
86 | write the requested data. | |
fd6c1025 | 87 | |
fd6c1025 MC |
88 | A server may choose to ignore early data that has been sent to it. Once the |
89 | connection has been completed you can determine whether the server accepted or | |
90 | rejected the early data by calling SSL_get_early_data_status(). This will return | |
91 | SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it | |
92 | was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function | |
93 | may be called by either the client or the server. | |
94 | ||
f533fbd4 | 95 | A server uses the SSL_read_early_data() function to receive early data on a |
0665b4ed MC |
96 | connection. As for SSL_write_early_data() this must be the first IO function |
97 | called on a connection, i.e. it must occur before any calls to | |
98 | L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>, | |
99 | or other similar functions. | |
fd6c1025 | 100 | |
cd9f7f62 MC |
101 | SSL_read_early_data() is similar to L<SSL_read_ex(3)> with the following |
102 | differences. Refer to L<SSL_read_ex(3)> for full details. | |
fd6c1025 | 103 | |
f533fbd4 | 104 | SSL_read_early_data() may return 3 possible values: |
fd6c1025 MC |
105 | |
106 | =over 4 | |
107 | ||
f533fbd4 | 108 | =item SSL_READ_EARLY_DATA_ERROR |
fd6c1025 MC |
109 | |
110 | This indicates an IO or some other error occured. This should be treated in the | |
111 | same way as a 0 return value from L<SSL_read_ex(3)>. | |
112 | ||
f533fbd4 | 113 | =item SSL_READ_EARLY_DATA_SUCCESS |
fd6c1025 MC |
114 | |
115 | This indicates that early data was successfully read. This should be treated in | |
116 | the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to | |
f533fbd4 | 117 | call SSL_read_early_data() to read more data. |
fd6c1025 | 118 | |
f533fbd4 | 119 | =item SSL_READ_EARLY_DATA_FINISH |
fd6c1025 MC |
120 | |
121 | This indicates that no more early data can be read. It may be returned on the | |
f533fbd4 MC |
122 | first call to SSL_read_early_data() if the client has not sent any early data, |
123 | or if the early data was rejected. | |
fd6c1025 MC |
124 | |
125 | =back | |
126 | ||
09f28874 MC |
127 | Once the initial SSL_read_early_data() call has completed successfully (i.e. it |
128 | has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the | |
129 | server may choose to write data immediately to the unauthenticated client using | |
130 | SSL_write_early_data(). If SSL_read_early_data() returned | |
131 | SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only | |
cd9f7f62 | 132 | supports TLSv1.2) the handshake may have already been completed and calls |
09f28874 MC |
133 | to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to |
134 | determine whether the handshake has completed or not. If the handshake is still | |
135 | in progress then the server may interleave calls to SSL_write_early_data() with | |
136 | calls to SSL_read_early_data() as required. | |
137 | ||
138 | Servers must not call L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or | |
139 | L<SSL_write(3)> until SSL_read_early_data() has returned with | |
140 | SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client | |
141 | still needs to be completed. Complete the connection by calling a function such | |
142 | as L<SSL_accept(3)> or L<SSL_do_handshake(3)>. Alternatively you can call a | |
143 | standard read function such as L<SSL_read_ex(3)>, which will transparently | |
144 | complete the connection and read the requested data. Note that it is an error to | |
145 | attempt to complete the connection before SSL_read_early_data() has returned | |
146 | SSL_READ_EARLY_DATA_FINISH. | |
f533fbd4 MC |
147 | |
148 | Only servers may call SSL_read_early_data(). | |
149 | ||
150 | Calls to SSL_read_early_data() may, in certain circumstances, complete the | |
151 | connection immediately without further need to call a function such as | |
cd9f7f62 MC |
152 | L<SSL_accept(3)>. This can happen if the client is using a protocol version less |
153 | than TLSv1.3. Applications can test for this by calling | |
f533fbd4 MC |
154 | L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call |
155 | L<SSL_accept(3)> anway. Such a call will successfully return immediately with no | |
156 | further action taken. | |
ef466acc | 157 | |
fd6c1025 MC |
158 | When a session is created between a server and a client the server will specify |
159 | the maximum amount of any early data that it will accept on any future | |
160 | connection attempt. By default this is approximately 16k. A server may override | |
161 | this default value by calling SSL_CTX_set_max_early_data() or | |
162 | SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL | |
163 | object respectively. Similarly the SSL_CTX_get_max_early_data() and | |
164 | SSL_get_max_early_data() functions can be used to obtain the current maximum | |
165 | early data settings for the SSL_CTX and SSL objects respectively. | |
166 | ||
167 | In the event that the current maximum early data setting for the server is | |
168 | different to that originally specified in a session that a client is resuming | |
169 | with then the lower of the two values will apply. | |
170 | ||
171 | =head1 RETURN VALUES | |
172 | ||
0665b4ed | 173 | SSL_write_early_data() returns 1 for success or 0 for failure. In the event of a |
ef466acc | 174 | failure call L<SSL_get_error(3)> to determine the correct course of action. |
fd6c1025 | 175 | |
f533fbd4 MC |
176 | SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure, |
177 | SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and | |
cd9f7f62 MC |
178 | SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the |
179 | event of a failure call L<SSL_get_error(3)> to determine the correct course of | |
180 | action. | |
fd6c1025 MC |
181 | |
182 | SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and | |
183 | SSL_SESSION_get_max_early_data() return the maximum number of early data bytes | |
184 | that may be sent. | |
185 | ||
186 | SSL_set_max_early_data() and SSL_CTX_set_max_early_data() return 1 for success | |
187 | or 0 for failure. | |
188 | ||
189 | SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early data was | |
190 | accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by | |
191 | the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent. | |
192 | ||
193 | =head1 SEE ALSO | |
194 | ||
195 | L<SSL_get_error(3)>, | |
196 | L<SSL_write_ex(3)>, | |
197 | L<SSL_read_ex(3)>, | |
198 | L<SSL_connect(3)>, | |
199 | L<SSL_accept(3)>, | |
200 | L<SSL_do_handshake(3)>, | |
201 | L<ssl(7)> | |
202 | ||
203 | =head1 HISTORY | |
204 | ||
205 | All of the functions described above were added in OpenSSL 1.1.1. | |
206 | ||
207 | =head1 COPYRIGHT | |
208 | ||
209 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
210 | ||
211 | Licensed under the OpenSSL license (the "License"). You may not use | |
212 | this file except in compliance with the License. You can obtain a copy | |
213 | in the file LICENSE in the source distribution or at | |
214 | L<https://www.openssl.org/source/license.html>. | |
215 | ||
216 | =cut |