http_quik/profile/mod.rs
1//! Data-only definitions for Chrome transport identity profiles.
2//!
3//! This module defines the configuration schemas used by the `tls` and `http2`
4//! modules to construct browser-identical network handshakes. No protocol
5//! logic resides here; these structures serve as the single source of truth
6//! for all fingerprint-sensitive parameters.
7//!
8//! Each [`ChromeProfile`] encodes a complete, multi-layer network identity
9//! spanning TLS (Layer 4), HTTP/2 (Layer 5), and HTTP metadata (Layer 7).
10
11use boring::ssl::SslVersion;
12
13pub mod chrome_134;
14pub mod chrome_147;
15/// Profile definitions for Chrome 148, which serves as the default transport configuration.
16pub mod chrome_148;
17
18/// Alias for BoringSSL's internal version type.
19pub type TlsVersion = SslVersion;
20
21/// Target operating system and CPU architecture.
22///
23/// The platform determines OS-specific protocol parameters (ALPS payload
24/// length, User-Agent string, Client Hint values) and is used by
25/// [`chrome_148::profile_auto`] to align the network persona with the
26/// host kernel's TCP/IP characteristics.
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub enum Platform {
29 /// macOS on Apple Silicon (M1/M2/M3/M4).
30 MacOsArm,
31 /// macOS on Intel x86-64.
32 MacOsX86,
33 /// Windows 10/11 on x86-64.
34 WindowsX64,
35 /// Linux (Ubuntu, Debian, etc.) on x86-64.
36 LinuxX64,
37}
38
39/// Configuration for the TLS 1.2/1.3 handshake layer.
40///
41/// This structure defines the Layer 4 identity of the client. Small changes
42/// here (such as the order of cipher suites) will change the JA3/JA4
43/// fingerprint and can lead to immediate detection.
44#[derive(Debug, Clone, Copy, PartialEq, Eq)]
45pub struct TlsProfile {
46 /// Minimum allowed TLS version (typically TLS 1.2).
47 pub min_version: TlsVersion,
48 /// Maximum allowed TLS version (typically TLS 1.3).
49 pub max_version: TlsVersion,
50 /// Colon-separated list of cipher suites in OpenSSL format.
51 ///
52 /// Precision in the order of this list is critical as it directly
53 /// impacts the JA3/JA4 fingerprint.
54 pub cipher_list: &'static str,
55 /// Numeric IDs for supported elliptic curve groups.
56 pub curves: &'static [u16],
57 /// Whether to enable TLS GREASE (RFC 8701) to simulate randomized extensions.
58 pub grease_enabled: bool,
59 /// Whether to permute (shuffle) TLS extensions per connection.
60 pub permute_extensions: bool,
61 /// Whether to send a dummy ECH (Encrypted Client Hello) extension for GREASE.
62 pub enable_ech_grease: bool,
63 /// Whether to enable ALPS (Application-Layer Protocol Settings).
64 pub alps_enabled: bool,
65 /// Whether to use the draft-01 or final ALPS codepoint.
66 pub alps_use_new_codepoint: bool,
67 /// Additional H2 SETTINGS IDs to append in the ALPS payload.
68 ///
69 /// Windows and Linux Chrome include an extra setting (ID 31386) in the
70 /// ALPS handshake data that macOS omits. Each tuple is `(id, value)`.
71 pub alps_extra_settings: &'static [(u16, u32)],
72 /// Whether to support RFC 8879 certificate compression (Brotli).
73 pub compress_certificate: bool,
74 /// Whether to enable stateless session tickets for fast reconnection.
75 pub session_ticket_enabled: bool,
76 /// Ordered list of ALPN protocol identifiers.
77 pub alpn_protocols: &'static [&'static [u8]],
78 /// Ordered list of signature algorithm IDs (used for JA4_r).
79 pub sigalgs: &'static [u16],
80 /// Whether to verify the server's certificate chain.
81 ///
82 /// Real browsers always verify certificates. Disable only for testing or
83 /// local proxy interception.
84 pub verify_peer: bool,
85}
86
87/// Initial HTTP/2 SETTINGS frame parameters.
88///
89/// The values and the *order* in which they are sent are used by Akamai
90/// and other WAFs to identify the client implementation.
91#[derive(Debug, Clone, Copy, PartialEq, Eq)]
92pub struct SettingsFrame {
93 /// SETTINGS_HEADER_TABLE_SIZE (ID 0x1).
94 pub header_table_size: u32,
95 /// SETTINGS_ENABLE_PUSH (ID 0x2).
96 pub enable_push: bool,
97 /// SETTINGS_INITIAL_WINDOW_SIZE (ID 0x4).
98 pub initial_window_size: u32,
99 /// SETTINGS_MAX_HEADER_LIST_SIZE (ID 0x6).
100 pub max_header_list_size: u32,
101}
102
103/// Configuration for the HTTP/2 protocol layer.
104///
105/// Defines the Layer 5 identity, focusing on behavioral markers like
106/// pseudo-header ordering and stream priority.
107#[derive(Debug, Clone, Copy, PartialEq, Eq)]
108pub struct Http2Profile {
109 /// Initial SETTINGS frame values and order.
110 pub settings: SettingsFrame,
111 /// Total connection-level window size (default + delta).
112 ///
113 /// This value determines the initial `WINDOW_UPDATE` frame increment
114 /// sent immediately after the handshake. Chrome uses a specific non-standard
115 /// increment that acts as a strong identity signal.
116 pub initial_connection_window_size: u32,
117 /// Ordering of pseudo-headers (e.g., :method, :authority, :scheme, :path).
118 pub pseudo_order: [PseudoOrder; 4],
119 /// Priority parameters for the initial HEADERS frame.
120 pub headers_priority: HeadersPriority,
121}
122
123/// Stream priority parameters embedded in the HEADERS frame.
124#[derive(Debug, Clone, Copy, PartialEq, Eq)]
125pub struct HeadersPriority {
126 /// Stream ID that this request depends on (typically 0).
127 pub dep: u32,
128 /// Priority weight (0-255).
129 pub weight: u8,
130 /// Whether this dependency is exclusive.
131 pub exclusive: bool,
132}
133
134/// Canonical HTTP/2 pseudo-header identifiers.
135#[derive(Debug, Clone, Copy, PartialEq, Eq)]
136pub enum PseudoOrder {
137 /// `:method`
138 Method,
139 /// `:authority`
140 Authority,
141 /// `:scheme`
142 Scheme,
143 /// `:path`
144 Path,
145}
146
147/// Chrome-specific HTTP header values and Client Hint metadata.
148///
149/// These values are injected into every outbound request and must match
150/// the declared platform. WAFs cross-check `sec-ch-ua-platform` against
151/// the TLS handshake and TCP stack to detect spoofed identities.
152#[derive(Debug, Clone, PartialEq, Eq)]
153pub struct HeaderProfile {
154 /// Full `User-Agent` header value.
155 pub user_agent: String,
156 /// `sec-ch-ua` Client Hint brand list.
157 pub sec_ch_ua: String,
158 /// `sec-ch-ua-platform` Client Hint (e.g., `"macOS"`, `"Windows"`, `"Linux"`).
159 pub sec_ch_ua_platform: String,
160 /// `sec-ch-ua-platform-version` Client Hint.
161 ///
162 /// Must match the host OS: Windows 11 reports `"15.0.0"`,
163 /// macOS Sequoia reports `"15.0.0"`, Linux reports `"0.0.0"`.
164 pub sec_ch_ua_platform_version: String,
165 /// Whether to include the RFC 9218 `priority` header (e.g., `u=0, i`).
166 pub include_priority_header: bool,
167 /// Whether to advertise `zstd` in the `accept-encoding` header.
168 pub zstd_encoding: bool,
169 /// The Accept-Language header value.
170 pub accept_language: String,
171}
172
173/// A complete, multi-layer identity profile for a Chrome instance.
174///
175/// Combines TLS, HTTP/2, and HTTP metadata into a single configuration
176/// that, when applied, makes the transport layer indistinguishable from
177/// the specified Chrome version and platform.
178#[derive(Debug, Clone, PartialEq, Eq)]
179pub struct ChromeProfile {
180 /// Major Chrome version (e.g., `134`).
181 pub version: u32,
182 /// Target operating system and architecture.
183 pub platform: Platform,
184 /// TLS handshake configuration (JA3/JA4 fingerprint source).
185 pub tls: TlsProfile,
186 /// HTTP/2 handshake configuration (Akamai fingerprint source).
187 pub h2: Http2Profile,
188 /// HTTP-level metadata and Client Hints.
189 pub headers: HeaderProfile,
190}