diff options
author | Todd Short <tshort@akamai.com> | 2021-09-08 16:23:04 -0400 |
---|---|---|
committer | Todd Short <todd.short@me.com> | 2022-03-10 10:42:43 -0500 |
commit | a3e53d56831adb60d6875297b3339a4251f735d2 (patch) | |
tree | c931c5b2cc9a63f80e4f3ae3a366b70064b897ae /doc | |
parent | 97896f744d9ee4f2e821e3383caac8e8c5f226cf (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man1/openssl-s_client.pod.in | 7 | ||||
-rw-r--r-- | doc/man1/openssl-s_server.pod.in | 8 | ||||
-rw-r--r-- | doc/man3/BIO_ADDR.pod | 14 | ||||
-rw-r--r-- | doc/man3/BIO_connect.pod | 9 | ||||
-rw-r--r-- | doc/man3/BIO_ctrl.pod | 30 | ||||
-rw-r--r-- | doc/man3/BIO_s_accept.pod | 16 | ||||
-rw-r--r-- | doc/man7/bio.pod | 32 |
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 - |