Skip to content

feat(application): implement DTLS 1.3 unified-header records (#2467) - #2494

Merged
JarryShaw merged 3 commits into
mainfrom
feat/2467-dtls13-unified-header
Oct 31, 2026
Merged

feat(application): implement DTLS 1.3 unified-header records (#2467)#2494
JarryShaw merged 3 commits into
mainfrom
feat/2467-dtls13-unified-header

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Oct 31, 2026

Copy link
Copy Markdown
Owner

Closes #2467. Parses and builds RFC 9147 unified-header records. Refuses connection-ID records. Enforces the 16-octet minimum ciphertext from RFC 9147 section 4.2.3. Narrow: unified-header file 15 passed, 13 subtests; DTLS-referencing files 223 passed.

@JarryShaw
feat(application): implement DTLS 1.3 unified-header records (#2467)
2f83321 
- Parse and make the unified-header ciphertext record (RFC 9147 4.1) in DTLS:
  first octet 001CSLEE, 8- or 16-bit sequence number, optional length.
- Dispatch on the first octet's 001 prefix ahead of legacy content types.
- A record with a connection ID, or a length past the buffer, degrades to Raw.
- Add DTLSCiphertext header schema and data model.
- Update the DTLS docs and the constant-home allowlist for the EE bit offset.

Tests: 11 new unit tests, all passing; DTLS modules at 100% coverage.
@JarryShaw
fix(application): refuse DTLS 1.3 unified-header records under the sa…
e8011a8 
…mple length (#2467)

- Refuse a unified-header ciphertext shorter than 16 octets, the record-number
  sample (RFC 9147 4.2.3), so the datagram degrades to Raw on UDP 5684.
- Raise the test fixture to 16 octets; the old 12-octet stand-in was not a
  record the RFC allows.
- Allowlist the new constant in the one-home test: it is not a pcap header.

Tests: new short-ciphertext cases fail without the check and pass with it.
@JarryShaw JarryShaw added the review: pending No verdict for the current head - never reviewed, or the head moved since the last one label Oct 31, 2026
@JarryShaw JarryShaw mentioned this pull request Oct 31, 2026
Closed
@JarryShaw

JarryShaw commented Oct 31, 2026

Copy link
Copy Markdown
Owner Author

GOOD TO GO (Sonnet, e8011a8b9). The unified header matches RFC 9147 section 4, with 001 prefix and the C, S, L and EE fields. Connection-ID records are refused. The 16-octet floor from section 4.2.3 applies to the AES and ChaCha20 procedure, which is all DTLS 1.3 defines today. DTLSCiphertext is its own model. Narrow tests: 15 passed, 13 subtests. Minor, not blocking: the new test at line 114 triggers a SchemaWarning for a -16 length. Merge is yours.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 31, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 31, 2026
@JarryShaw

JarryShaw commented Oct 31, 2026

Copy link
Copy Markdown
Owner Author

Red required check on e8011a8b9, fix in progress. Python 3.15 fails on tests/protocols/test_package_reexports_1807_unit.py:129: a child export, most likely the new DTLSCiphertext, is not re-exported by its package. The fix is a worker commit on top of this head, a fast-forward, which I will push once the Actions queue is below 20 (it is 9 now). The review: good-to-go label stays until the new head is reviewed.

@github-actions

github-actions Bot commented Oct 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Coverage: 94.51% (unit tier, Python 3.15, 27e5bcfe5, Unit Tests run success)

Package Statements Missed Branches Partial Cover
pcapkit (top level) 104 4 20 2 95.16%
pcapkit/const 19677 133 2628 120 98.85%
pcapkit/corekit 2605 74 818 37 96.52%
pcapkit/dumpkit 281 3 100 3 98.43%
pcapkit/foundation 3070 24 1072 26 98.79%
pcapkit/interface 138 4 52 3 96.32%
pcapkit/protocols 18117 194 4802 180 98.36%
pcapkit/toolkit 924 36 334 10 95.55%
pcapkit/utilities 502 7 144 5 98.14%
pcapkit/vendor 4449 1854 1020 167 55.11%

Per-file detail: the coverage-html artifact of this run.

@JarryShaw
fix(protocols): re-export DTLSCiphertext from the data and schema pac…
27e5bcf 
…kages (#2467)

- pcapkit/protocols/data/application/__init__.py and
  pcapkit/protocols/schema/application/__init__.py do not import
  DTLSCiphertext, which their dtls __all__ lists.
- Re-export it as DTLS_Ciphertext, matching DTLS_Handshake.
- Add the alias to the data and schema aggregator __all__ lists.

Fixes test_package_reexports_1807_unit (test_every_package_reexports_every_child_export).
@JarryShaw JarryShaw added review: pending No verdict for the current head - never reviewed, or the head moved since the last one and removed review: good-to-go Cross-review at the current head says ready; CI state is separate labels Oct 31, 2026
@JarryShaw

JarryShaw commented Oct 31, 2026

Copy link
Copy Markdown
Owner Author

GOOD TO GO (Sonnet, 27e5bcfe5). The fix only adds DTLS_Ciphertext to the re-export lists in four __init__.py files, following the DTLS_Handshake convention. Re-export test: 6 passed. Wider run: 85 passed, 366 subtests. Not verified: Python 3.15 itself, so the red check clearing is inferred from the passing test, not observed. Watch the 3.15 leg on the new head. Merge is yours.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 31, 2026
@JarryShaw
JarryShaw merged commit b915586 into main Oct 31, 2026
65 checks passed
@JarryShaw
JarryShaw deleted the feat/2467-dtls13-unified-header branch October 31, 2026 15:19
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 31, 2026
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

PyPCAPKit
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

DTLS 1.3's unified-header (RFC 9147) encrypted-record format is unimplemented

1 participant

@JarryShaw