espIPsec Encapsulating Security PayloadCanonical IPsec ESP Headers & Reverse Scrubbing (esp 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.
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
50or IPv6 Next Header50with 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 theicv. - Round-trips cleanly through
frameassembly reversepreservingspiandseq.
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.
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}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| spi <number> | Whole number (decimal or 0x hex) | 0x00000100 | Sets the 4-byte ESP Security Parameters Index (0..255 reserved by IANA; >= 256 assigned by IKE). |
| seq <number> | Whole number | 1 | Sets the 4-byte ESP Sequence Number field. |
| iv "<hex>" | Double-quoted even-length hex string | 8-byte IV | Sets the explicit Initialization Vector bytes (8B AES-GCM/CBC or 16B AES-CBC). |
| icv "<hex>" | Double-quoted even-length hex string | 12-byte ICV | Appends the Integrity Check Value trailer (12B HMAC-SHA1-96 / 16B AES-GCM-128). |
| nextheader <0..255> | 8-bit IP protocol number | 4 (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
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
| 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
NAT-Traversal ESP-in-UDP vs Native Protocol 50
spoke -> hub esp spi 0x1010 seq 1 // Native IP Protocol 50esp 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
spoke -> hub esp iv "abc"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.