Commit 5aa97a43 authored by Sabrina Dubroca's avatar Sabrina Dubroca Committed by David S. Miller
Browse files

docs: tls: document TLS1.3 key updates 



Document the kernel's behavior and userspace expectations.

Suggested-by: default avatarJakub Kicinski <kuba@kernel.org>
Signed-off-by: default avatarSabrina Dubroca <sd@queasysnail.net>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 510128b3

Documentation/networking/tls.rst

+36 −0
Original line number Diff line number Diff line
@@ -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