1.. SPDX-License-Identifier: GPL-2.0-only 2 3===================== 4PSP Security Protocol 5===================== 6 7Protocol 8======== 9 10PSP Security Protocol (PSP) was defined at Google and published in: 11 12https://raw.githubusercontent.com/google/psp/main/doc/PSP_Arch_Spec.pdf 13 14This section briefly covers protocol aspects crucial for understanding 15the kernel API. Refer to the protocol specification for further details. 16 17Note that the kernel implementation and documentation uses the term 18"device key" in place of "master key", it is both less confusing 19to an average developer and is less likely to run afoul any naming 20guidelines. 21 22Derived Rx keys 23--------------- 24 25PSP borrows some terms and mechanisms from IPsec. PSP was designed 26with HW offloads in mind. The key feature of PSP is that Rx keys for every 27connection do not have to be stored by the receiver but can be derived 28from device key and information present in packet headers. 29This makes it possible to implement receivers which require a constant 30amount of memory regardless of the number of connections (``O(1)`` scaling). 31 32Tx keys have to be stored like with any other protocol, but Tx is much 33less latency sensitive than Rx, and delays in fetching keys from slow 34memory is less likely to cause packet drops. Preferably, the Tx keys 35should be provided with the packet (e.g. as part of the descriptors). 36 37Key rotation 38------------ 39 40The device key known only to the receiver is fundamental to the design. 41Per specification this state cannot be directly accessible (it must be 42impossible to read it out of the hardware of the receiver NIC). 43Moreover, it has to be "rotated" periodically (usually daily). Rotation 44means that new device key gets generated (by a random number generator 45of the device), and used for all new connections. To avoid disrupting 46old connections the old device key remains in the NIC. A phase bit 47carried in the packet headers indicates which generation of device key 48the packet has been encrypted with. 49 50User facing API 51=============== 52 53PSP is designed primarily for hardware offloads. There is currently 54no software fallback for systems which do not have PSP capable NICs. 55There is also no standard (or otherwise defined) way of establishing 56a PSP-secured connection or exchanging the symmetric keys. 57 58The expectation is that higher layer protocols will take care of 59protocol and key negotiation. For example one may use TLS key exchange, 60announce the PSP capability, and switch to PSP if both endpoints 61are PSP-capable. 62 63All configuration of PSP is performed via the PSP netlink family. 64 65Device discovery 66---------------- 67 68The PSP netlink family defines operations to retrieve information 69about the PSP devices available on the system, configure them and 70access PSP related statistics. 71 72Securing a connection 73--------------------- 74 75PSP encryption is currently only supported for TCP connections. 76Rx and Tx keys are allocated separately. First the ``rx-assoc`` 77Netlink command needs to be issued, specifying a target TCP socket. 78Kernel will allocate a new PSP Rx key from the NIC and associate it 79with given socket. At this stage socket will accept both PSP-secured 80and plain text TCP packets. 81 82Tx keys are installed using the ``tx-assoc`` Netlink command. 83Once the Tx keys are installed, all data read from the socket will 84be PSP-secured. In other words act of installing Tx keys has a secondary 85effect on the Rx direction. 86 87There is an intermediate period after ``tx-assoc`` successfully 88returns and before the TCP socket encounters it's first PSP 89authenticated packet, where the TCP stack will allow certain nondata 90packets, i.e. ACKs, FINs, and RSTs, to enter TCP receive processing 91even if not PSP authenticated. During the ``tx-assoc`` call, the TCP 92socket's ``rcv_nxt`` field is recorded. At this point, ACKs and RSTs 93will be accepted with any sequence number, while FINs will only be 94accepted at the latched value of ``rcv_nxt``. Once the TCP stack 95encounters the first TCP packet containing PSP authenticated data, the 96other end of the connection must have executed the ``tx-assoc`` 97command, so any TCP packet, including those without data, will be 98dropped before receive processing if it is not successfully 99authenticated. This is summarized in the table below. The 100aforementioned state of rejecting all non-PSP packets is labeled "PSP 101Full". 102 103+----------------+------------+------------+-------------+-------------+ 104| Event | Normal TCP | Rx PSP | Tx PSP | PSP Full | 105+================+============+============+=============+=============+ 106| Rx plain | accept | accept | drop | drop | 107| (data) | | | | | 108+----------------+------------+------------+-------------+-------------+ 109| Rx plain | accept | accept | accept | drop | 110| (ACK|FIN|RST) | | | | | 111+----------------+------------+------------+-------------+-------------+ 112| Rx PSP (good) | drop | accept | accept | accept | 113+----------------+------------+------------+-------------+-------------+ 114| Rx PSP (bad | drop | drop | drop | drop | 115| crypt, !=SPI) | | | | | 116+----------------+------------+------------+-------------+-------------+ 117| Tx | plain text | plain text | encrypted | encrypted | 118| | | | (excl. rtx) | (excl. rtx) | 119+----------------+------------+------------+-------------+-------------+ 120 121To ensure that any data read from the socket after the ``tx-assoc`` 122call returns success has been authenticated, the kernel will scan the 123receive and ofo queues of the socket at ``tx-assoc`` time. If any 124enqueued packet was received in clear text, the Tx association will 125fail, and the application should retry installing the Tx key after 126draining the socket (this should not be necessary if both endpoints 127are well behaved). 128 129Because TCP sequence numbers are not integrity protected prior to 130upgrading to PSP, it is possible that a MITM could offset sequence 131numbers in a way that deletes a prefix of the PSP protected part of 132the TCP stream. If userspace cares to mitigate this type of attack, a 133special "start of PSP" message should be exchanged after ``tx-assoc``. 134 135Rotation notifications 136---------------------- 137 138The rotations of device key happen asynchronously and are usually 139performed by management daemons, not under application control. 140The PSP netlink family will generate a notification whenever keys 141are rotated. The applications are expected to re-establish connections 142before keys are rotated again. 143 144Kernel implementation 145===================== 146 147Driver notes 148------------ 149 150Drivers are expected to start with no PSP enabled (``psp-versions-ena`` 151in ``dev-get`` set to ``0``) whenever possible. The user space should 152not depend on this behavior, as future extension may necessitate creation 153of devices with PSP already enabled, nonetheless drivers should not enable 154PSP by default. Enabling PSP should be the responsibility of the system 155component which also takes care of key rotation. 156 157Note that ``psp-versions-ena`` is expected to be used only for enabling 158receive processing. The device is not expected to reject transmit requests 159after ``psp-versions-ena`` has been disabled. User may also disable 160``psp-versions-ena`` while there are active associations, which will 161break all PSP Rx processing. 162 163Drivers are expected to ensure that a device key is usable and secure 164upon init, without explicit key rotation by the user space. It must be 165possible to allocate working keys, and that no duplicate keys must be 166generated. If the device allows the host to request the key for an 167arbitrary SPI - driver should discard both device keys (rotate the 168device key twice), to avoid potentially using a SPI+key which previous 169OS instance already had access to. 170 171Drivers must use ``psp_skb_get_assoc_rcu()`` to check if PSP Tx offload 172was requested for given skb. On Rx drivers should allocate and populate 173the ``SKB_EXT_PSP`` skb extension, and set the skb->decrypted bit to 1. 174 175Kernel implementation notes 176--------------------------- 177 178PSP implementation follows the TLS offload more closely than the IPsec 179offload, with per-socket state, and the use of skb->decrypted to prevent 180clear text leaks. 181 182PSP device is separate from netdev, to make it possible to "delegate" 183PSP offload capabilities to software devices (e.g. ``veth``). 184