Linux Documentation
 help / color / mirror / Atom feed
From: Todd Freed <toddfreed@meta.com>
To: <netdev@vger.kernel.org>
Cc: "David S. Miller" <davem@davemloft.net>,
	"Andrew Lunn" <andrew+netdev@lunn.ch>,
	"Björn Töpel" <bjorn@kernel.org>,
	"Boris Pismenny" <borisp@nvidia.com>,
	"Cosmin Ratiu" <cratiu@nvidia.com>,
	"Daniel Zahka" <daniel.zahka@gmail.com>,
	"Donald Hunter" <donald.hunter@gmail.com>,
	"Dragos Tatulea" <dtatulea@nvidia.com>,
	"Eric Dumazet" <edumazet@kernel.org>,
	"Jakub Kicinski" <kuba@kernel.org>,
	"Jamal Hadi Salim" <jhs@mojatatu.com>,
	"Jiri Pirko" <jiri@resnulli.us>,
	"Leon Romanovsky" <leon@kernel.org>,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	linux-kselftest@vger.kernel.org, linux-rdma@vger.kernel.org,
	"Mark Bloch" <mbloch@nvidia.com>,
	"Paolo Abeni" <pabeni@redhat.com>,
	"Pedro Tammela" <pctammela@mojatatu.com>,
	"Saeed Mahameed" <saeedm@nvidia.com>,
	"Simon Horman" <horms@kernel.org>,
	"Tariq Toukan" <tariqt@nvidia.com>,
	"Wei Wang" <weiwan@google.com>,
	"Willem de Bruijn" <willemdebruijn.kernel@gmail.com>
Subject: [PATCH net-next v2 12/12] Documentation: networking: psp: document socket-less associations
Date: Wed, 18 Nov 2026 17:31:03 -0800	[thread overview]
Message-ID: <20261119013103.1092559-13-toddfreed@meta.com> (raw)
In-Reply-To: <20261119013103.1092559-1-toddfreed@meta.com>

Describe PSP associations, and how they differ for the socket and tc use
cases.

Document the new netlink commands for socket-less PSP, and what
userspace must do on key rotation, since the kernel keeps no state for
socket-less Rx SPIs.

Document the psp tc action, and the flower psp_spi, psp_ver, and psp_dev
matches.

Add a new section to describe pre-existing PSP device stats.

Signed-off-by: Todd Freed <toddfreed@meta.com>
---
 Documentation/networking/psp.rst | 169 ++++++++++++++++++++++++++++---
 1 file changed, 153 insertions(+), 16 deletions(-)

diff --git a/Documentation/networking/psp.rst b/Documentation/networking/psp.rst
index 0f9b6b73f244..32d53f6050b7 100644
--- a/Documentation/networking/psp.rst
+++ b/Documentation/networking/psp.rst
@@ -69,20 +69,43 @@ 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.
+PSP Associations
+----------------
 
-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.
+PSP encryption and decryption happen in the context of an association.
+An association holds the PSP device, PSP version, and either Rx state
+for decrypting and authenticating packets (the SPI and Rx key), a Tx key
+for encrypting packets, or both.
+
+Associations are used in two ways. First, a TCP socket can be bound to
+an association, and all packets flowing over that socket inherit its
+association. Second, socket-less Tx associations are used with tc,
+together with Rx SPIs allocated without a socket. This allows PSP for
+forwarded traffic, or for non-TCP traffic. A tc action attaches a Tx
+association to packets. On Rx, the device decrypts packets sent to an
+SPI it allocated, and a tc filter matches the SPI, version and PSP
+device a packet was decrypted with. The kernel keeps no state for
+socket-less Rx.
+
+An association is of one type or the other; that is, sockets may not
+use socket-less associations, and tc actions do not address associations
+which are attached to a socket. Device statistics count both.
+
+Securing a socket connection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PSP encryption can be enabled for TCP sockets. Other kinds of sockets
+are not supported. For a TCP socket, 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, create an association with it, and bind it to the given
+socket. At this stage socket will accept both PSP-secured and plain text
+TCP packets.
+
+The Tx key is installed into the socket's association with the
+``tx-assoc`` Netlink command. Once it is 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
@@ -140,6 +163,83 @@ The PSP assoc state of a socket is not reset when the connection is
 torn down. ``connect()`` on a socket that has PSP assoc state will
 return ``-EINVAL``.
 
