diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_read_early_data.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_read_early_data.3 | 199 |
1 files changed, 64 insertions, 135 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_read_early_data.3 b/secure/lib/libcrypto/man/man3/SSL_read_early_data.3 index 8f3406673c2e..4d4a657e91ba 100644 --- a/secure/lib/libcrypto/man/man3/SSL_read_early_data.3 +++ b/secure/lib/libcrypto/man/man3/SSL_read_early_data.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,75 +52,15 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "SSL_READ_EARLY_DATA 3ossl" -.TH SSL_READ_EARLY_DATA 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH SSL_READ_EARLY_DATA 3ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME SSL_set_max_early_data, SSL_CTX_set_max_early_data, SSL_get_max_early_data, @@ -154,7 +78,7 @@ SSL_allow_early_data_cb_fn, SSL_CTX_set_allow_early_data_cb, SSL_set_allow_early_data_cb \&\- functions for sending and receiving early data -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/ssl.h> @@ -188,22 +112,22 @@ SSL_set_allow_early_data_cb \& SSL_allow_early_data_cb_fn cb, \& void *arg); .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" These functions are used to send and receive early data where TLSv1.3 has been negotiated. Early data can be sent by the client immediately after its initial ClientHello without having to wait for the server to complete the handshake. Early data can be sent if a session has previously been established with the -server or when establishing a new session using an out-of-band \s-1PSK,\s0 and only +server or when establishing a new session using an out-of-band PSK, and only when the server is known to support it. Additionally these functions can be used to send data from the server to the client when the client has not yet completed the authentication stage of the handshake. .PP -Early data has weaker security properties than other data sent over an \s-1SSL/TLS\s0 +Early data has weaker security properties than other data sent over an SSL/TLS connection. In particular the data does not have forward secrecy. There are also -additional considerations around replay attacks (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0 +additional considerations around replay attacks (see "REPLAY PROTECTION" below). For these reasons extreme care should be exercised when using early -data. For specific details, consult the \s-1TLS 1.3\s0 specification. +data. For specific details, consult the TLS 1.3 specification. .PP When a server receives early data it may opt to immediately respond by sending application data back to the client. Data sent by the server at this stage is @@ -222,8 +146,8 @@ will return the maximum number of early data bytes that can be sent. .PP The function \fBSSL_SESSION_set_max_early_data()\fR sets the maximum number of early data bytes that can be sent for a session. This would typically be used when -creating a \s-1PSK\s0 session file (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). If -using a ticket based \s-1PSK\s0 then this is set automatically to the value provided by +creating a PSK session file (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). If +using a ticket based PSK then this is set automatically to the value provided by the server. .PP A client uses the function \fBSSL_write_early_data()\fR to send early data. This @@ -233,7 +157,7 @@ the underlying connection, and how to handle any errors that may arise. This page describes the differences between \fBSSL_write_early_data()\fR and \&\fBSSL_write_ex\fR\|(3). .PP -When called by a client, \fBSSL_write_early_data()\fR must be the first \s-1IO\s0 function +When called by a client, \fBSSL_write_early_data()\fR must be the first IO function called on a new connection, i.e. it must occur before any calls to \&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_connect\fR\|(3), \fBSSL_do_handshake\fR\|(3) or other similar functions. It may be called multiple times to stream data to @@ -255,14 +179,14 @@ write the requested data. A server may choose to ignore early data that has been sent to it. Once the connection has been completed you can determine whether the server accepted or rejected the early data by calling \fBSSL_get_early_data_status()\fR. This will return -\&\s-1SSL_EARLY_DATA_ACCEPTED\s0 if the data was accepted, \s-1SSL_EARLY_DATA_REJECTED\s0 if it -was rejected or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent. This function +SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it +was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function may be called by either the client or the server. .PP A server uses the \fBSSL_read_early_data()\fR function to receive early data on a connection for which early data has been enabled using \&\fBSSL_CTX_set_max_early_data()\fR or \fBSSL_set_max_early_data()\fR. As for -\&\fBSSL_write_early_data()\fR, this must be the first \s-1IO\s0 function +\&\fBSSL_write_early_data()\fR, this must be the first IO function called on a connection, i.e. it must occur before any calls to \&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_accept\fR\|(3), \fBSSL_do_handshake\fR\|(3), or other similar functions. @@ -271,26 +195,26 @@ or other similar functions. differences. Refer to \fBSSL_read_ex\fR\|(3) for full details. .PP \&\fBSSL_read_early_data()\fR may return 3 possible values: -.IP "\s-1SSL_READ_EARLY_DATA_ERROR\s0" 4 +.IP SSL_READ_EARLY_DATA_ERROR 4 .IX Item "SSL_READ_EARLY_DATA_ERROR" -This indicates an \s-1IO\s0 or some other error occurred. This should be treated in the +This indicates an IO or some other error occurred. This should be treated in the same way as a 0 return value from \fBSSL_read_ex\fR\|(3). -.IP "\s-1SSL_READ_EARLY_DATA_SUCCESS\s0" 4 +.IP SSL_READ_EARLY_DATA_SUCCESS 4 .IX Item "SSL_READ_EARLY_DATA_SUCCESS" This indicates that early data was successfully read. This should be treated in the same way as a 1 return value from \fBSSL_read_ex\fR\|(3). You should continue to call \fBSSL_read_early_data()\fR to read more data. -.IP "\s-1SSL_READ_EARLY_DATA_FINISH\s0" 4 +.IP SSL_READ_EARLY_DATA_FINISH 4 .IX Item "SSL_READ_EARLY_DATA_FINISH" This indicates that no more early data can be read. It may be returned on the first call to \fBSSL_read_early_data()\fR if the client has not sent any early data, or if the early data was rejected. .PP Once the initial \fBSSL_read_early_data()\fR call has completed successfully (i.e. it -has returned \s-1SSL_READ_EARLY_DATA_SUCCESS\s0 or \s-1SSL_READ_EARLY_DATA_FINISH\s0) then the +has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the server may choose to write data immediately to the unauthenticated client using \&\fBSSL_write_early_data()\fR. If \fBSSL_read_early_data()\fR returned -\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 then in some situations (e.g. if the client only +SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only supports TLSv1.2) the handshake may have already been completed and calls to \fBSSL_write_early_data()\fR are not allowed. Call \fBSSL_is_init_finished\fR\|(3) to determine whether the handshake has completed or not. If the handshake is still @@ -299,13 +223,13 @@ calls to \fBSSL_read_early_data()\fR as required. .PP Servers must not call \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or \&\fBSSL_write\fR\|(3) until \fBSSL_read_early_data()\fR has returned with -\&\s-1SSL_READ_EARLY_DATA_FINISH.\s0 Once it has done so the connection to the client +SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client still needs to be completed. Complete the connection by calling a function such as \fBSSL_accept\fR\|(3) or \fBSSL_do_handshake\fR\|(3). Alternatively you can call a standard read function such as \fBSSL_read_ex\fR\|(3), which will transparently complete the connection and read the requested data. Note that it is an error to attempt to complete the connection before \fBSSL_read_early_data()\fR has returned -\&\s-1SSL_READ_EARLY_DATA_FINISH.\s0 +SSL_READ_EARLY_DATA_FINISH. .PP Only servers may call \fBSSL_read_early_data()\fR. .PP @@ -322,17 +246,17 @@ the maximum amount of any early data that it will accept on any future connection attempt. By default the server does not accept early data; a server may indicate support for early data by calling \&\fBSSL_CTX_set_max_early_data()\fR or -\&\fBSSL_set_max_early_data()\fR to set it for the whole \s-1SSL_CTX\s0 or an individual \s-1SSL\s0 +\&\fBSSL_set_max_early_data()\fR to set it for the whole SSL_CTX or an individual SSL object respectively. The \fBmax_early_data\fR parameter specifies the maximum amount of early data in bytes that is permitted to be sent on a single connection. Similarly the \fBSSL_CTX_get_max_early_data()\fR and \&\fBSSL_get_max_early_data()\fR functions can be used to obtain the current maximum -early data settings for the \s-1SSL_CTX\s0 and \s-1SSL\s0 objects respectively. Generally a +early data settings for the SSL_CTX and SSL objects respectively. Generally a server application will either use both of \fBSSL_read_early_data()\fR and \&\fBSSL_CTX_set_max_early_data()\fR (or \fBSSL_set_max_early_data()\fR), or neither of them, since there is no practical benefit from using only one of them. If the maximum early data setting for a server is nonzero then replay protection is -automatically enabled (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0 below). +automatically enabled (see "REPLAY PROTECTION" below). .PP If the server rejects the early data sent by a client then it will skip over the data that is sent. The maximum amount of received early data that is skipped @@ -356,7 +280,7 @@ aborted connections. The recv_max_early_data should never be set to less than the current configured max_early_data value. .PP Some server applications may wish to have more control over whether early data -is accepted or not, for example to mitigate replay risks (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0 +is accepted or not, for example to mitigate replay risks (see "REPLAY PROTECTION" below) or to decline early_data when the server is heavily loaded. The functions \&\fBSSL_CTX_set_allow_early_data_cb()\fR and \fBSSL_set_allow_early_data_cb()\fR set a callback which is called at a point in the handshake immediately before a @@ -366,31 +290,36 @@ set. Returning 1 from the callback will allow early data and returning 0 will reject it. Note that the OpenSSL library may reject early data for other reasons in which case this callback will not get called. Notably, the built-in replay protection feature will still be used even if a callback is present unless it -has been explicitly disabled using the \s-1SSL_OP_NO_ANTI_REPLAY\s0 option. See -\&\*(L"\s-1REPLAY PROTECTION\*(R"\s0 below. -.SH "NOTES" +has been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See +"REPLAY PROTECTION" below. +.PP +These functions cannot currently be used with QUIC SSL objects. +\&\fBSSL_set_max_early_data()\fR, \fBSSL_set_recv_max_early_data()\fR, \fBSSL_write_early_data()\fR, +\&\fBSSL_read_early_data()\fR, \fBSSL_get_early_data_status()\fR and +\&\fBSSL_set_allow_early_data_cb()\fR fail if called on a QUIC SSL object. +.SH NOTES .IX Header "NOTES" The whole purpose of early data is to enable a client to start sending data to the server before a full round trip of network traffic has occurred. Application -developers should ensure they consider optimisation of the underlying \s-1TCP\s0 socket +developers should ensure they consider optimisation of the underlying TCP socket to obtain a performant solution. For example Nagle's algorithm is commonly used -by operating systems in an attempt to avoid lots of small \s-1TCP\s0 packets. In many +by operating systems in an attempt to avoid lots of small TCP packets. In many scenarios this is beneficial for performance, but it does not work well with the -early data solution as implemented in OpenSSL. In Nagle's algorithm the \s-1OS\s0 will -buffer outgoing \s-1TCP\s0 data if a \s-1TCP\s0 packet has already been sent which we have not -yet received an \s-1ACK\s0 for from the peer. The buffered data will only be -transmitted if enough data to fill an entire \s-1TCP\s0 packet is accumulated, or if -the \s-1ACK\s0 is received from the peer. The initial ClientHello will be sent in the -first \s-1TCP\s0 packet along with any data from the first call to +early data solution as implemented in OpenSSL. In Nagle's algorithm the OS will +buffer outgoing TCP data if a TCP packet has already been sent which we have not +yet received an ACK for from the peer. The buffered data will only be +transmitted if enough data to fill an entire TCP packet is accumulated, or if +the ACK is received from the peer. The initial ClientHello will be sent in the +first TCP packet along with any data from the first call to \&\fBSSL_write_early_data()\fR. If the amount of data written will exceed the size of a -single \s-1TCP\s0 packet, or if there are more calls to \fBSSL_write_early_data()\fR then -that additional data will be sent in subsequent \s-1TCP\s0 packets which will be -buffered by the \s-1OS\s0 and not sent until an \s-1ACK\s0 is received for the first packet +single TCP packet, or if there are more calls to \fBSSL_write_early_data()\fR then +that additional data will be sent in subsequent TCP packets which will be +buffered by the OS and not sent until an ACK is received for the first packet containing the ClientHello. This means the early data is not actually sent until a complete round trip with the server has occurred which defeats the objective of early data. .PP -In many operating systems the \s-1TCP_NODELAY\s0 socket option is available to disable +In many operating systems the TCP_NODELAY socket option is available to disable Nagle's algorithm. If an application opts to disable Nagle's algorithm consideration should be given to turning it back on again after the handshake is complete if appropriate. @@ -404,12 +333,12 @@ support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such a server will cause the connection to abort. Clients that encounter an aborted connection while sending early data may want to retry the connection without sending early data as this does not happen automatically. A client will have to -establish a new transport layer connection to the server and attempt the \s-1SSL/TLS\s0 +establish a new transport layer connection to the server and attempt the SSL/TLS connection again but without sending early data. Note that it is inadvisable to retry with a lower maximum protocol version. .SH "REPLAY PROTECTION" .IX Header "REPLAY PROTECTION" -When early data is in use the \s-1TLS\s0 protocol provides no security guarantees that +When early data is in use the TLS protocol provides no security guarantees that the same early data was not replayed across multiple connections. As a mitigation for this issue OpenSSL automatically enables replay protection if the server is configured with a nonzero max early data value. With replay @@ -421,7 +350,7 @@ if a client does not send any early data. .PP The replay protection mechanism relies on the internal OpenSSL server session cache (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). When replay protection is -being used the server will operate as if the \s-1SSL_OP_NO_TICKET\s0 option had been +being used the server will operate as if the SSL_OP_NO_TICKET option had been selected (see \fBSSL_CTX_set_options\fR\|(3)). Sessions will be added to the cache whenever a session ticket is issued. When a client attempts to resume the session, OpenSSL will check for its presence in the internal cache. If it exists @@ -448,7 +377,7 @@ should be applied when combining external PSKs with early data. .PP Some applications may mitigate the replay risks in other ways. For those applications it is possible to turn off the built-in replay protection feature -using the \fB\s-1SSL_OP_NO_ANTI_REPLAY\s0\fR option. See \fBSSL_CTX_set_options\fR\|(3) for +using the \fBSSL_OP_NO_ANTI_REPLAY\fR option. See \fBSSL_CTX_set_options\fR\|(3) for details. Applications can also set a callback to make decisions about accepting early data or not. See \fBSSL_CTX_set_allow_early_data_cb()\fR above for details. .SH "RETURN VALUES" @@ -456,9 +385,9 @@ early data or not. See \fBSSL_CTX_set_allow_early_data_cb()\fR above for details \&\fBSSL_write_early_data()\fR returns 1 for success or 0 for failure. In the event of a failure call \fBSSL_get_error\fR\|(3) to determine the correct course of action. .PP -\&\fBSSL_read_early_data()\fR returns \s-1SSL_READ_EARLY_DATA_ERROR\s0 for failure, -\&\s-1SSL_READ_EARLY_DATA_SUCCESS\s0 for success with more data to read and -\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 for success with no more to data be read. In the +\&\fBSSL_read_early_data()\fR returns SSL_READ_EARLY_DATA_ERROR for failure, +SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and +SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the event of a failure call \fBSSL_get_error\fR\|(3) to determine the correct course of action. .PP @@ -469,9 +398,9 @@ that may be sent. \&\fBSSL_set_max_early_data()\fR, \fBSSL_CTX_set_max_early_data()\fR and \&\fBSSL_SESSION_set_max_early_data()\fR return 1 for success or 0 for failure. .PP -\&\fBSSL_get_early_data_status()\fR returns \s-1SSL_EARLY_DATA_ACCEPTED\s0 if early data was -accepted by the server, \s-1SSL_EARLY_DATA_REJECTED\s0 if early data was rejected by -the server, or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent. +\&\fBSSL_get_early_data_status()\fR returns SSL_EARLY_DATA_ACCEPTED if early data was +accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by +the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBSSL_get_error\fR\|(3), @@ -482,14 +411,14 @@ the server, or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent. \&\fBSSL_do_handshake\fR\|(3), \&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3), \&\fBssl\fR\|(7) -.SH "HISTORY" +.SH HISTORY .IX Header "HISTORY" All of the functions described above were added in OpenSSL 1.1.1. -.SH "COPYRIGHT" +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |