Commit 64d26169 authored by Paolo Abeni's avatar Paolo Abeni
Browse files

Merge branch 'add-basic-psp-encryption-for-tcp-connections' 

Daniel Zahka says:

==================
add basic PSP encryption for TCP connections

This is v13 of the PSP RFC [1] posted by Jakub Kicinski one year
ago. General developments since v1 include a fork of packetdrill [2]
with support for PSP added, as well as some test cases, and an
implementation of PSP key exchange and connection upgrade [3]
integrated into the fbthrift RPC library. Both [2] and [3] have been
tested on server platforms with PSP-capable CX7 NICs. Below is the
cover letter from the original RFC:

Add support for PSP encryption of TCP connections.

PSP is a protocol out of Google:
https://github.com/google/psp/blob/main/doc/PSP_Arch_Spec.pdf
which shares some similarities with IPsec. I added some more info
in the first patch so I'll keep it short here.

The protocol can work in multiple modes including tunneling.
But I'm mostly interested in using it as TLS replacement because
of its superior offload characteristics. So this patch does three
things:

 - it adds "core" PSP code
   PSP is offload-centric, and requires some additional care and
   feeding, so first chunk of the code exposes device info.
   This part can be reused by PSP implementations in xfrm, tunneling etc.

 - TCP integration TLS style
   Reuse some of the existing concepts from TLS offload, such as
   attaching crypto state to a socket, marking skbs as "decrypted",
   egress validation. PSP does not prescribe key exchange protocols.
   To use PSP as a more efficient TLS offload we intend to perform
   a TLS handshake ("inline" in the same TCP connection) and negotiate
   switching to PSP based on capabilities of both endpoints.
   This is also why I'm not including a software implementation.
   Nobody would use it in production, software TLS is faster,
   it has larger crypto records.

 - mlx5 implementation
   That's mostly other people's work, not 100% sure those folks
   consider it ready hence the RFC in the title. But it works :)

Not posted, queued a branch [4] are follow up pieces:
 - standard stats
 - netdevsim implementation and tests

[1] https://lore.kernel.org/netdev/20240510030435.120935-1-kuba@kernel.org/
[2] https://github.com/danieldzahka/packetdrill
[3] https://github.com/danieldzahka/fbthrift/tree/dzahka/psp
[4] https://github.com/kuba-moo/linux/tree/psp

Comments we intend to defer to future series:
   - we prefer to keep the version field in the tx-assoc netlink
     request, because it makes parsing keys require less state early
     on, but we are willing to change in the next version of this
     series.
   - using a static branch to wrap psp_enqueue_set_decrypted() and
     other functions called from tcp.
   - using INDIRECT_CALL for tls/psp in sk_validate_xmit_skb(). We
     prefer to address this in a dedicated patch series, so that this
     series does not need to modify the way tls_validate_xmit_skb() is
     declared and stubbed out.

v12: https://lore.kernel.org/netdev/20250916000559.1320151-1-kuba@kernel.org/
v11: https://lore.kernel.org/20250911014735.118695-1-daniel.zahka@gmail.com
v10: https://lore.kernel.org/netdev/20250828162953.2707727-1-daniel.zahka@gmail.com/
v9: https://lore.kernel.org/netdev/20250827155340.2738246-1-daniel.zahka@gmail.com/
v8: https://lore.kernel.org/netdev/20250825200112.1750547-1-daniel.zahka@gmail.com/
v7: https://lore.kernel.org/netdev/20250820113120.992829-1-daniel.zahka@gmail.com/
v6: https://lore.kernel.org/netdev/20250812003009.2455540-1-daniel.zahka@gmail.com/
v5: https://lore.kernel.org/netdev/20250723203454.519540-1-daniel.zahka@gmail.com/
v4: https://lore.kernel.org/netdev/20250716144551.3646755-1-daniel.zahka@gmail.com/
v3: https://lore.kernel.org/netdev/20250702171326.3265825-1-daniel.zahka@gmail.com/
v2: https://lore.kernel.org/netdev/20250625135210.2975231-1-daniel.zahka@gmail.com/
v1: https://lore.kernel.org/netdev/20240510030435.120935-1-kuba@kernel.org/
==================

Links: https://patch.msgid.link/20250917000954.859376-1-daniel.zahka@gmail.com


Signed-off-by: default avatarPaolo Abeni <pabeni@redhat.com>
---
* add-basic-psp-encryption-for-tcp-connections:
  net/mlx5e: Implement PSP key_rotate operation
  net/mlx5e: Add Rx data path offload
  psp: provide decapsulation and receive helper for drivers
  net/mlx5e: Configure PSP Rx flow steering rules
  net/mlx5e: Add PSP steering in local NIC RX
  net/mlx5e: Implement PSP Tx data path
  psp: provide encapsulation helper for drivers
  net/mlx5e: Implement PSP operations .assoc_add and .assoc_del
  net/mlx5e: Support PSP offload functionality
  psp: track generations of device key
  net: psp: update the TCP MSS to reflect PSP packet overhead
  net: psp: add socket security association code
  net: tcp: allow tcp_timewait_sock to validate skbs before handing to device
  net: move sk_validate_xmit_skb() to net/core/dev.c
  psp: add op for rotation of device key
  tcp: add datapath logic for PSP with inline key exchange
  net: modify core data structures for PSP datapath support
  psp: base PSP device support
  psp: add documentation
parents b332fb72 411d9d33

