| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "SSL_READ_EARLY_DATA 3SSL" |
| 58 |
.TH SSL_READ_EARLY_DATA 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
SSL_set_max_early_data, |
| 65 |
SSL_CTX_set_max_early_data, |
| 66 |
SSL_get_max_early_data, |
| 67 |
SSL_CTX_get_max_early_data, |
| 68 |
SSL_set_recv_max_early_data, |
| 69 |
SSL_CTX_set_recv_max_early_data, |
| 70 |
SSL_get_recv_max_early_data, |
| 71 |
SSL_CTX_get_recv_max_early_data, |
| 72 |
SSL_SESSION_get_max_early_data, |
| 73 |
SSL_SESSION_set_max_early_data, |
| 74 |
SSL_write_early_data, |
| 75 |
SSL_read_early_data, |
| 76 |
SSL_get_early_data_status, |
| 77 |
SSL_allow_early_data_cb_fn, |
| 78 |
SSL_CTX_set_allow_early_data_cb, |
| 79 |
SSL_set_allow_early_data_cb |
| 80 |
\&\- functions for sending and receiving early data |
| 81 |
.SH SYNOPSIS |
| 82 |
.IX Header "SYNOPSIS" |
| 83 |
.Vb 1 |
| 84 |
\& #include <openssl/ssl.h> |
| 85 |
\& |
| 86 |
\& int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data); |
| 87 |
\& uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx); |
| 88 |
\& int SSL_set_max_early_data(SSL *s, uint32_t max_early_data); |
| 89 |
\& uint32_t SSL_get_max_early_data(const SSL *s); |
| 90 |
\& |
| 91 |
\& int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data); |
| 92 |
\& uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx); |
| 93 |
\& int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data); |
| 94 |
\& uint32_t SSL_get_recv_max_early_data(const SSL *s); |
| 95 |
\& |
| 96 |
\& uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s); |
| 97 |
\& int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data); |
| 98 |
\& |
| 99 |
\& int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written); |
| 100 |
\& |
| 101 |
\& int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes); |
| 102 |
\& |
| 103 |
\& int SSL_get_early_data_status(const SSL *s); |
| 104 |
\& |
| 105 |
\& |
| 106 |
\& typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg); |
| 107 |
\& |
| 108 |
\& void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx, |
| 109 |
\& SSL_allow_early_data_cb_fn cb, |
| 110 |
\& void *arg); |
| 111 |
\& void SSL_set_allow_early_data_cb(SSL *s, |
| 112 |
\& SSL_allow_early_data_cb_fn cb, |
| 113 |
\& void *arg); |
| 114 |
.Ve |
| 115 |
.SH DESCRIPTION |
| 116 |
.IX Header "DESCRIPTION" |
| 117 |
These functions are used to send and receive early data where TLSv1.3 has been |
| 118 |
negotiated. Early data can be sent by the client immediately after its initial |
| 119 |
ClientHello without having to wait for the server to complete the handshake. |
| 120 |
Early data can be sent if a session has previously been established with the |
| 121 |
server or when establishing a new session using an out-of-band PSK, and only |
| 122 |
when the server is known to support it. Additionally these functions can be used |
| 123 |
to send data from the server to the client when the client has not yet completed |
| 124 |
the authentication stage of the handshake. |
| 125 |
.PP |
| 126 |
Early data has weaker security properties than other data sent over an SSL/TLS |
| 127 |
connection. In particular the data does not have forward secrecy. There are also |
| 128 |
additional considerations around replay attacks (see "REPLAY PROTECTION" |
| 129 |
below). For these reasons extreme care should be exercised when using early |
| 130 |
data. For specific details, consult the TLS 1.3 specification. |
| 131 |
.PP |
| 132 |
When a server receives early data it may opt to immediately respond by sending |
| 133 |
application data back to the client. Data sent by the server at this stage is |
| 134 |
done before the full handshake has been completed. Specifically the client's |
| 135 |
authentication messages have not yet been received, i.e. the client is |
| 136 |
unauthenticated at this point and care should be taken when using this |
| 137 |
capability. |
| 138 |
.PP |
| 139 |
A server or client can determine whether the full handshake has been completed |
| 140 |
or not by calling \fBSSL_is_init_finished\fR\|(3). |
| 141 |
.PP |
| 142 |
On the client side, the function \fBSSL_SESSION_get_max_early_data()\fR can be used to |
| 143 |
determine if a session established with a server can be used to send early data. |
| 144 |
If the session cannot be used then this function will return 0. Otherwise it |
| 145 |
will return the maximum number of early data bytes that can be sent. |
| 146 |
.PP |
| 147 |
The function \fBSSL_SESSION_set_max_early_data()\fR sets the maximum number of early |
| 148 |
data bytes that can be sent for a session. This would typically be used when |
| 149 |
creating a PSK session file (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). If |
| 150 |
using a ticket based PSK then this is set automatically to the value provided by |
| 151 |
the server. |
| 152 |
.PP |
| 153 |
A client uses the function \fBSSL_write_early_data()\fR to send early data. This |
| 154 |
function is similar to the \fBSSL_write_ex\fR\|(3) function, but with the following |
| 155 |
differences. See \fBSSL_write_ex\fR\|(3) for information on how to write bytes to |
| 156 |
the underlying connection, and how to handle any errors that may arise. This |
| 157 |
page describes the differences between \fBSSL_write_early_data()\fR and |
| 158 |
\&\fBSSL_write_ex\fR\|(3). |
| 159 |
.PP |
| 160 |
When called by a client, \fBSSL_write_early_data()\fR must be the first IO function |
| 161 |
called on a new connection, i.e. it must occur before any calls to |
| 162 |
\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_connect\fR\|(3), \fBSSL_do_handshake\fR\|(3) |
| 163 |
or other similar functions. It may be called multiple times to stream data to |
| 164 |
the server, but the total number of bytes written must not exceed the value |
| 165 |
returned from \fBSSL_SESSION_get_max_early_data()\fR. Once the initial |
| 166 |
\&\fBSSL_write_early_data()\fR call has completed successfully the client may interleave |
| 167 |
calls to \fBSSL_read_ex\fR\|(3) and \fBSSL_read\fR\|(3) with calls to |
| 168 |
\&\fBSSL_write_early_data()\fR as required. |
| 169 |
.PP |
| 170 |
If \fBSSL_write_early_data()\fR fails you should call \fBSSL_get_error\fR\|(3) to determine |
| 171 |
the correct course of action, as for \fBSSL_write_ex\fR\|(3). |
| 172 |
.PP |
| 173 |
When the client no longer wishes to send any more early data then it should |
| 174 |
complete the handshake by calling a function such as \fBSSL_connect\fR\|(3) or |
| 175 |
\&\fBSSL_do_handshake\fR\|(3). Alternatively you can call a standard write function |
| 176 |
such as \fBSSL_write_ex\fR\|(3), which will transparently complete the connection and |
| 177 |
write the requested data. |
| 178 |
.PP |
| 179 |
A server may choose to ignore early data that has been sent to it. Once the |
| 180 |
connection has been completed you can determine whether the server accepted or |
| 181 |
rejected the early data by calling \fBSSL_get_early_data_status()\fR. This will return |
| 182 |
SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it |
| 183 |
was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function |
| 184 |
may be called by either the client or the server. |
| 185 |
.PP |
| 186 |
A server uses the \fBSSL_read_early_data()\fR function to receive early data on a |
| 187 |
connection for which early data has been enabled using |
| 188 |
\&\fBSSL_CTX_set_max_early_data()\fR or \fBSSL_set_max_early_data()\fR. As for |
| 189 |
\&\fBSSL_write_early_data()\fR, this must be the first IO function |
| 190 |
called on a connection, i.e. it must occur before any calls to |
| 191 |
\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_accept\fR\|(3), \fBSSL_do_handshake\fR\|(3), |
| 192 |
or other similar functions. |
| 193 |
.PP |
| 194 |
\&\fBSSL_read_early_data()\fR is similar to \fBSSL_read_ex\fR\|(3) with the following |
| 195 |
differences. Refer to \fBSSL_read_ex\fR\|(3) for full details. |
| 196 |
.PP |
| 197 |
\&\fBSSL_read_early_data()\fR may return 3 possible values: |
| 198 |
.IP SSL_READ_EARLY_DATA_ERROR 4 |
| 199 |
.IX Item "SSL_READ_EARLY_DATA_ERROR" |
| 200 |
This indicates an IO or some other error occurred. This should be treated in the |
| 201 |
same way as a 0 return value from \fBSSL_read_ex\fR\|(3). |
| 202 |
.IP SSL_READ_EARLY_DATA_SUCCESS 4 |
| 203 |
.IX Item "SSL_READ_EARLY_DATA_SUCCESS" |
| 204 |
This indicates that early data was successfully read. This should be treated in |
| 205 |
the same way as a 1 return value from \fBSSL_read_ex\fR\|(3). You should continue to |
| 206 |
call \fBSSL_read_early_data()\fR to read more data. |
| 207 |
.IP SSL_READ_EARLY_DATA_FINISH 4 |
| 208 |
.IX Item "SSL_READ_EARLY_DATA_FINISH" |
| 209 |
This indicates that no more early data can be read. It may be returned on the |
| 210 |
first call to \fBSSL_read_early_data()\fR if the client has not sent any early data, |
| 211 |
or if the early data was rejected. |
| 212 |
.PP |
| 213 |
Once the initial \fBSSL_read_early_data()\fR call has completed successfully (i.e. it |
| 214 |
has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the |
| 215 |
server may choose to write data immediately to the unauthenticated client using |
| 216 |
\&\fBSSL_write_early_data()\fR. If \fBSSL_read_early_data()\fR returned |
| 217 |
SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only |
| 218 |
supports TLSv1.2) the handshake may have already been completed and calls |
| 219 |
to \fBSSL_write_early_data()\fR are not allowed. Call \fBSSL_is_init_finished\fR\|(3) to |
| 220 |
determine whether the handshake has completed or not. If the handshake is still |
| 221 |
in progress then the server may interleave calls to \fBSSL_write_early_data()\fR with |
| 222 |
calls to \fBSSL_read_early_data()\fR as required. |
| 223 |
.PP |
| 224 |
Servers must not call \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or |
| 225 |
\&\fBSSL_write\fR\|(3) until \fBSSL_read_early_data()\fR has returned with |
| 226 |
SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client |
| 227 |
still needs to be completed. Complete the connection by calling a function such |
| 228 |
as \fBSSL_accept\fR\|(3) or \fBSSL_do_handshake\fR\|(3). Alternatively you can call a |
| 229 |
standard read function such as \fBSSL_read_ex\fR\|(3), which will transparently |
| 230 |
complete the connection and read the requested data. Note that it is an error to |
| 231 |
attempt to complete the connection before \fBSSL_read_early_data()\fR has returned |
| 232 |
SSL_READ_EARLY_DATA_FINISH. |
| 233 |
.PP |
| 234 |
Only servers may call \fBSSL_read_early_data()\fR. |
| 235 |
.PP |
| 236 |
Calls to \fBSSL_read_early_data()\fR may, in certain circumstances, complete the |
| 237 |
connection immediately without further need to call a function such as |
| 238 |
\&\fBSSL_accept\fR\|(3). This can happen if the client is using a protocol version less |
| 239 |
than TLSv1.3. Applications can test for this by calling |
| 240 |
\&\fBSSL_is_init_finished\fR\|(3). Alternatively, applications may choose to call |
| 241 |
\&\fBSSL_accept\fR\|(3) anyway. Such a call will successfully return immediately with no |
| 242 |
further action taken. |
| 243 |
.PP |
| 244 |
When a session is created between a server and a client the server will specify |
| 245 |
the maximum amount of any early data that it will accept on any future |
| 246 |
connection attempt. By default the server does not accept early data; a |
| 247 |
server may indicate support for early data by calling |
| 248 |
\&\fBSSL_CTX_set_max_early_data()\fR or |
| 249 |
\&\fBSSL_set_max_early_data()\fR to set it for the whole SSL_CTX or an individual SSL |
| 250 |
object respectively. The \fBmax_early_data\fR parameter specifies the maximum |
| 251 |
amount of early data in bytes that is permitted to be sent on a single |
| 252 |
connection. Similarly the \fBSSL_CTX_get_max_early_data()\fR and |
| 253 |
\&\fBSSL_get_max_early_data()\fR functions can be used to obtain the current maximum |
| 254 |
early data settings for the SSL_CTX and SSL objects respectively. Generally a |
| 255 |
server application will either use both of \fBSSL_read_early_data()\fR and |
| 256 |
\&\fBSSL_CTX_set_max_early_data()\fR (or \fBSSL_set_max_early_data()\fR), or neither of them, |
| 257 |
since there is no practical benefit from using only one of them. If the maximum |
| 258 |
early data setting for a server is nonzero then replay protection is |
| 259 |
automatically enabled (see "REPLAY PROTECTION" below). |
| 260 |
.PP |
| 261 |
If the server rejects the early data sent by a client then it will skip over |
| 262 |
the data that is sent. The maximum amount of received early data that is skipped |
| 263 |
is controlled by the recv_max_early_data setting. If a client sends more than |
| 264 |
this then the connection will abort. This value can be set by calling |
| 265 |
\&\fBSSL_CTX_set_recv_max_early_data()\fR or \fBSSL_set_recv_max_early_data()\fR. The current |
| 266 |
value for this setting can be obtained by calling |
| 267 |
\&\fBSSL_CTX_get_recv_max_early_data()\fR or \fBSSL_get_recv_max_early_data()\fR. The default |
| 268 |
value for this setting is 16,384 bytes. |
| 269 |
.PP |
| 270 |
The recv_max_early_data value also has an impact on early data that is accepted. |
| 271 |
The amount of data that is accepted will always be the lower of the |
| 272 |
max_early_data for the session and the recv_max_early_data setting for the |
| 273 |
server. If a client sends more data than this then the connection will abort. |
| 274 |
.PP |
| 275 |
The configured value for max_early_data on a server may change over time as |
| 276 |
required. However, clients may have tickets containing the previously configured |
| 277 |
max_early_data value. The recv_max_early_data should always be equal to or |
| 278 |
higher than any recently configured max_early_data value in order to avoid |
| 279 |
aborted connections. The recv_max_early_data should never be set to less than |
| 280 |
the current configured max_early_data value. |
| 281 |
.PP |
| 282 |
Some server applications may wish to have more control over whether early data |
| 283 |
is accepted or not, for example to mitigate replay risks (see "REPLAY PROTECTION" |
| 284 |
below) or to decline early_data when the server is heavily loaded. The functions |
| 285 |
\&\fBSSL_CTX_set_allow_early_data_cb()\fR and \fBSSL_set_allow_early_data_cb()\fR set a |
| 286 |
callback which is called at a point in the handshake immediately before a |
| 287 |
decision is made to accept or reject early data. The callback is provided with a |
| 288 |
pointer to the user data argument that was provided when the callback was first |
| 289 |
set. Returning 1 from the callback will allow early data and returning 0 will |
| 290 |
reject it. Note that the OpenSSL library may reject early data for other reasons |
| 291 |
in which case this callback will not get called. Notably, the built-in replay |
| 292 |
protection feature will still be used even if a callback is present unless it |
| 293 |
has been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See |
| 294 |
"REPLAY PROTECTION" below. |
| 295 |
.PP |
| 296 |
These functions cannot currently be used with QUIC SSL objects. |
| 297 |
\&\fBSSL_set_max_early_data()\fR, \fBSSL_set_recv_max_early_data()\fR, \fBSSL_write_early_data()\fR, |
| 298 |
\&\fBSSL_read_early_data()\fR, \fBSSL_get_early_data_status()\fR and |
| 299 |
\&\fBSSL_set_allow_early_data_cb()\fR fail if called on a QUIC SSL object. |
| 300 |
.SH NOTES |
| 301 |
.IX Header "NOTES" |
| 302 |
The whole purpose of early data is to enable a client to start sending data to |
| 303 |
the server before a full round trip of network traffic has occurred. Application |
| 304 |
developers should ensure they consider optimisation of the underlying TCP socket |
| 305 |
to obtain a performant solution. For example Nagle's algorithm is commonly used |
| 306 |
by operating systems in an attempt to avoid lots of small TCP packets. In many |
| 307 |
scenarios this is beneficial for performance, but it does not work well with the |
| 308 |
early data solution as implemented in OpenSSL. In Nagle's algorithm the OS will |
| 309 |
buffer outgoing TCP data if a TCP packet has already been sent which we have not |
| 310 |
yet received an ACK for from the peer. The buffered data will only be |
| 311 |
transmitted if enough data to fill an entire TCP packet is accumulated, or if |
| 312 |
the ACK is received from the peer. The initial ClientHello will be sent in the |
| 313 |
first TCP packet along with any data from the first call to |
| 314 |
\&\fBSSL_write_early_data()\fR. If the amount of data written will exceed the size of a |
| 315 |
single TCP packet, or if there are more calls to \fBSSL_write_early_data()\fR then |
| 316 |
that additional data will be sent in subsequent TCP packets which will be |
| 317 |
buffered by the OS and not sent until an ACK is received for the first packet |
| 318 |
containing the ClientHello. This means the early data is not actually |
| 319 |
sent until a complete round trip with the server has occurred which defeats the |
| 320 |
objective of early data. |
| 321 |
.PP |
| 322 |
In many operating systems the TCP_NODELAY socket option is available to disable |
| 323 |
Nagle's algorithm. If an application opts to disable Nagle's algorithm |
| 324 |
consideration should be given to turning it back on again after the handshake is |
| 325 |
complete if appropriate. |
| 326 |
.PP |
| 327 |
In rare circumstances, it may be possible for a client to have a session that |
| 328 |
reports a max early data value greater than 0, but where the server does not |
| 329 |
support this. For example, this can occur if a server has had its configuration |
| 330 |
changed to accept a lower max early data value such as by calling |
| 331 |
\&\fBSSL_CTX_set_recv_max_early_data()\fR. Another example is if a server used to |
| 332 |
support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such |
| 333 |
a server will cause the connection to abort. Clients that encounter an aborted |
| 334 |
connection while sending early data may want to retry the connection without |
| 335 |
sending early data as this does not happen automatically. A client will have to |
| 336 |
establish a new transport layer connection to the server and attempt the SSL/TLS |
| 337 |
connection again but without sending early data. Note that it is inadvisable to |
| 338 |
retry with a lower maximum protocol version. |
| 339 |
.SH "REPLAY PROTECTION" |
| 340 |
.IX Header "REPLAY PROTECTION" |
| 341 |
When early data is in use the TLS protocol provides no security guarantees that |
| 342 |
the same early data was not replayed across multiple connections. As a |
| 343 |
mitigation for this issue OpenSSL automatically enables replay protection if the |
| 344 |
server is configured with a nonzero max early data value. With replay |
| 345 |
protection enabled sessions are forced to be single use only. If a client |
| 346 |
attempts to reuse a session ticket more than once, then the second and |
| 347 |
subsequent attempts will fall back to a full handshake (and any early data that |
| 348 |
was submitted will be ignored). Note that single use tickets are enforced even |
| 349 |
if a client does not send any early data. |
| 350 |
.PP |
| 351 |
The replay protection mechanism relies on the internal OpenSSL server session |
| 352 |
cache (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). When replay protection is |
| 353 |
being used the server will operate as if the SSL_OP_NO_TICKET option had been |
| 354 |
selected (see \fBSSL_CTX_set_options\fR\|(3)). Sessions will be added to the cache |
| 355 |
whenever a session ticket is issued. When a client attempts to resume the |
| 356 |
session, OpenSSL will check for its presence in the internal cache. If it exists |
| 357 |
then the resumption is allowed and the session is removed from the cache. If it |
| 358 |
does not exist then the resumption is not allowed and a full handshake will |
| 359 |
occur. |
| 360 |
.PP |
| 361 |
Note that some applications may maintain an external cache of sessions (see |
| 362 |
\&\fBSSL_CTX_sess_set_new_cb\fR\|(3) and similar functions). It is the application's |
| 363 |
responsibility to ensure that any sessions in the external cache are also |
| 364 |
populated in the internal cache and that once removed from the internal cache |
| 365 |
they are similarly removed from the external cache. Failing to do this could |
| 366 |
result in an application becoming vulnerable to replay attacks. Note that |
| 367 |
OpenSSL will lock the internal cache while a session is removed but that lock is |
| 368 |
not held when the remove session callback (see \fBSSL_CTX_sess_set_remove_cb\fR\|(3)) |
| 369 |
is called. This could result in a small amount of time where the session has |
| 370 |
been removed from the internal cache but is still available in the external |
| 371 |
cache. Applications should be designed with this in mind in order to minimise |
| 372 |
the possibility of replay attacks. |
| 373 |
.PP |
| 374 |
The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs) |
| 375 |
(e.g. see \fBSSL_CTX_set_psk_find_session_callback\fR\|(3)). Therefore, extreme caution |
| 376 |
should be applied when combining external PSKs with early data. |
| 377 |
.PP |
| 378 |
Some applications may mitigate the replay risks in other ways. For those |
| 379 |
applications it is possible to turn off the built-in replay protection feature |
| 380 |
using the \fBSSL_OP_NO_ANTI_REPLAY\fR option. See \fBSSL_CTX_set_options\fR\|(3) for |
| 381 |
details. Applications can also set a callback to make decisions about accepting |
| 382 |
early data or not. See \fBSSL_CTX_set_allow_early_data_cb()\fR above for details. |
| 383 |
.SH "RETURN VALUES" |
| 384 |
.IX Header "RETURN VALUES" |
| 385 |
\&\fBSSL_write_early_data()\fR returns 1 for success or 0 for failure. In the event of a |
| 386 |
failure call \fBSSL_get_error\fR\|(3) to determine the correct course of action. |
| 387 |
.PP |
| 388 |
\&\fBSSL_read_early_data()\fR returns SSL_READ_EARLY_DATA_ERROR for failure, |
| 389 |
SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and |
| 390 |
SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the |
| 391 |
event of a failure call \fBSSL_get_error\fR\|(3) to determine the correct course of |
| 392 |
action. |
| 393 |
.PP |
| 394 |
\&\fBSSL_get_max_early_data()\fR, \fBSSL_CTX_get_max_early_data()\fR and |
| 395 |
\&\fBSSL_SESSION_get_max_early_data()\fR return the maximum number of early data bytes |
| 396 |
that may be sent. |
| 397 |
.PP |
| 398 |
\&\fBSSL_set_max_early_data()\fR, \fBSSL_CTX_set_max_early_data()\fR and |
| 399 |
\&\fBSSL_SESSION_set_max_early_data()\fR return 1 for success or 0 for failure. |
| 400 |
.PP |
| 401 |
\&\fBSSL_get_early_data_status()\fR returns SSL_EARLY_DATA_ACCEPTED if early data was |
| 402 |
accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by |
| 403 |
the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent. |
| 404 |
.SH "SEE ALSO" |
| 405 |
.IX Header "SEE ALSO" |
| 406 |
\&\fBSSL_get_error\fR\|(3), |
| 407 |
\&\fBSSL_write_ex\fR\|(3), |
| 408 |
\&\fBSSL_read_ex\fR\|(3), |
| 409 |
\&\fBSSL_connect\fR\|(3), |
| 410 |
\&\fBSSL_accept\fR\|(3), |
| 411 |
\&\fBSSL_do_handshake\fR\|(3), |
| 412 |
\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3), |
| 413 |
\&\fBssl\fR\|(7) |
| 414 |
.SH HISTORY |
| 415 |
.IX Header "HISTORY" |
| 416 |
All of the functions described above were added in OpenSSL 1.1.1. |
| 417 |
.SH COPYRIGHT |
| 418 |
.IX Header "COPYRIGHT" |
| 419 |
Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. |
| 420 |
.PP |
| 421 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 422 |
this file except in compliance with the License. You can obtain a copy |
| 423 |
in the file LICENSE in the source distribution or at |
| 424 |
<https://www.openssl.org/source/license.html>. |