Protocol 16 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
ipsecIPsec Encapsulating Security Payload (Protocol Alias)

Encrypted VPN Tunnel Frames (gw1 <-> gw2 ipsec / Proto 50)

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

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.

ipsec_quickstart.frasm6 lines
Open in 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 (default 0x00000100), 4-byte ESP seq (default 1), 8-byte iv, block-aligned ciphertext + 2-byte ESP trailer (Pad Length + nextheader), and 12-byte icv authentication tag.
  • Parses iv and icv hex strings cleanly whether formatted continuously ("0102030405060708"), colon-separated, or space-separated.
Multi-Frame Lab · Ready to Compile

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.

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

All 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 / OptionAccepted ValueDefaultEffect on Packet
spi <number>Whole number (decimal or 0x hex)0x00000100Sets the 4-byte Security Parameters Index identifying the unidirectional IPsec Security Association.
seq <number>Whole number1Sets the 4-byte RFC 4303 ESP anti-replay Sequence Number (contextual to IPsec rather than TCP).
iv "<hex>"Double-quoted even-length hex octets8-byte deterministic IVWrites the explicit Initialization Vector octets immediately after spi + seq.
icv "<hex>"Double-quoted even-length hex octets12-byte (96-bit) authenticatorAppends the trailing Integrity Check Value authentication tag.
nextheader <0..255>8-bit IP protocol number4 (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
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

ipsec vs esp vs ah Keyword Selection

Valid v3.1.2 Syntax
gw_a -> gw_b esp spi 0x1001 seq 1 // or ah spi 0x2001 seq 1

ipsec 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

Avoid
gw_a -> gw_b ipsec iv 0102030405060708
Valid v3.1.2 Syntax
gw_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").

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