Skip to content

[DTLS 1.3] Thread TLS Flavors through TLS 1.3 implementation - #6062

Open
atreiber94 wants to merge 1 commit into
randombit:masterfrom
Rohde-Schwarz:dtls13/flavor_logic
Open

atreiber94 wants to merge 1 commit into
randombit:masterfrom
Rohde-Schwarz:dtls13/flavor_logic

Conversation

@atreiber94

@atreiber94 atreiber94 commented Oct 26, 2026 •

Copy link
Copy Markdown
Collaborator

In preparation for DTLS 1.3 (#5000), introduce all flavor-dependent logic that will be in the TLS base files: every place where the base 1.3 implementation must behave differently for DTLS now branches on TLS_Flavor, and the polymorphic layer interfaces (Channel_IO, Handshake_Layer, Record_Layer, Cipher_State) expose the hooks that the DTLS 1.3 implementation will override. The DTLS 1.3 implementation itself is not part of this change: creating a DTLS 1.3 client still throws, and DTLS 1.3 remains disabled via Policy::allow_dtls13() defaulting to false.

Note that a lot of the introduced code is dead / not active yet. Reviewing it by looking at the DTLS 1.3 WIP (Rohde-Schwarz#20) may help in understanding some choices of DTLS-specific behavior that we added into the base TLS implementation here.

This is hopefully the last or second-to-last refactoring before contributing the full DTLS 1.3 implementation.

Concretely:

  • Channel_Impl_13 takes a Connection_Side and TLS_Flavor; Client and Server select the 1.3 implementation for is_tls_13_or_later() versions and pass the flavor down. Cipher_State::create() and Channel_IO::create() gain (still unreachable) DTLS branches that throw Not_Implemented until the DTLS 1.3 module lands.
  • Client/Server Hello 1.3 handle the DTLS legacy_version, ciphersuite lists and supported_versions, skip the middlebox compatibility mode and the session ID echo for DTLS; Hello_Retry_Request may carry a Cookie for the DTLS stateless cookie exchange; Encrypted_Extensions negotiates DTLS-SRTP (RFC 5764) and the negotiated SRTP profile is stored in the session.
  • Channel_IO grows no-op notification hooks for the DTLS ACK and retransmission logic (protocol version committed, complete/final flight received); Record_Layer and Handshake_Layer report ingestion outcomes and support epoch-specific record protection as needed for DTLS.
  • KeyUpdate handling: Channel_IO::handle_key_update() becomes virtual and subsumes the schedule_read_epoch_pruning() hook, which is removed. The DTLS implementation overrides it to reject KeyUpdates beyond the epoch limit (RFC 9147 8.) and to schedule pruning of superseded read epochs itself; TLS simply updates its read keys.
  • Downgrade handling: the client preserves epoch-0 sequence numbers for the 1.2 implementation; random_signals_downgrade() moves to the Server_Hello base class.
  • PSK binder calculation handles the DTLS legacy_cookie field and the PSK importer uses the "dtls13" label prefix for DTLS 1.3.
  • Policy gains allow_dtls13() (default: false).

@atreiber94 atreiber94 changed the title [DTLS 1.3} Thread TLS Flavors through TLS 1.3 implementation [DTLS 1.3] Thread TLS Flavors through TLS 1.3 implementation Oct 26, 2026
@atreiber94
atreiber94 marked this pull request as ready for review November 5, 2026 12:35
@atreiber94
atreiber94 force-pushed the dtls13/flavor_logic branch 2 times, most recently from 94ec7c9 to ed0c628 Compare November 5, 2026 14:36
@reneme

reneme commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

CI fails because this is currently not based on #6104. Edit: fixed.

@reneme
reneme force-pushed the dtls13/flavor_logic branch 3 times, most recently from a4e74a0 to 783b2f4 Compare November 10, 2026 11:04
@reneme
reneme requested review from randombit and a balanced review from Copilot and removed request for Copilot and randombit November 10, 2026 11:06
@reneme
reneme force-pushed the dtls13/flavor_logic branch 3 times, most recently from 07aeaeb to 7a30d25 Compare November 10, 2026 13:42
@reneme
reneme requested review from randombit and a balanced review from Copilot November 10, 2026 13:54

This comment was marked as resolved.

@atreiber94

Copy link
Copy Markdown
Collaborator Author

Copilot comments are addressed, also removed BOTAN_HAS_DTLS_13 macro checks that were incorrectly added to this PR (will be re-introduced in the final DTLS 1.3 PR).

@randombit

Copy link
Copy Markdown
Owner

Some merge conflicts, also should pick up the flavor changes from #6132

@reneme
reneme force-pushed the dtls13/flavor_logic branch from e16e843 to 56ca88e Compare November 16, 2026 15:55
@reneme

reneme commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Some merge conflicts, also should pick up the flavor changes from #6132

Thanks. Done now.

In preparation for DTLS 1.3 (randombit#5000), introduce all flavor-dependent
logic that will be in the TLS base files: every place where the base 1.3
implementation must behave differently for DTLS now branches on
TLS_Flavor, and the polymorphic layer interfaces (Channel_IO,
Handshake_Layer, Record_Layer, Cipher_State) expose the hooks that the
DTLS 1.3 implementation will override. The DTLS 1.3 implementation
itself is not part of this change: creating a DTLS 1.3 client still
throws, and DTLS 1.3 remains disabled via Policy::allow_dtls13()
defaulting to false.

Concretely:
* Channel_Impl_13 takes a Connection_Side and TLS_Flavor; Client and
  Server select the 1.3 implementation for is_tls_13_or_later()
  versions and pass the flavor down. Cipher_State::create() and
  Channel_IO::create() gain (still unreachable) DTLS branches that
  throw Not_Implemented until the DTLS 1.3 module lands.
* Client/Server Hello 1.3 handle the DTLS legacy_version, ciphersuite
  lists and supported_versions, skip the middlebox compatibility mode
  and the session ID echo for DTLS; Hello_Retry_Request may carry a
  Cookie for the DTLS stateless cookie exchange; Encrypted_Extensions
  negotiates DTLS-SRTP (RFC 5764) and the negotiated SRTP profile is
  stored in the session.
* Channel_IO grows no-op notification hooks for the DTLS ACK and
  retransmission logic (protocol version committed, complete/final
  flight received); Record_Layer and Handshake_Layer report ingestion
  outcomes and support epoch-specific record protection as needed for
  DTLS.
* KeyUpdate handling: Channel_IO::handle_key_update() becomes virtual
  and subsumes the schedule_read_epoch_pruning() hook, which is
  removed. The DTLS implementation overrides it to reject KeyUpdates
  beyond the epoch limit (RFC 9147 8.) and to schedule pruning of
  superseded read epochs itself; TLS simply updates its read keys.
* Downgrade handling: the client preserves epoch-0 sequence numbers for
  the 1.2 implementation; random_signals_downgrade() moves to the
  Server_Hello base class. Handling of Hello_Verify_Request as a
  downgrade trigger to DTLS 1.2 is factored out into a subsequent
  commit, as it belongs to the DTLS 1.3 implementation itself.
* PSK binder calculation handles the DTLS legacy_cookie field and the
  PSK importer uses the "dtls13" label prefix for DTLS 1.3.
* Policy gains allow_dtls13() (default: false).

The handling of ACK records (RFC 9147 7.) together with the
dtls_maximum_queued_acknowledgements() policy knob is likewise factored
out into a subsequent commit, as the DTLS 1.3 implementation is their
only consumer.

Co-Authored-By: René Meusel <rene.meusel@rohde-schwarz.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants