stunSession Traversal Utilities for NATWebRTC NAT Hole-Punching & 0x2112a442 Magic Cookies (stun UDP 3478)
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.
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
3478and writes the mandatory RFC 5389 magic cookie0x2112a442in bytes 4..7. - XOR-encodes IPv4 (
32-bit ^ 0x2112a442) and IPv6 (128-bit ^ (0x2112a442 || txid))xormappedaddrattributes (0x0020) automatically. - Pads
software(0x8022) TLV strings to 4-byte boundaries as required by RFC 5389 §15.
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.
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}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| bindingrequest | bindingresponse | bindingerror | STUN message class/method | bindingrequest (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) | 0x12345678 | Matches STUN responses to their initiating request. |
| xormappedaddr <ip> | IPv4 or IPv6 public/reflexive IP address | Client IP on bindingresponse | Adds Attribute 0x0020 (XOR-MAPPED-ADDRESS) with RFC 5389 XOR obfuscation applied. |
| software "<text>" | Quoted agent/server string | Omitted unless set | Adds 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
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
| 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). |
| srcport <0..65535> | dstport <0..65535> | Port number 0..65535 | srcport 49152 (remembered), UDP 3478 | Overrides source or destination port and remembers the port pair automatically on <- replies. |
Gotchas & Quick Fixes
No Hyphens or Underscores in xormappedaddr or bindingrequest
webrtc_tab <- stun_srv stun binding_response xor_mapped_addr 203.0.113.88webrtc_tab <- stun_srv stun bindingresponse xormappedaddr 203.0.113.88Spell STUN keywords in strict lowercase without underscores: bindingrequest, bindingresponse, bindingerror, and xormappedaddr.