Add DTLS 1.3 Unified Header by theodorsm · Pull Request #793 · pion/dtls

theodorsm · 2026-02-05T11:16:49Z

Description

This PR implements the new DTLS 1.3 Unified Header that is part of the new record layer encoding.

https://datatracker.ietf.org/doc/html/rfc9147#name-the-dtls-record-layer:

    0 1 2 3 4 5 6 7
    +-+-+-+-+-+-+-+-+
    |0|0|1|C|S|L|E E|
    +-+-+-+-+-+-+-+-+
    | Connection ID |   Legend:
    | (if any,      |
    /  length as    /   C   - Connection ID (CID) present
    |  negotiated)  |   S   - Sequence number length
    +-+-+-+-+-+-+-+-+   L   - Length present
    |  8 or 16 bit  |   E   - Epoch
    |Sequence Number|
    +-+-+-+-+-+-+-+-+
    | 16 bit Length |
    | (if present)  |
    +-+-+-+-+-+-+-+-+

Reference issue

Partly fixes #755

codecov · 2026-02-05T11:21:29Z

Codecov Report

❌ Patch coverage is 67.60563% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.32%. Comparing base (d7a09d4) to head (97f1d37).

Files with missing lines	Patch %	Lines
pkg/protocol/recordlayer/header_13.go	66.66%	17 Missing and 6 partials ⚠️

