[PATCH RFC net-next 2/5] tls: add socket options to register the traffic secrets
Hannes Reinecke
hare at suse.de
Mon Oct 26 00:37:00 PDT 2026
On 10/26/26 1:36 AM, Martin Belanger via B4 Relay wrote:
> From: Martin Belanger <martin.belanger at dell.com>
>
> kTLS holds the key and IV of each direction, but not the traffic secret
> they were derived from. The derivation is one-way, so the kernel cannot
> compute the next generation for a KeyUpdate on its own.
>
> Add TLS_TX_TRAFFIC_SECRET and TLS_RX_TRAFFIC_SECRET. The owner of the
> socket passes the TLS 1.3 application traffic secret of a direction after
> installing its key. The cipher of the installed key selects the hash, so
> the option takes only the secret. A socket without a registered secret
> behaves as before.
>
> The TX secret can be registered alone. The RX secret needs the TX secret
> first: a received KeyUpdate can ask for one in reply, and since the
> kernel consumes the record, only the kernel can send that reply.
>
> Installing a new key with TLS_TX or TLS_RX removes the secrets that no
> longer apply. The secrets are cleared when the context is freed and
> cannot be read back.
>
> Assisted-by: LLM
> Signed-off-by: Martin Belanger <martin.belanger at dell.com>
> ---
> Documentation/networking/tls.rst | 26 ++++++++++++
> include/net/tls.h | 13 ++++++
> include/uapi/linux/tls.h | 2 +
> net/tls/tls_main.c | 86 +++++++++++++++++++++++++++++++++++++++-
> 4 files changed, 126 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/networking/tls.rst b/Documentation/networking/tls.rst
> index 980c442d7161..2e011bd1ce4a 100644
> --- a/Documentation/networking/tls.rst
> +++ b/Documentation/networking/tls.rst
> @@ -300,6 +300,32 @@ extra byte used by the ContentType field.
>
> [1] https://datatracker.ietf.org/doc/html/rfc8449
>
> +TLS_TX_TRAFFIC_SECRET and TLS_RX_TRAFFIC_SECRET
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +``TLS_TX_TRAFFIC_SECRET`` registers the TLS 1.3 application traffic secret
> +of the transmit direction, ``TLS_RX_TRAFFIC_SECRET`` that of the receive
> +direction. With a registered secret, the kernel performs KeyUpdate for that
> +direction itself (RFC 9846, section 4.7.3). The value is the secret itself.
> +TLS 1.3 only, software path only.
> +
> +Install the key of the direction first, with the ``TLS_TX`` or ``TLS_RX``
> +socket option described above. The cipher of that key selects the hash, and
> +the secret must have the length of that hash: 32 bytes for SHA-256
> +(AES-128-GCM, AES-128-CCM, ChaCha20-Poly1305) or 48 bytes for SHA-384
> +(AES-256-GCM). Other ciphers return ``EOPNOTSUPP``.
> +
> +Each secret can be registered once. ``TLS_RX_TRAFFIC_SECRET`` needs
> +``TLS_TX_TRAFFIC_SECRET`` first: a received KeyUpdate can ask for one in
> +reply, and only the kernel sees it. ``TLS_TX_TRAFFIC_SECRET`` alone is
> +allowed.
> +
> +If the application installs a new key itself with ``TLS_TX``, both secrets
> +are removed. With ``TLS_RX``, the RX secret is removed. KeyUpdate for that
> +direction is then left to the application again.
> +
> +The secrets cannot be read back.
> +
> Statistics
> ==========
>
> diff --git a/include/net/tls.h b/include/net/tls.h
> index e57bef58851e..aacc6d12226e 100644
> --- a/include/net/tls.h
> +++ b/include/net/tls.h
> @@ -65,6 +65,9 @@ struct tls_rec;
>
> #define TLS_AAD_SPACE_SIZE 13
>
> +/* SHA-384, the longest hash of a TLS 1.3 cipher suite kTLS supports */
> +#define TLS_MAX_TRAFFIC_SECRET_SIZE 48
> +
> #define TLS_MAX_IV_SIZE 16
> #define TLS_MAX_SALT_SIZE 4
> #define TLS_TAG_SIZE 16
> @@ -224,6 +227,12 @@ struct tls_prot_info {
> u16 tail_size;
> };
>
> +/* A TLS 1.3 application traffic secret. len is 0 if none is registered. */
> +struct tls_traffic_secret {
> + u8 data[TLS_MAX_TRAFFIC_SECRET_SIZE];
> + u8 len;
> +};
> +
> struct tls_context {
> /* read-only cache line */
> struct tls_prot_info prot_info;
> @@ -266,6 +275,10 @@ struct tls_context {
> union tls_crypto_context crypto_send;
> union tls_crypto_context crypto_recv;
>
> + /* Registered for KeyUpdate, protected by the socket lock */
> + struct tls_traffic_secret tx_secret;
> + struct tls_traffic_secret rx_secret;
> +
> struct list_head list;
> refcount_t refcount;
> struct rcu_head rcu;
> diff --git a/include/uapi/linux/tls.h b/include/uapi/linux/tls.h
> index 1245ab38afc1..d1b136ecea96 100644
> --- a/include/uapi/linux/tls.h
> +++ b/include/uapi/linux/tls.h
> @@ -42,6 +42,8 @@
> #define TLS_TX_ZEROCOPY_RO 3 /* TX zerocopy (only sendfile now) */
> #define TLS_RX_EXPECT_NO_PAD 4 /* Attempt opportunistic zero-copy */
> #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 */
>
> /* Supported versions */
> #define TLS_VERSION_MINOR(ver) ((ver) & 0xFF)
> diff --git a/net/tls/tls_main.c b/net/tls/tls_main.c
> index 8bdb78718a8d..1c6e993ec012 100644
> --- a/net/tls/tls_main.c
> +++ b/net/tls/tls_main.c
> @@ -31,6 +31,7 @@
> * SOFTWARE.
> */
>
> +#include <crypto/sha2.h>
> #include <linux/module.h>
>
> #include <net/tcp.h>
> @@ -325,6 +326,8 @@ void tls_ctx_free(struct sock *sk, struct tls_context *ctx)
>
> memzero_explicit(&ctx->crypto_send, sizeof(ctx->crypto_send));
> memzero_explicit(&ctx->crypto_recv, sizeof(ctx->crypto_recv));
> + memzero_explicit(&ctx->tx_secret, sizeof(ctx->tx_secret));
> + memzero_explicit(&ctx->rx_secret, sizeof(ctx->rx_secret));
> mutex_destroy(&ctx->tx_lock);
>
> if (sk)
> @@ -757,8 +760,16 @@ static int do_tls_setsockopt_conf(struct sock *sk, sockptr_t optval,
> ctx->rx_conf = conf;
> update_sk_prot(sk, ctx);
>
> - if (update)
> + if (update) {
> + /* The registered secret no longer matches the key. The RX
> + * secret also needs the TX one, see do_tls_setsockopt_secret().
> + */
What is a bit unfortunate that we don't have a direct link between the
key and the traffic secret. So a user might set a key which is _not_
derived from the traffic secret, rendering the KeyUpdate non-workable.
Can we add a check here?
It should be possible to calculate the key from the traffic secret, no?
> + if (tx)
> + memzero_explicit(&ctx->tx_secret,
> + sizeof(ctx->tx_secret));
> + memzero_explicit(&ctx->rx_secret, sizeof(ctx->rx_secret));
> return 0;
> + }
>
> if (tx) {
> ctx->sk_write_space = sk->sk_write_space;
> @@ -857,6 +868,72 @@ static int do_tls_setsockopt_tx_payload_len(struct sock *sk, sockptr_t optval,
> return 0;
> }
>
> +/* Length of the TLS 1.3 traffic secret for @cipher_type, the size of
> + * its hash. 0 if KeyUpdate is not supported for the cipher.
> + */
> +static int tls_traffic_secret_len(u16 cipher_type)
> +{
> + switch (cipher_type) {
> + case TLS_CIPHER_AES_GCM_128:
> + case TLS_CIPHER_AES_CCM_128:
> + case TLS_CIPHER_CHACHA20_POLY1305:
> + return SHA256_DIGEST_SIZE;
> + case TLS_CIPHER_AES_GCM_256:
> + return SHA384_DIGEST_SIZE;
> + default:
> + return 0;
> + }
> +}
> +
> +static int do_tls_setsockopt_secret(struct sock *sk, sockptr_t optval,
> + unsigned int optlen, int tx)
> +{
> + struct tls_context *ctx = tls_get_ctx(sk);
> + struct tls_crypto_info *crypto_info;
> + struct tls_traffic_secret *secret;
> + int len;
> +
> + if (tx) {
> + crypto_info = &ctx->crypto_send.info;
> + secret = &ctx->tx_secret;
> + } else {
> + crypto_info = &ctx->crypto_recv.info;
> + secret = &ctx->rx_secret;
> + }
> +
> + /* The key must be installed first: its cipher selects the hash */
> + if (!TLS_CRYPTO_INFO_READY(crypto_info) ||
> + crypto_info->version != TLS_1_3_VERSION)
> + return -EINVAL;
> +
> + if ((tx ? ctx->tx_conf : ctx->rx_conf) != TLS_SW)
> + return -EOPNOTSUPP;
> +
> + len = tls_traffic_secret_len(crypto_info->cipher_type);
> + if (!len)
> + return -EOPNOTSUPP;
> +
> + if (sockptr_is_null(optval) || optlen != len)
> + return -EINVAL;
> +
> + /* A received KeyUpdate may ask for one in reply. The kernel
> + * consumes the record, so only the kernel can send the reply.
> + */
> + if (!tx && !ctx->tx_secret.len)
> + return -EINVAL;
Hmm? What is this? Doesn't that imply that you first have to set the
TX key before setting the RX key?
The documentation says we can do either way ...
> +
> + if (secret->len)
> + return -EBUSY;
> +
> + if (copy_from_sockptr(secret->data, optval, len)) {
> + memzero_explicit(secret->data, sizeof(secret->data));
> + return -EFAULT;
> + }
> + secret->len = len;
> +
> + return 0;
> +}
> +
> static int do_tls_setsockopt(struct sock *sk, int optname, sockptr_t optval,
> unsigned int optlen)
> {
> @@ -883,6 +960,13 @@ static int do_tls_setsockopt(struct sock *sk, int optname, sockptr_t optval,
> rc = do_tls_setsockopt_tx_payload_len(sk, optval, optlen);
> release_sock(sk);
> break;
> + case TLS_TX_TRAFFIC_SECRET:
> + case TLS_RX_TRAFFIC_SECRET:
> + lock_sock(sk);
> + rc = do_tls_setsockopt_secret(sk, optval, optlen,
> + optname == TLS_TX_TRAFFIC_SECRET);
> + release_sock(sk);
> + break;
> default:
> rc = -ENOPROTOOPT;
> break;
>
Cheers,
Hannes
--
Dr. Hannes Reinecke Kernel Storage Architect
hare at 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
More information about the Linux-nvme
mailing list