diff options
| -rw-r--r-- | lib/libssl/man/Makefile | 5 | ||||
| -rw-r--r-- | lib/libssl/man/SSL_read_early_data.3 | 175 | ||||
| -rw-r--r-- | lib/libssl/man/ssl.3 | 7 |
3 files changed, 183 insertions, 4 deletions
diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile index f8e5cffd591..c8edf6311ed 100644 --- a/lib/libssl/man/Makefile +++ b/lib/libssl/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.68 2020/09/20 10:20:43 schwarze Exp $ +# $OpenBSD: Makefile,v 1.69 2020/09/21 08:53:56 schwarze Exp $ .include <bsd.own.mk> @@ -120,6 +120,9 @@ MAN = BIO_f_ssl.3 \ d2i_SSL_SESSION.3 \ ssl.3 +# To be enabled after the release of OpenBSD 6.8: +# SSL_read_early_data.3 \ + all clean cleandir depend includes obj tags: install: maninstall diff --git a/lib/libssl/man/SSL_read_early_data.3 b/lib/libssl/man/SSL_read_early_data.3 new file mode 100644 index 00000000000..71ad3c52a39 --- /dev/null +++ b/lib/libssl/man/SSL_read_early_data.3 @@ -0,0 +1,175 @@ +.\" $OpenBSD: SSL_read_early_data.3,v 1.1 2020/09/21 08:53:56 schwarze Exp $ +.\" content checked up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: September 21 2020 $ +.Dt SSL_READ_EARLY_DATA 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_max_early_data , +.Nm SSL_set_max_early_data , +.Nm SSL_SESSION_set_max_early_data , +.Nm SSL_CTX_get_max_early_data , +.Nm SSL_get_max_early_data , +.Nm SSL_SESSION_get_max_early_data , +.Nm SSL_write_early_data , +.Nm SSL_read_early_data , +.Nm SSL_get_early_data_status +.Nd transmit application data before the handshake is complete +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_max_early_data +.Fa "SSL_CTX *ctx" +.Fa "uint32_t max_bytes" +.Fc +.Ft int +.Fo SSL_set_max_early_data +.Fa "SSL *ssl" +.Fa "uint32_t max_bytes" +.Fc +.Ft int +.Fo SSL_SESSION_set_max_early_data +.Fa "SSL_SESSION *session" +.Fa "uint32_t max_bytes" +.Fc +.Ft uint32_t +.Fo SSL_CTX_get_max_early_data +.Fa "const SSL_CTX *ctx" +.Fc +.Ft uint32_t +.Fo SSL_get_max_early_data +.Fa "const SSL *ssl" +.Fc +.Ft uint32_t +.Fo SSL_SESSION_get_max_early_data +.Fa "const SSL_SESSION *session" +.Fc +.Ft int +.Fo SSL_write_early_data +.Fa "SSL *ssl" +.Fa "const void *buf" +.Fa "size_t len" +.Fa "size_t *written" +.Fc +.Ft int +.Fo SSL_read_early_data +.Fa "SSL *ssl" +.Fa "void *buf" +.Fa "size_t maxlen" +.Fa "size_t *readbytes" +.Fc +.Ft int +.Fo SSL_get_early_data_status +.Fa "const SSL *ssl" +.Fc +.Sh DESCRIPTION +In LibreSSL, these functions have no effect. +They are only provided because some application programs +expect the API to be available when TLSv1.3 is supported. +Using these functions is strongly discouraged because they provide +marginal benefit in the first place even when implemented and +used as designed, because they have absurdly complicated semantics, +and because when they are used, inconspicuous oversights are likely +to cause serious security vulnerabilities. +.Pp +If these functions are used, other TLS implementations +may allow the transfer of application data +before the inital handshake is complete. +Even when used as designed, security of the connection is compromised; +in particular, application data is exchanged with unauthenticated peers, +and there is no forward secrecy. +Other downsides include an increased risk of replay attacks. +.Pp +.Fn SSL_CTX_set_max_early_data , +.Fn SSL_set_max_early_data , +and +.Fn SSL_SESSION_set_max_early_data +are intended to configure the maximum number of bytes per session +that can be transmitted before the handshake is complete. +With LibreSSL, all arguments are ignored. +.Pp +An endpoint can attempt to send application data with +.Fn SSL_write_early_data +before the handshake is complete. +With LibreSSL, such attempts always fail and set +.Pf * Fa written +to 0. +.Pp +A server can attempt to read application data from the client using +.Fn SSL_read_early_data +before the handshake is complete. +With LibreSSL, no such data is ever accepted and +.Pf * Fa readbytes +is always set to 0. +.Sh RETURN VALUES +.Fn SSL_CTX_set_max_early_data , +.Fn SSL_set_max_early_data , +and +.Fn SSL_SESSION_set_max_early_data +return 1 for success or 0 for failure. +With LibreSSL, they always succeed. +.Pp +.Fn SSL_CTX_get_max_early_data , +.Fn SSL_get_max_early_data , +and +.Fn SSL_SESSION_get_max_early_data +return the maximum number of bytes of application data +that will be accepted from the peer before the handshake is complete. +With LibreSSL, they always return 0. +.Pp +.Fn SSL_write_early_data +returns 1 for success or 0 for failure. +With LibreSSL, it always fails. +.Pp +With LibreSSL, +.Fn SSL_read_early_data +always returns +.Dv SSL_READ_EARLY_DATA_FINISH +on the server side and +.Dv SSL_READ_EARLY_DATA_ERROR +on the client side. +.Dv SSL_READ_EARLY_DATA_SUCCESS +can occur with other implementations, but not with LibreSSL. +.Pp +With LibreSSL, +.Fn SSL_get_early_data_status +always returns +.Dv SSL_EARLY_DATA_REJECTED . +With other implementations, it might also return +.Dv SSL_EARLY_DATA_NOT_SENT +or +.Dv SSL_EARLY_DATA_ACCEPTED . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh STANDARDS +RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3: +.Bl -tag -width "section 4.2.10" -compact +.It Section 2.3 +0-RTT data +.It Section 4.2.10 +Early Data Indication +.It Section 8 +0-RTT and Anti-Replay +.It Appendix E.5 +Replay Attacks on 0-RTT +.El +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 6.9 . diff --git a/lib/libssl/man/ssl.3 b/lib/libssl/man/ssl.3 index 26596a5f8ca..81778df7904 100644 --- a/lib/libssl/man/ssl.3 +++ b/lib/libssl/man/ssl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ssl.3,v 1.19 2020/09/20 10:20:44 schwarze Exp $ +.\" $OpenBSD: ssl.3,v 1.20 2020/09/21 08:53:56 schwarze Exp $ .\" full merge up to: OpenSSL e330f55d Nov 11 00:51:04 2016 +0100 .\" selective merge up to: OpenSSL 322755cc Sep 1 08:40:51 2018 +0800 .\" @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: September 20 2020 $ +.Dd $Mdocdate: September 21 2020 $ .Dt SSL 3 .Os .Sh NAME @@ -301,7 +301,7 @@ To change the configuration: .Xr SSL_set_connect_state 3 , .Xr SSL_set_fd 3 , .Xr SSL_set_session 3 , -.Xr SSL_set1_host.3 , +.Xr SSL_set1_host 3 , .Xr SSL_set_verify_result 3 .Pp To inspect the configuration: @@ -318,6 +318,7 @@ To transmit data: .Xr SSL_connect 3 , .Xr SSL_do_handshake 3 , .Xr SSL_read 3 , +.\" XXX enable after the 6.8 release: Xr SSL_read_early_data 3 , .Xr SSL_renegotiate 3 , .Xr SSL_shutdown 3 , .Xr SSL_write 3 |