ipsecIPsec Encapsulating Security Payload (Protocol Alias)Encrypted VPN Tunnel Frames (gw1 <-> gw2 ipsec / Proto 50)
What It Does on the Wire
Edge firewalls love dropping IP Protocol 50 when someone only opened UDP 500. ipsec emits clean ESP headers (spi, seq, iv, icv) so you can prove whether the tunnel pipe is open.
The ipsec keyword in FrameAssembly v3.1.2 is a convenient ergonomic alias for esp (RFC 4303 Encapsulating Security Payload, IP Protocol 50). Both ipsec and esp share the exact same underlying IpsecSpec wire builder: 32-bit Security Parameters Index (spi), 32-bit monotonically increasing Sequence Number (seq), Initialization Vector (iv), padded payload + trailer (Pad Length + nextheader), and Integrity Check Value (icv).
Note that when decompiling existing .pcap files containing IP Protocol 50, frameassembly reverse canonically emits the explicit esp keyword, while both ipsec and esp compile to byte-identical wire packets.
Site-to-Site VPN Firewall & ACL Validation
Verify perimeter firewalls pass IP Protocol 50 (ipsec/esp) alongside UDP 500/4500 (ikev2) between VPN concentrators.
Anti-Replay Window & SPI Demultiplexing Tests
Craft sequential, duplicate, or out-of-window seq numbers under a specific spi to validate IPsec anti-replay counters.
Dual-Stack IPv6 OSPFv3 / IPsec Transport Verification
Emit IPv6 Next Header 50 frames with explicit iv and icv hex octets for router control-plane authentication labs.
Minimal Quickstart (ipsec_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host vpn_branch { ip 198.51.100.10 }host vpn_hq { ip 203.0.113.20 }compile { vpn_branch -> vpn_hq ipsec spi 0x00001001 seq 1}What the Compiler Calculates So You Don't Have To
- Sets outer IPv4 Protocol or IPv6 Next Header to
50(ESP). - Encodes the 4-byte
spi(default0x00000100), 4-byte ESPseq(default1), 8-byteiv, block-aligned ciphertext + 2-byte ESP trailer (Pad Length+nextheader), and 12-byteicvauthentication tag. - Parses
ivandicvhex strings cleanly whether formatted continuously ("0102030405060708"), colon-separated, or space-separated.
IKEv2 Tunnel Bring-Up Followed by Bidirectional IPsec Data Frames
Pairs an ikev2 SA_INIT + IKE_AUTH negotiation on UDP 500 with encrypted ipsec tunnel-mode (nextheader 4) data packets in both directions.
host gw_west { ip 198.51.100.10 }host gw_east { ip 203.0.113.20 }compile { // 1. IKEv2 SA_INIT and IKE_AUTH key exchange on UDP 500 gw_west -> gw_east ikev2 sainit initiatorspi 0xa1b2c3d4e5f60708 msgid 0 nextheader 33 wait 3ms gw_west <- gw_east ikev2 sainit initiatorspi 0xa1b2c3d4e5f60708 responderspi 0x1122334455667788 flags 0x20 wait 3ms gw_west -> gw_east ikev2 auth initiatorspi 0xa1b2c3d4e5f60708 responderspi 0x1122334455667788 msgid 1 nextheader 46 wait 4ms // 2. Bidirectional IPsec ESP tunnel frames (outbound SPI 0x1001, inbound SPI 0x2002) gw_west -> gw_east ipsec spi 0x00001001 seq 1 iv "0102030405060708" icv "aabbccddeeff001122334455" nextheader 4 wait 1ms gw_west -> gw_east ipsec spi 0x00001001 seq 2 iv "090a0b0c0d0e0f10" icv "112233445566778899aabbcc" nextheader 4 wait 2ms gw_west <- gw_east ipsec spi 0x00002002 seq 1 iv "f1f2f3f4f5f6f7f8" icv "99887766554433221100ffaa" nextheader 4}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show ipsec_site_to_site.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly ipsec_site_to_site.frasm ipsec_site_to_site.pcap
frameassembly ipsec_site_to_site.frasm ipsec_site_to_site.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse ipsec_site_to_site.pcap ipsec_site_to_site_edited.frasmAll ipsec 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 ipsec:
src_host -> dst_host ipsec [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 Security Parameters Index identifying the unidirectional IPsec Security Association. |
| seq <number> | Whole number | 1 | Sets the 4-byte RFC 4303 ESP anti-replay Sequence Number (contextual to IPsec rather than TCP). |
| iv "<hex>" | Double-quoted even-length hex octets | 8-byte deterministic IV | Writes the explicit Initialization Vector octets immediately after spi + seq. |
| icv "<hex>" | Double-quoted even-length hex octets | 12-byte (96-bit) authenticator | Appends the trailing Integrity Check Value authentication tag. |
| nextheader <0..255> | 8-bit IP protocol number | 4 (IPv4-in-IP tunnel mode) | Sets the ESP trailer Next Header byte (4 IPv4-in-IP, 41 IPv6-in-IP, 6 TCP transport mode). |
Cross-Layer Wrappers Valid with ipsec
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 ipsec
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
ipsec vs esp vs ah Keyword Selection
gw_a -> gw_b esp spi 0x1001 seq 1 // or ah spi 0x2001 seq 1ipsec and esp both emit IP Protocol 50 (ESP). If you need IP Protocol 51 (RFC 4302 Authentication Header without encryption), use the ah keyword.
Hex Strings Must Be Double-Quoted
gw_a -> gw_b ipsec iv 0102030405060708gw_a -> gw_b ipsec iv "0102030405060708"Pass iv and icv byte arrays as double-quoted hex strings ("0102030405060708" or "01:02:03:04:05:06:07:08").