Protocol 60 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
stunSession Traversal Utilities for NAT

WebRTC NAT Hole-Punching & 0x2112a442 Magic Cookies (stun UDP 3478)

Default Port / Protocol
UDP 3478
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
stun
Standards & Specs
RFC 5389
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6UDP 3478STUN (NAT)

What It Does on the Wire

Pass xormappedaddr 203.0.113.42 on stun bindingresponse and the compiler genuinely XORs your IPv4 or IPv6 address against magic cookie 0x2112a442 (+ transaction ID on IPv6) so Wireshark decodes the reflexive NAT address cleanly!

Session Traversal Utilities for NAT (stun, RFC 5389) lets WebRTC browsers, Zoom/Teams clients, VoIP phones, and peer-to-peer VPNs (Tailscale/WireGuard) discover their public reflexive IP and port via UDP port 3478 (or 19302). Every RFC 5389 STUN header carries the 2-byte Message Type, 2-byte Message Length, 4-byte Magic Cookie 0x2112a442, and 96-bit Transaction ID.

On bindingresponse, RFC 5389 requires the XOR-MAPPED-ADDRESS attribute (0x0020) to be XOR-masked against 0x2112a442 (for IPv4) or 0x2112a442 || transaction_id (for IPv6) so legacy NAT routers cannot corrupt the payload. FrameAssembly computes that XOR masking automatically so Wireshark displays your exact xormappedaddr IP cleanly.

Corporate WebRTC / Conferencing Firewall Egress Checks

Test UDP 3478 and dstport 19302 rules to verify whether enterprise firewalls allow direct WebRTC ICE/STUN NAT discovery or force TURN TCP relays.

Verify NAT ALG Non-Interference on XOR-MAPPED-ADDRESS

Generate bindingrequest and bindingresponse pairs carrying public xormappedaddr IPv4 or IPv6 addresses.

Peer-to-Peer Overlay & Unauthorized Tunneling Detection

Test NDR signatures matching software attributes or high-frequency STUN Binding probes from restricted server subnets.

Minimal Quickstart (stun_quickstart.frasm)

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

stun_quickstart.frasm7 lines
Open in Playground
host webrtc_tab { ip 10.10.20.45 }
host stun_srv { ip 198.51.100.34 }
compile {
webrtc_tab -> stun_srv stun bindingrequest txid 0x10203040 software "webrtc-client" wait 3ms
webrtc_tab <- stun_srv stun bindingresponse txid 0x10203040 xormappedaddr 203.0.113.88
}

What the Compiler Calculates So You Don't Have To

  • Defaults to UDP destination port 3478 and writes the mandatory RFC 5389 magic cookie 0x2112a442 in bytes 4..7.
  • XOR-encodes IPv4 (32-bit ^ 0x2112a442) and IPv6 (128-bit ^ (0x2112a442 || txid)) xormappedaddr attributes (0x0020) automatically.
  • Pads software (0x8022) TLV strings to 4-byte boundaries as required by RFC 5389 §15.
Multi-Frame Lab · Ready to Compile

Dual-Stack IPv4 & IPv6 WebRTC ICE STUN Discovery + Error Response

Performs an IPv4 STUN check on port 19302, an IPv6 STUN check on port 3478, and a bindingerror (0x0111) test.

stun_webrtc_ice.frasm14 lines
Open in Playground
host client_v4 { ip 172.16.10.25 }
host stun_v4 { ip 198.51.100.10 }
host client_v6 { ip 2001:db8:10::25 }
host stun_v6 { ip 2001:db8:99::3478 }
compile {
// 1. WebRTC UDP 19302 STUN check returning NAT public IPv4 203.0.113.50
client_v4 -> stun_v4 stun bindingrequest dstport 19302 txid 0xa1b2c3d4 software "Chromium-ICE" wait 2ms
client_v4 <- stun_v4 stun bindingresponse txid 0xa1b2c3d4 xormappedaddr 203.0.113.50 software "coturn-4.6" wait 4ms
// 2. IPv6 STUN Binding check + Error response
client_v6 -> stun_v6 stun bindingrequest txid 0x55667788 wait 2ms
client_v6 <- stun_v6 stun bindingresponse txid 0x55667788 xormappedaddr 2001:db8:10::25 wait 3ms
client_v4 <- stun_v4 stun bindingerror txid 0x99990000
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show stun_webrtc_ice.frasm

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

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

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

src_host -> dst_host stun [bindingrequest | bindingresponse | bindingerror] [txid <hex_or_num>] [xormappedaddr <ip>] [software "<text>"]
Keyword / OptionAccepted ValueDefaultEffect on Packet
bindingrequest | bindingresponse | bindingerrorSTUN message class/methodbindingrequest (0x0001)Selects STUN Binding Request (0x0001), Binding Success Response (0x0101), or Binding Error Response (0x0111).
txid <hex_or_num>32-bit Transaction ID seed (placed into the 96-bit STUN Transaction ID)0x12345678Matches STUN responses to their initiating request.
xormappedaddr <ip>IPv4 or IPv6 public/reflexive IP addressClient IP on bindingresponseAdds Attribute 0x0020 (XOR-MAPPED-ADDRESS) with RFC 5389 XOR obfuscation applied.
software "<text>"Quoted agent/server stringOmitted unless setAdds 4-byte-padded Attribute 0x8022 (SOFTWARE).

Cross-Layer Wrappers Valid with stun

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

10 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).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), UDP 3478Overrides source or destination port and remembers the port pair automatically on <- replies.

Gotchas & Quick Fixes

No Hyphens or Underscores in xormappedaddr or bindingrequest

Avoid
webrtc_tab <- stun_srv stun binding_response xor_mapped_addr 203.0.113.88
Valid v3.1.2 Syntax
webrtc_tab <- stun_srv stun bindingresponse xormappedaddr 203.0.113.88

Spell STUN keywords in strict lowercase without underscores: bindingrequest, bindingresponse, bindingerror, and xormappedaddr.

Field Guide 03
Poke Stateful Firewalls, Suricata, Zeek & OT Conduits