+Socket-less associations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Socket-less PSP is managed with these netlink commands:
+
+- ``rx-spi-alloc`` allocates an Rx SPI and key, like ``rx-assoc`` but
+  without a socket, and creates no association. It also returns
+  ``key-rotations``, the number of key rotations of the PSP device so
+  far. The key should be passed to the peer out of band, and installed
+  with ``assoc-add``.
+- ``assoc-add`` adds a Tx association with the peer's SPI and key, and
+  returns its ID.
+- ``assoc-del`` deletes a Tx association. tc actions and packets which
+  still reference it keep it alive.
+- ``assoc-get`` reports Tx associations, never their keys.
+
+Tx associations are removed when their PSP device is unregistered.
+
+The ``psp`` tc action attaches these associations to packets:
+
+- ``psp encap assoc ID`` attaches a Tx association. The packet must then
+  be transmitted on the main netdev of the association's PSP device, which
+  encrypts it (``mirred egress redirect``). If the packet loses the
+  association on the way (e.g. its dst is replaced), is transmitted on any
+  other device, or the PSP device is unregistered before transmit, it will
+  be dropped, rather than sent in the clear. Encap on ingress isn't
+  supported: the action drops the packet.
+
+- ``psp decap`` removes the PSP Rx state (the ``SKB_EXT_PSP`` extension and
+  ``skb->decrypted``) of a decrypted packet, so that it can be forwarded. It
+  takes no association. Its filter should match ``psp_spi``, ``psp_ver``
+  and ``psp_dev``.
+
+The flower classifier matches what a packet was decrypted with:
+``psp_spi SPI[/MASK]``, ``psp_ver VERSION`` and ``psp_dev DEV_ID``, the
+ID of the PSP device which decrypted it. These never match a clear text
+packet, so ``psp_spi 0/0`` matches any packet decrypted with PSP.
+Together they tie a decap rule to one Rx SPI.
+
+The top bit of an SPI, the key phase, selects which of the two device
+keys its Rx key is derived from. A key rotation replaces the device key
+of the other phase than the SPIs allocated since the previous rotation,
+and the SPIs allocated after it have that phase. An SPI keeps decrypting
+through one rotation, which leaves time to move peers to new SPIs. After
+the second rotation its device key is gone, and the device may allocate
+the same SPI again, with a new key.
+
+Unlike for sockets, the kernel does not enforce key rotation for
+socket-less Rx: a decap rule for an SPI also takes the packets of a later
+allocation of the same SPI. Userspace which installs decap rules is
+responsible for removing them in time:
+
+- Any process with ``CAP_NET_ADMIN`` over the PSP device can rotate its
+  key, or allocate SPIs. Once the device has rotated twice,
+  ``rx-spi-alloc`` can return an SPI which a stale decap rule still
+  matches. Remove the decap rules of the SPIs allocated before the
+  previous rotation, which have the phase of the SPIs allocated from
+  now on, on a rotation notification (``key-rotate-ntf``), and in any
+  case before an SPI allocated after the rotation is given to a peer.
+  This is simplest when one process allocates the SPIs and owns the
+  decap rules. Then move peers to new SPIs before the next rotation.
+- An SPI allocated when ``key-rotations`` was N stops decrypting with
+  rotation N + 2. Comparing it with the ``key-rotations`` of a later
+  ``rx-spi-alloc``, or of ``get-stats``, detects missed notifications.
+
+tc can help with this bookkeeping. A tc action cookie (``cookie``, up to
+16 bytes) is opaque to the kernel and dumped with the action, so it can
+record the owner of a decap rule, its SPI and its ``key-rotations``.
+Filters added with a known priority and handle can be deleted without a
+dump. Putting the decap rules of each key phase in their own chain lets
+one command remove all of them on rotation.
+
+The device adds 40 bytes to each packet on transmit: the UDP and PSP
+headers, and the ICV. The operator must size the MTU of the traffic
+source for this. A packet which would not fit the PSP device's MTU once
+encapsulated is dropped on transmit.
+
 Rotation notifications
 ----------------------
 
@@ -149,6 +249,39 @@ 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.
 
