codec::client_hello

seleniumbase_rs_codec::client_hello parses a captured TLS ClientHello incrementally, from the record header onwards, without trusting its lengths. ClientHello::needed_len tells a capture loop how many bytes make up the first handshake message while it is still arriving, and ClientHello::parse decodes the whole message, which may span several TLS records. Every length is checked against the bytes that remain, so hostile or truncated input returns a ClientHelloError and never panics. GREASE values (RFC 8701) are kept as received; the JA3, JA4 and spec builders strip them.

ClientHello#

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]pub struct ClientHello {    pub record_version: u16,    pub legacy_version: u16,    pub random: [u8; 32],    pub session_id: Vec<u8>,    pub cipher_suites: Vec<u16>,    pub compression_methods: Vec<u8>,    pub extensions: Vec<Extension>,    pub sni: Option<String>,    pub alpn: Vec<Vec<u8>>,    pub supported_versions: Vec<u16>,    pub supported_groups: Vec<u16>,    pub key_share_groups: Vec<u16>,    pub point_formats: Vec<u8>,    pub signature_algorithms: Vec<u16>,    pub psk_modes: Vec<u8>,    pub cert_compression: Vec<u16>,    pub alps: Vec<Vec<u8>>,    pub record_size_limit: Option<u16>,    pub delegated_credentials: Vec<u16>,}

A parsed ClientHello, with the typed fields the fingerprints read. Lists keep GREASE values and wire order. When an extension occurs twice, the typed field holds the value of its first occurrence; extensions keeps both.

ClientHello::needed_len#

pub fn needed_len(prefix: &[u8]) -> Result<Option<usize>, ClientHelloError>

How many bytes the first ClientHello occupies, as far as prefix shows. Returns the byte length of all records that carry the message once the headers seen so far make it known (it may exceed prefix.len()), and None while more bytes are needed. A capture loop reads until the answer is at most the bytes it holds. Each call costs at most MAX_HELLO_RECORDS record headers, however the prefix arrived.

ClientHello::parse#

pub fn parse(records: &[u8]) -> Result<Self, ClientHelloError>

Parses the first ClientHello in records, reassembled across handshake records. Bytes after the message (further records) are ignored. Returns ClientHelloError::Truncated when the message is incomplete and another variant when it is malformed; nothing in the input can make it panic.

ClientHello::extension, has_extension, extension_ids, has_grease#

pub fn extension(&self, id: u16) -> Option<&Extension>pub fn has_extension(&self, id: u16) -> boolpub fn extension_ids(&self) -> Vec<u16>pub fn has_grease(&self) -> bool

The first extension with this id; whether the hello carries one; the extension ids in wire order, GREASE included; and whether a GREASE value appears in the ciphers, extensions, versions, groups or key shares.

Extension#

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]pub struct Extension {    pub id: u16,    pub data: Vec<u8>,}

One extension as it arrived.

ClientHelloError#

#[derive(Debug, Clone, PartialEq, Eq, Error)]pub enum ClientHelloError {    NotHandshake,    NotClientHello(u8),    Truncated { need: usize, have: usize },    Length,    TooLarge,    TooManyRecords,    Extension { id: u16 },}

Why a byte stream is not a usable ClientHello.

without_grease#

pub fn without_grease(values: &[u16]) -> Vec<u16>

Returns values without its GREASE entries, in the same order.

is_grease#

pub const fn is_grease(id: u16) -> bool

Whether id is a GREASE value (RFC 8701): both bytes are equal and the low nibble is 0xA. Defined in ids and re-exported here.

Constants#

pub const MAX_CLIENT_HELLO: usize = 64 * 1024;pub const MAX_HELLO_RECORDS: usize = 1024;

The largest ClientHello handshake message, header included, that the parser accepts; and the most TLS records one ClientHello may span. A 64 KiB message fits four full records, so the record limit allows any fragmentation a client stack would use, and no peer can make the readers walk more than that many record headers per call.

ext_id#

pub mod ext_id {    pub const SERVER_NAME: u16 = 0x0000;    pub const STATUS_REQUEST: u16 = 0x0005;    pub const SUPPORTED_GROUPS: u16 = 0x000A;    pub const EC_POINT_FORMATS: u16 = 0x000B;    pub const SIGNATURE_ALGORITHMS: u16 = 0x000D;    pub const ALPN: u16 = 0x0010;    pub const SIGNED_CERT_TIMESTAMP: u16 = 0x0012;    pub const PADDING: u16 = 0x0015;    pub const EXTENDED_MASTER_SECRET: u16 = 0x0017;    pub const COMPRESS_CERTIFICATE: u16 = 0x001B;    pub const RECORD_SIZE_LIMIT: u16 = 0x001C;    pub const DELEGATED_CREDENTIAL: u16 = 0x0022;    pub const SESSION_TICKET: u16 = 0x0023;    pub const SUPPORTED_VERSIONS: u16 = 0x002B;    pub const PSK_KEY_EXCHANGE_MODES: u16 = 0x002D;    pub const KEY_SHARE: u16 = 0x0033;    pub const ALPS_OLD: u16 = 0x4469;    pub const ALPS: u16 = 0x44CD;    pub const TRUST_ANCHORS: u16 = 0xCA34;    pub const ENCRYPTED_CLIENT_HELLO: u16 = 0xFE0D;    pub const RENEGOTIATION_INFO: u16 = 0xFF01;}

The extension ids the parser decodes, plus the ones the spec layer reasons about. ALPS_OLD and ALPS are application_settings on its old and new codepoint; TRUST_ANCHORS is the extension that BoringSSL as vendored by btls 0.5.6 cannot emit.

Related#