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

[Martin Belanger <martin.nvme.dev@gmail.com>]

On 10/28/26 10:23, Hannes Reinecke wrote:
> 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()'?

A "should" name usually means a check that returns bool, like
tcp_should_autocork(). This function also sends the KeyUpdate, and it
returns -EKEYEXPIRED at the epoch limit.

net/tls already uses "maybe" for a function that acts only when needed:
tls_rx_msg_maybe_announce() in tls_strp.c. I will rename this one to
tls_tx_maybe_update_key() in v3.

> 
> But otherwise looks good.
> 
> Cheers,
> 
> Hannes