Protocol 17 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
espIPsec Encapsulating Security Payload

Canonical IPsec ESP Headers & Reverse Scrubbing (esp Proto 50)

Default Port / Protocol
IP Proto 50
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
esp
Standards & Specs
RFC 4303
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6IPsec ESP (IP Proto 50)

What It Does on the Wire

esp is the canonical keyword emitted when frameassembly reverse decompiles IP Protocol 50 captures, making it trivial to scrub customer VPN gateway IPs before emailing a trace to vendor TAC.

Encapsulating Security Payload (esp, RFC 4303) provides confidentiality, data-origin authentication, connectionless integrity, and anti-replay protection over IP Protocol 50 (and IPv6 Extension / Next Header 50).

esp is the canonical protocol keyword emitted by frameassembly reverse whenever decompiling IP Protocol 50 packets from .pcap or .pcapng traces, and accepts the exact same modifiers (spi, seq, iv, icv, nextheader) as its ipsec alias.

Round-Trip PCAP Decompilation & Sanitization

Run frameassembly reverse vpn_capture.pcap to decompile live ESP sessions into esp spi ... seq ... lines, anonymize outer gateway IPs, and recompile for vendor TAC tickets.

Wireshark ESP SA Decryption Table Fixture Generation

Craft deterministic spi, iv, and icv test vectors over IPv4 and IPv6 to verify automated packet capture analysis pipelines.

QoS DiffServ Preservation Across Encrypted Tunnels

Combine esp with dscp 46 (EF) or dscp 34 (AF41) and vlan tags to verify WAN QoS queuing on encrypted VPN links.

Minimal Quickstart (esp_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

esp_quickstart.frasm6 lines
Open in Playground
host peer_a { ip 172.16.50.1 }
host peer_b { ip 172.16.50.2 }
compile {
peer_a -> peer_b esp spi 0xdead0001 seq 1 iv "0102030405060708"
}

What the Compiler Calculates So You Don't Have To

  • Emits IPv4 Protocol 50 or IPv6 Next Header 50 with computed outer IPv4 header checksum and exact payload length.
  • Aligns ciphertext + padding + 2-byte trailer (Pad Length, Next Header) cleanly to cipher block boundaries before appending the icv.
  • Round-trips cleanly through frameassembly reverse preserving spi and seq.
Multi-Frame Lab · Ready to Compile

Dual-Stack IPv4 & IPv6 ESP Security Associations With DiffServ QoS

Emits unidirectional outbound and inbound ESP Security Associations across both IPv4 and IPv6 WAN endpoints with preserved DiffServ markings.

esp_dualstack_vpn.frasm12 lines
Open in Playground
host hub_v4 { ip 198.51.100.1 }
host spoke_v4 { ip 203.0.113.50 }
host hub_v6 { ip 2001:db8:100::1 }
host spoke_v6 { ip 2001:db8:200::50 }
compile {
// IPv4 ESP tunnel (SPI 0x1010 -> 0x2020) with Expedited Forwarding (dscp 46)
spoke_v4 -> hub_v4 esp spi 0x00001010 seq 101 iv "1011121314151617" icv "a1a2a3a4a5a6a7a8a9aaabac" nextheader 4 dscp 46 df wait 1ms
spoke_v4 <- hub_v4 esp spi 0x00002020 seq 88 iv "2021222324252627" icv "b1b2b3b4b5b6b7b8b9babbbc" nextheader 4 dscp 46 df wait 3ms
// IPv6 ESP tunnel (Next Header 50, inner Next Header 41 = IPv6-in-IPv6)
spoke_v6 -> hub_v6 esp spi 0x00061010 seq 1 iv "3031323334353637" icv "c1c2c3c4c5c6c7c8c9cacbcc" nextheader 41 flowlabel 0x50001
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show esp_dualstack_vpn.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly esp_dualstack_vpn.frasm esp_dualstack_vpn.pcap
frameassembly esp_dualstack_vpn.frasm esp_dualstack_vpn.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse esp_dualstack_vpn.pcap esp_dualstack_vpn_edited.frasm

All esp 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 esp:

src_host -> dst_host esp [spi <number>] [seq <number>] [iv "<hex>"] [icv "<hex>"] [nextheader <0..255>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
spi <number>Whole number (decimal or 0x hex)0x00000100Sets the 4-byte ESP Security Parameters Index (0..255 reserved by IANA; >= 256 assigned by IKE).
seq <number>Whole number1Sets the 4-byte ESP Sequence Number field.
iv "<hex>"Double-quoted even-length hex string8-byte IVSets the explicit Initialization Vector bytes (8B AES-GCM/CBC or 16B AES-CBC).
icv "<hex>"Double-quoted even-length hex string12-byte ICVAppends the Integrity Check Value trailer (12B HMAC-SHA1-96 / 16B AES-GCM-128).
nextheader <0..255>8-bit IP protocol number4 (IPv4)Sets the inner protocol number inside the encrypted ESP trailer.

Cross-Layer Wrappers Valid with esp

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

9 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).

Gotchas & Quick Fixes

NAT-Traversal ESP-in-UDP vs Native Protocol 50

Valid v3.1.2 Syntax
spoke -> hub esp spi 0x1010 seq 1 // Native IP Protocol 50

esp emits native IP Protocol 50 (not UDP 4500 NAT-T encapsulation). To simulate UDP 4500 NAT-T packets, use ikev2 srcport 4500 dstport 4500 or udp srcport 4500 dstport 4500 hexpayload "...".

Even-Length Hex Octets in iv and icv

Avoid
spoke -> hub esp iv "abc"
Valid v3.1.2 Syntax
spoke -> hub esp iv "0a0b0c0d0e0f1011"

Hex byte literals must contain an even number of hexadecimal digits (0-9, a-f, A-F) representing complete 8-bit octets.

Field Guide 05
VLANs, QinQ, MPLS, Tunnel Soup & Dual-Stack IPv6