Documentation/netlink/specs/psp.yaml

0 → 100644
+187 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

---

name: psp



doc:

  PSP Security Protocol Generic Netlink family.



definitions:

  -

    type: enum

    name: version

    entries: [hdr0-aes-gcm-128, hdr0-aes-gcm-256,

              hdr0-aes-gmac-128, hdr0-aes-gmac-256]



attribute-sets:

  -

    name: dev

    attributes:

      -

        name: id

        doc: PSP device ID.

        type: u32

        checks:

          min: 1

      -

        name: ifindex

        doc: ifindex of the main netdevice linked to the PSP device.

        type: u32

      -

        name: psp-versions-cap

        doc: Bitmask of PSP versions supported by the device.

        type: u32

        enum: version

        enum-as-flags: true

      -

        name: psp-versions-ena

        doc: Bitmask of currently enabled (accepted on Rx) PSP versions.

        type: u32

        enum: version

        enum-as-flags: true

  -

    name: assoc

    attributes:

      -

        name: dev-id

        doc: PSP device ID.

        type: u32

        checks:

          min: 1

      -

        name: version

        doc: |

          PSP versions (AEAD and protocol version) used by this association,

          dictates the size of the key.

        type: u32

        enum: version

      -

        name: rx-key

        type: nest

        nested-attributes: keys

      -

        name: tx-key

        type: nest

        nested-attributes: keys

      -

        name: sock-fd

        doc: Sockets which should be bound to the association immediately.

        type: u32

  -

    name: keys

    attributes:

      -

        name: key

        type: binary

      -

        name: spi

        doc: Security Parameters Index (SPI) of the association.

        type: u32



operations:

  list:

    -

      name: dev-get

      doc: Get / dump information about PSP capable devices on the system.

      attribute-set: dev

      do:

        request:

          attributes:

            - id

        reply: &dev-all

          attributes:

            - id

            - ifindex

            - psp-versions-cap

            - psp-versions-ena

        pre: psp-device-get-locked

        post: psp-device-unlock

      dump:

        reply: *dev-all

    -

      name: dev-add-ntf

      doc: Notification about device appearing.

      notify: dev-get

      mcgrp: mgmt

    -

      name: dev-del-ntf

      doc: Notification about device disappearing.

      notify: dev-get

      mcgrp: mgmt

    -

      name: dev-set

      doc: Set the configuration of a PSP device.

      attribute-set: dev

      do:

        request:

          attributes:

            - id

            - psp-versions-ena

        reply:

          attributes: []

        pre: psp-device-get-locked

        post: psp-device-unlock

    -

      name: dev-change-ntf

      doc: Notification about device configuration being changed.

      notify: dev-get

      mcgrp: mgmt



    -

      name: key-rotate

      doc: Rotate the device key.

      attribute-set: dev

      do:

        request:

          attributes:

            - id

        reply:

          attributes:

            - id

        pre: psp-device-get-locked

        post: psp-device-unlock

    -

      name: key-rotate-ntf

      doc: Notification about device key getting rotated.

      notify: key-rotate

      mcgrp: use



    -

      name: rx-assoc

      doc: Allocate a new Rx key + SPI pair, associate it with a socket.

      attribute-set: assoc

      do:

        request:

          attributes:

            - dev-id

            - version

            - sock-fd

        reply:

          attributes:

            - dev-id

            - rx-key

        pre: psp-assoc-device-get-locked

        post: psp-device-unlock

    -

      name: tx-assoc

      doc: Add a PSP Tx association.

      attribute-set: assoc

      do:

        request:

          attributes:

            - dev-id

            - version

            - tx-key

            - sock-fd

        reply:

          attributes: []

        pre: psp-assoc-device-get-locked

        post: psp-device-unlock



mcast-groups:

  list:

    -

      name: mgmt

    -

      name: use



...

Documentation/networking/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -101,6 +101,7 @@ Contents: 
   ppp_generic

   proc_net_tcp

   pse-pd/index

   psp

   radiotap-headers

   rds

   regulatory

Documentation/networking/psp.rst

0 → 100644
+183 −0
Original line number Diff line number Diff line 
.. 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``).

drivers/net/ethernet/mellanox/mlx5/core/Kconfig

+11 −0
Original line number Diff line number Diff line
@@ -207,3 +207,14 @@ config MLX5_DPLL 
	help

	  DPLL support in Mellanox Technologies ConnectX NICs.



config MLX5_EN_PSP

	bool "Mellanox Technologies support for PSP cryptography-offload acceleration"

	depends on INET_PSP

	depends on MLX5_CORE_EN

	default y

	help

	  mlx5 device offload support for Google PSP Security Protocol offload.

	  Adds support for PSP encryption offload and for SPI and key generation

	  interfaces to PSP Stack which supports PSP crypto offload.



	  If unsure, say Y.

drivers/net/ethernet/mellanox/mlx5/core/Makefile

+2 −0
Original line number Diff line number Diff line
@@ -112,6 +112,8 @@ mlx5_core-$(CONFIG_MLX5_EN_TLS) += en_accel/ktls_stats.o \ 
				   en_accel/fs_tcp.o en_accel/ktls.o en_accel/ktls_txrx.o \

				   en_accel/ktls_tx.o en_accel/ktls_rx.o



mlx5_core-$(CONFIG_MLX5_EN_PSP) += en_accel/psp.o en_accel/psp_rxtx.o



#

# SW Steering

#