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 (data) |
accept |
accept |
drop |
drop |
Rx plain (ACK|FIN|RST) |
accept |
accept |
accept |
drop |
Rx PSP (good) |
drop |
accept |
accept |
accept |
Rx PSP (bad crypt, !=SPI) |
drop |
drop |
drop |
drop |
Tx |
plain text |
plain text |
encrypted (excl. rtx) |
encrypted (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
).