Skip to main content

Module quic

flowscope

Module quic 

Source
Available on crate feature quic only.
Expand description

QUIC (RFC 9000) Initial-packet passive metadata parser.

Gated by the quic Cargo feature. Wraps the quic_parser crate (zero-copy QUIC Initial header decode + RFC 9001 §5.2 Initial-secret derivation + AEAD decrypt + CRYPTO-frame reassembly). The reassembled ClientHello is then parsed with tls-parser to surface SNI / ALPN.

§Why

HTTP/3 + DNS-over-QUIC are encrypted-by-default but QUIC’s first-packet keying material is public — derived from the destination Connection ID + a per-version “Initial Salt” (RFC 9001 §5.2). Any passive observer can decrypt the ClientHello, which carries SNI / ALPN / TLS version / cipher list / JA3-style fingerprintable fields.

For HTTP/3 hosts that are otherwise encrypted-end-to-end, the QUIC ClientHello is the only L7 visibility a passive collector has — same shape and value as TLS 1.3 ClientHello visibility over TCP/443.

§Surfaced fields

QuicInitial carries:

  • version — QUIC version number (0x00000001 v1 = RFC 9000, 0x6b3343cf v2 = RFC 9369, 0xff000020+ draft versions).
  • dcid / scid — destination / source connection IDs (max 20 bytes each per RFC 9000).
  • token_present — whether a Retry token was attached to the Initial packet.
  • sni — Server Name Indication from the TLS ClientHello extension.
  • alpn — Application-Layer Protocol Negotiation list (["h3", "h3-29", ...]).

§Scope limits

  • Initial packets only. Subsequent QUIC packets (Handshake, 1-RTT) use keys derived from the TLS handshake we don’t have, so they stay opaque to a passive observer. The Initial packet is enough for ClientHello visibility — that’s the whole point.
  • No 0-RTT decryption. 0-RTT uses keys from a prior session, also not available passively.
  • No QUIC connection-state tracking — one record per Initial packet. CRYPTO-frame coalescence across multiple Initial packets (rare in practice) is OUT of M1.
  • JA4 / JA3 fingerprints not computed here yet — the tls-fingerprints feature works on TCP TLS today; QUIC ClientHello fingerprinting is a follow-up (the JA4 spec recognises QUIC via a transport-letter q instead of t).

Issue #3 (0.18).

Structs§

QuicConfig
Bounds on QuicUdpParser’s cross-datagram reassembly state.
QuicInitial
One decoded QUIC Initial packet with its TLS ClientHello extracted.
QuicUdpParser
QUIC Initial parser with cross-datagram CRYPTO reassembly.

Enums§

ParseError
Failure mode for parse. Each variant maps to one operationally-distinct step of the QUIC Initial pipeline.
QuicVersion
QUIC version, decoded from the long-header version field. RFC-named versions get dedicated variants; IETF drafts and unknowns preserve the raw u32 for forensics.

Constants§

QUIC_PORT
The IANA-assigned QUIC port. Real-world deployments may also use 80 (h3 over alternate-svc) and arbitrary ports; route additional ports yourself via the typed driver.

Functions§

initials_from_pcappcap
Iterate every QuicInitial in the pcap, paired with the FiveTupleKey of the UDP flow it was seen on. Wraps the full pcap → tracker → QuicUdpParser pipeline (which derives the Initial keys, AEAD-decrypts the payload, reassembles CRYPTO frames, and extracts the TLS ClientHello SNI / ALPN) in one call.
ja4tls-fingerprints
JA4 client fingerprint (transport q) for a decoded QUIC Initial — convenience over crate::tls::ja4_quic (issue #82).
parse
Decode one QUIC Initial datagram. Returns the parsed QuicInitial on success, or a ParseError indicating which stage of the pipeline failed.
parser_kind