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