+Fragments
+---------
+
+PSP transport mode does not support IP fragments, either for sockets or
+socket-less associations.
+
+Statistics
+----------
+
+The ``get-stats`` netlink command reports the PSP device statistics:
+kernel statistics (key rotations, stale events), and the device statistics
+defined by the PSP specification. The device statistics count what the
+device decrypts and encrypts.
+
+The tc action counts the packets it processes and the ones it drops
+(``tc -s``). Encapsulated packets dropped on transmit count in the
+device's ``tx_dropped``. Drops are reported with these drop reasons:
+
+- ``SKB_DROP_REASON_PSP_OUTPUT``: encap ran on ingress in software, or
+  failed to parse the packet, or it is an IPv4 fragment or has IPv6
+  extension headers, which transport mode doesn't support, or it is
+  already encapsulated for a tunnel, already marked decrypted, or of a
+  socket with its own encryption offload; or an encapsulated packet
+  reached a device which isn't its PSP device's netdev, or its PSP
+  device was unregistered while it was queued.
+- ``SKB_DROP_REASON_PKT_TOO_BIG``: an encapsulated packet would not fit
+  the device's MTU once the device adds the PSP encapsulation.
+
+A packet encapsulated on egress which lost its association on the way is
+dropped on transmit by ``sk_validate_xmit_skb()``, without a specific drop
+reason, unless its socket has an encryption offload of its own: then the
+socket's validator handles it.
+
 Kernel implementation
 =====================
 
@@ -177,14 +310,18 @@ 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.
+was requested for given skb. The association comes from the skb's socket
+or, for socket-less associations, from a ``METADATA_PSP`` dst which the
+core keeps on the skb for the driver to use. 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
+offload, with per-socket state (or per-association state, for
+socket-less associations), and the use of ``skb->decrypted`` to prevent
 clear text leaks.
 
 PSP device is separate from netdev, to make it possible to "delegate"
-- 
2.53.1-Meta


      parent reply	other threads:[~2026-11-19  1:31 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-19  1:30 [PATCH net-next v2 00/12] psp: introduce socket-less associations Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 01/12] psp: get netns from net_device instead of sock Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 02/12] psp: take the psp nexthdr from the packet on encap Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 03/12] psp: declare psp_assoc_set_tx() in psp.h Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 04/12] psp: add support for socket-less psp associations Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 05/12] net: add METADATA_PSP dst to carry a psp association on an skb Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 06/12] net/sched: add act_psp for psp transport mode Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 07/12] net/sched: flower: add psp_spi, psp_ver, and psp_dev matches Todd Freed
2026-11-19  1:30 ` [PATCH net-next v2 08/12] selftests: drv-net: psp: test socket-less associations and the tc psp action Todd Freed
2026-11-19  1:31 ` [PATCH net-next v2 09/12] selftests: drv-net: psp: test that software encap on ingress drops Todd Freed
2026-11-19  1:31 ` [PATCH net-next v2 10/12] selftests: tc-testing: run dependsOn probes outside the test namespace Todd Freed
2026-11-19  1:31 ` [PATCH net-next v2 11/12] selftests: tc-testing: add tests for the psp action Todd Freed
2026-11-19  1:31 ` Todd Freed [this message]

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=20261119013103.1092559-13-toddfreed@meta.com \
    --to=toddfreed@meta.com \
    --cc=andrew+netdev@lunn.ch \
    --cc=bjorn@kernel.org \
    --cc=borisp@nvidia.com \
    --cc=cratiu@nvidia.com \
    --cc=daniel.zahka@gmail.com \
    --cc=davem@davemloft.net \
    --cc=donald.hunter@gmail.com \
    --cc=dtatulea@nvidia.com \
    --cc=edumazet@kernel.org \
    --cc=horms@kernel.org \
    --cc=jhs@mojatatu.com \
    --cc=jiri@resnulli.us \
    --cc=kuba@kernel.org \
    --cc=leon@kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-kselftest@vger.kernel.org \
    --cc=linux-rdma@vger.kernel.org \
    --cc=mbloch@nvidia.com \
    --cc=netdev@vger.kernel.org \
    --cc=pabeni@redhat.com \
    --cc=pctammela@mojatatu.com \
    --cc=saeedm@nvidia.com \
    --cc=tariqt@nvidia.com \
    --cc=weiwan@google.com \
    --cc=willemdebruijn.kernel@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
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