From owner-dev-commits-src-branches@freebsd.org Mon Sep 6 01:16:59 2021 Return-Path: Delivered-To: dev-commits-src-branches@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 6C4A76658D5; Mon, 6 Sep 2021 01:16:59 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4H2r8q2QNTz3MvR; Mon, 6 Sep 2021 01:16:59 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 2AB0315AE1; Mon, 6 Sep 2021 01:16:59 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 1861GxZ3085173; Mon, 6 Sep 2021 01:16:59 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 1861GxMr085172; Mon, 6 Sep 2021 01:16:59 GMT (envelope-from git) Date: Mon, 6 Sep 2021 01:16:59 GMT Message-Id: <202109060116.1861GxMr085172@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Philip Paeps Subject: git: 7aa030f7ccf4 - stable/12 - tcp: document TCP Fast Open (RFC 7413) in tcp(4) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: philip X-Git-Repository: src X-Git-Refname: refs/heads/stable/12 X-Git-Reftype: branch X-Git-Commit: 7aa030f7ccf48d639e5c7e10cdd0392515890541 Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-branches@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commits to the stable branches of the FreeBSD src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 06 Sep 2021 01:16:59 -0000 The branch stable/12 has been updated by philip: URL: https://cgit.FreeBSD.org/src/commit/?id=7aa030f7ccf48d639e5c7e10cdd0392515890541 commit 7aa030f7ccf48d639e5c7e10cdd0392515890541 Author: Philip Paeps AuthorDate: 2021-09-03 02:33:12 +0000 Commit: Philip Paeps CommitDate: 2021-09-06 01:13:47 +0000 tcp: document TCP Fast Open (RFC 7413) in tcp(4) Adds documentation for the TCP_FASTOPEN socket option and related MIB variables to the tcp(4) manual page. PR: 257907 Reviewed by: gbe Differential Revision: https://reviews.freebsd.org/D31764 (cherry picked from commit 71611b0c688568d513c665e1af3d95fcd50605fa) --- share/man/man4/tcp.4 | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/share/man/man4/tcp.4 b/share/man/man4/tcp.4 index ad7e3f117d68..d8f481697879 100644 --- a/share/man/man4/tcp.4 +++ b/share/man/man4/tcp.4 @@ -148,6 +148,54 @@ connection. See .Xr mod_cc 4 for details. +.It Dv TCP_FASTOPEN +Enable or disable TCP Fast Open (TFO). +To use this option, the kernel must be built with the +.Dv TCP_RFC7413 +option. +.Pp +This option can be set on the socket either before or after the +.Xr listen 2 +is invoked. +Clearing this option on a listen socket after it has been set has no effect on +existing TFO connections or TFO connections in progress; it only prevents new +TFO connections from being established. +.Pp +For passively-created sockets, the +.Dv TCP_FASTOPEN +socket option can be queried to determine whether the connection was established +using TFO. +Note that connections that are established via a TFO +.Tn SYN , +but that fall back to using a non-TFO +.Tn SYN|ACK +will have the +.Dv TCP_FASTOPEN +socket option set. +.Pp +In addition to the facilities defined in RFC7413, this implementation supports a +pre-shared key (PSK) mode of operation in which the TFO server requires the +client to be in posession of a shared secret in order for the client to be able +to successfully open TFO connections with the server. +This is useful, for example, in environments where TFO servers are exposed to +both internal and external clients and only wish to allow TFO connections from +internal clients. +.Pp +In the PSK mode of operation, the server generates and sends TFO cookies to +requesting clients as usual. +However, when validating cookies received in TFO SYNs from clients, the server +requires the client-supplied cookie to equal +.Bd -literal -offset left +SipHash24(key=\fI16-byte-psk\fP, msg=\fIcookie-sent-to-client\fP) +.Ed +.Pp +Multiple concurrent valid pre-shared keys are supported so that time-based +rolling PSK invalidation policies can be implemented in the system. +The default number of concurrent pre-shared keys is 2. +.Pp +This can be adjusted with the +.Dv TCP_RFC7413_MAX_PSKS +kernel option. .It Dv TCP_FUNCTION_BLK Select or query the set of functions that TCP will use for this connection. This allows a user to select an alternate TCP stack. @@ -613,6 +661,92 @@ Enable path MTU blackhole detection only for IPv6. MSS to try for IPv4 if PMTU blackhole detection is turned on. .It Va v6pmtud_blackhole_mss MSS to try for IPv6 if PMTU blackhole detection is turned on. +.It Va fastopen.acceptany +When non-zero, all client-supplied TFO cookies will be considered to be valid. +The default is 0. +.It Va fastopen.autokey +When this and +.Va net.inet.tcp.fastopen.server_enable +are non-zero, a new key will be automatically generated after this specified +seconds. +The default is 120. +.It Va fastopen.ccache_bucket_limit +The maximum number of entries in a client cookie cache bucket. +The default value can be tuned with the +.Dv TCP_FASTOPEN_CCACHE_BUCKET_LIMIT_DEFAULT +kernel option or by setting +.Va net.inet.tcp.fastopen_ccache_bucket_limit +in the +.Xr loader 8 . +.It Va fastopen.ccache_buckets +The number of client cookie cache buckets. +Read-only. +The value can be tuned with the +.Dv TCP_FASTOPEN_CCACHE_BUCKETS_DEFAULT +kernel option or by setting +.Va fastopen.ccache_buckets +in the +.Xr loader 8 . +.It Va fastopen.ccache_list +Print the client cookie cache. +Read-only. +.It Va fastopen.client_enable +When zero, no new active (i.e., client) TFO connections can be created. +On the transition from enabled to disabled, the client cookie cache is cleared +and disabled. +The transition from enabled to disabled does not affect any active TFO +connections in progress; it only prevents new ones from being established. +The default is 0. +.It Va fastopen.keylen +The key length in bytes. +Read-only. +.It Va fastopen.maxkeys +The maximum number of keys supported. +Read-only, +.It Va fastopen.maxpsks +The maximum number of pre-shared keys supported. +Read-only. +.It Va fastopen.numkeys +The current number of keys installed. +Read-only. +.It Va fastopen.numpsks +The current number of pre-shared keys installed. +Read-only. +.It Va fastopen.path_disable_time +When a failure occurs while trying to create a new active (i.e., client) TFO +connection, new active connections on the same path, as determined by the tuple +.Brq client_ip, server_ip, server_port , +will be forced to be non-TFO for this many seconds. +Note that the path disable mechanism relies on state stored in client cookie +cache entries, so it is possible for the disable time for a given path to be +reduced if the corresponding client cookie cache entry is reused due to resource +pressure before the disable period has elapsed. +The default is +.Dv TCP_FASTOPEN_PATH_DISABLE_TIME_DEFAULT . +.It Va fastopen.psk_enable +When non-zero, pre-shared key (PSK) mode is enabled for all TFO servers. +On the transition from enabled to disabled, all installed pre-shared keys are +removed. +The default is 0. +.It Va fastopen.server_enable +When zero, no new passive (i.e., server) TFO connections can be created. +On the transition from enabled to disabled, all installed keys and pre-shared +keys are removed. +On the transition from disabled to enabled, if +.Va fastopen.autokey +is non-zero and there are no keys installed, a new key will be generated +immediately. +The transition from enabled to disabled does not affect any passive TFO +connections in progress; it only prevents new ones from being established. +The default is 0. +.It Va fastopen.setkey +Install a new key by writing +.Va net.inet.tcp.fastopen.keylen +bytes to this sysctl. +.It Va fastopen.setpsk +Install a new pre-shared key by writing +.Va net.inet.tcp.fastopen.keylen +bytes to this sysctl. .It Va functions_available List of available TCP function blocks (TCP stacks). .It Va functions_default