❌ Your patch check has failed because the patch coverage (67.60%) is below the target coverage (70.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #793      +/-   ##
==========================================
- Coverage   82.47%   82.32%   -0.16%     
==========================================
  Files         121      123       +2     
  Lines        6928     6999      +71     
==========================================
+ Hits         5714     5762      +48     
- Misses        803      821      +18     
- Partials      411      416       +5

Flag	Coverage Δ
go	`82.32% <67.60%> (-0.16%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

Implements DTLS 1.3 “Unified Header” support (RFC 9147 §4) and wires it into recordlayer.Header marshal/unmarshal paths.

Changes:

Add UnifiedHeader marshal/unmarshal implementation for DTLS 1.3.
Route recordlayer.Header marshal/unmarshal through the DTLS 1.3 unified header when DTLS 1.3 is detected/selected.
Add unit tests and supporting errors/helpers (IsDTLS13Ciphertext).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
pkg/protocol/recordlayer/header_13.go	New DTLS 1.3 unified header encoding/decoding.
pkg/protocol/recordlayer/header_13_test.go	Tests for unified header and `Header.Unmarshal` DTLS 1.3 path.
pkg/protocol/recordlayer/header.go	DTLS 1.3 branch in `Header.Marshal` and `Header.Unmarshal`.
pkg/protocol/recordlayer/errors.go	Adds unified-header-specific errors and reformats existing ones.
pkg/protocol/content.go	Adds helper to detect DTLS 1.3 ciphertext/unified-header first byte.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-18T14:59:03Z

+	if u.Length > 0 {
+		contentType |= UnifiedHeaderLengthBit
+		head.AddUint16(u.Length)
+	}


The L bit (length present) is controlled by whether the Length field is included, not by whether the length value is non-zero. Using u.Length > 0 to decide whether to set the length bit makes it impossible to (a) omit the length field for non-zero payloads (common for the last record in a datagram) or (b) include a zero length field if needed. Consider adding an explicit boolean (e.g., LengthPresent) and using it to control the L bit independently from the value.

The length can be controlled by not initializing Length or by setting it to 0 explicitly, there is no need for a seperate boolean.

Similar comment to S bit i guess.

JoTurk · 2026-04-18T15:46:10Z

Can you please look at the AI's comments, I think some of them are worth fixing, I'll re read the rfcs and the code and review all your pending prs, sorry it might take a bit because I caught a fever :)

JoTurk

Thank you, sorry i was taking a short break, before things really start, I read the spec few times, my comments are nits feel free to ignore them but I think they are kinda important for tests, and for long term. so we don't have to break the api in the future.

Thank you and sorry again!

JoTurk · 2026-05-06T08:49:34Z

+	if u.Length > 0 {
+		contentType |= UnifiedHeaderLengthBit
+		head.AddUint16(u.Length)
+	}


Similar comment to S bit i guess.

theodorsm · 2026-05-06T22:46:51Z

+)
+
+func TestUnifiedHeader(t *testing.T) {
+	uh := UnifiedHeader{SequenceNumber: 0xaabb, SeqBit: true, Length: 42, LengthBit: true, EpochLow: 15}


The usage of the UnifiedHeader is now very explicit and I would argue it's easier to forget to set the bit flags (we just have to be aware). But I guess it's worth it with the control and round trip correctness.

Interestingly, boringssl only uses 16-bit seq numbers: https://pigweed.googlesource.com/third_party/github/google/boringssl/%2B/HEAD/ssl/dtls_record.cc#541

I wonder if we should do the same as boringssl.

theodorsm · 2026-05-06T22:50:53Z

@JoTurk, thanks for the review! No worries, I have been out sick this week.

I have added the bits to the struct, but now the interface is very explicit. We can try this interface out and see if it becomes messy, if it does, we can move the bits to be implicit again.

JoTurk · 2026-05-08T05:37:26Z

@theodorsm Sorry about this, I hope you're doing better.
Yeah we can test it for a bit and change anything if we don't like it, since we're not tagging from main until 1.3 is ready :)

Add DTLS 1.3 unified header

74e85e1

theodorsm added 2 commits February 5, 2026 15:07

Multi-line errors

13d3194

Merge branch 'master' into theodorsm/record_layer_13

291de58

theodorsm force-pushed the theodorsm/record_layer_13 branch from c26fc58 to 8043e6f Compare April 13, 2026 16:00

Add UnifiedHeader to recordlayer header

ec6817e

theodorsm force-pushed the theodorsm/record_layer_13 branch from 8043e6f to ec6817e Compare April 13, 2026 18:43

theodorsm marked this pull request as ready for review April 13, 2026 20:56

theodorsm mentioned this pull request Apr 13, 2026

DTLS 1.3 FSM architecture #738

Open

theodorsm commented Apr 13, 2026

View reviewed changes

Comment thread pkg/protocol/recordlayer/header.go Outdated

Merge branch 'main' into theodorsm/record_layer_13

00ca5b2

theodorsm requested a review from JoTurk April 14, 2026 18:53

JoTurk requested a review from Copilot April 18, 2026 14:54

Copilot started reviewing on behalf of JoTurk April 18, 2026 14:55 View session

Copilot AI reviewed Apr 18, 2026

View reviewed changes

theodorsm added 2 commits April 19, 2026 22:02

Fix CID length and header size

fc1c8af

Fix test and optional header fields clearing

c48aa27

JoTurk reviewed Apr 25, 2026

View reviewed changes

Comment thread pkg/protocol/recordlayer/header.go Outdated

theodorsm added 2 commits April 27, 2026 21:47

Restore header

8d9ca0b

Add fuzz tests for unified header

b5b860a

JoTurk approved these changes May 6, 2026

View reviewed changes

Add bit bool to struct

6c0de20

theodorsm commented May 6, 2026

View reviewed changes

Merge branch 'main' into theodorsm/record_layer_13

97f1d37

Conversation

theodorsm commented Feb 5, 2026

Description

Reference issue

Uh oh!

codecov Bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 18, 2026

Choose a reason for hiding this comment

Uh oh!

theodorsm Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JoTurk commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JoTurk May 6, 2026

Choose a reason for hiding this comment

Uh oh!

theodorsm May 6, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk May 8, 2026

Choose a reason for hiding this comment

Uh oh!

theodorsm commented May 6, 2026

Uh oh!

JoTurk commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Feb 5, 2026 •

edited

Loading

JoTurk commented Apr 18, 2026 •

edited

Loading