Skip to content

feat(application): implement TLS/SSL and DTLS, sharing a record-layer base #2437

Closed

Description

@JarryShaw

Is your feature request related to a problem? Please describe.
Wave 2 of the roadmap (docs/source/contributing/pep.rst). TLS/SSL and DTLS have no implementation — pcapkit/protocols/application/NotImplemented/tls.py is one of 20 identical 0-byte placeholders dating to the project's earliest commits, not a stalled design with prior art to reconcile.

Describe the solution you'd like
A shared record-layer base over the part TLS and DTLS genuinely have in common: the ContentType/legacy-version/length record header (RFC 8446 §5.1 for TLS, RFC 9147 §4.1 for DTLS) is byte-identical in shape between the two — a real, non-trivial shared surface, unlike ICMP/ICMPv6's thin case. DTLS's own divergence (explicit epoch + sequence number, and handshake-message fragmentation that a reliable TLS stream never needs) stays entirely in DTLS's own subclass, so the shared base doesn't force an awkward abstraction across the two.

Confirmed no structural conflict: Application (the base both would sit under -- TLS over TCP, DTLS over UDP) makes no transport assumption at all. It's generic over protocol/schema type parameters with a -1 sentinel for undissected trailing bytes, and never references TCP; HTTP's own class has zero TCP/reassembly coupling either, since all segment reassembly lives in pcapkit/foundation/reassembly/, orthogonal to the Application-layer classes.

DTLS's handshake-fragment reassembly should be a new subclass of the existing Reassembly base (pcapkit/foundation/reassembly/reassembly.py), which is already generic over packet-type/datagram-type/buffer-ID/buffer-type with tcp.py/ipv4.py/ipv6.py as concrete examples -- DTLS's buffer-ID would be the UDP 5-tuple plus epoch. This is a clean extension of existing infrastructure, not a new mechanism.

Describe alternatives you've considered
Building TLS alone first and deferring DTLS -- rejected per pep.rst's own framing: doing either half of the pair alone answers the shared-base design question twice.

Additional context
Discussion #251 separately notes DTLS currently blocks several SCTP PPID dispatch entries. Scope for a first PR: the record layer plus TLS 1.2/1.3 handshake framing (ClientHello/ServerHello/Certificate at the message-type level, not necessarily every extension); full extension parsing and DTLS's fragmentation/reassembly can be follow-ups within the same tracking issue.

Activity

  1. added
    enhancementIssues requesting a new capability (set by the feature request template)
    on Oct 30, 2026
  2. added this to the PyPCAPKit v1.5 milestone on Oct 30, 2026
  3. moved this to Pending in PyPCAPKiton Oct 30, 2026
  4. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 30, 2026
  5. moved this from Pending to WIP in PyPCAPKiton Oct 30, 2026
  6. added
    blockedDeferred pending another issue or decision; see the last comment for what unblocks it
    and removed
    blockedDeferred pending another issue or decision; see the last comment for what unblocks it
    on Oct 30, 2026
  7. 1 remaining item

  8. JarryShaw commented on Nov 1, 2026

    @JarryShaw
    OwnerAuthor

    Decision needed: is this tracker done?

    Landed so far: the record layer for SSLv3/TLS 1.0–1.3 and DTLS 1.0/1.2/1.3 (#2441), DTLS handshake reassembly (#2440, via #2451), the DTLS 1.3 unified header (#2467), SSLv2 (#2466), and the TLS content-type/handshake-type crawlers (#2503). This issue still names two follow-ups: full handshake-extension parsing, and RFC 9146 connection-ID records (these currently fall back to Raw).

    1. Close this tracker and file those two as separate issues.
    2. Keep it open as their umbrella.

    Recommendation: 1. The first-PR scope this issue set has landed, and separate issues can be labelled and dispatched on their own.

  9. added
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    and removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 1, 2026
  10. moved this from WIP to Needs decision in PyPCAPKiton Nov 1, 2026
  11. JarryShaw commented on Nov 1, 2026

    @JarryShaw
    OwnerAuthor

    take 1

  12. JarryShaw commented on Nov 1, 2026

    @JarryShaw
    OwnerAuthor

    Owner chose option 1: close this tracker and track its two follow-ups on their own. Handshake-extension parsing is #2514, and RFC 9146 connection-ID records are #2515. Both are blocked on in-flight work in the same files: #2514 on #2490 and #2457, #2515 on #2496. Closing.

  13. removed
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Nov 1, 2026
  14. moved this from Needs decision to Done in PyPCAPKiton Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementIssues requesting a new capability (set by the feature request template)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions