codec::tls_spec - SeleniumBase for Rust

Experimental Crate: codec

seleniumbase_rs_codec::tls_spec holds the TLS specification a client should reproduce. A TlsSpec is a whole TLS profile as plain data: the ids a ClientHello carries and the content of the extensions that have any. TlsSpec::from_client_hello records it from a parsed hello. A caller can layer a custom JA3, JA4 (as JA4_r or JA4_ro) or peetprint over a base spec; each overlay replaces what its fingerprint carries, takes the rest from the base, runs check_reproducible, and recomputes its own fingerprint to compare with the input, so an accepted input reproduces its own fingerprint and a spec BoringSSL cannot emit is refused before any client exists.

The lists never hold GREASE: the grease flag says BoringSSL adds its GREASE values. The per-extension flags of the design plan (ocsp_stapling, sct, session_ticket, renegotiation, ech_grease) are methods that read the extension list, so they cannot disagree with it. The table of what is refused is in Wire formats.

The measured spec carries the trust_anchors extension and the ML-DSA signature schemes, which BoringSSL cannot send, so its own check_reproducible fails; the spec without its known gaps passes.

`TlsSpec`#

struct

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]pub struct TlsSpec {    pub legacy_version: u16,    pub cipher_suites: Vec<u16>,    pub extensions: Vec<u16>,    #[serde(default)]    pub permute_extensions: bool,    #[serde(default)]    pub grease: bool,    #[serde(default)]    pub supported_groups: Vec<u16>,    #[serde(default)]    pub key_share_groups: Vec<u16>,    #[serde(default)]    pub point_formats: Vec<u8>,    #[serde(default)]    pub signature_algorithms: Vec<u16>,    #[serde(default)]    pub alpn: Vec<String>,    #[serde(default)]    pub alps: Option<Alps>,    #[serde(default)]    pub delegated_credentials: Vec<u16>,    #[serde(default)]    pub supported_versions: Vec<u16>,    #[serde(default)]    pub psk_modes: Vec<u8>,    #[serde(default)]    pub cert_compression: Vec<u16>,    #[serde(default)]    pub record_size_limit: Option<u16>,}

A whole TLS profile: what a ClientHello must carry for a client to look like this one.

legacy_versionu16#

The handshake client_version (771).

cipher_suitesVec<u16>#

Cipher suites in wire order, without GREASE.

extensionsVec<u16>#

Extension ids in wire order, without GREASE; SNI and ALPN are listed when sent.

permute_extensionsbool#

Whether the client shuffles the extension order on every connection, as Chrome does (the measured Chrome 155 spec has true).

Default: "false"

greasebool#

Whether GREASE values are added: a cipher, a group, a version and two extensions.

Default: "false"

supported_groupsVec<u16>#

Supported groups in preference order.

point_formatsVec<u8>#

EC point formats: [0] when the extension is sent.

signature_algorithmsVec<u16>#

Signature algorithms in preference order.

alpnVec<String>#

ALPN protocol names in preference order.

alpsOption<Alps>#

The application_settings extension, when sent.

delegated_credentialsVec<u16>#

delegated_credential signature schemes.

supported_versionsVec<u16>#

supported_versions, highest first, without GREASE.

psk_modesVec<u8>#

psk_key_exchange_modes.

cert_compressionVec<u16>#

compress_certificate algorithms.

record_size_limitOption<u16>#

record_size_limit.

`TlsSpec::from_client_hello`, `with_observed_order`#

method

pub fn from_client_hello(hello: &ClientHello) -> Selfpub fn with_observed_order(&self, other: &ClientHello) -> Result<Self, SpecError>

from_client_hello records the profile a parsed hello shows; GREASE becomes the grease flag, and the extension order is taken as observed (permute_extensions is false). with_observed_order compares a second hello of the same client: a changed extension order sets permute_extensions. It returns SpecError::HellosDiffer when the cipher suites or the set of extensions differ.

Extension flags#

method

pub fn has_extension(&self, id: u16) -> boolpub fn ocsp_stapling(&self) -> boolpub fn sct(&self) -> boolpub fn session_ticket(&self) -> boolpub fn renegotiation(&self) -> boolpub fn ech_grease(&self) -> boolpub fn extended_master_secret(&self) -> bool

Whether the spec sends the extension with this id, status_request (OCSP stapling), signed_certificate_timestamp, session_ticket, renegotiation_info, encrypted_client_hello (as GREASE ECH) or extended_master_secret.

Fingerprints of a spec#

method

pub fn ja3(&self) -> Ja3pub fn ja4_facts(&self) -> Ja4Factspub fn ja4(&self) -> Ja4pub fn ja4_raw(&self, order: Ja4Order) -> Ja4Rawpub fn peetprint(&self) -> Peetprint

The JA3 this spec produces (extensions in the listed order); what JA4 reads from it; its JA4; the unhashed JA4 in the given order; and its peetprint, which with grease carries the GREASE tokens BoringSSL adds (one each in versions, groups and ciphers, two in the extensions). See JA3 and JA4.

`TlsSpec::without_known_gaps`#

method

pub fn without_known_gaps(&self, gaps: &[KnownGap]) -> Self

Removes the listed known gaps: TrustAnchorsExtension drops extension 0xCA34; MlDsaSignatureAlgorithms drops 0x0904 to 0x0906 from the signature algorithms and the delegated credentials.

`TlsSpec::check_reproducible`#

method

pub fn check_reproducible(&self) -> Result<(), SpecError>

Checks the spec against what BoringSSL can emit (plan section 3.8) and returns the first SpecError found, checking in this order: the version, the cipher suites, the extensions, the groups, the point formats, the signature algorithms, then extension content.

Show what is checked

legacy_version must be 771; supported_versions may hold TLS 1.0 to 1.3, each once.
The cipher list is not empty, every suite is in ids::BORINGSSL_CIPHERS, each once, and the three TLS 1.3 suites are present together exactly when TLS 1.3 is offered.
Every extension is one BoringSSL has an option for and is not refused (ids::REFUSED_EXTENSIONS, GREASE ids), each once.
Every group is in ids::BORINGSSL_GROUPS, each once; a key share needs its group offered.
point_formats is [0] with ec_point_formats and empty without it.
Every signature algorithm and delegated credential is in ids::BORINGSSL_SIGALGS and is not ML-DSA.
An extension that carries data and the field that holds it agree, and every ALPN name is 1 to 255 bytes.

Overlays#

method

pub fn with_ja3(&self, ja3: &Ja3) -> Result<Self, SpecError>pub fn with_signature_algorithms(&self, ids: &[u16]) -> Result<Self, SpecError>pub fn with_ja4_raw(&self, raw: &Ja4Raw, order: Ja4Order) -> Result<Self, SpecError>pub fn with_peetprint(&self, peet: &Peetprint) -> Result<Self, SpecError>

with_ja3method#

Replaces the version, ciphers, extensions, groups and point formats with a custom JA3. Everything JA3 does not carry (signature algorithms, ALPN, key shares, versions and the other extension bodies) comes from self; content of extensions the JA3 omits is dropped. Extension permutation is turned off, so the JA3 on the wire is exact.

with_signature_algorithmsmethod#

Replaces the signature algorithms. UnsupportedSigalg for a scheme BoringSSL cannot send, ExtensionContent when the list is empty or the extension is not sent.

with_ja4_rawmethod#

Replaces the ciphers, extensions and signature algorithms with a JA4_r (Ja4Order::Sorted) or JA4_ro (Ja4Order::Original). The sorted form carries no order: the ids keep the order they have in self, new ones follow in ascending order, and permute_extensions is kept. The original-order form pins ciphers and extensions and turns permutation off. The TLS version and the first ALPN name come from the a section; groups and the other bodies come from self. Ja4Mismatch when the result would not reproduce raw.

with_peetprintmethod#

Replaces the ciphers, extensions, groups, versions, ALPN, signature algorithms, PSK modes and certificate compression with a custom peetprint. The extension field is sorted, so extension order comes from self. GREASE tokens set the grease flag, and a layout BoringSSL would not produce is refused. PeetprintMismatch when the result would not reproduce peet.

`Alps`#

struct

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]pub struct Alps {    pub protocols: Vec<String>,    pub new_codepoint: bool,}

The application_settings extension: the protocols it announces (such as h2) and whether it uses the new codepoint (0x44CD) rather than the old one (0x4469).

`KnownGap`#

enum

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]pub enum KnownGap {    TrustAnchorsExtension,    MlDsaSignatureAlgorithms,}

A known difference between a measured browser hello and what BoringSSL can send. The measured file records them in provenance.known_gaps.

KnownGapenum#

Show variants

TrustAnchorsExtension#

The trust_anchors extension (0xCA34), which needs a newer btls and wreq.

MlDsaSignatureAlgorithms#

The ML-DSA signature schemes (0x0904 to 0x0906).

`SpecError`#

enum

// Re-exported at the crate root as TlsSpecError.#[derive(Debug, Clone, PartialEq, Eq, Error)]#[non_exhaustive]pub enum SpecError {    LegacyVersion(u16),    UnsupportedVersion(u16),    NoCipherSuites,    UnsupportedCipher(u16),    Tls13Suites,    UnsupportedExtension { id: u16, reason: &'static str },    DuplicateExtension(u16),    UnsupportedGroup(u16),    KeyShareNotOffered(u16),    PointFormats(Vec<u8>),    UnsupportedSigalg { id: u16, name: &'static str },    Duplicate { list: &'static str, id: u16 },    ExtensionContent(u16),    Alpn(String),    Ja4Mismatch(Ja4Section),    Ja4Alpn(String),    PeetprintMismatch(PeetField),    HellosDiffer,}

