From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-yw1-f175.google.com (mail-yw1-f175.google.com [209.85.128.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 82A25235044 for ; Wed, 23 Jul 2025 20:34:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.175 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753302900; cv=none; b=cCyXTA7NcJmSBMSLzcP0aAcvCQIWvyUd6Oyo8lOUAc0V95CIt0K8KakyMuOJAX2/FDqTYzH9osjPfxF5bPNhL4eET9u0ppks2kZS8Ez3fwMCMHelB/U3Bu8Oq0Dpee7i0Dlomby4IRd/rPobHNUrxSfp3WE8fIzkJyNhxZLkR+Y= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753302900; c=relaxed/simple; bh=kumc1QD0fBDyBJr62JLiy4rvZUlJgiTUDYF6m0p5vJU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rQaB7DxDcFTEmlziBgI4jbzHL8QG/mY9+MdeadeaNIpWK0HUeWLqaXDP2NURPiMzb3zjjC/iKGOI9RMM1oXjMnZf8IGcBNcEdM4NcuBB9przWq3Fk29GD0laeOcmRK5KwMsL3qlrNHcJAcfBYSnCDylnC3BD1E8tmW5O+EbwrLc= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=TwypUhWQ; arc=none smtp.client-ip=209.85.128.175 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="TwypUhWQ" Received: by mail-yw1-f175.google.com with SMTP id 00721157ae682-7086dcab64bso3255407b3.1 for ; Wed, 23 Jul 2025 13:34:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1753302897; x=1753907697; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=QVT5CQOwzKVkDNZJFX3q/wEgxKZ/O4DUjFKQYrKV89s=; b=TwypUhWQcd+l0yeoXUiCzAmMwDQkDVBfnE8U4AUEkadYslQoSWLFogrpO7Jp+NKPZj 4wzNNm0MbD1du/HbHdv538QxQVZyoPrI6Tp7yxSmVOSbHYCt6e8kdGbwaBiOkoLPUcJV GLf4OovEOXeqSp6q1JxjCTSdyz8msTQbPKx8aKG+Y0ynavu+yGfAX9wRpM69dpvFkzNC SG73uz1r9Gzvf0UKOCJvLsnBLGOpo5utL/miUSCOMyFRp7vtgmXR0C4v2h1N+94ReoAD j7ra9g0IRxkofghRGq6hJfln1ASNRfBneUe295lZOnXRZmm/2h5SkUco213W1n6E/s1A Da8Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1753302897; x=1753907697; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=QVT5CQOwzKVkDNZJFX3q/wEgxKZ/O4DUjFKQYrKV89s=; b=IxlDzPKEoFbsCamwz1FGI4KIOBvp+HNbN2vLbmi782h+LYpcTqyr4ndEv52ayi75LP dsy5WmsLM44/oLku6box6CbEpoB4igiue4TUQwu9xcAXlorrC+2QQJV0LC2bbwZ0T1vx FSCh3SCHp0Qj6hqjLfWXMWo983HJ/7RBfum5XeZqL2L8jUXSrUDEGR72vHYqWPLZP9yN j8LbWQuG5hJGItNV70Xn/+W8A44TLDL5KfLGCtYJJ2ReyqH6dA2HntjXBN2/HZqDFBQq cNu4+B5AwCvWJAoi/NTCAwpNjV2pqzL1AA0V/C//qR09/SCEDUGH9SqCm644UMoqj0B5 3Dkg== X-Forwarded-Encrypted: i=1; AJvYcCUqpwC0B7UUIKufcLkD/zeYSxFyetR2MkzW3nmzebrNo+htKUYTFNEzNLYDZgS0hawkFhSENTE=@vger.kernel.org X-Gm-Message-State: AOJu0Yx8cOAYohHmseH8JazwQIYzwnviXEs7Ek2nb5yq5VUZBv2uXtsU t6rQEfyyq/hOgEInoEV87IoRG4AWnVW1hMUOk0kU7YGQAh5y3DUAjSgU X-Gm-Gg: ASbGncvPBn/h5GSQfW0ih+ZIhoqn5XO5Ws48MXNbiCZFBe6y8a0qojWfiw1dFdEnEZ+ d4OFj7w/iraCB6vsIAg6HCmIj76I8O302tmjmbxYfecku3S7BElrezU00MTrhWpfHB707nNOYW+ v2NsuPir8S6KQli0wRwVCvGgWQN5WyaC/y1+RvRjSiSsaLeADvi1veJyyjUAkpPNCmuvVh2B9nn MSqKCZVlxUJ0jVMDqs21OcDH9w0V4ZAr4itzMweW6jYmJ6SjWLpQ3NdqpW9f/DTgnH8EdVsCl/F WZkNMd8Xaa7SZAbB3rvulVPOlSPxzFGqxizVbhi3M3H9I6Tid8cKDodwbwdcean0/0sDVLj5RKH W8vukSZeTkiMhD1GQblWx X-Google-Smtp-Source: AGHT+IFEcMoDJGWugjcYP+f1mZNd3bbhNR5/z1pselR0tM4Pu3/NROfl8ghH6uXpXj8Ap7tPpltVxQ== X-Received: by 2002:a05:690c:4c0f:b0:719:924d:f6aa with SMTP id 00721157ae682-719b427d32dmr60151077b3.41.1753302897061; Wed, 23 Jul 2025 13:34:57 -0700 (PDT) Received: from localhost ([2a03:2880:25ff:5b::]) by smtp.gmail.com with ESMTPSA id 00721157ae682-7195330940fsm30897817b3.94.2025.07.23.13.34.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Jul 2025 13:34:56 -0700 (PDT) From: Daniel Zahka To: Donald Hunter , Jakub Kicinski , "David S. Miller" , Eric Dumazet , Paolo Abeni , Simon Horman , Jonathan Corbet , Andrew Lunn Cc: Saeed Mahameed , Leon Romanovsky , Tariq Toukan , Boris Pismenny , Kuniyuki Iwashima , Willem de Bruijn , David Ahern , Neal Cardwell , Patrisious Haddad , Raed Salem , Jianbo Liu , Dragos Tatulea , Rahul Rameshbabu , Stanislav Fomichev , =?UTF-8?q?Toke=20H=C3=B8iland-J=C3=B8rgensen?= , Alexander Lobakin , Jacob Keller , netdev@vger.kernel.org Subject: [PATCH net-next v5 01/19] psp: add documentation Date: Wed, 23 Jul 2025 13:34:12 -0700 Message-ID: <20250723203454.519540-2-daniel.zahka@gmail.com> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20250723203454.519540-1-daniel.zahka@gmail.com> References: <20250723203454.519540-1-daniel.zahka@gmail.com> Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: Jakub Kicinski Add documentation of things which belong in the docs rather than commit messages. Reviewed-by: Willem de Bruijn Signed-off-by: Jakub Kicinski Signed-off-by: Daniel Zahka --- Notes: v3: - reword driver requirement about double rotating keys when the device supports requesting arbitrary spi key pairs. v2: - add note about MITM deletion attack, and expectation from userspace - add information about accepting clear text ACKs, RSTs, and FINs to `Securing Connections` section. v1: - https://lore.kernel.org/netdev/20240510030435.120935-2-kuba@kernel.org/ Documentation/networking/index.rst | 1 + Documentation/networking/psp.rst | 183 +++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 Documentation/networking/psp.rst diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index ac90b82f3ce9..23382ff52285 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -101,6 +101,7 @@ Contents: ppp_generic proc_net_tcp pse-pd/index + psp radiotap-headers rds regulatory diff --git a/Documentation/networking/psp.rst b/Documentation/networking/psp.rst new file mode 100644 index 000000000000..4ac09e64e95a --- /dev/null +++ b/Documentation/networking/psp.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +===================== +PSP Security Protocol +===================== + +Protocol +======== + +PSP Security Protocol (PSP) was defined at Google and published in: + +https://raw.githubusercontent.com/google/psp/main/doc/PSP_Arch_Spec.pdf + +This section briefly covers protocol aspects crucial for understanding +the kernel API. Refer to the protocol specification for further details. + +Note that the kernel implementation and documentation uses the term +"device key" in place of "master key", it is both less confusing +to an average developer and is less likely to run afoul any naming +guidelines. + +Derived Rx keys +--------------- + +PSP borrows some terms and mechanisms from IPsec. PSP was designed +with HW offloads in mind. The key feature of PSP is that Rx keys for every +connection do not have to be stored by the receiver but can be derived +from device key and information present in packet headers. +This makes it possible to implement receivers which require a constant +amount of memory regardless of the number of connections (``O(1)`` scaling). + +Tx keys have to be stored like with any other protocol, but Tx is much +less latency sensitive than Rx, and delays in fetching keys from slow +memory is less likely to cause packet drops. Preferably, the Tx keys +should be provided with the packet (e.g. as part of the descriptors). + +Key rotation +------------ + +The device key known only to the receiver is fundamental to the design. +Per specification this state cannot be directly accessible (it must be +impossible to read it out of the hardware of the receiver NIC). +Moreover, it has to be "rotated" periodically (usually daily). Rotation +means that new device key gets generated (by a random number generator +of the device), and used for all new connections. To avoid disrupting +old connections the old device key remains in the NIC. A phase bit +carried in the packet headers indicates which generation of device key +the packet has been encrypted with. + +User facing API +=============== + +PSP is designed primarily for hardware offloads. There is currently +no software fallback for systems which do not have PSP capable NICs. +There is also no standard (or otherwise defined) way of establishing +a PSP-secured connection or exchanging the symmetric keys. + +The expectation is that higher layer protocols will take care of +protocol and key negotiation. For example one may use TLS key exchange, +announce the PSP capability, and switch to PSP if both endpoints +are PSP-capable. + +All configuration of PSP is performed via the PSP netlink family. + +Device discovery +---------------- + +The PSP netlink family defines operations to retrieve information +about the PSP devices available on the system, configure them and +access PSP related statistics. + +Securing a connection +--------------------- + +PSP encryption is currently only supported for TCP connections. +Rx and Tx keys are allocated separately. First the ``rx-assoc`` +Netlink command needs to be issued, specifying a target TCP socket. +Kernel will allocate a new PSP Rx key from the NIC and associate it +with given socket. At this stage socket will accept both PSP-secured +and plain text TCP packets. + +Tx keys are installed using the ``tx-assoc`` Netlink command. +Once the Tx keys are installed, all data read from the socket will +be PSP-secured. In other words act of installing Tx keys has a secondary +effect on the Rx direction. + +There is an intermediate period after ``tx-assoc`` successfully +returns and before the TCP socket encounters it's first PSP +authenticated packet, where the TCP stack will allow certain nondata +packets, i.e. ACKs, FINs, and RSTs, to enter TCP receive processing +even if not PSP authenticated. During the ``tx-assoc`` call, the TCP +socket's ``rcv_nxt`` field is recorded. At this point, ACKs and RSTs +will be accepted with any sequence number, while FINs will only be +accepted at the latched value of ``rcv_nxt``. Once the TCP stack +encounters the first TCP packet containing PSP authenticated data, the +other end of the connection must have executed the ``tx-assoc`` +command, so any TCP packet, including those without data, will be +dropped before receive processing if it is not successfully +authenticated. This is summarized in the table below. The +aforementioned state of rejecting all non-PSP packets is labeled "PSP +Full". + ++----------------+------------+------------+-------------+-------------+ +| Event | Normal TCP | Rx PSP | Tx PSP | PSP Full | ++================+============+============+=============+=============+ +| Rx plain | accept | accept | drop | drop | +| (data) | | | | | ++----------------+------------+------------+-------------+-------------+ +| Rx plain | accept | accept | accept | drop | +| (ACK|FIN|RST) | | | | | ++----------------+------------+------------+-------------+-------------+ +| Rx PSP (good) | drop | accept | accept | accept | ++----------------+------------+------------+-------------+-------------+ +| Rx PSP (bad | drop | drop | drop | drop | +| crypt, !=SPI) | | | | | ++----------------+------------+------------+-------------+-------------+ +| Tx | plain text | plain text | encrypted | encrypted | +| | | | (excl. rtx) | (excl. rtx) | ++----------------+------------+------------+-------------+-------------+ + +To ensure that any data read from the socket after the ``tx-assoc`` +call returns success has been authenticated, the kernel will scan the +receive and ofo queues of the socket at ``tx-assoc`` time. If any +enqueued packet was received in clear text, the Tx association will +fail, and the application should retry installing the Tx key after +draining the socket (this should not be necessary if both endpoints +are well behaved). + +Because TCP sequence numbers are not integrity protected prior to +upgrading to PSP, it is possible that a MITM could offset sequence +numbers in a way that deletes a prefix of the PSP protected part of +the TCP stream. If userspace cares to mitigate this type of attack, a +special "start of PSP" message should be exchanged after ``tx-assoc``. + +Rotation notifications +---------------------- + +The rotations of device key happen asynchronously and are usually +performed by management daemons, not under application control. +The PSP netlink family will generate a notification whenever keys +are rotated. The applications are expected to re-establish connections +before keys are rotated again. + +Kernel implementation +===================== + +Driver notes +------------ + +Drivers are expected to start with no PSP enabled (``psp-versions-ena`` +in ``dev-get`` set to ``0``) whenever possible. The user space should +not depend on this behavior, as future extension may necessitate creation +of devices with PSP already enabled, nonetheless drivers should not enable +PSP by default. Enabling PSP should be the responsibility of the system +component which also takes care of key rotation. + +Note that ``psp-versions-ena`` is expected to be used only for enabling +receive processing. The device is not expected to reject transmit requests +after ``psp-versions-ena`` has been disabled. User may also disable +``psp-versions-ena`` while there are active associations, which will +break all PSP Rx processing. + +Drivers are expected to ensure that a device key is usable and secure +upon init, without explicit key rotation by the user space. It must be +possible to allocate working keys, and that no duplicate keys must be +generated. If the device allows the host to request the key for an +arbitrary SPI - driver should discard both device keys (rotate the +device key twice), to avoid potentially using a SPI+key which previous +OS instance already had access to. + +Drivers must use ``psp_skb_get_assoc_rcu()`` to check if PSP Tx offload +was requested for given skb. On Rx drivers should allocate and populate +the ``SKB_EXT_PSP`` skb extension, and set the skb->decrypted bit to 1. + +Kernel implementation notes +--------------------------- + +PSP implementation follows the TLS offload more closely than the IPsec +offload, with per-socket state, and the use of skb->decrypted to prevent +clear text leaks. + +PSP device is separate from netdev, to make it possible to "delegate" +PSP offload capabilities to software devices (e.g. ``veth``). -- 2.47.1