tcpTransmission Control Protocol & RFC 7323 OptionsStateful 3-Way Handshakes, RFC 7323 Options & Intentional Chaos (tcp)
What It Does on the Wire
The crown jewel of the compiler: declare srcport and dstport once on tcp syn, and FrameAssembly tracks seq and acknum across ->, <-, and every TCP Layer 7 protocol (unless you override seq to inject chaos on purpose).
Transmission Control Protocol (tcp, IP protocol 6, RFC 9293) is the connection-oriented Layer 4 transport powering HTTP, TLS, BGP, SSH, databases, and industrial protocols. FrameAssembly includes a built-in stateful 4-tuple TCP sequence tracker shared automatically across raw tcp frames and every TCP-carried Layer 7 protocol.
Once you open a connection with srcport and dstport on tcp syn, subsequent <- and -> statements inherit the reversed port pair, advance seq and acknum by +1 on syn/fin and +payload.len() on data segments, pad RFC 7323 options (mss, wscale, sackperm, tsval, tsecr) to 32-bit boundaries with NOP/EOL bytes, and compute the exact IPv4 or IPv6 pseudo-header checksum.
Stateful Firewall & SYN-Cookie / Window-Scale Inspection
Test NGFW state tables, asymmetric routing drops, TCP timestamp PAWS checks, and RFC 7323 window scaling (wscale 7, sackperm, mss 1460) in Wireshark.
IDS/NDR Retransmission, Out-of-Order & RST Injection Testing
Override seq and acknum explicitly on targeted segments to model overlapping TCP segments, blind rst teardown, or urg/ece/cwr flag edge cases for Suricata and Zeek.
Pre-Handshake Setup Before L7 Application Protocols
Prepend a realistic 3-way tcp handshake ahead of http, tls, bgp, smb, mysql, or modbus frames—the L7 frames automatically continue the exact TCP sequence numbers.
Minimal Quickstart (tcp_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host client { ip 10.10.1.15 }host server { ip 10.10.1.80 }compile { client -> server tcp syn srcport 52400 dstport 443 win 65535 mss 1460 wscale 7 sackperm wait 1ms client <- server tcp syn ack win 65535 mss 1460 wscale 7 sackperm wait 1ms client -> server tcp ack}What the Compiler Calculates So You Don't Have To
- Tracks 4-tuple
(src_ip, dst_ip, src_port, dst_port)sequence state starting atseq 1000—advancingseqby+1forsyn/finand+payload_lenfor data without manual arithmetic. - Remembers
srcport 52400anddstport 443from the openingsynso<-and->follow-up frames swap443 <-> 52400automatically. - Aligns variable-length TCP options (
mss4B,sackperm2B,tsval/tsecr10B,wscale3B) to 4-byte multiples with RFC 9293NOP(0x01) padding and updates Data Offset.
Full Lifecycle: RFC 7323 Handshake, ECN-Capable Data Exchange & Graceful FIN Close
Captures a complete 7-packet TCP lifecycle with RFC 7323 timestamps (tsval/tsecr), selective ACK permission (sackperm), payload push (psh ack), and 4-way fin ack teardown.
host app_client { ip 172.16.20.10 }host api_origin { ip 172.16.20.90 }compile { // 1. 3-way handshake negotiating MSS 1460, Window Scale 7, SACK, and Timestamps app_client -> api_origin tcp syn srcport 54110 dstport 8443 win 65535 mss 1460 wscale 7 sackperm tsval 1000 tsecr 0 wait 1ms app_client <- api_origin tcp syn ack win 65535 mss 1460 wscale 7 sackperm tsval 5000 tsecr 1000 wait 1ms app_client -> api_origin tcp ack tsval 1001 tsecr 5000 wait 2ms // 2. Bidirectional application payload (seq/acknum advance automatically by byte length) app_client -> api_origin tcp psh ack tsval 1003 tsecr 5000 payload "PING /healthz
" wait 2ms app_client <- api_origin tcp psh ack tsval 5002 tsecr 1003 payload "200 OK
" wait 3ms // 3. Clean 3-packet FIN/ACK session close app_client -> api_origin tcp fin ack tsval 1006 tsecr 5002 wait 1ms app_client <- api_origin tcp fin ack tsval 5003 tsecr 1007 wait 1ms app_client -> api_origin tcp ack tsval 1007 tsecr 5004}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show tcp_rfc7323_lifecycle.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly tcp_rfc7323_lifecycle.frasm tcp_rfc7323_lifecycle.pcap
frameassembly tcp_rfc7323_lifecycle.frasm tcp_rfc7323_lifecycle.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse tcp_rfc7323_lifecycle.pcap tcp_rfc7323_lifecycle_edited.frasmAll tcp 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 tcp:
src_host -> dst_host tcp [syn] [ack] [fin] [rst] [psh] [urg] [ece] [cwr] [srcport <0..65535>] [dstport <0..65535>] [seq <number>] [acknum <number>] [win|window <0..65535>] [urgent <0..65535>] [mss <0..65535>] [wscale <0..255>] [sackperm] [tsval <number>] [tsecr <number>]| Keyword / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| syn | ack | fin | rst | psh | urg | ece | cwr | Bare lowercase flag keywords (combinable) | ack (or psh ack when payload present) | Sets individual control bits in byte 13 of the 20-byte TCP header. |
| srcport <0..65535> | dstport <0..65535> | Whole number (0..65535) | srcport 49152, dstport 80 (or inherited) | Sets TCP source and destination ports and anchors bidirectional pair port memory. |
| seq <number> | acknum <number> | Whole number | Tracked 4-tuple state (initial seq 1000) | Explicitly overrides the 32-bit Sequence Number or Acknowledgment Number (acknum) and updates tracker state. |
| win <0..65535> | window <0..65535> | Whole number (0..65535) | 65535 | Sets the 16-bit Receive Window field (window is an exact alias for win). |
| urgent <0..65535> | Whole number (0..65535) | 0 | Sets the 16-bit Urgent Pointer field (pair with the urg flag). |
| mss <0..65535> | Whole number (0..65535) (bytes) | Omitted | Appends TCP Option Kind 2 (Maximum Segment Size, 4 bytes, e.g. 1460 IPv4 or 1440 IPv6). |
| wscale <0..255> | 8-bit shift count (RFC 7323 <= 14) | Omitted | Appends TCP Option Kind 3 (Window Scale, 3 bytes + 1-byte alignment NOP). |
| sackperm | Boolean flag keyword | Omitted | Appends TCP Option Kind 4 (SACK Permitted, 2 bytes) per RFC 2018. |
| tsval <number> [tsecr <number>] | Whole number | Omitted (tsecr 0 when only tsval set) | Appends TCP Option Kind 8 (RFC 7323 Timestamps, 10 bytes + 2-byte alignment NOPs). |
Cross-Layer Wrappers Valid with tcp
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
9 options
Cross-Layer Wrappers Valid with tcp
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). |
Gotchas & Quick Fixes
Use acknum <number> for the Acknowledgment Number (Bare ack Is the Flag)
client -> server tcp syn ack 1001 sport 50000 dport 443client -> server tcp syn ack acknum 1001 srcport 50000 dstport 443Bare ack sets the 1-bit ACK flag in the TCP header. Use acknum <number> to set the 32-bit Acknowledgment Number, and always spell out srcport / dstport.
Never Add Underscores to sackperm or TCP Flags
client -> server tcp flags [SYN] sack_permclient -> server tcp syn sackpermEvery FrameAssembly v3.1.2 built-in keyword is strictly lowercase alphanumeric (syn, ack, psh, sackperm, wscale, tsval, tsecr) without brackets or underscores.