Skip to content

DTLS v1.3 #5000

Open
Open

Description

@randombit

Holding ticket

Activity

  1. reneme commented on Feb 13, 2026

    @reneme
    Collaborator

    Originally posted here, but this ticket is probably more appropriate.

    It turns out we have a use case for DTLS 1.3 and will likely start working on an implementation based on the existing TLS 1.3 code. I did a first read-through of RFC 9147 and below are some scratchy notes on what probably has to be done. At this point, we're not ready to provide an exact time frame for this, but it should be measured in months not in years.

    TL;DR: We'll probably need alternative implementations or significant extensions of TLS::Record_Layer, TLS::Handshake_Layer, and TLS::Cipher_State. All the higher layers of the protocol, particularly the implementation of the actual handshake messages and the TLS state machines in TLS::[Client/Server]_Impl_13 can probably stay mostly untouched.

    • Record Layer

      • Support demux of DTLS records ✅
      • Handling of Epoch and Sequence Number ✅
      • Deprotection of Epoch/SeqNumber (see here) ✅
      • Replay protection via a sliding window per epoch ✅
    • Handshake Layer

      • Fragmentation (additional header values + handling of them) ✅
        Note: Transcript hash is calculated from the TLS marshalling (w/o the additional headers)
      • Allow re-fragmenting handshake messages if necessary (MTU discovery)
      • Timeout and Retransmission ✅
    • Key Management in Cipher_State

      • Explicit cipher state handling (Epochs) ✅
        Out-of-order messages at epoch boundaries requires keeping multiple sets of keys for some period ✅
      • Adopt DTLS-specific HKDF labels ✅
    • Handshake Messages and Extensions

      • ClientHello/HelloRetryRequest

      • Client Hello

        • additionally contains a legacy_cookie field from DTLS 1.2 ✅
      • ACK Message ✅

      • Optional? New Post-Handshake Message: RequestConnectionID

      • Optional? New Post-Handshake Message: NewConnectionID

      • Optional? Connection_ID extension

    • Misc

  2. reneme commented on Jun 24, 2026

    @reneme
    Collaborator

    @atreiber94 and I are starting to work on this. It'll be some time before anything lands of course. We're planning to introduce a new dtls13 module that allows disabling support for DTLS 1.3 at compile time and to centralize DTLS-variants of the internal TLS structures. If it appears sensible, we might -- at some point -- flag this new module as "experimental" and start opening pull requests for integration even before the full implementation is ready to go.

    At this point, we don't expect a fully functional implementation to be ready in time for Botan 3.13 but certainly 3.14 is a reasonable goal.

    FYI: @randombit

  3. added this to the Botan 3.14 milestone on Jun 24, 2026
  4. randombit commented on Jun 24, 2026

    @randombit
    OwnerAuthor

    @reneme Great. FYI I have a WIP branch addressing some issues with DTLS 1.2 handshaking (retransmit logic, etc) I'll try to get that up ASAP to minimize conflicts.

  5. reneme commented on Sep 10, 2026

    @reneme
    Collaborator

    @atreiber94 and I are happy to report that our prototypical DTLS implementation just passed essentially all BoGo tests that seem reasonable to enable at this point. Note-worthy omissions include proper support for SRTP and the ability to re-fragment messages to react to changing PMTU requirements. We think that both are reasonable additions after upstreaming the current feature set.

    Major clean-up, unittest and refactoring work is still needed. We hope to create some more preparatory PRs that introduce hooks and abstractions in the existing TLS 1.3 machinery. In the best case, the final DTLS PR should then contain mostly additions to tls_channel_impl13.* and code in a new dtls13 submodule.

    We still aim to get that ready for Botan 3.14.

  6. reneme commented on Oct 2, 2026

    @reneme
    Collaborator

    The clean-up of the actual logic is mostly done. Just the unit tests are currently in a pretty bad shape, because we based the final refactorings entirely on the BoGo integration tests (to avoid having to re-shape the unit tests several times). I'll re-align the unit tests along the way, when opening pull requests for the different preparatory refactorings in the existing TLS implementation.

    Essentially, the TLS 1.3 Channel_Impl_13 will become fairly dumb and most of its logic moves into a Channel_IO class (similar to the TLS 1.2 setup). Channel_IO is abstract and splits into TLS_Channel_IO and DTLS_Channel_IO. The base class holds some common functionality, but most of the beef will be in the flavor-dependent sub classes. Similarly, Handshake_Layer, Record_Layer and Cipher_State will become polymorphic. The concrete Channel_IO implementations orchestrate their respective concrete "layers". For instance, the entire retransmission and acknowledgement state handling is encapsulated behind DTLS_Channel_IO. The state machines in Client_Impl_13 and Server_Impl_13 stay mostly unchanged and rest on top of the flavor-specific transport that I just layed out.

    I'm using this draft PR to keep an overview of the full diff. I will update the base of this PR along with the split-out aspects as they land. That might be useful for context while reviewing.

    @randombit Please let me know if there's anything I can do to make your life easier while upstreaming these ~10k new LOC.

  7. pinned this issue on Oct 2, 2026
  8. randombit commented on Oct 2, 2026

    @randombit
    OwnerAuthor

    @reneme Thanks I will start looking asap. The new TLS test suite I mentioned is basically done but not yet quite baked for release, I invited you as a collab probably worth extending the shim there to support DTLS 1.3 and running the tests to see what falls out - so far I have only run the DTLS 1.3 support against BoringSSL, so there may be some rough bits or incorrect test expectations.

  9. reneme commented on Oct 8, 2026

    @reneme
    Collaborator

    Checking in, because I'll be AFK until Tuesday: The preparatory PRs are moving along nicely! Thanks to @randombit for the swift reviews. Much appreciated! That saves me a lot of cumbersome stacking work. Also, AI is a real help in breaking up the large patch set into smaller parts. I really like that workflow, as it also provides a decent self-review opportunity.

    What's already in (or on the way in)

    What's outstanding (in the planned order of integration)

    • The actual DTLS I/O implementation
      • DTLS_Channel_IO
      • DTLS_Record_Layer
      • DTLS_Handshake_Layer
      • DTLS_Cipher_State
      • plus helper structures

    Needs a second look

    • Double-check that the cookie-secret is provided by the Credentials_Manager in DTLS 1.3
      See here: [DTLS 1.3] Check availability of cookie-secret more centrally #6088 (comment)
    • Dummy CCS before a client replies with an Alert as its second flight
      Sometimes BoGo insists on it, sometimes it doesn't. My understanding: if the alert happens in response to a TLS 1.2 ServerHello (i.e. during downgrade) it has to be omitted, because a TLS 1.2 implementation doesn't expect it.
    • Test (relevant only for TLS but affected by the changes coalescing the entire first server flight): Dummy CCS sent from a server within the server flight will be after the ServerHello and before the encrypted part of the flight)
    • Interleaving of Handshake records carrying fragmented Handshake messages (both in TLS and DTLS) and other record types MUST be prevented, as stated in RFC 9846 in various places. For DTLS this seems hard to check, due to out-of-order delivery of records. Similarly KeyUpdates must always be aligned with a record boundary. These checks aren't well covered by BoGo and our validation story is vague at best.
    • See if we can resolve the need for dynamic_casting the Cipher_State within the Record_Layers. See: [DTLS 1.3] Refactor TLS::Cipher_State for TLS/DTLS polymorphism #6016 (comment)
    • Check if any adaptions have to be added to the DTLS 1.3 implementation to accommodate Add a limit to the number of useless TLS records we will accept #6051
    • Consider capping the MTU at 64k (2^16-1) as done in DTLS 1.2

    /cc @atreiber94

  10. modified the milestones: Botan 3.14, Botan 3.15 on Oct 26, 2026
  11. reneme commented on Oct 30, 2026

    @reneme
    Collaborator

    @atreiber94 and I believe that #6074 should be the final prep-PR for DTLS 1.3 so that the actual implementation PR can be opened as soon as the current PR-stack has landed. Hopefully that can happen shortly after Botan 3.14 is released. For a sneak preview see Rohde-Schwarz#20 which is essentially just the final patch without all the prep-work.

  12. 3 remaining items

  13. reneme commented on Nov 5, 2026

    @reneme
    Collaborator

    @randombit This is coming together finally. The open PRs mostly build on top of each other and we will rebase them as they land.

    There are also two free-standing PRs that can land independently:

    Here's an overview of the current PR stack towards DTLS 1.3 (in order of reviewability):

    Once the stack is merged, we're ready to open the DTLS 1.3 implementation PR. Probably it doesn't make much sense to split this one up further, unfortunately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementEnhancement or new feature

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions