Skip to main content

Crate pingly

Crate pingly 

Source
Expand description

Protocol data models and fingerprint parsers used by the pingly server.

The crate can parse TLS ClientHello captures, HTTP/1 message heads, HTTP/2 byte streams, decrypted HTTP/3 streams, and QUIC transport parameters. Decoded structures can be serialized to JSON and restored without losing protocol data.

§TLS ClientHello

tls::ClientHello::parse handles a complete ClientHello across one or more TLS records. For TCP chunks, append bytes to tls::ClientHelloBuffer and call try_parse until it returns a value.

use pingly::tls::ClientHello;

let record = std::fs::read("client-hello.bin")?;
let hello = ClientHello::parse(&record)?;
let ja3 = hello.ja3();
let ja4 = hello.ja4();

let json = serde_json::to_vec_pretty(&hello)?;
let restored: ClientHello = serde_json::from_slice(&json)?;
assert_eq!(restored.ja3(), ja3);
assert_eq!(restored.ja4(), ja4);

§HTTP/1

h1::Http1HeadBuffer captures arbitrary chunks without parsing fields, so validation and owned model construction can be moved off an I/O path. h1::Http1Parser parses immediately. Both preserve field order, original field-name casing, and field-value bytes.

use pingly::h1::Http1HeadBuffer;

let mut capture = Http1HeadBuffer::response();

for chunk in b"HTTP/1.1 200 OK\r\nServer: pingly\r\n\r\n".chunks(9) {
    capture.extend(chunk);
}

let response = capture
    .parse()?
    .into_response()
    .ok_or_else(|| std::io::Error::other("capture did not contain an HTTP/1 response"))?;
assert_eq!(response.status_code, 200);

§HTTP/2

h2::parse_connection handles finite bytes beginning with the HTTP/2 client connection preface. h2::Http2Parser accepts arbitrary TCP chunks, while h2::parse_frames starts directly at a frame header.

use pingly::h2::{parse_connection, AkamaiFingerprint};

let bytes = std::fs::read("http2-connection.bin")?;
let frames = parse_connection(&bytes)?;
let fingerprint = AkamaiFingerprint::from_frames(&frames);

let json = serde_json::to_vec_pretty(&frames)?;
let restored = serde_json::from_slice::<Vec<pingly::h2::Frame>>(&json)?;
assert_eq!(AkamaiFingerprint::from_frames(&restored), fingerprint);

§HTTP/3 and QUIC

h3::Http3Parser accepts decrypted bytes from one HTTP/3 request stream or client-initiated unidirectional stream. It does not decrypt QUIC packets, and its stateless QPACK decoder rejects field sections that reference the dynamic table. quic::parse_transport_parameters decodes the QUIC parameters carried in a TLS ClientHello. See RFC 9114, RFC 9204, and RFC 9001, Section 8.2.

Modules§

h1
HTTP/1 request and response head parsing.
h2
HTTP/2 wire models, stream parsers, and Akamai fingerprinting.
h3
HTTP/3 stream models, incremental frame parsing, and fingerprinting.
quic
QUIC wire models used by TLS and HTTP/3 fingerprint analysis.
tcp
TCP/IP packet models, link-layer parsing, and passive client fingerprinting.
tls
TLS ClientHello capture, parsing, and fingerprint analysis.