Re: [PATCH RFC net-next v2 4/5] tls: send a KeyUpdate at the record limit and on request

[Hannes Reinecke <hare@suse.de>]

On 10/28/26 2:52 PM, Martin Belanger via B4 Relay wrote:
> From: Martin Belanger <martin.belanger@dell.com>
> 
> RFC 9846 section 5.5 requires a key update before the key reaches its
> usage limit, 2^24.5 full-size records for AES-GCM. The limit counts
> records, and only the record layer knows where records start and end.
> Section 4.7.3 also requires a reply to a KeyUpdate with
> update_requested, sent before the next Application Data record. Both
> need a KeyUpdate at an exact position in the record stream.
> 
> For a socket with a registered TX secret, send a KeyUpdate before the
> next record when the key has protected 2^24 records, as GnuTLS does,
> or when the peer asked for one. ChaCha20-Poly1305 has no record limit.
> The KeyUpdate is sent as a handshake record, which closes the open data
> record first. Pending encryptions are then completed, and only then is
> the next key installed.
> 
> Add TLS_TX_KEY_UPDATE to send a KeyUpdate now, optionally asking the
> peer to update too. It can only bring a KeyUpdate forward: the record
> limit is enforced either way. Following section 4.7.3, a new request
> to the peer waits for the answer to the previous one, and no more than
> 2^48-1 epochs are used.
> 
> Assisted-by: LLM
> Signed-off-by: Martin Belanger <martin.belanger@dell.com>
> ---
>   Documentation/networking/tls.rst |  17 +++++
>   include/net/tls.h                |   5 +-
>   include/uapi/linux/tls.h         |   1 +
>   net/tls/tls.h                    |   1 +
>   net/tls/tls_keyupdate.c          |   5 ++
>   net/tls/tls_main.c               |  38 +++++++++-
>   net/tls/tls_sw.c                 | 150 ++++++++++++++++++++++++++++++++++++++-
>   7 files changed, 214 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/networking/tls.rst b/Documentation/networking/tls.rst
> index 2e011bd1ce4a..69752a6d67df 100644
> --- a/Documentation/networking/tls.rst
> +++ b/Documentation/networking/tls.rst
> @@ -326,6 +326,23 @@ direction is then left to the application again.
>   
>   The secrets cannot be read back.
>   
> +With a registered TX secret, the kernel sends a KeyUpdate before the key
> +reaches its record limit (RFC 9846, section 5.5): after 2^24 records, except
> +for ChaCha20-Poly1305, which has no limit. It also sends one before the next
> +record when a received KeyUpdate asks for it. With a registered RX secret,
> +the kernel processes a received KeyUpdate and does not pass the record to
> +the application. A peer that sends more than 8 KeyUpdates in one second ends
> +the connection.
> +
> +TLS_TX_KEY_UPDATE
> +~~~~~~~~~~~~~~~~~
> +
> +TLS 1.3 only. Send a KeyUpdate now and install the next TX key. Needs a
> +registered TX secret. The value is an ``int``: 0 to send a KeyUpdate, 1 to
> +also ask the peer to update its key. Asking the peer needs a registered RX
> +secret, and fails with ``EBUSY`` until the peer has answered the previous
> +request.
> +
>   Statistics
>   ==========
>   
> diff --git a/include/net/tls.h b/include/net/tls.h
> index a5bc28a7d1f5..d3123b17030c 100644
> --- a/include/net/tls.h
> +++ b/include/net/tls.h
> @@ -282,9 +282,12 @@ struct tls_context {
>   	union tls_crypto_context crypto_send;
>   	union tls_crypto_context crypto_recv;
>   
> -	/* Registered for KeyUpdate, protected by the socket lock */
> +	/* KeyUpdate state, protected by the socket lock */
>   	struct tls_traffic_secret tx_secret;
>   	struct tls_traffic_secret rx_secret;
> +	u64 tx_key_updates;		/* KeyUpdates sent */
> +	bool tx_key_update_reply;	/* peer set update_requested */
> +	bool tx_key_update_asked;	/* we set it, no answer yet */
>   
>   	struct list_head list;
>   	refcount_t refcount;
> diff --git a/include/uapi/linux/tls.h b/include/uapi/linux/tls.h
> index d1b136ecea96..c85408cb6ce7 100644
> --- a/include/uapi/linux/tls.h
> +++ b/include/uapi/linux/tls.h
> @@ -44,6 +44,7 @@
>   #define TLS_TX_MAX_PAYLOAD_LEN	5	/* Maximum plaintext size */
>   #define TLS_TX_TRAFFIC_SECRET	6	/* TLS 1.3 TX traffic secret */
>   #define TLS_RX_TRAFFIC_SECRET	7	/* TLS 1.3 RX traffic secret */
> +#define TLS_TX_KEY_UPDATE	8	/* Send a TLS 1.3 KeyUpdate now */
>   
>   /* Supported versions */
>   #define TLS_VERSION_MINOR(ver)	((ver) & 0xFF)
> diff --git a/net/tls/tls.h b/net/tls/tls.h
> index 63ece8074985..d12c9278c814 100644
> --- a/net/tls/tls.h
> +++ b/net/tls/tls.h
> @@ -151,6 +151,7 @@ int tls_hkdf_expand_label(const u8 *secret, size_t secret_len,
>   			  const char *label, u8 *out, size_t out_len);
>   int tls_keyupdate_rekey(struct sock *sk, int tx);
>   int tls_keyupdate_rx(struct sock *sk, struct sk_buff *skb);
> +int tls_sw_key_update(struct sock *sk, int request);
>   int tls_set_sw_offload(struct sock *sk, int tx,
>   		       struct tls_crypto_info *new_crypto_info);
>   void tls_update_rx_zc_capable(struct tls_context *tls_ctx);
> diff --git a/net/tls/tls_keyupdate.c b/net/tls/tls_keyupdate.c
> index 543bf57599c7..851d5b54b336 100644
> --- a/net/tls/tls_keyupdate.c
> +++ b/net/tls/tls_keyupdate.c
> @@ -146,5 +146,10 @@ int tls_keyupdate_rx(struct sock *sk, struct sk_buff *skb)
>   	}
>   	TLS_INC_STATS(sock_net(sk), LINUX_MIB_TLSRXREKEYOK);
>   
> +	/* Any KeyUpdate from the peer answers our update_requested */
> +	ctx->tx_key_update_asked = false;
> +	if (msg[4] == TLS_KEY_UPDATE_REQUESTED)
> +		ctx->tx_key_update_reply = true;
> +
>   	return 0;
>   }
> diff --git a/net/tls/tls_main.c b/net/tls/tls_main.c
> index 8bb1b2773f3f..d71de99d8890 100644
> --- a/net/tls/tls_main.c
> +++ b/net/tls/tls_main.c
> @@ -765,10 +765,14 @@ static int do_tls_setsockopt_conf(struct sock *sk, sockptr_t optval,
>   		/* The registered secret no longer matches the key. The RX
>   		 * secret also needs the TX one, see do_tls_setsockopt_secret().
>   		 */
> -		if (tx)
> +		if (tx) {
>   			memzero_explicit(&ctx->tx_secret,
>   					 sizeof(ctx->tx_secret));
> +			ctx->tx_key_update_reply = false;
> +		}
>   		memzero_explicit(&ctx->rx_secret, sizeof(ctx->rx_secret));
> +		/* the answer now goes to user space */
> +		ctx->tx_key_update_asked = false;
>   		return 0;
>   	}
>   
> @@ -987,6 +991,35 @@ static int do_tls_setsockopt_secret(struct sock *sk, sockptr_t optval,
>   	return rc;
>   }
>   
> +static int do_tls_setsockopt_key_update(struct sock *sk, sockptr_t optval,
> +					unsigned int optlen)
> +{
> +	struct tls_context *ctx = tls_get_ctx(sk);
> +	int value, rc;
> +
> +	if (sockptr_is_null(optval) || optlen != sizeof(value))
> +		return -EINVAL;
> +
> +	if (copy_from_sockptr(&value, optval, sizeof(value)))
> +		return -EFAULT;
> +
> +	if (value != 0 && value != 1)
> +		return -EINVAL;
> +
> +	rc = mutex_lock_interruptible(&ctx->tx_lock);
> +	if (rc)
> +		return rc;
> +	lock_sock(sk);
> +	if (ctx->tx_conf == TLS_SW)
> +		rc = tls_sw_key_update(sk, value);
> +	else
> +		rc = -EINVAL;
> +	release_sock(sk);
> +	mutex_unlock(&ctx->tx_lock);
> +
> +	return rc;
> +}
> +
>   static int do_tls_setsockopt(struct sock *sk, int optname, sockptr_t optval,
>   			     unsigned int optlen)
>   {
> @@ -1020,6 +1053,9 @@ static int do_tls_setsockopt(struct sock *sk, int optname, sockptr_t optval,
>   					      optname == TLS_TX_TRAFFIC_SECRET);
>   		release_sock(sk);
>   		break;
> +	case TLS_TX_KEY_UPDATE:
> +		rc = do_tls_setsockopt_key_update(sk, optval, optlen);
> +		break;
>   	default:
>   		rc = -ENOPROTOOPT;
>   		break;
> diff --git a/net/tls/tls_sw.c b/net/tls/tls_sw.c
> index cc0177320e7e..4fe78624859d 100644
> --- a/net/tls/tls_sw.c
> +++ b/net/tls/tls_sw.c
> @@ -40,6 +40,7 @@
>   #include <linux/module.h>
>   #include <linux/kernel.h>
>   #include <linux/splice.h>
> +#include <linux/unaligned.h>
>   #include <crypto/aead.h>
>   
>   #include <net/strparser.h>
> @@ -1005,6 +1006,151 @@ static int tls_sw_sendmsg_locked(struct sock *sk, struct msghdr *msg,
>   	return copied > 0 ? copied : ret;
>   }
>   
> +/* RFC 9846 section 5.5 allows 2^24.5 full-size records per AES-GCM key.
> + * Send the KeyUpdate a little earlier.
> + */
> +#define TLS_KEYUPDATE_TX_RECORDS	BIT_ULL(24)
> +
> +/* Section 4.7.3: the epoch must not exceed 2^48-1. The application
> + * traffic secrets start at epoch 3.
> + */
> +#define TLS_KEYUPDATE_MAX		(BIT_ULL(48) - 4)
> +
> +/* Send a KeyUpdate with the current key, then install the next key.
> + * Called with tx_lock held and the socket locked.
> + */
> +static int tls_tx_key_update(struct sock *sk, u8 request, int flags)
> +{
> +	u8 body[TLS_KEYUPDATE_MSG_SIZE] = {
> +		TLS_HANDSHAKE_KEYUPDATE, 0, 0, 1, request
> +	};
> +	struct tls_context *tls_ctx = tls_get_ctx(sk);
> +	struct tls_sw_context_tx *ctx = tls_sw_ctx_tx(tls_ctx);
> +	u8 record_type = TLS_RECORD_TYPE_HANDSHAKE;
> +	u8 buf[CMSG_SPACE(sizeof(record_type))];
> +	struct msghdr msg = {};
> +	struct cmsghdr *cmsg;
> +	struct kvec iov;
> +	int ret;
> +
> +	memset(buf, 0, sizeof(buf));
> +	msg.msg_control = buf;
> +	msg.msg_controllen = sizeof(buf);
> +	msg.msg_flags = flags & (MSG_DONTWAIT | MSG_NOSIGNAL);
> +
> +	cmsg = CMSG_FIRSTHDR(&msg);
> +	cmsg->cmsg_level = SOL_TLS;
> +	cmsg->cmsg_type = TLS_SET_RECORD_TYPE;
> +	cmsg->cmsg_len = CMSG_LEN(sizeof(record_type));
> +	memcpy(CMSG_DATA(cmsg), &record_type, sizeof(record_type));
> +
> +	iov.iov_base = body;
> +	iov.iov_len = sizeof(body);
> +	iov_iter_kvec(&msg.msg_iter, ITER_SOURCE, &iov, 1, sizeof(body));
> +
> +	/* A control record closes the open record first, so all data
> +	 * written so far goes out with the current key, ahead of the
> +	 * KeyUpdate.
> +	 */
> +	ret = tls_sw_sendmsg_locked(sk, &msg, sizeof(body));
> +	if (ret < 0)
> +		return ret;
> +
> +	/* Nothing may be encrypted with the next key before the KeyUpdate
> +	 * is encrypted with the current one.
> +	 */
> +	ret = tls_encrypt_async_wait(ctx);
> +	if (!ret)
> +		ret = tls_keyupdate_rekey(sk, 1);
> +	if (ret) {
> +		/* The peer expects the next key: the connection is lost */
> +		TLS_INC_STATS(sock_net(sk), LINUX_MIB_TLSTXREKEYERROR);
> +		tls_err_abort(sk, ret);
> +		return ret;
> +	}
> +
> +	TLS_INC_STATS(sock_net(sk), LINUX_MIB_TLSTXREKEYOK);
> +	tls_ctx->tx_key_updates++;
> +	if (request == TLS_KEY_UPDATE_NOT_REQUESTED)
> +		tls_ctx->tx_key_update_reply = false;
> +
> +	return 0;
> +}
> +
> +/* Send a KeyUpdate if one is due: in reply to the peer's
> + * update_requested (RFC 9846 section 4.7.3), or before the key reaches
> + * its record limit (section 5.5). ChaCha20-Poly1305 has no record limit:
> + * the sequence number would wrap first.
> + */
> +static int tls_tx_key_update_if_due(struct sock *sk, int flags)

'_if_due()' ? Hmm. 'tls_tx_should_update_key()'?

But otherwise looks good.

Cheers,

Hannes
-- 
Dr. Hannes Reinecke                  Kernel Storage Architect
hare@suse.de                                +49 911 74053 688
SUSE Software Solutions GmbH, Frankenstr. 146, 90461 Nürnberg
HRB 36809 (AG Nürnberg), GF: I. Totev, A. McDonald, W. Knoblich