Derived Rx keys¶

PSP borrows some terms and mechanisms from IPsec. PSP was designedwith HW offloads in mind. The key feature of PSP is that Rx keys for everyconnection do not have to be stored by the receiver but can be derivedfrom device key and information present in packet headers.This makes it possible to implement receivers which require a constantamount 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 muchless latency sensitive than Rx, and delays in fetching keys from slowmemory is less likely to cause packet drops. Preferably, the Tx keysshould 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 beimpossible to read it out of the hardware of the receiver NIC).Moreover, it has to be “rotated” periodically (usually daily). Rotationmeans that new device key gets generated (by a random number generatorof the device), and used for all new connections. To avoid disruptingold connections the old device key remains in the NIC. A phase bitcarried in the packet headers indicates which generation of device keythe packet has been encrypted with.

Device discovery¶

The PSP netlink family defines operations to retrieve informationabout the PSP devices available on the system, configure them andaccess PSP related statistics.

Securing a connection¶

PSP encryption is currently only supported for TCP connections.Rx and Tx keys are allocated separately. First therx-assocNetlink command needs to be issued, specifying a target TCP socket.Kernel will allocate a new PSP Rx key from the NIC and associate itwith given socket. At this stage socket will accept both PSP-securedand plain text TCP packets.

Tx keys are installed using thetx-assoc Netlink command.Once the Tx keys are installed, all data read from the socket willbe PSP-secured. In other words act of installing Tx keys has a secondaryeffect on the Rx direction.

There is an intermediate period aftertx-assoc successfullyreturns and before the TCP socket encounters it’s first PSPauthenticated packet, where the TCP stack will allow certain nondatapackets, i.e. ACKs, FINs, and RSTs, to enter TCP receive processingeven if not PSP authenticated. During thetx-assoc call, the TCPsocket’srcv_nxt field is recorded. At this point, ACKs and RSTswill be accepted with any sequence number, while FINs will only beaccepted at the latched value ofrcv_nxt. Once the TCP stackencounters the first TCP packet containing PSP authenticated data, theother end of the connection must have executed thetx-assoccommand, so any TCP packet, including those without data, will bedropped before receive processing if it is not successfullyauthenticated. This is summarized in the table below. Theaforementioned state of rejecting all non-PSP packets is labeled “PSPFull”.

To ensure that any data read from the socket after thetx-assoccall returns success has been authenticated, the kernel will scan thereceive and ofo queues of the socket attx-assoc time. If anyenqueued packet was received in clear text, the Tx association willfail, and the application should retry installing the Tx key afterdraining the socket (this should not be necessary if both endpointsare well behaved).

Because TCP sequence numbers are not integrity protected prior toupgrading to PSP, it is possible that a MITM could offset sequencenumbers in a way that deletes a prefix of the PSP protected part ofthe TCP stream. If userspace cares to mitigate this type of attack, aspecial “start of PSP” message should be exchanged aftertx-assoc.

Rotation notifications¶

The rotations of device key happen asynchronously and are usuallyperformed by management daemons, not under application control.The PSP netlink family will generate a notification whenever keysare rotated. The applications are expected to re-establish connectionsbefore keys are rotated again.

Driver notes¶

Drivers are expected to start with no PSP enabled (psp-versions-enaindev-get set to0) whenever possible. The user space shouldnot depend on this behavior, as future extension may necessitate creationof devices with PSP already enabled, nonetheless drivers should not enablePSP by default. Enabling PSP should be the responsibility of the systemcomponent which also takes care of key rotation.

Note thatpsp-versions-ena is expected to be used only for enablingreceive processing. The device is not expected to reject transmit requestsafterpsp-versions-ena has been disabled. User may also disablepsp-versions-ena while there are active associations, which willbreak all PSP Rx processing.

Drivers are expected to ensure that a device key is usable and secureupon init, without explicit key rotation by the user space. It must bepossible to allocate working keys, and that no duplicate keys must begenerated. If the device allows the host to request the key for anarbitrary SPI - driver should discard both device keys (rotate thedevice key twice), to avoid potentially using a SPI+key which previousOS instance already had access to.

Drivers must usepsp_skb_get_assoc_rcu() to check if PSP Tx offloadwas requested for given skb. On Rx drivers should allocate and populatetheSKB_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 IPsecoffload, with per-socket state, and the use of skb->decrypted to preventclear text leaks.

PSP device is separate from netdev, to make it possible to “delegate”PSP offload capabilities to software devices (e.g.veth).