Protocol 50 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
tlsTransport Layer Security Record & Handshake Layer

Cleartext SNI & ALPN Inside ClientHello (client <-> edge tls TCP 443)

Default Port / Protocol
TCP 443
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
tls
Standards & Specs
RFC 8446, RFC 5246, RFC 6066
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP 443TLS 1.2 / 1.3

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.

tls_quickstart.frasm10 lines
Open in 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 version 0x0303 (RFC 8446 compatibility layer), and TLS 1.3 cipher suite 0x1301 (TLS_AES_128_GCM_SHA256).
  • Automatically encodes Extension 0x0000 (server_name when sni is set), Extension 0x002b (supported_versions advertising TLS 1.3 0x0304 + TLS 1.2 0x0303), and Extension 0x0010 (alpn when alpn is set).
  • Computes all nested 16-bit and 24-bit TLS Record, Handshake, and Extension lengths automatically.
Multi-Frame Lab · Ready to Compile

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.

tls13_sni_handshake.frasm18 lines
Open in Playground
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
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 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.frasm

All 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 / OptionAccepted ValueDefaultEffect on Packet
clienthello | serverhello | certificate | finished | appdata | alertTLS record / handshake message typeclienthelloSelects 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 setAdds TLS Extension 0x0000 (server_name) to clienthello for proxy/firewall SNI inspection.
alpn "<text>"Quoted protocol ID ("h2", "http/1.1", "mqtt")Omitted unless setAdds 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)0x1301Sets 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)0x0303Overrides 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
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances 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)OmittedAppends 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 MACHost MAC / RFC multicast MACOverrides 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..1UntaggedWraps 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..4095Untagged (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..255Unlabeled (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..3ttl 64, dscp 0, ecn 0Sets 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..8191ipid 1, flags 0, fragoffset 0Sets 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)0Sets 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..65535srcport 49152 (remembered), TCP 443Overrides source or destination port and remembers the port pair automatically on <- replies.
seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rstTCP sequence/ack numbers, window size, flags & RFC 7323 optionspsh ack, win 65535, automatic TCP seq/acknumOverrides 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

Valid v3.1.2 Syntax
tls clienthello sni "app.local" ciphersuite 0x1301

Per 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

Avoid
a -> b tls client_hello cipher_suite 0x1301
Valid v3.1.2 Syntax
a -> b tls clienthello ciphersuite 0x1301

Write clienthello, serverhello, appdata, recordversion, handshakeversion, and ciphersuite as single lowercase words.

Field Guide 03
Poke Stateful Firewalls, Suricata, Zeek & OT Conduits