In ssl.h rev. 1.174 to 1.176, tb@ added some stubs related to 0-RTT data.

Write documentation from scratch explaining why we don't support 0-RTT
but how we stub it out instead.
Tweaks and OK tb@.

... and beck@ pointed out that this OpenSSL API is akin to adding a
laser sighting system to a giant blackpowder cannon that one keeps
blowing one's own feet to mangled scraps with ...

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