From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-yw1-f181.google.com (mail-yw1-f181.google.com [209.85.128.181]) (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 0570E25D534 for ; Wed, 25 Jun 2025 13:52:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.181 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750859535; cv=none; b=gtE+TZ4qdEldtRXAVjJrOSUe5RtRKEPj9k4NNEWSZfGLINArQPZkeKr7QpNuowsSqG348bxOyo/hJGfVEJoWwzy+Ww8Gyzpaxm3ohLGCZOnv0ujvvsoXqfLVsEcAUBiL92LgNteyPRF2OTUVInNCT5oBiYXnMpHYnKdb7+c+LNs= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750859535; c=relaxed/simple; bh=zueMauR5CdKG45o768eLULl50Bu4kazmG/3s/ODZw30=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=N+em4EhAcgSOfpnQpN4RqCmaf4NGvlSsNVPD9A8lMQQjFdeFFakFztezrFg7NwqO3fWamRS2vKru0TJHoG8wS3Yul4JL3QBTjP5QIrUZtmP6k8XxwsujLfEyEMl9BoeM8Iq4lIVPzvtMvTKxFkItEf2/nYY2Vd23BMUTed+0i18= 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=HN6v/Hbn; arc=none smtp.client-ip=209.85.128.181 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="HN6v/Hbn" Received: by mail-yw1-f181.google.com with SMTP id 00721157ae682-710fe491842so15045437b3.0 for ; Wed, 25 Jun 2025 06:52:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1750859533; x=1751464333; 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=q/C1vY9ZaHrfc5R+Fd5xoPpxdF1RyZVcrQRkXLQfaRs=; b=HN6v/HbnVHfJtE8LcUEy4G/7f4FPl+VMwPv1W5VYtfYYFfofZEn1K32X7TtomSyZAs K+iAYi10+u60Gpri4wMpyMLFIgGnK/eYAHQ6w/tk/pa0crY5ESWYINTi6ke0na1wfjFl mMbnlqCSyaKRnb+CFOEQvCHCI1pVz7lYry7OqjcgycrkYqWmJ/PPGdGpwp9V6KTKS1W6 FhbU++BvAYt1hgOgFK6SCYsQWrdZ+YUR2ZBrlQ7y1bboFP0crbGhE+jEwqInlvLC9Czj IUdMoJSoUhtbcw9yUZUzn+8/b/FKVBVNxCkkZKCDJQyDGpvsGZC4PmYZ8KGtGqzQ7xXZ phYw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1750859533; x=1751464333; 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=q/C1vY9ZaHrfc5R+Fd5xoPpxdF1RyZVcrQRkXLQfaRs=; b=Z20xCEVUNitsviAPZkEiwfw3HNM0ySZ++BQ2jthurgHQqMtdPk2NDRvfcOvW9V7a0B SXhYW8YsfU/iWXJs8+7s71Rbn2XUMHm8meU/Elm+hTiLgdabOydF7u3wDag9P9VL7yss qOl0JOjbSdBQ4nZzhTi0dMVoQ8sqT2FpHCIortCqI3KioWntjSAjVh6tCa0lq0RnadPG Y6VfPGtP5ZDC9w40qDrrk/UT+azODo5Sr2qXQHMNADvH6XI3v0I0yDc0g4koJc/YbS9S cUhLPBmndJwJTF4EPcKJYckQ6rUnxqfeATM6UoPWolibYMiNQ2BBUWwqzKIa1hvt4AW+ QEUw== X-Forwarded-Encrypted: i=1; AJvYcCWNaR3aebAygBvZsOk2jnal6UWHNCnWkkRVvWl3otEp6QTGc/VCK4pznhQH5inTEsQbv2wLQG4=@vger.kernel.org X-Gm-Message-State: AOJu0YwduQnttEG0zH5bc5jaOlq6Hr8u9W9L798B1272d+yzLu+K2SgR wuW4qrPjuhcvATTYbieW0Gy62kT4l9U4kcVAvCTUaDWrg4pd5PHVhGzkOn8jGeW4 X-Gm-Gg: ASbGncuheJk5/K7V33DoOSc2X2aC8xMtkgICByEBV4hVa9Zv2A/3NMyQbIcN4jk7tU8 mdOv2sYU8MU1LLla16P0ZogrnrL1kxd9DRRF0kht/olQhgGLMLL7meosonFKX8mSlXqaxI8Kbys Zog/yNeL9g1OhOPWS9rGe9SvFUtVRobpblpyLyajCi/mUUByXoZbCr6AcgCFLpFtMl1A962Tuv+ G7bF175V22U8+EP4+WnrHgnQsaqfswmdU/G2BBHKy0MbtS2jfbnVENY3dkGCbCXyui/cQtu7CZW KfCzkleX6PgYRpJuE+x8HRANWJ78RxXAPxYNhRKlcnbjpEJ5/IbnY5sz8u8= X-Google-Smtp-Source: AGHT+IG6tlk/vzE9CEuDBp9+i4sFLocTu2Y55BMDIcrB9GVrsCYSRfMOsPu5cU5s5gcmvP05uETZ7g== X-Received: by 2002:a05:690c:4b10:b0:708:16b0:59c3 with SMTP id 00721157ae682-71406e11befmr44395277b3.33.1750859532761; Wed, 25 Jun 2025 06:52:12 -0700 (PDT) Received: from localhost ([2a03:2880:25ff:6::]) by smtp.gmail.com with ESMTPSA id 00721157ae682-712c4a162c7sm24351287b3.35.2025.06.25.06.52.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 25 Jun 2025 06:52:12 -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 v2 01/17] psp: add documentation Date: Wed, 25 Jun 2025 06:51:51 -0700 Message-ID: <20250625135210.2975231-2-daniel.zahka@gmail.com> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20250625135210.2975231-1-daniel.zahka@gmail.com> References: <20250625135210.2975231-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. Signed-off-by: Jakub Kicinski Signed-off-by: Daniel Zahka --- Notes: 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 | 180 +++++++++++++++++++++++++++++ 2 files changed, 181 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..dc558d050f30 --- /dev/null +++ b/Documentation/networking/psp.rst @@ -0,0 +1,180 @@ +.. 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 device key is usable upon init +(working keys can be allocated), and that no duplicate keys may be generated +(reuse of SPI without key rotation). Drivers may achieve this by rotating +keys twice before registering the PSP device. + +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