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: 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 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..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.1