Module tls 

Available on crate feature tls only.

Passive TLS handshake observer.

Bridges tls-parser into flowscope’s SessionParser abstraction. Receives bytes from the per-flow TCP stream, emits parsed TlsClientHello / TlsServerHello / TlsAlert as TlsMessage variants.

Two SessionParser shapes ship side by side:

• TlsParser — per-message stream (ClientHello, ServerHello, Alert, optional JA3/JA4 fingerprints).
• TlsHandshakeParser — aggregator that emits one TlsHandshake event per observed handshake with SNI, ALPN, fingerprints, version, cipher, and HandshakeOutcome in a single struct.

Quick start

Register a TlsParser on the typed Driver and drain its slot:

use flowscope::driver::Driver;
use flowscope::extract::FiveTuple;
use flowscope::tls::TlsParser;

let mut builder = Driver::builder(FiveTuple::bidirectional());
let mut tls = builder.session_on_ports(TlsParser::default(), [443]);
let _driver = builder.build();

Scope

• Passive observation only — no decryption, no MITM.
• ClientHello, ServerHello, Alert from the unencrypted handshake.
• SNI / ALPN / supported versions / cipher list / extension order.
• TLS 1.0 — TLS 1.3 (visibility limited after ChangeCipherSpec in 1.2 and after ServerHello in 1.3 since records are encrypted onward).
• Optional JA3 and JA4 client fingerprinting behind the tls-fingerprints feature (was ja3 + ja4 pre-0.12; collapsed in plan 131).

Convenience accessors

TlsClientHello

Method / field	Returns	Notes
sni	Option<&str>	Server Name Indication extension
cipher_suites	Vec<u16>	offered cipher suites in order
supported_versions	Vec<TlsVersion>	TLS 1.3 supported_versions extension
alpn	Vec<String>	ALPN protocols offered
extension_types	Vec<u16>	extension order — used by JA3 / JA4

TlsServerHello

Method / field	Returns	Notes
cipher_suite	u16	the chosen cipher
alpn	Option<String>	negotiated ALPN protocol
supported_version	Option<TlsVersion>	actual TLS 1.3 version
extension_types	Vec<u16>	extension order — used by JA4S

TlsHandshakeParser + TlsHandshake

The aggregator emits one TlsHandshake event per observed handshake with SNI / ALPN / JA3 / JA4 / version / cipher / resumption_attempted / HandshakeOutcome in a single struct.

Re-exports

pub use ech::EchState;

pub use handshake::EchOutcome;

pub use handshake::HandshakeOutcome;

pub use handshake::TlsHandshake;

pub use handshake::TlsHandshakeParser;

pub use ja4::Ja4Parts;tls-fingerprints

pub use ja4::ja4 as ja4_fingerprint;tls-fingerprints

pub use ja4::ja4_parts;tls-fingerprints

pub use ja4::ja4_quic;tls-fingerprints

pub use ja4::ja4_quic_parts;tls-fingerprints

pub use ja4s::Ja4sParts;ja4plus

pub use ja4s::ja4s as ja4s_fingerprint;ja4plus

pub use ja4s::ja4s_parts;ja4plus

pub use ja4x::ja4x_for_chain;ja4plus

pub use ja4x::ja4x_for_der;ja4plus

Modules

ech

ECH (Encrypted ClientHello) GREASE-vs-real detector.

handshake

TlsHandshakeParser — aggregates ClientHello + ServerHello + Alert into a single TlsHandshake message per flow.

ja4tls-fingerprints

JA4 client fingerprint (FoxIO v1, 2023).

ja4sja4plus

JA4S server fingerprint (FoxIO, 2023).

ja4xja4plus

JA4X — X.509 certificate fingerprint (FoxIO, 2023).

Structs

TlsAlert

TLS Alert record (RFC 5246 §7.2).

TlsClientHello

Parsed TLS ClientHello — what the client offered to the server.

TlsConfig

Tunables for the TLS observer.

TlsParser

Per-flow TLS handshake parser. Holds independent state for the initiator (client) and responder (server) directions.

TlsServerHello

Parsed TLS ServerHello.

Enums

TlsAlertLevel

TlsMessage

Unified message type emitted by TlsParser.

TlsVersion

Constants

PARSER_KIND

Slug returned by TlsParser’s parser_kind() — the ParserKind::Tls slug.

Functions

client_hellos_from_pcappcap

Iterate every TlsClientHello in the pcap, paired with the FiveTupleKey of the flow it was seen on. Wraps the full pcap → tracker → reassembler → TlsParser path in one call.

handshakes_from_pcappcap

Iterate every aggregated TlsHandshake in the pcap, paired with the FiveTupleKey of the flow it was seen on. One event per handshake (ClientHello + ServerHello + outcome rolled into a single value), rather than one per TLS record.

is_pq_hybrid_group

true if group is a known post-quantum hybrid key-exchange named group (IANA TLS Supported Groups).

ja3_canonicaltls-fingerprints

JA3 canonical string (the pre-hash Version,Ciphers,Extensions,Curves,PointFormats form) for a TlsClientHello. Useful for debugging a fingerprint or feeding an alternate hash. See ja3_fingerprint for the hash.

ja3_fingerprinttls-fingerprints

JA3 client fingerprint hash (hex MD5) for a TlsClientHello.

pq_hybrid_group_name

Human-readable name for a known PQ hybrid group, or None if group isn’t a recognised PQ hybrid. Useful for logs / metric labels.