Add TFO support to socket BIO and s_client/s_server

Supports Linux, MacOS and FreeBSD
Disabled by default, enabled via `enabled-tfo`
Some tests

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8692)

7 files changed, 108 insertions, 8 deletions

diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index c0a940aa71..0167485d61 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -119,6 +119,7 @@ B<openssl> B<s_client>
 [B<-srp_moregroups>]
 [B<-srp_strength> I<number>]
 [B<-ktls>]
+[B<-tfo>]
 {- $OpenSSL::safe::opt_name_synopsis -}
 {- $OpenSSL::safe::opt_version_synopsis -}
 {- $OpenSSL::safe::opt_x_synopsis -}
@@ -782,6 +783,10 @@ Enable Kernel TLS for sending and receiving.
 This option was introduced in OpenSSL 3.1.0.
 Kernel TLS is off by default as of OpenSSL 3.1.0.
 
+=item B<-tfo>
+
+Enable creation of connections via TCP fast open (RFC7413).
+
 {- $OpenSSL::safe::opt_version_item -}
 
 {- $OpenSSL::safe::opt_name_item -}
@@ -924,6 +929,8 @@ The B<-certform> option has become obsolete in OpenSSL 3.0.0 and has no effect.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
+The -tfo option was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in
index f61ff3bc09..fa6269397a 100644
--- a/doc/man1/openssl-s_server.pod.in
+++ b/doc/man1/openssl-s_server.pod.in
@@ -139,6 +139,7 @@ B<openssl> B<s_server>
 [B<-anti_replay>]
 [B<-no_anti_replay>]
 [B<-num_tickets>]
+[B<-tfo>]
 {- $OpenSSL::safe::opt_name_synopsis -}
 {- $OpenSSL::safe::opt_version_synopsis -}
 {- $OpenSSL::safe::opt_v_synopsis -}
@@ -816,6 +817,11 @@ has been negotiated, and early data is enabled on the server. A full handshake
 is forced if a session ticket is used a second or subsequent time. Any early
 data that was sent will be rejected.
 
+=item B<-tfo>
+
+Enable acceptance of TCP Fast Open (RFC7413) connections.
+
+
 {- $OpenSSL::safe::opt_name_item -}
 
 {- $OpenSSL::safe::opt_version_item -}
@@ -942,6 +948,8 @@ The
 The B<-srpvfile>, B<-srpuserseed>, and B<-engine>
 option were deprecated in OpenSSL 3.0.
 
+The -tfo option was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/BIO_ADDR.pod b/doc/man3/BIO_ADDR.pod
index 5ab88622ce..d037bcf715 100644
--- a/doc/man3/BIO_ADDR.pod
+++ b/doc/man3/BIO_ADDR.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
+BIO_ADDR, BIO_ADDR_new, BIO_ADDR_dup, BIO_ADDR_clear, BIO_ADDR_free,
+BIO_ADDR_rawmake,
 BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
 BIO_ADDR_hostname_string, BIO_ADDR_service_string,
 BIO_ADDR_path_string - BIO_ADDR routines
@@ -15,6 +16,7 @@ BIO_ADDR_path_string - BIO_ADDR routines
  typedef union bio_addr_st BIO_ADDR;
 
  BIO_ADDR *BIO_ADDR_new(void);
+ BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
  void BIO_ADDR_free(BIO_ADDR *);
  void BIO_ADDR_clear(BIO_ADDR *ap);
  int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
@@ -37,7 +39,11 @@ BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
 with routines that will fill it with information, such as
 BIO_accept_ex().
 
-BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
+BIO_ADDR_dup() creates a new B<BIO_ADDR>, with a copy of the
+address data in B<ap>.
+
+BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new()
+or BIO_ADDR_dup();
 
 BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
 it back to an uninitialised state.
@@ -113,6 +119,10 @@ information they should return isn't available.
 
 L<BIO_connect(3)>, L<BIO_s_connect(3)>
 
+=head1 HISTORY
+
+BIO_ADDR_dup() was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod
index 3134ccb8c3..dc9a64b040 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -73,6 +73,15 @@ port.
 When creating an IPv6 socket, make it only listen for IPv6 addresses
 and not IPv4 addresses mapped to IPv6.
 
+=item BIO_SOCK_TFO
+
+Enables TCP Fast Open on the socket. Uses appropriate APIs on
+supported operating systems, including Linux, macOS and FreeBSD. Can
+be used with BIO_connect(), BIO_set_conn_mode(), BIO_set_bind_mode(),
+and BIO_listen().
+On Linux kernels before 4.14, use BIO_set_conn_address() to specify
+the peer address before starting the TLS handshake.
+
 =back
 
 These flags are bit flags, so they are to be combined with the
diff --git a/doc/man3/BIO_ctrl.pod b/doc/man3/BIO_ctrl.pod
index cfb505e314..4ba8c54539 100644
--- a/doc/man3/BIO_ctrl.pod
+++ b/doc/man3/BIO_ctrl.pod
@@ -6,7 +6,7 @@ BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
 BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
 BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
 BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send,
-BIO_get_ktls_recv
+BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo
 - BIO control operations
 
 =head1 SYNOPSIS
@@ -38,6 +38,11 @@ BIO_get_ktls_recv
  int BIO_get_ktls_send(BIO *b);
  int BIO_get_ktls_recv(BIO *b);
 
+ int BIO_set_conn_mode(BIO *b, int mode);
+ int BIO_get_conn_mode(BIO *b);
+
+ int BIO_set_tfo(BIO *b, int onoff);
+
 =head1 DESCRIPTION
 
 BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
@@ -81,6 +86,13 @@ sending. Otherwise, it returns zero. It also returns negative values for failure
 BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for
 receiving. Otherwise, it returns zero. It also returns negative values for failure.
 
+BIO_get_conn_mode() returns the BIO connection mode. BIO_set_conn_mode() sets
+the BIO connection mode.
+
+BIO_set_tfo() disables TCP Fast Open when B<onoff> is 0, and enables TCP Fast
+Open when B<onoff> is nonzero. Setting the value to 1 is equivalent to setting
+B<BIO_SOCK_TFO> in BIO_set_conn_mode().
+
 =head1 RETURN VALUES
 
 BIO_reset() normally returns 1 for success and <=0 for failure. File
@@ -107,6 +119,19 @@ sending. Otherwise, it returns zero.
 BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for
 receiving. Otherwise, it returns zero.
 
+BIO_set_conn_mode() returns 1 for success and 0 for failure. BIO_get_conn_mode()
+returns the current connection mode. Which may contain the bitwise-or of the
+following flags:
+
+ BIO_SOCK_REUSEADDR
+ BIO_SOCK_V6_ONLY
+ BIO_SOCK_KEEPALIVE
+ BIO_SOCK_NONBLOCK
+ BIO_SOCK_NODELAY
+ BIO_SOCK_TFO
+
+BIO_set_tfo() returns 1 for success, and 0 for failure.
+
 =head1 NOTES
 
 BIO_flush(), because it can write data may return 0 or -1 indicating
@@ -144,6 +169,9 @@ the case of BIO_seek() on a file BIO for a successful operation.
 The BIO_get_ktls_send() and BIO_get_ktls_recv() functions were added in
 OpenSSL 3.0.
 
+The BIO_get_conn_mode(), BIO_set_conn_mode() and BIO_set_tfo() functions
+were added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod
index c3826a609f..a01793c8c5 100644
--- a/doc/man3/BIO_s_accept.pod
+++ b/doc/man3/BIO_s_accept.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
-BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios,
+BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios,
 BIO_get_peer_name, BIO_get_peer_port,
 BIO_get_accept_ip_family, BIO_set_accept_ip_family,
 BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
@@ -23,6 +23,7 @@ BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
  BIO *BIO_new_accept(char *host_port);
 
  long BIO_set_nbio_accept(BIO *b, int n);
+ long BIO_set_tfo_accept(BIO *b, int n);
  long BIO_set_accept_bios(BIO *b, char *bio);
 
  char *BIO_get_peer_name(BIO *b);
@@ -87,6 +88,11 @@ B<host_port>.
 BIO_set_nbio_accept() sets the accept socket to blocking mode
 (the default) if B<n> is 0 or non blocking mode if B<n> is 1.
 
+BIO_set_tfo_accept() enables TCP Fast Open on the accept socket
+if B<n> is 1 or disables TCP Fast Open if B<n> is 0 (the default).
+Setting the value to 1 is equivalent to setting B<BIO_SOCK_TFO>
+in BIO_set_bind_mode().
+
 BIO_set_accept_bios() can be used to set a chain of BIOs which
 will be duplicated and prepended to the chain when an incoming
 connection is received. This is useful if, for example, a
@@ -107,7 +113,9 @@ B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
 same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
 attempt is first made to use BIO_BIN_NORMAL, if this fails
 and the port is not in use then a second attempt is made
-using B<BIO_BIND_REUSEADDR>.
+using B<BIO_BIND_REUSEADDR>. If B<BIO_SOCK_TFO> is set, then
+the socket will be configured to accept TCP Fast Open
+connections.
 
 BIO_do_accept() serves two functions. When it is first
 called, after the accept BIO has been setup, it will attempt
@@ -230,6 +238,10 @@ down each and finally closes both down.
  BIO_free(cbio);
  BIO_free(cbio2);
 
+=head1 HISTORY
+
+BIO_set_tfo_accept() was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod
index 9b86e9493d..0155bf6a40 100644
--- a/doc/man7/bio.pod
+++ b/doc/man7/bio.pod
@@ -36,7 +36,6 @@ BIO and one or more filter BIOs. Data read from or written to the
 first BIO then traverses the chain to the end (normally a source/sink
 BIO).
 
-
 Some BIOs (such as memory BIOs) can be used immediately after calling
 BIO_new(). Others (such as file BIOs) need some additional initialization,
 and frequently a utility function exists to create and initialize such BIOs.
@@ -52,6 +51,29 @@ pointer to a BIO_METHOD. There is a naming convention for such functions:
 a source/sink BIO typically starts with I<BIO_s_> and
 a filter BIO with I<BIO_f_>.
 
+=head2 TCP Fast Open
+
+TCP Fast Open (RFC7413), abbreviated "TFO", is supported by the BIO
+interface since OpenSSL 3.1. TFO is supported in the following operating systems:
+
+=over 4
+
+=item * Linux kernel 3.13 and later, where TFO is enabled by default.
+
+=item * Linux kernel 4.11 and later, using TCP_FASTOPEN_CONNECT.
+
+=item * FreeBSD 10.3 to 11.4, supports server TFO only.
+
+=item * FreeBSD 12.0 and later, supports both client and server TFO.
+
+=item * macOS 10.14 and later.
+
+=back
+
+Each operating system has a slightly different API for TFO. Please
+refer to the operating systems' API documentation when using
+sockets directly.
+
 =head1 EXAMPLES
 
 Create a memory BIO:
@@ -65,7 +87,9 @@ L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>,
 L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
 L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
 L<BIO_f_readbuffer(3)>,
-L<BIO_find_type(3)>, L<BIO_new(3)>,
+L<BIO_find_type(3)>,
+L<BIO_get_conn_mode(3)>,
+L<BIO_new(3)>,
 L<BIO_new_bio_pair(3)>,
 L<BIO_push(3)>, L<BIO_read_ex(3)>,
 L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
@@ -73,6 +97,9 @@ L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
 L<BIO_s_file(3)>, L<BIO_s_mem(3)>,
 L<BIO_s_null(3)>, L<BIO_s_socket(3)>,
 L<BIO_set_callback(3)>,
+L<BIO_set_conn_mode(3)>,
+L<BIO_set_tfo(3)>,
+L<BIO_set_tfo_accept(3)>,
 L<BIO_should_retry(3)>
 
 =head1 COPYRIGHT
@@ -85,4 +112,3 @@ in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.
 
 =cut
-