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