You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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)
@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.
@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.
@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.
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.
@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.
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)
Cipher_State now (de)protects full record structs, and is prepared for (D)TLS polymorphy. Also, it now performs the check that was introduces due to CVE-2026-34582
The Flight abstraction is flexible enough to handle DTLS, mostly because it now keeps messages individually. Also, it now allows to schedule dummy-CCS records for the "compatibility mode"
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.
@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.
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.
Activity
reneme commentedon Feb 13, 2026
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, andTLS::Cipher_State. All the higher layers of the protocol, particularly the implementation of the actual handshake messages and the TLS state machines inTLS::[Client/Server]_Impl_13can probably stay mostly untouched.Record Layer
Handshake Layer
Note: Transcript hash is calculated from the TLS marshalling (w/o the additional headers)
Handshake_Layer_13will need to be able to actively create messages (i.e. ACKs)Key Management in
Cipher_StateOut-of-order messages at epoch boundaries requires keeping multiple sets of keys for some period ✅
Handshake Messages and Extensions
ClientHello/HelloRetryRequest
Client Hello
ACK Message ✅
Optional? New Post-Handshake Message: RequestConnectionID
Optional? New Post-Handshake Message: NewConnectionID
Optional? Connection_ID extension
Misc
reneme commentedon Jun 24, 2026
@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
dtls13module 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
randombit commentedon Jun 24, 2026
@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.
reneme commentedon Sep 10, 2026
@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 SRTPand 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 newdtls13submodule.We still aim to get that ready for Botan 3.14.
reneme commentedon Oct 2, 2026
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_13will become fairly dumb and most of its logic moves into aChannel_IOclass (similar to the TLS 1.2 setup).Channel_IOis abstract and splits intoTLS_Channel_IOandDTLS_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_LayerandCipher_Statewill become polymorphic. The concreteChannel_IOimplementations orchestrate their respective concrete "layers". For instance, the entire retransmission and acknowledgement state handling is encapsulated behindDTLS_Channel_IO. The state machines inClient_Impl_13andServer_Impl_13stay 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.
randombit commentedon Oct 2, 2026
@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.
reneme commentedon Oct 8, 2026
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)
Cipher_Statenow (de)protects full record structs, and is prepared for (D)TLS polymorphy. Also, it now performs the check that was introduces due to CVE-2026-34582TLS::Cipher_Statefor TLS/DTLS polymorphism #6016Cipher_State#6019Channel_IOnow manages the "record" and "handshake" layers. Here is where most of the differences between TLS and DTLS liveTranscript_Hash_Statenow handles the TLS handshake header independently from the serialized messages and learned about strong typesTranscript_Hash_state+ introduce strong record types #6006Flightabstraction is flexible enough to handle DTLS, mostly because it now keeps messages individually. Also, it now allows to schedule dummy-CCS records for the "compatibility mode"Record_Layerpolymorphic abstraction #6030Handshake_Layerpolymorphic abstraction #6034Integration tests ensuring that the behaviour of
Channel_IO+Record_Layer+Handshake_Layer+Cipher_Stateare as expectedWhat's outstanding (in the planned order of integration)
DTLS_Channel_IODTLS_Record_LayerDTLS_Handshake_LayerDTLS_Cipher_StateNeeds a second look
Credentials_Managerin DTLS 1.3See here: [DTLS 1.3] Check availability of cookie-secret more centrally #6088 (comment)
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.
dynamic_casting theCipher_Statewithin theRecord_Layers. See: [DTLS 1.3] RefactorTLS::Cipher_Statefor TLS/DTLS polymorphism #6016 (comment)/cc @atreiber94
Thread TLS Flavors through TLS 1.3 implementation
reneme commentedon Oct 30, 2026
@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.
Thread TLS Flavors through TLS 1.3 implementation
3 remaining items
Thread TLS Flavors through TLS 1.3 implementation
reneme commentedon Nov 5, 2026
@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):
Hello_Verify_Requestand the culledHello_Verify_Request_Shim#6104CI is green and ready for review
CI is green
CI is green
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.
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation
Thread TLS Flavors through TLS 1.3 implementation