Why a spec cannot be reproduced, or an overlay cannot be applied.

SpecErrorenum#

Show variants

LegacyVersion(u16)#

The handshake version is not TLS 1.2 (771), the only value BoringSSL writes.

UnsupportedVersion(u16)#

supported_versions lists a version BoringSSL does not offer.

NoCipherSuites#

The cipher suite list is empty.

UnsupportedCipher(u16)#

BoringSSL cannot send this cipher suite (or the spec refuses it by policy, as for the DHE suites).

Tls13Suites#

The TLS 1.3 suites are not all present, or do not match supported_versions.

UnsupportedExtension { id, reason }#

BoringSSL cannot send this extension; reason says why, such as needs btls newer than 0.5.6 and wreq newer than rc.31 for 0xCA34.

DuplicateExtension(u16)#

An extension is listed twice.

UnsupportedGroup(u16)#

BoringSSL cannot offer this supported group.

PointFormats(Vec<u8>)#

The point formats are not [0] with the extension, or not empty without it.

UnsupportedSigalg { id, name }#

BoringSSL cannot send this signature scheme; name is its IANA name, or unassigned.

Duplicate { list, id }#

An id occurs twice in a list where each may occur once.

ExtensionContent(u16)#

An extension is listed without its content, or the content has no extension.

Alpn(String)#

An ALPN protocol name is empty or longer than 255 bytes.

Ja4Mismatch(Ja4Section)#

The recomputed JA4_r differs from the input in this section.

Ja4Alpn(String)#

No known ALPN name has this two-character JA4 ALPN code.

PeetprintMismatch(PeetField)#

The recomputed peetprint differs from the input in this field.

HellosDiffer#

Two hellos meant to show one client differ in more than extension order.

TlsSpec#

TlsSpec::from_client_hello, with_observed_order#

Extension flags#

Fingerprints of a spec#

TlsSpec::without_known_gaps#

TlsSpec::check_reproducible#

Overlays#

Alps#

KnownGap#

SpecError#

Related#

`TlsSpec`#

`TlsSpec::from_client_hello`, `with_observed_order`#

`TlsSpec::without_known_gaps`#

`TlsSpec::check_reproducible`#

`Alps`#

`KnownGap`#

`SpecError`#