요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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``).
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
프로토콜과 device key 용어
1-21PSP Security Protocol(PSP)은 Google에서 정의해 공개한 packet 보안 프로토콜입니다. 이 문서는 kernel API를 이해하는 데 꼭 필요한 protocol 특성을 간략히 설명하며, 세부 wire format과 cryptographic 절차는 링크된 `PSP_Arch_Spec.pdf` 규격을 참고해야 합니다.
Kernel 구현과 문서는 규격의 `master key` 대신 `device key`라는 용어를 씁니다. 일반 개발자에게 역할이 더 분명하고 명명 지침과 충돌할 가능성도 작기 때문입니다. 두 용어는 이 문맥에서 같은 receiver-side root secret을 가리킵니다.
Kernel 문서와 protocol 규격의 역할을 구분합니다.
.. 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.
파생 Rx key와 device key 순환
22-49PSP는 IPsec의 일부 용어와 mechanism을 빌리지만 처음부터 hardware offload를 염두에 두고 설계되었습니다. 핵심은 receiver가 connection마다 Rx key를 저장하지 않아도 된다는 점입니다. NIC는 자신만 아는 device key와 packet header에 들어 있는 정보를 조합해 필요한 Rx key를 즉석에서 파생합니다.
따라서 connection 수가 늘어도 receiver의 key storage가 비례해 늘지 않고 `O(1)` memory scaling을 달성할 수 있습니다. 반면 Tx key는 다른 protocol과 마찬가지로 저장해야 합니다. 다만 Tx path는 Rx보다 latency에 덜 민감하므로 느린 memory에서 key를 가져오는 지연이 packet drop으로 이어질 가능성이 낮습니다. 가능하면 descriptor 일부처럼 packet과 함께 Tx key를 hardware에 제공하는 방식이 바람직합니다.
Device key는 receiver만 알아야 하며 receiver NIC hardware에서 직접 읽어낼 수 없어야 합니다. 이 secret은 보통 하루에 한 번 주기적으로 순환합니다. Device의 random number generator가 새 device key를 만들면 새 connection에는 새 key를 사용하고, 기존 connection을 끊지 않도록 이전 key도 NIC에 남겨 둡니다. Packet header의 phase bit가 어느 세대의 device key로 암호화했는지 표시합니다.
Connection별 Rx key를 저장하지 않는 receiver data path입니다.
새 connection과 기존 connection이 두 key generation을 나누어 사용합니다.
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.
Userspace API와 device 탐색
50-71PSP는 주로 hardware offload용으로 설계되었습니다. 현재 PSP 기능이 없는 NIC를 위한 software fallback은 없고, PSP 보호 connection을 설정하거나 symmetric key를 교환하는 표준 절차도 protocol 자체에는 정의되어 있지 않습니다.
대신 higher-layer protocol이 capability와 key를 협상해야 합니다. 예를 들어 TLS key exchange 중 PSP 지원 여부를 알리고 양 endpoint가 모두 PSP-capable이면 data path를 PSP로 전환할 수 있습니다. PSP가 TLS를 대체해 handshake까지 수행한다는 뜻이 아니라, 상위 계층이 합의한 뒤 PSP의 packet protection을 사용하는 구조입니다.
PSP의 모든 설정은 PSP netlink family를 통해 수행합니다. 이 family는 system에 존재하는 PSP device 정보를 조회하고 device를 설정하며 PSP 관련 statistics를 읽는 operation도 제공합니다.
협상과 packet offload의 책임 경계를 나타냅니다.
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.
TCP association과 PSP Full 상태
72-120현재 PSP 암호화는 TCP connection만 지원하며 Rx key와 Tx key를 따로 할당합니다. 먼저 target TCP socket을 지정해 `rx-assoc` Netlink command를 실행합니다. Kernel은 NIC에서 새 PSP Rx key를 할당해 socket에 연결하며, 이 단계의 socket은 PSP로 보호된 TCP packet과 plaintext TCP packet을 모두 받습니다.
그다음 `tx-assoc` command로 Tx key를 설치합니다. 성공한 뒤 socket에서 읽는 모든 data는 PSP 인증을 거친 것이어야 하므로 Tx key 설치는 Rx 방향의 허용 정책도 강화합니다. 다만 `tx-assoc` 반환 직후부터 첫 PSP-authenticated data packet을 만날 때까지는 전환 중간 상태가 존재합니다.
중간 상태에서는 인증되지 않은 ACK, FIN, RST 같은 nondata packet도 TCP receive processing에 들어갈 수 있습니다. `tx-assoc` 시점의 socket `rcv_nxt`를 기록하고 ACK와 RST는 sequence number와 관계없이 허용하지만, FIN은 기록한 `rcv_nxt` 값에서만 허용합니다. Plaintext data는 이 단계부터 거부됩니다.
첫 PSP-authenticated data packet이 도착했다는 것은 peer도 `tx-assoc`를 마쳤다는 뜻입니다. 이후 socket은 `PSP Full` 상태가 되어 data 유무와 관계없이 인증에 성공하지 못한 모든 TCP packet을 receive processing 전에 버립니다. Cryptographic 검증에 실패하거나 SPI가 다른 PSP packet은 어느 상태에서도 버립니다.
원문의 ASCII 상태 표를 동일한 의미의 구조화 표로 재구성했습니다.
두 association command와 첫 인증 data가 receive policy를 단계적으로 바꿉니다.
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) |
+----------------+------------+------------+-------------+-------------+
Queue 검사, sequence 공격과 순환 알림
121-143`tx-assoc`가 성공한 뒤 읽는 data가 모두 인증되었음을 보장하려고 kernel은 association 시점에 socket의 receive queue와 out-of-order(`ofo`) queue를 검사합니다. 이미 queue에 plaintext로 받은 packet이 하나라도 있으면 Tx association은 실패합니다. Application은 socket을 비운 뒤 Tx key 설치를 다시 시도해야 합니다. 양 endpoint가 올바르게 동작한다면 보통 이 재시도는 필요하지 않습니다.
PSP로 upgrade하기 전 TCP sequence number에는 integrity protection이 없습니다. 따라서 MITM이 sequence number를 이동시켜 PSP로 보호되는 TCP stream 앞부분을 삭제하는 공격 가능성이 남습니다. Userspace가 이를 완화해야 한다면 `tx-assoc` 뒤에 특별한 `start of PSP` message를 교환해 보호 구간의 시작을 명시해야 합니다.
Device key 순환은 application 제어와 별개로 비동기적으로 일어나며 보통 management daemon이 수행합니다. Key가 순환할 때마다 PSP netlink family가 notification을 생성합니다. Application은 다음 key 순환이 오기 전에 connection을 다시 설정해야 이전 generation이 제거되어도 통신이 끊기지 않습니다.
기존 plaintext가 application에 노출되지 않도록 association 성공 조건을 확인합니다.
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.
Driver 초기화와 Tx·Rx offload contract
144-174가능하면 driver는 `dev-get`의 `psp-versions-ena`를 `0`으로 두어 PSP가 비활성화된 상태로 시작해야 합니다. 미래 확장에서는 처음부터 PSP가 켜진 device가 필요할 수 있으므로 userspace가 이 초기 상태를 영구적인 보장으로 의존해서는 안 됩니다. 기본 활성화와 key 순환은 같은 system component가 책임지는 것이 원칙입니다.
`psp-versions-ena`는 receive processing을 켜는 데만 쓰는 값입니다. 이를 끈 뒤에도 device는 transmit request를 거부해서는 안 됩니다. Active association이 남아 있을 때 userspace가 이 값을 끌 수도 있으며, 그 경우 모든 PSP Rx processing이 깨진다는 점을 관리 계층이 감수해야 합니다.
Driver는 userspace가 명시적으로 key를 순환하지 않아도 초기화 직후 device key가 안전하고 usable하도록 보장해야 합니다. 실제로 동작하는 key를 할당할 수 있어야 하고 duplicate key를 생성해서는 안 됩니다. Host가 임의 SPI의 key를 요청할 수 있는 device라면 이전 OS instance가 이미 알던 SPI+key를 재사용하지 않도록 두 device key를 모두 폐기해야 합니다. 즉 device key를 두 번 순환합니다.
Tx path에서는 주어진 `skb`에 PSP Tx offload가 요청되었는지 `psp_skb_get_assoc_rcu()`로 확인해야 합니다. Rx path에서는 `SKB_EXT_PSP` skb extension을 할당하고 내용을 채운 뒤 `skb->decrypted` bit를 `1`로 설정해 packet이 PSP에서 정상적으로 처리되었음을 networking stack에 전달합니다.
초기화와 packet direction별 필수 동작입니다.
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.
Per-socket TLS형 구현과 독립 PSP device
175-183Linux PSP 구현은 IPsec offload보다 TLS offload model을 더 가깝게 따릅니다. State를 socket마다 유지하고 `skb->decrypted`를 사용해 인증·복호화되지 않은 plaintext가 보호된 socket으로 새어 들어오는 것을 막습니다.
PSP device object는 `netdev`와 분리되어 있습니다. 이 구조 덕분에 physical NIC에만 capability를 묶지 않고 `veth` 같은 software device에도 PSP offload capability를 위임할 수 있습니다.
Per-socket state와 독립 device object가 data path를 연결합니다.
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``).
요약·해설
psp.rst:1-183PSP는 receiver가 packet header와 device key로 connection별 Rx key를 파생해 connection 수와 무관한 `O(1)` key memory를 달성하는 hardware-offload 중심 보안 protocol입니다. Userspace는 PSP netlink의 `rx-assoc`와 `tx-assoc`로 TCP socket을 단계적으로 보호하고, driver는 per-socket association과 skb metadata를 이용해 Tx·Rx offload를 수행합니다.
협상에서 완전 보호 상태까지의 핵심 경로입니다.