tlsTransport Layer Security Record & Handshake LayerCleartext SNI & ALPN Inside ClientHello (client <-> edge tls TCP 443)
What It Does on the Wire
Next-gen firewalls and NDR sensors live and breathe the sni and alpn extensions inside tls clienthello. FrameAssembly computes all nested Record, Handshake, and Extension length fields automatically.
Transport Layer Security (tls, RFC 8446 / RFC 5246) encrypts HTTPS, API, mail, and VPN sessions over TCP port 443. Even when payload bytes are encrypted, firewalls, web proxies, and IDS engines (Suricata tls.sni, Zeek ssl.log) rely heavily on the unencrypted TLS ClientHello, specifically the Server Name Indication (sni), ALPN (alpn, such as "h2"), negotiated ciphersuite, and TLS version extensions.
FrameAssembly builds valid TLS 1.2 and TLS 1.3 record headers and handshake messages (clienthello, serverhello, certificate, finished, appdata, and alert) with automatic nested length fields across the Record header, Handshake header, and Extensions block.
Test Next-Gen Firewall URL / SNI Category Blocking
Send a TCP 3-way handshake + tls clienthello sni "blocked-domain.example" on port 443 to verify whether your firewall resets (tcp rst) or sends a tls alert block page.
Validate Suricata tls.sni & Zeek ssl.log Threat-Intel Rules
Replay known C2 domain SNIs, weak legacy cipher suites (ciphersuite 0x002f), or obsolete TLS record versions (recordversion 0x0301) safely inside an offline .pcap.
Troubleshoot Reverse Proxy ALPN (h2 vs http/1.1) Negotiation
Model alpn "h2" vs alpn "http/1.1" handshakes followed by appdata records and TLS teardown alerts.
Minimal Quickstart (tls_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host workstation { ip 10.10.5.20 }host https_edge { ip 198.51.100.44 }compile { workstation -> https_edge tcp syn srcport 53443 dstport 443 wait 1ms workstation <- https_edge tcp syn ack wait 1ms workstation -> https_edge tcp ack wait 1ms workstation -> https_edge tls clienthello sni "portal.corp.internal" ciphersuite 0x1301 alpn "h2" wait 2ms workstation <- https_edge tls serverhello ciphersuite 0x1301}What the Compiler Calculates So You Don't Have To
- Defaults to TCP destination port
443(psh ack), TLS record version0x0303(RFC 8446 compatibility layer), and TLS 1.3 cipher suite0x1301(TLS_AES_128_GCM_SHA256). - Automatically encodes Extension
0x0000(server_namewhensniis set), Extension0x002b(supported_versionsadvertising TLS 1.30x0304+ TLS 1.20x0303), and Extension0x0010(alpnwhenalpnis set). - Computes all nested 16-bit and 24-bit TLS Record, Handshake, and Extension lengths automatically.
Full TLS 1.3 Handshake (sni + alpn "h2"), Encrypted AppData & Alert Teardown
Completes a TCP 443 handshake, negotiates TLS_CHACHA20_POLY1305_SHA256 (0x1303) with SNI and ALPN, exchanges encrypted Application Data records, and closes with a TLS alert.
host branch_pc { ip 172.16.12.34 }host saas_gw { ip 203.0.113.100 }compile { branch_pc -> saas_gw tcp syn srcport 54443 dstport 443 win 65535 mss 1460 sackperm wait 1ms branch_pc <- saas_gw tcp syn ack win 65535 mss 1460 sackperm wait 1ms branch_pc -> saas_gw tcp ack wait 1ms // 1. TLS 1.3 ClientHello + ServerHello + Encrypted Handshake / AppData branch_pc -> saas_gw tls clienthello sni "api.saas-vendor.example" ciphersuite 0x1303 alpn "h2" wait 2ms branch_pc <- saas_gw tls serverhello ciphersuite 0x1303 wait 1ms branch_pc <- saas_gw tls certificate wait 1ms branch_pc <- saas_gw tls finished wait 1ms branch_pc -> saas_gw tls finished wait 2ms // 2. Encrypted TLS Record Type 23 (Application Data) + Record Type 21 (Alert) branch_pc -> saas_gw tls appdata hexpayload "9f4a1c880021bc773310aa55" wait 3ms branch_pc <- saas_gw tls appdata hexpayload "41e82209ff12008ac491bb02" wait 5ms branch_pc -> saas_gw tls alert}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show tls13_sni_handshake.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly tls13_sni_handshake.frasm tls13_sni_handshake.pcap
frameassembly tls13_sni_handshake.frasm tls13_sni_handshake.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse tls13_sni_handshake.pcap tls13_sni_handshake_edited.frasmAll tls Keywords & Header Options
Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after tls:
src_host -> dst_host tls [clienthello | serverhello | certificate | finished | appdata | alert] [recordversion <hex>] [handshakeversion <hex>] [sni "<text>"] [ciphersuite <hex>] [alpn "<text>"]| Keyword / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| clienthello | serverhello | certificate | finished | appdata | alert | TLS record / handshake message type | clienthello | Selects Handshake (22: clienthello, serverhello, certificate, finished), Application Data (23: appdata), or Alert (21: alert). |
| sni "<text>" | Quoted hostname (e.g. "api.example.com") | Omitted unless set | Adds TLS Extension 0x0000 (server_name) to clienthello for proxy/firewall SNI inspection. |
| alpn "<text>" | Quoted protocol ID ("h2", "http/1.1", "mqtt") | Omitted unless set | Adds TLS Extension 0x0010 (Application-Layer Protocol Negotiation) to clienthello. |
| ciphersuite <hex> | 16-bit IANA cipher code (0x1301 AES-128-GCM, 0x1302 AES-256-GCM, 0x1303 ChaCha20) | 0x1301 | Sets the offered or selected Cipher Suite in clienthello / serverhello. |
| recordversion <hex> | handshakeversion <hex> | 16-bit TLS version (0x0301 TLS 1.0, 0x0303 TLS 1.2/1.3 record) | 0x0303 | Overrides the outer 5-byte TLS Record version or inner Handshake legacy version. |
Cross-Layer Wrappers Valid with tls
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
11 options
Cross-Layer Wrappers Valid with tls
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
| Option | Range / Format | Default | Effect on Packet |
|---|---|---|---|
| wait <number><ns|us|ms|s|m> | Time gap (ns, us, ms, s, m) | 10ms | Advances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back). |
| payload "<text>" | hexpayload "<hex>" | Quoted text or hex bytes (choose one) | Omitted | Appends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums. |
| srcmac <mac> | dstmac <mac> | Colon, hyphen, or Cisco dot MAC | Host MAC / RFC multicast MAC | Overrides the 14-byte Ethernet II source or destination MAC address for this single packet. |
| vlan <0..4095> [pcp <0..7>] [dei <0|1>] | VLAN ID 0..4095, PCP 0..7, DEI 0..1 | Untagged | Wraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority. |
| qinq <0..4095> [innervlan <0..4095>] | Outer S-VLAN 0..4095, Inner C-VLAN 0..4095 | Untagged (innervlan 1 when qinq is set) | Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100). |
| mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>] | Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255 | Unlabeled (at most 1 mpls tag per packet) | Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header. |
| ttl <0..255> [dscp <0..63>] [ecn <0..3>] | TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3 | ttl 64, dscp 0, ecn 0 | Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings. |
| ipid <0..65535> [df] [mf] [fragoffset <0..8191>] | IPv4 ID, DF/MF flags, fragment offset 0..8191 | ipid 1, flags 0, fragoffset 0 | Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6). |
| flowlabel <0..1048575> | 20-bit IPv6 Flow Label (0..1048575) | 0 | Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts). |
| srcport <0..65535> | dstport <0..65535> | Port number 0..65535 | srcport 49152 (remembered), TCP 443 | Overrides source or destination port and remembers the port pair automatically on <- replies. |
| seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rst | TCP sequence/ack numbers, window size, flags & RFC 7323 options | psh ack, win 65535, automatic TCP seq/acknum | Overrides automatic TCP sequence tracking, flags, or RFC 7323 options (mss, wscale, sackperm, tsval, tsecr). |
Gotchas & Quick Fixes
TLS 1.3 Still Uses 0x0303 in the Outer Record Header by RFC 8446 Design
tls clienthello sni "app.local" ciphersuite 0x1301Per RFC 8446, TLS 1.3 keeps recordversion at 0x0303 for middlebox compatibility and negotiates TLS 1.3 (0x0304) inside the supported_versions extension—which FrameAssembly adds automatically.
No Underscores in clienthello, serverhello, or ciphersuite
a -> b tls client_hello cipher_suite 0x1301a -> b tls clienthello ciphersuite 0x1301Write clienthello, serverhello, appdata, recordversion, handshakeversion, and ciphersuite as single lowercase words.