Kernel/linux-next
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git synced 2024-12-29 17:22:07 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: tls: document TLS1.3 key updates

Browse Source 
Document the kernel's behavior and userspace expectations.

Suggested-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Sabrina Dubroca <sd@queasysnail.net>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Sabrina Dubroca 2024-12-12 16:36:07 +01:00 committed by David S. Miller
parent 510128b30f
commit 5aa97a43d0
1 changed files with 36 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Documentation/networking/tls.rst
View File

@ -200,6 +200,32 @@ received without a cmsg buffer set.
recv will never return data from mixed types of TLS records.
TLS 1.3 Key Updates
-------------------
In TLS 1.3, KeyUpdate handshake messages signal that the sender is
updating its TX key. Any message sent after a KeyUpdate will be
encrypted using the new key. The userspace library can pass the new
key to the kernel using the TLS_TX and TLS_RX socket options, as for
the initial keys. TLS version and cipher cannot be changed.
To prevent attempting to decrypt incoming records using the wrong key,
decryption will be paused when a KeyUpdate message is received by the
kernel, until the new key has been provided using the TLS_RX socket
option. Any read occurring after the KeyUpdate has been read and
before the new key is provided will fail with EKEYEXPIRED. poll() will
not report any read events from the socket until the new key is
provided. There is no pausing on the transmit side.
Userspace should make sure that the crypto_info provided has been set
properly. In particular, the kernel will not check for key/nonce
reuse.
The number of successful and failed key updates is tracked in the
``TlsTxRekeyOk``, ``TlsRxRekeyOk``, ``TlsTxRekeyError``,
``TlsRxRekeyError`` statistics. The ``TlsRxRekeyReceived`` statistic
counts KeyUpdate handshake messages that have been received.
Integrating in to userspace TLS library
---------------------------------------
@ -286,3 +312,13 @@ TLS implementation exposes the following per-namespace statistics
- ``TlsRxNoPadViolation`` -
number of data RX records which had to be re-decrypted due to
``TLS_RX_EXPECT_NO_PAD`` mis-prediction.
- ``TlsTxRekeyOk``, ``TlsRxRekeyOk`` -
number of successful rekeys on existing sessions for TX and RX
- ``TlsTxRekeyError``, ``TlsRxRekeyError`` -
number of failed rekeys on existing sessions for TX and RX
- ``TlsRxRekeyReceived`` -
number of received KeyUpdate handshake messages, requiring userspace
to provide a new RX key