Repository navigation
DTLS 1.3's unified-header (RFC 9147) encrypted-record format is unimplemented #2467
Description
Summary
Follow-up from the family-wide restructure on PR #2441. The current DTLS implementation (#2441/#2451) parses only the legacy fixed-format record header shared by DTLS 1.0/1.2 (content type, legacy version, 2-byte epoch, 48-bit sequence number, 2-byte length). DTLS 1.3 (RFC 9147) keeps that format for plaintext records (alert/handshake/ack content types) but introduces a genuinely different unified header for encrypted records:
- First byte is a bit field: top 3 bits fixed
001, then C (Connection ID present), S (sequence number width: 8 or 16 bits), L (length field present), and the 2 low bits of a shortened epoch. - No content-type or version byte at all — the real content type is inside the encrypted payload.
- Sequence number is encrypted (masked from the ciphertext) and shortened.
- Length is optional — a record with L=0 runs to the end of the datagram.
- Receivers distinguish an encrypted DTLS 1.3 record from a legacy-format one by checking whether the first byte's top 3 bits are
001(ciphertext) vs. a recognized legacy content-type value (plaintext).
Scope
New parsing capability, not a refactor: a schema/dissector for the unified header, record-format auto-detection (legacy vs. unified) ahead of the existing content-type dispatch, and Connection ID support if that's in scope for this project. This should land as its own PR once the version-split restructure from #2441 is in place, since the new DTLSv1_3 concrete class is the natural place for it.
Activity
JarryShaw commentedon Oct 30, 2026
Blocked on the TLS/DTLS version-split restructure (PR #2441) landing first — the new DTLSv1_3 class is the natural home for this. Unblocks when #2441 merges.
feat(application): split TLS into a version dispatcher, add an SSLv2 …
feat(application): split DTLS into a version dispatcher over its own …
feat(application): implement TLS/SSL and DTLS record layer + handshak…
1 remaining item
JarryShaw commentedon Oct 31, 2026
Open questions for the owner, paraphrased: (1) decode connection-ID records? That needs the negotiated CID length, which this layer does not track; the commit refuses them. (2) add a plausibility rule on UDP 5684? Any datagram whose first octet is 0x20 to 0x3F and whose header fits parses as DTLS 1.3 today. (3) keep DTLSCiphertext as its own data model, or fold the optional fields into DTLS? Commit 504ca20c4 is local and not pushed.
JarryShaw commentedon Oct 31, 2026
Decisions needed, DTLS 1.3 records (
504ca20c4, local, unpushed): (1) Decode connection-ID records? Options: refuse them (current, degrades to Raw) or decode using a negotiated CID length this layer does not track. Recommendation: refuse until CID length is tracked. (2) Plausibility rule on UDP 5684? Options: keep as-is (any datagram with first octet 0x20–0x3F that fits the header parses) or add a version-field check. Recommendation: add the version check to avoid false DTLS 1.3 matches. (3)DTLSCiphertextseparate model or folded intoDTLS? Recommendation: separate, since the optional fields differ.JarryShaw commentedon Oct 31, 2026
take your recommendations. but RFC is the source of truth on the correct behaviour.
JarryShaw commentedon Oct 31, 2026
Hold, not pushed. The DTLS 1.3 work is local commit
e8011a8b9on top of maineaddd9061, and it adds the 16-octet minimum ciphertext check from RFC 9147 section 4.2.3. Push and PR wait until the Actions queue drops below 20 (currently 26 queued). The commit is ready for review as soon as it is pushed.JarryShaw commentedon Oct 31, 2026
PR opened as #2494 from the held commit
e8011a8b9.fix(protocols): re-export DTLSCiphertext from the data and schema pac…
feat(application): implement DTLS 1.3 unified-header records (#2467) (#…