Studying the STUN protocol
Giacomo Vacca, @giavac
STUN: Session Traversal Utilities for NAT
RFC 5389 (8489)
"[STUN] can be used by an endpoint to determine the IP address and port allocated
to it by a NAT. It can also be used to check connectivity between two endpoints, and
as a keep-alive protocol to maintain NAT bindings."
Combination with other protocols:
- Connectivity checks: ICE (RFC 8845)
- Relay: TURN (RFC 5766, 8656) 2
- Extensible packet format
- Several transport protocols
- Two forms of authentication
A “usage” deﬁnes:
- When STUN messages get sent
- Optional Attributes to include
- What server is used
- The authentication mechanism
ICE (RFC 8445), SIP OUTBOUND (RFC 5626) and NAT Behaviour Discovery (RFC
5780) are all “STUN usages” and are “complete NAT traversal solutions”.
A STUN extension may deﬁne new methods, attributes or response codes. 4
STUN is a client-server protocol.
STUN deﬁnes 2 types of transactions:
Request/Response: client sends a
request, server sends a response.
Indication: either client or server sends
an indication, without the need for a
A 96-bit transaction ID is required.
All STUN messages start with a ﬁxed header with:
- Method (e.g. Binding)
- Class (Request, Success Response, Error Response or Indication)
- Transaction ID (96-bit number)
After the header there are zero or more Attributes (in the form of
Type-Length-Value). Attributes can be required (“comprehension-required”) or
Attributes are always padded to a multiple of 4 Bytes. Optional: FINGERPRINT 6
Binary, network order, big endian.
20 Bytes header + 0 or more Attributes.
The header contains:
- Message Type (16 bits)
- Message Length (16 bits)
- Magic Cookie (32 bits)
- Transaction ID (96 bits)
Message Type: First 2 most signiﬁcant
bits: 00, Class (Request, Success
Response, Error Response, Indication),
The Magic Cookie
0010 0001 0001 0010 1010 0100 0100 0010
It’s used to further distinguish a STUN packet from other types, and to XOR the transport addresses.
A Transport Address is the combination of an IP address and port, e.g. 172.17.0.3:44567
Reﬂexive Transport Address: A Transport Address learned by a STUN client, identifying that client as
seen by another host or network, typically a STUN server. e.g. “What’s my public IP and port?”
Provided in MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attributes in STUN responses.
STUN Binding method 1/2
Used in Request/Response transactions: to determine what binding a STUN
server has allocated for the client, and keep the binding alive.
Used in Indication transactions: to keep the binding alive.
In Request/Response transactions, a STUN client sends a “Binding Request” to
the STUN server. The STUN server replies with a “Binding Success Response”,
containing an attribute called XOR-MAPPED-ADDRESS, which value is the XOR’d
source transport address, as seen by the STUN server. In this way the STUN
client learns its Reﬂexive Transport Address allocated by the outermost NAT. 10
STUN mechanisms (optional procedures)
- DNS discovery
- Redirection to an alternate server
- A ﬁngerprint attribute for demultiplexing
- 2 authentication and message integrity exchanges (username, password,
- long-term credentials (pre-provisioned credentials)
- short-term credentials (out-of-band method before STUN exchange,
credentials expire quickly; e.g. ICE)
Authentication and message integrity
- long-term credentials (pre-provisioned credentials with digest authentication)
- Server replies with ERROR-CODE 401, REALM and NONCE (for replay protection)
- Client sends request again, with USERNAME, REALM, NONCE and the computed
- Indications cannot be challenged so cannot use this method
- short-term credentials (out-of-band method before STUN, credentials expire; e.g. ICE)
- Authentication requires USERNAME and MESSAGE-INTEGRITY Attributes.
- Responses contain the MESSAGE-INTEGRITY Attribute.
Errors: 401 (unauthorized, failed authentication), 400 (bad request, missing attributes), 438 (stale nonce)
STUN Messages can be multiplexed with other protocols, e.g. with RTP.
Sending Requests or Indications over UDP
Requests can be retransmitted until a Response is received. Exponential backoff
with RTO (Retransmission TimeOut)
Indications are not retransmitted and so are not reliable.
Sending Requests or Indications over TCP or
The STUN client opens a TCP connection to the STUN server.
- Minimum TLS_RSA_WITH_AES_128_CBC_SHA ciphersuite
- The client SHOULD verify the server certiﬁcate
- The client MUST verify the server identity
The STUN server should not close TCP connections (nor open connections
towards the client).
Sending Responses (Success or Error)
The Method is the same as the Request. Class is either “Success Response” or “Error Response”.
For Success Response to Binding method:
- The server adds a XOR-MAPPED-ADDRESS Attribute with source Transport Address.
For Error Response:
- The server adds an ERROR-CODE Attribute.
- Add the authentication Attributes if applicable (e.g. error 401)
- Add other applicable Attributes (e.g. UNKNOWN-ATTRIBUTES for error 420)
SRV records: the service type is stun (stuns for TLS-over-TCP)
Default port for UDP and TCP: 3478
Default port for TLS: 5349
No SRV record: perform A or AAAA lookup.
Used to redirect STUN clients to another STUN server.
ERROR-CODE is 300
ALTERNATE-SERVER Attribute present in response
A STUN message can have 0 or more Attributes, after the header. Attributes can
appear more than once inside a message
Each Attribute is a Type-Length-Value structure.
Type: 16 bits - 0x0000 to 0x7FFF are comprehension-required, 0x8000 to 0xFFFF
Length: 16 bits
Value: variable, padded to multiple of 32 bits. 20
A reﬂexive transport address of the client.
First 8 bits set to 0
Address family: 8 bits (0x01: IPv4, 0x02: IPv6)
Port: 16 bits
IP address: 32 bits if IPv4, 128 bits if IPv6
Network byte order
Same as MAPPED-ADDRESS, but the reﬂexive transport address is obfuscated
through the XOR function (with the Magic Cookie).
X-Port is the Port XOR’d with the 16 most signiﬁcant bits of the Magic Cookie.
- IPv4: XOR’d Address with Magic Cookie (32 bits)
- IPv6: XOR-d Address with Magic Cookie (32 bits) + Transaction ID (96 bits)
HMAC-SHA1 of the STUN message
For long-term credentials: key = MD5(username ":" realm ":" SASLprep(password))
For short-term credentials: key = SASLprep(password)
CRC-32 of the STUN message (excluding the FINGERPRINT Attribute itself),
XOR’d with 0x5354554E.
When present must be the last Attribute, so also after MESSAGE-INTEGRITY.
This means FINGERPRINT depends on MESSAGE-INTEGRITY value.
1. Attacks against the protocol
- Outside attacks
- Inside attacks
2. Attacks affecting the usage
- DDoS against a Target
- Silencing a Client
- Assuming the identity of a
3. Hash agility plan
- In case HMAC-SHA1
Attacks against the protocol
Outside attacks: an attacker modiﬁes a message in transit. These are detected
through the message-integrity mechanism. Such packets must be dropped.
Subject to oﬄine dictionary attacks: use TLS or strong passwords.
Inside attacks: DDoS attack from a malicious client to a STUN server. False
source address to generate traﬃc (responses) to a victim: apply ingress source
Revealing software versions in SOFTWARE attribute: make it optional.
Attacks affecting the usage
DDoS against a Target: The attacker provides one or more clients with a faked reﬂexive address that
points to the target. Only possible if the packets from the server pass through the attacker.
Silencing a Client: The attacker provides a client with a faked reﬂexive address that points nowhere, so
the target can’t receive.
Assuming the identity of a Client: As in “Silencing a Client”, but the faked reﬂexive address points to the
Eavesdropping: The attacker forces the client to use a reﬂexive address that routes to the attacker itself,
then the attacker forwards any client it receives to the client. The attacker sees all the packets received
by the target.
https://tools.ietf.org/html/rfc5389, “Session Traversal Utilities for NAT”