From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-yb1-f173.google.com (mail-yb1-f173.google.com [209.85.219.173]) (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 1A080275869 for ; Thu, 28 Aug 2025 16:29:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.219.173 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1756398598; cv=none; b=bqk8H4s6rxiJ/pjmj6hVQmU+Bz37CskqlVLoPohUgkdzx9hxK7/gqUV/lfTwTi0z7bj6PGJRL3o+lPS/dwBasH0G9lnFGfOfQIzCLYpmTEUglT/+us1XB5oNhb1GbckNB/20cmlnYyPV8UQMWVbqFRngvPlRdHhAZly9ACYu7vE= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1756398598; c=relaxed/simple; bh=7OHamNe80vMy1JfT5X5HsbgZ0A1AzwbxRhldJWA8UW0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MQf31Jv90Y/TM2mZdVB5bwbRMk2AzWWsG6TbZag1+a5e1Fh2vJGcx7Gpe2BPuX4RIAtKJzLA2FO2GsHftsDIe+e3U7B8sXMbVMaRDYx7Br/Qna83xsmEQor6So/iOuYASq5RQt3h5J6C17vQ1AYrZxz6HTOoNsuLx43fW7+4j2M= 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=KmlzfChV; arc=none smtp.client-ip=209.85.219.173 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="KmlzfChV" Received: by mail-yb1-f173.google.com with SMTP id 3f1490d57ef6-e97021a3695so673443276.3 for ; Thu, 28 Aug 2025 09:29:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1756398596; x=1757003396; 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=DIBNm5paeiAnQo3yS59NcdyWincUwPqnjjEngtvb/fE=; b=KmlzfChVWGmcQXU9YRdtPSq8WoxL9bRbk9Elggg8FSdpo9AlMLB+05oCqZaBuEB6m1 JB8rn2zTGMGRjFLCAZIaOV5vjDH2s4+PM9llU//VeTM1ccfjN70JHA/ymSrL8YqV9Hs0 OuqvedCkrGi7hIda8hpI88zyd2KJTL1uZxBzTELpOfTEpf9vJa14bv5p5pD5yCwLDZCm nPGVnIR8QP6GI5KShxAquI4z21nbxo2MCXkHKVDyx1fxmC3etJyG2Q1ya9LD5ka7su6n NXMqI2gaIblXpm0cudV0J8E/QTQqmNKfikRbfjcZh+2AMtMLd/eisCCsbaubKh7fHnR4 flpA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1756398596; x=1757003396; 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=DIBNm5paeiAnQo3yS59NcdyWincUwPqnjjEngtvb/fE=; b=cR8hSvA29GLNCvO3RVfSxJ9o7IyHZkvq+PPtfKSP2YL7HQhWrtPhqdGLRCsXzljC0/ Z8Rp3fGUYpfe843sNnS+Uw5S/yL88S12dczMlK2cDn05LlIM/tYo9EBqJtQTlgM9pG4X Ey+TX4sHjU3SDw8JB7EiUrOxH+GYmIqBbZl6qKF/1HtjjD5F7CDNxyj/91fJQvxTiWmq in1X4JhOV7gStYVzrE/aNA3lopFT+/7dH9UCOLC1kGTCdjoYaBzI1Lc93cWe8u5vHdgj n0Xr8QhkCXzxtHPYN1DYj2wNijdcDBUlEqgYx5eZ1jp+RRaCUsj7G5cz7YNc2ZgCBu+3 YTFg== X-Forwarded-Encrypted: i=1; AJvYcCU9fwtHD+GgkBSM2SC1fQ33+NGEjXCBaiPiPCUon/IRNvWwvsYxwRABw8a1hvY4oroJ60dEp5s=@vger.kernel.org X-Gm-Message-State: AOJu0Yzc0lcAkmeoYYXKvWHKwsgYz0Vydz+PSiZj8ai7yi20ITEyL/Xt tlTllxGfRcCopWuHrE0uk5J14NPlXQo5qj2BAcMr17+aiGbao7SvNyWZ X-Gm-Gg: ASbGncsIpcSrcuNo2BBAJc95inZdTOlR3DxpRKuzkvT0B4OQg0QRd+BCT4F8esuOY8h Z6BpnMOxeV0atQ48qYtZFJitJx8JpGC9GXrp/H41eu83qRJ326sGuhNlbsB+F02FZH+gx7v7h2R 2YIPbVmB38Pl2XVWCDUODOo1LWTmY4RWHaxjUB7lhspLEGJnDHKl+uDYNUHBdRS4X9htID6qtP6 COGFUxMF8j/STl4HH8OhvM4XlbJtgw6e/LRpvG28/L3tBz5MwAY7MQlysP3NbDNcy62JCugqZqv qKdnKiE7H2v4sVsAdwdou0gJ04GOI5ILdTnJ5F8vxg2PR78/4vgOZSl6E5cemnK1bYKNwYorrDS oEGGQBi9qtrISACq98h4d+4Jh4rlaHg== X-Google-Smtp-Source: AGHT+IEFo7UDwzAk4wRP/qxCR+CZH9usdLoC2+DWu/RruwwM8CFT4+upOuP4vgfCzwYweGtnDOQ7hg== X-Received: by 2002:a05:6902:2b92:b0:e96:fbfd:1508 with SMTP id 3f1490d57ef6-e96fbfd1d33mr5522528276.34.1756398595790; Thu, 28 Aug 2025 09:29:55 -0700 (PDT) Received: from localhost ([2a03:2880:25ff:9::]) by smtp.gmail.com with ESMTPSA id 3f1490d57ef6-e952c2591ddsm5129190276.5.2025.08.28.09.29.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 28 Aug 2025 09:29:55 -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 , Kiran Kella , Jacob Keller , netdev@vger.kernel.org Subject: [PATCH net-next v10 01/19] psp: add documentation Date: Thu, 28 Aug 2025 09:29:27 -0700 Message-ID: <20250828162953.2707727-2-daniel.zahka@gmail.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20250828162953.2707727-1-daniel.zahka@gmail.com> References: <20250828162953.2707727-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 b7a4969e9bc9..c775cababc8c 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.3