From: Jakub Kicinski <kuba@kernel•org>
To: netdev@vger•kernel.org
Cc: pabeni@redhat•com, willemdebruijn.kernel@gmail•com,
borisp@nvidia•com, gal@nvidia•com, cratiu@nvidia•com,
rrameshbabu@nvidia•com, steffen.klassert@secunet•com,
tariqt@nvidia•com, Jakub Kicinski <kuba@kernel•org>
Subject: [RFC net-next 01/15] psp: add documentation
Date: Thu, 9 May 2024 20:04:21 -0700 [thread overview]
Message-ID: <20240510030435.120935-2-kuba@kernel.org> (raw)
In-Reply-To: <20240510030435.120935-1-kuba@kernel.org>
Add documentation of things which belong in the docs rather
than commit messages.
Signed-off-by: Jakub Kicinski <kuba@kernel•org>
---
Documentation/networking/index.rst | 1 +
Documentation/networking/psp.rst | 138 +++++++++++++++++++++++++++++
2 files changed, 139 insertions(+)
create mode 100644 Documentation/networking/psp.rst
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 7664c0bfe461..0376029ecbdf 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -94,6 +94,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics.
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..a39b464813ab
--- /dev/null
+++ b/Documentation/networking/psp.rst
@@ -0,0 +1,138 @@
+.. 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
+"secret state" 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 secret state 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.
+
+Key rotation
+------------
+
+The secret state 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 secret state gets generated (by a random number generator
+of the device), and used for all new connections. To avoid disrupting
+old connections the old secret state remains in the NIC. A phase bit
+carried in the packet headers indicates which generation of secret state
+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 the secondary
+effect on the Rx direction, requring all received packets to be encrypted.
+Since packet reception is asynchronous, to make it possible for the
+application to trust that any data read from the socket after the ``tx-assoc``
+call returns success has been encrypted, the kernel will scan the receive
+queue of the socket at ``tx-assoc`` time. If any enqueued packet was received
+in clear text the Tx association will fail, and application should retry
+installing the Tx key after draining the socket (this should not be necessary
+if both endpoints are well behaved).
+
+Rotation notifications
+----------------------
+
+The rotations of secret state happen asynchornously 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 secret state 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.45.0
next prev parent reply other threads:[~2024-05-10 3:04 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-10 3:04 [RFC net-next 00/15] add basic PSP encryption for TCP connections Jakub Kicinski
2024-05-10 3:04 ` Jakub Kicinski [this message]
2024-05-10 22:19 ` [RFC net-next 01/15] psp: add documentation Saeed Mahameed
2024-05-11 0:11 ` Jakub Kicinski
2024-05-11 9:41 ` Vadim Fedorenko
2024-05-11 16:25 ` David Ahern
2024-06-26 13:57 ` Sasha Levin
2024-05-13 1:24 ` Willem de Bruijn
2024-05-29 17:35 ` Jakub Kicinski
2024-05-30 0:47 ` Willem de Bruijn
2024-05-30 19:51 ` Jakub Kicinski
2024-05-30 20:15 ` Jakub Kicinski
2024-05-30 21:03 ` Willem de Bruijn
2024-05-31 13:56 ` Willem de Bruijn
2024-06-05 0:08 ` Jakub Kicinski
2024-06-05 20:11 ` Willem de Bruijn
2024-06-05 22:24 ` Jakub Kicinski
2024-06-06 2:40 ` Willem de Bruijn
2024-06-27 15:14 ` Lance Richardson
2024-06-27 22:33 ` Jakub Kicinski
2024-06-28 19:33 ` Lance Richardson
2024-06-28 23:41 ` Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 02/15] psp: base PSP device support Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 03/15] net: modify core data structures for PSP datapath support Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 04/15] tcp: add datapath logic for PSP with inline key exchange Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 05/15] psp: add op for rotation of secret state Jakub Kicinski
2024-05-16 19:59 ` Lance Richardson
2024-05-29 17:43 ` Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 06/15] net: psp: add socket security association code Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 07/15] net: psp: update the TCP MSS to reflect PSP packet overhead Jakub Kicinski
2024-05-13 1:47 ` Willem de Bruijn
2024-05-29 17:48 ` Jakub Kicinski
2024-05-30 0:52 ` Willem de Bruijn
2024-05-10 3:04 ` [RFC net-next 08/15] psp: track generations of secret state Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 09/15] net/mlx5e: Support PSP offload functionality Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 10/15] net/mlx5e: Implement PSP operations .assoc_add and .assoc_del Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 11/15] net/mlx5e: Implement PSP Tx data path Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 12/15] net/mlx5e: Add PSP steering in local NIC RX Jakub Kicinski
2024-05-13 1:52 ` Willem de Bruijn
2024-05-10 3:04 ` [RFC net-next 13/15] net/mlx5e: Configure PSP Rx flow steering rules Jakub Kicinski
2024-05-10 3:04 ` [RFC net-next 14/15] net/mlx5e: Add Rx data path offload Jakub Kicinski
2024-05-13 1:54 ` Willem de Bruijn
2024-05-29 18:38 ` Jakub Kicinski
2024-05-30 9:04 ` Cosmin Ratiu
2024-05-10 3:04 ` [RFC net-next 15/15] net/mlx5e: Implement PSP key_rotate operation Jakub Kicinski
2024-05-29 9:16 ` [RFC net-next 00/15] add basic PSP encryption for TCP connections Boris Pismenny
2024-05-29 18:50 ` Jakub Kicinski
2024-05-29 20:01 ` Boris Pismenny
2024-05-29 20:38 ` Jakub Kicinski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240510030435.120935-2-kuba@kernel.org \
--to=kuba@kernel$(echo .)org \
--cc=borisp@nvidia$(echo .)com \
--cc=cratiu@nvidia$(echo .)com \
--cc=gal@nvidia$(echo .)com \
--cc=netdev@vger$(echo .)kernel.org \
--cc=pabeni@redhat$(echo .)com \
--cc=rrameshbabu@nvidia$(echo .)com \
--cc=steffen.klassert@secunet$(echo .)com \
--cc=tariqt@nvidia$(echo .)com \
--cc=willemdebruijn.kernel@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox