draft-ietf-behave-rfc3489bis-06.txt   draft-ietf-behave-rfc3489bis-07.txt 
BEHAVE J. Rosenberg BEHAVE Working Group J. Rosenberg
Internet-Draft Cisco Internet-Draft Cisco
Obsoletes: 3489 (if approved) C. Huitema Obsoletes: 3489 (if approved) C. Huitema
Intended status: Standards Track Microsoft Intended status: Standards Track Microsoft
Expires: September 6, 2007 R. Mahy Expires: January 9, 2008 R. Mahy
Plantronics Plantronics
P. Matthews
Avaya
D. Wing D. Wing
Cisco Systems Cisco
March 5, 2007 July 8, 2007
Session Traversal Utilities for (NAT) (STUN) Session Traversal Utilities for (NAT) (STUN)
draft-ietf-behave-rfc3489bis-06 draft-ietf-behave-rfc3489bis-07
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 39 skipping to change at page 1, line 41
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 6, 2007. This Internet-Draft will expire on January 9, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
Abstract Abstract
Session Traversal Utilities for NAT (STUN) is a lightweight protocol Session Traversal Utilities for NAT (STUN) is a protocol that serves
that serves as a tool for application protocols in dealing with NAT as a tool for other protocols in dealing with NAT traversal. It can
traversal. It allows a client to determine the IP address and port be used by an endpoint to determine the IP address and port allocated
allocated to them by a NAT and to keep NAT bindings open. It can to it by a NAT. It can also be used to check connectivity between
also serve as a check for connectivity between a client and a server two endpoints, and as a keep-alive protocol to maintain NAT bindings.
in the presence of NAT, and for the client to detect failure of the STUN works with many existing NATs, and does not require any special
server. STUN works with many existing NATs, and does not require any behavior from them.
special behavior from them. As a result, it allows a wide variety of
applications to work through existing NAT infrastructure. STUN is not a NAT traversal solution by itself. Rather, it is a tool
to be used in the context of a NAT traversal solution. This is an
important change from the previous version of this specification (RFC
3489), which presented STUN as a complete solution.
This document obsoletes RFC 3489.
Table of Contents Table of Contents
1. Applicability Statement . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Evolution from RFC 3489 . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Overview of Operation . . . . . . . . . . . . . . . . . . . . 5
4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Overview of Operation . . . . . . . . . . . . . . . . . . . . 7 5. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. STUN Message Structure . . . . . . . . . . . . . . . . . . . . 11 6. STUN Message Structure . . . . . . . . . . . . . . . . . . . . 10
7. STUN Transactions . . . . . . . . . . . . . . . . . . . . . . 14 7. Base Protocol Procedures . . . . . . . . . . . . . . . . . . . 12
7.1. Request/Response Transactions . . . . . . . . . . . . . . 14 7.1. Forming a Request or an Indication . . . . . . . . . . . 12
7.2. Indications . . . . . . . . . . . . . . . . . . . . . . . 15 7.2. Sending the Request or Indication . . . . . . . . . . . . 13
8. Client Behavior . . . . . . . . . . . . . . . . . . . . . . . 15 7.2.1. Sending over UDP . . . . . . . . . . . . . . . . . . . 13
8.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 15 7.2.2. Sending over TCP or TLS-over-TCP . . . . . . . . . . . 14
8.2. Obtaining a Shared Secret . . . . . . . . . . . . . . . . 16 7.3. Receiving a STUN Message . . . . . . . . . . . . . . . . 15
8.3. Request/Response Transactions . . . . . . . . . . . . . . 17 7.3.1. Processing a Request . . . . . . . . . . . . . . . . . 16
8.3.1. Formulating the Request Message . . . . . . . . . . . 17 7.3.1.1. Forming a Success or Error Response . . . . . . . 17
8.3.2. Processing Responses . . . . . . . . . . . . . . . . . 19 7.3.1.2. Sending the Success or Error Response . . . . . . 17
8.3.3. Timeouts . . . . . . . . . . . . . . . . . . . . . . . 22 7.3.2. Processing an Indication . . . . . . . . . . . . . . . 18
8.4. Indication Transactions . . . . . . . . . . . . . . . . . 22 7.3.3. Processing a Success Response . . . . . . . . . . . . 18
9. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 23 7.3.4. Processing an Error Response . . . . . . . . . . . . . 18
9.1. Request/Response Transactions . . . . . . . . . . . . . . 23 8. FINGERPRINT Mechanism . . . . . . . . . . . . . . . . . . . . 19
9.1.1. Receive Request Message . . . . . . . . . . . . . . . 23 9. DNS Discovery of a Server . . . . . . . . . . . . . . . . . . 19
9.1.2. Constructing the Response . . . . . . . . . . . . . . 26 10. Authentication and Message-Integrity Mechanisms . . . . . . . 20
9.1.3. Sending the Response . . . . . . . . . . . . . . . . . 27 10.1. Short-Term Credential Mechanism . . . . . . . . . . . . . 21
9.2. Indication Transactions . . . . . . . . . . . . . . . . . 27 10.1.1. Forming a Request or Indication . . . . . . . . . . . 21
10. Demultiplexing of STUN and Application Traffic . . . . . . . . 28 10.1.2. Receiving a Request or Indication . . . . . . . . . . 21
11. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 29 10.1.3. Receiving a Response . . . . . . . . . . . . . . . . . 22
11.1. MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . . . 29 10.2. Long-term Credential Mechanism . . . . . . . . . . . . . 23
11.2. USERNAME . . . . . . . . . . . . . . . . . . . . . . . . 30 10.2.1. Forming a Request . . . . . . . . . . . . . . . . . . 24
11.3. PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . 31 10.2.1.1. First Request . . . . . . . . . . . . . . . . . . 24
11.4. MESSAGE-INTEGRITY . . . . . . . . . . . . . . . . . . . . 31 10.2.1.2. Subsequent Requests . . . . . . . . . . . . . . . 24
11.5. FINGERPRINT . . . . . . . . . . . . . . . . . . . . . . . 31 10.2.2. Receiving a Request . . . . . . . . . . . . . . . . . 24
11.6. ERROR-CODE . . . . . . . . . . . . . . . . . . . . . . . 31 10.2.3. Receiving a Response . . . . . . . . . . . . . . . . . 25
11.7. REALM . . . . . . . . . . . . . . . . . . . . . . . . . . 33 11. ALTERNATE-SERVER Mechanism . . . . . . . . . . . . . . . . . . 26
11.8. NONCE . . . . . . . . . . . . . . . . . . . . . . . . . . 33 12. Backwards Compatibility with RFC 3489 . . . . . . . . . . . . 26
11.9. UNKNOWN-ATTRIBUTES . . . . . . . . . . . . . . . . . . . 33 12.1. Changes to Client Processing . . . . . . . . . . . . . . 27
11.10. XOR-MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . 34 12.2. Changes to Server Processing . . . . . . . . . . . . . . 27
11.11. SERVER . . . . . . . . . . . . . . . . . . . . . . . . . 35 13. STUN Usages . . . . . . . . . . . . . . . . . . . . . . . . . 28
11.12. ALTERNATE-SERVER . . . . . . . . . . . . . . . . . . . . 35 14. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 29
11.13. REFRESH-INTERVAL . . . . . . . . . . . . . . . . . . . . 35 14.1. MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . . . 30
12. STUN Usages . . . . . . . . . . . . . . . . . . . . . . . . . 36 14.2. XOR-MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . 31
12.1. Binding Discovery . . . . . . . . . . . . . . . . . . . . 36 14.3. USERNAME . . . . . . . . . . . . . . . . . . . . . . . . 32
12.1.1. Applicability . . . . . . . . . . . . . . . . . . . . 36 14.4. MESSAGE-INTEGRITY . . . . . . . . . . . . . . . . . . . . 32
12.1.2. Client Discovery of Server . . . . . . . . . . . . . . 37 14.5. FINGERPRINT . . . . . . . . . . . . . . . . . . . . . . . 33
12.1.3. Server Determination of Usage . . . . . . . . . . . . 38 14.6. ERROR-CODE . . . . . . . . . . . . . . . . . . . . . . . 33
12.1.4. New Requests or Indications . . . . . . . . . . . . . 38 14.7. REALM . . . . . . . . . . . . . . . . . . . . . . . . . . 34
12.1.5. New Attributes . . . . . . . . . . . . . . . . . . . . 38 14.8. NONCE . . . . . . . . . . . . . . . . . . . . . . . . . . 35
12.1.6. New Error Response Codes . . . . . . . . . . . . . . . 38 14.9. UNKNOWN-ATTRIBUTES . . . . . . . . . . . . . . . . . . . 35
12.1.7. Client Procedures . . . . . . . . . . . . . . . . . . 38 14.10. SERVER . . . . . . . . . . . . . . . . . . . . . . . . . 35
12.1.8. Server Procedures . . . . . . . . . . . . . . . . . . 38 14.11. ALTERNATE-SERVER . . . . . . . . . . . . . . . . . . . . 36
12.1.9. Security Considerations for Binding Discovery . . . . 38 15. Security Considerations . . . . . . . . . . . . . . . . . . . 36
12.2. NAT Keepalives . . . . . . . . . . . . . . . . . . . . . 39 15.1. Attacks against the Protocol . . . . . . . . . . . . . . 36
12.2.1. Applicability . . . . . . . . . . . . . . . . . . . . 39 15.1.1. Outside Attacks . . . . . . . . . . . . . . . . . . . 36
12.2.2. Client Discovery of Server . . . . . . . . . . . . . . 39 15.1.2. Inside Attacks . . . . . . . . . . . . . . . . . . . . 36
12.2.3. Server Determination of Usage . . . . . . . . . . . . 39 15.2. Attacks Affecting the Usage . . . . . . . . . . . . . . . 36
12.2.4. New Requests or Indications . . . . . . . . . . . . . 39 15.2.1. Attack I: DDoS Against a Target . . . . . . . . . . . 37
12.2.5. New Attributes . . . . . . . . . . . . . . . . . . . . 40 15.2.2. Attack II: Silencing a Client . . . . . . . . . . . . 37
12.2.6. New Error Response Codes . . . . . . . . . . . . . . . 40 15.2.3. Attack III: Assuming the Identity of a Client . . . . 37
12.2.7. Client Procedures . . . . . . . . . . . . . . . . . . 40 15.2.4. Attack IV: Eavesdropping . . . . . . . . . . . . . . . 38
12.2.8. Server Procedures . . . . . . . . . . . . . . . . . . 40 15.3. Hash Agility Plan . . . . . . . . . . . . . . . . . . . . 38
12.2.9. Security Considerations for NAT Keepalives . . . . . . 40 16. IAB Considerations . . . . . . . . . . . . . . . . . . . . . . 38
12.3. Short-Term Password . . . . . . . . . . . . . . . . . . . 41 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39
12.3.1. Applicability . . . . . . . . . . . . . . . . . . . . 41 17.1. STUN Methods Registry . . . . . . . . . . . . . . . . . . 39
12.3.2. Client Discovery of Server . . . . . . . . . . . . . . 41 17.2. STUN Attribute Registry . . . . . . . . . . . . . . . . . 39
12.3.3. Server Determination of Usage . . . . . . . . . . . . 42 17.3. STUN Error Code Registry . . . . . . . . . . . . . . . . 40
12.3.4. New Requests or Indications . . . . . . . . . . . . . 42 18. Changes Since RFC 3489 . . . . . . . . . . . . . . . . . . . . 40
12.3.5. New Attributes . . . . . . . . . . . . . . . . . . . . 43 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 42
12.3.6. New Error Response Codes . . . . . . . . . . . . . . . 43 20. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42
12.3.7. Client Procedures . . . . . . . . . . . . . . . . . . 43 20.1. Normative References . . . . . . . . . . . . . . . . . . 42
12.3.8. Server Procedures . . . . . . . . . . . . . . . . . . 43 20.2. Informational References . . . . . . . . . . . . . . . . 43
12.3.9. Security Considerations for Short-Term Password . . . 44 Appendix A. C Snippet to Determine STUN Message Types . . . . . . 44
13. Security Considerations . . . . . . . . . . . . . . . . . . . 45 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44
13.1. Attacks on STUN . . . . . . . . . . . . . . . . . . . . . 45 Intellectual Property and Copyright Statements . . . . . . . . . . 46
13.1.1. Attack I: DDoS Against a Target . . . . . . . . . . . 46
13.1.2. Attack II: Silencing a Client . . . . . . . . . . . . 46
13.1.3. Attack III: Assuming the Identity of a Client . . . . 46
13.1.4. Attack IV: Eavesdropping . . . . . . . . . . . . . . . 46
13.2. Launching the Attacks . . . . . . . . . . . . . . . . . . 47
13.2.1. Approach I: Compromise a Legitimate STUN Server . . . 47
13.2.2. Approach II: DNS Attacks . . . . . . . . . . . . . . . 47
13.2.3. Approach III: Rogue Router or NAT . . . . . . . . . . 48
13.2.4. Approach IV: Man in the Middle . . . . . . . . . . . . 48
13.2.5. Approach V: Response Injection Plus DoS . . . . . . . 49
13.2.6. Approach VI: Duplication . . . . . . . . . . . . . . . 49
13.3. Countermeasures . . . . . . . . . . . . . . . . . . . . . 50
13.4. Residual Threats . . . . . . . . . . . . . . . . . . . . 51
14. IAB Considerations . . . . . . . . . . . . . . . . . . . . . . 51
14.1. Problem Definition . . . . . . . . . . . . . . . . . . . 52
14.2. Exit Strategy . . . . . . . . . . . . . . . . . . . . . . 52
14.3. Brittleness Introduced by STUN . . . . . . . . . . . . . 52
14.4. Requirements for a Long Term Solution . . . . . . . . . . 54
14.5. Issues with Existing NAPT Boxes . . . . . . . . . . . . . 55
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
15.1. STUN Methods Registry . . . . . . . . . . . . . . . . . . 55
15.2. STUN Attribute Registry . . . . . . . . . . . . . . . . . 55
16. Changes Since RFC 3489 . . . . . . . . . . . . . . . . . . . . 56
17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 57
18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
18.1. Normative References . . . . . . . . . . . . . . . . . . 57
18.2. Informational References . . . . . . . . . . . . . . . . 58
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59
Intellectual Property and Copyright Statements . . . . . . . . . . 61
1. Applicability Statement 1. Introduction
This protocol is not a cure-all for the problems associated with NAT. The protocol defined in this specification, Session Traversal
It is a tool that is typically used in conjunction with other Utilities for NAT, provides a toolkit of functions for dealing with
protocols, such as Interactive Connectivity Establishment (ICE) [13] NATs. It provides a means for an endpoint to determine the IP
for a more complete solution. The binding discovery usage, defined address and port allocated by a NAT that corresponds to its private
by this specification, can be used by itself with numerous IP address and port. It also provides a way for an endpoint to keep
application protocols as a solution for NAT traversal. However, when a NAT binding alive. With some extensions, the protocol can be used
used in that way, STUN will not work with applications that require to do connectivity checks between two endpoints
incoming TCP connections through NAT. It will allow incoming UDP [I-D.ietf-mmusic-ice], or to relay packets between two endpoints
packets through NAT, but only through a subset of existing NAT types. [I-D.ietf-behave-turn].
In particular, the STUN binding usage by itself does not enable
incoming UDP packets through NATs whose mapping property is address
dependent or address and port dependent [14]. Furthermore, the
binding usage, when used by itself, does not work when a client is
communicating with a peer which happens to be behind the same NAT.
Nor will it work when the STUN server is not in a common shared
address realm.
The STUN relay usage, defined in [16], allows a client to obtain an In keeping with its toolkit nature, this specification defines an
IP address and port that actually reside on the STUN server. The extensible packet format, defines operation over several transport
STUN relay usage, when used by itself, eliminates all of the protocols, and provides for two forms of authentication.
limitations of using the binding usage by itself, as described above.
However, it requires a server to act as a relay for application
traffic, which can be expensive to provide, operate, and manage.
For multimedia protocols based on the offer/answer model [22], STUN is intended to be used in context of one or more NAT traversal
including the Session Initiation Protocol (SIP) [11], Interactive solutions. These solutions are known as STUN usages. Each usage
Connectivity Establishment (ICE) uses both the binding usage and describes how STUN is utilized to achieve the NAT traversal solution.
relay usage, and furthermore defines a connectivity check usage to Typically, a usage indicates when STUN messages get sent, which
help determine which transport address to use. optional attributes to include, what server is used, and what
authentication mechanism is to be used. Interactive Connectivity
Establishment (ICE) [I-D.ietf-mmusic-ice] is one usage of ICE. SIP
Outbound [I-D.ietf-sip-outbound] is another usage of ICE. In some
cases, a usage will require extensions to STUN. A STUN extension can
be in the form of new methods, attributes, or error response codes.
More information on STUN usages can be found in Section 13.
Implementers should be aware of the specific deployment scenarios and 2. Evolution from RFC 3489
the specific protocol (SIP, etc) being used to determine whether NAT
traversal can be facilitated by STUN and which STUN usages are
required.
2. Introduction STUN was originally defined in RFC 3489 [RFC3489]. That
specification, sometimes referred to as "classic STUN", represented
itself as a complete solution to the NAT traversal problem. In that
solution, a client would discover whether it was behind a NAT,
determine its NAT type, discover its IP address and port on the
public side of the outermost NAT, and then utilize that IP address
and port within the body of protocols, such as the Session Initiation
Protocol (SIP) [RFC3261]. However, experience since the publication
of RFC 3489 has found that classic STUN simply does not work
sufficiently well to be a deployable solution. The address and port
learned through classic STUN are sometimes usable for communications
with a peer, and sometimes not. Classic STUN provided no way to
discover whether it would, in fact, work or not, and it provided no
remedy in cases where it did not. Furthermore, classic STUN's
algorithm for classification of NAT types was found to be faulty, as
many NATs did not fit cleanly into the types defined there. Classic
STUN also had security vulnerabilities which required an extremely
complicated mechanism to address, and despite the complexity of the
mechanism, were not fully remedied.
Network Address Translators (NATs), while providing many benefits, For these reasons, this specification obsoletes RFC 3489, and instead
also come with many drawbacks. The most troublesome of those describes STUN as a tool that is utilized as part of a complete NAT
drawbacks is the fact that they break many existing IP applications traversal solution. ICE is a complete NAT traversal solutions for
and make it difficult to deploy new ones. Guidelines have been protocols based on the offer/answer [RFC3264] methodology, such as
developed [20] that describe how to build "NAT friendly" protocols, SIP. SIP Outbound is a complete solution for traversal of SIP
but many protocols simply cannot be constructed according to those signaling, and it uses STUN in a very different way. Though it is
guidelines. Examples of such protocols include almost all peer-to- possible that a protocol may be able to use STUN by itself (classic
peer protocols such as multimedia communications, file sharing and STUN) as a traversal solution, such usage is not described here and
games. is strongly discouraged for the reasons described above.
To combat this problem, Application Layer Gateways (ALGs) have been The on-the-wire protocol described here is changed only slightly from
embedded in NATs. ALGs perform the application layer functions classic STUN. The protocol now runs over TCP in addition to UDP.
required for a particular protocol to traverse a NAT. Typically, Extensibility was added to the protocol in a more structured way. A
this involves rewriting application layer messages to contain magic-cookie mechanism for demultiplexing STUN with application
translated addresses, rather than the ones inserted by the sender of protocols was added by stealing 32 bits from the 128 bit transaction
the message. ALGs have serious limitations, including scalability, ID defined in RFC 3489, allowing the change to be backwards
reliability, and speed of deploying new applications. compatible. Mapped addresses are encoded using a new exclusive-or
format. There are other, more minor changes. See Section 18 for a
more complete listing.
Many existing proprietary protocols, such as those for online games Due to the change in scope, STUN has also been renamed from "Simple
(such as the games described in RFC3027 [21]) and Voice over IP, have Traversal of UDP Through NAT" to "Session Traversal Utilities for
developed tricks that allow them to operate through NATs without NAT". The acronym remains STUN, which is all anyone ever remembers
changing those NATs and without relying on ALG behavior in the NATs. anyway.
This document takes some of those ideas and codifies them into an
interoperable protocol that can meet the needs of many applications.
The protocol described here, Session Traversal Utilities for NAT 3. Overview of Operation
(STUN), provides a toolkit of functions. These functions allow
entities behind a NAT to learn the address bindings allocated by the
NAT and to keep those bindings open. STUN requires no changes to
NATs and works with an arbitrary number of NATs in tandem between the
application entity and the public Internet.
3. Terminology This section is descriptive only.
/--------\
// STUN \\
| Agent |
\\ (server) //
\--------/
+----------------+ Public Internet
................| NAT 2 |.......................
+----------------+
+----------------+ Private NET 2
................| NAT 1 |.......................
+----------------+
/--------\
// STUN \\
| Agent |
\\ (client) // Private NET 1
\--------/
Figure 1: One possible STUN Configuration
One possible STUN configuration is shown in Figure 1. In this
configuration, there are two entities (called STUN agents) that
implement the STUN protocol. The lower agent in the figure is
connected to private network 1. This network connects to private
network 2 through NAT 1. Private network 2 connects to the public
Internet through NAT 2. The upper agent in the figure resides on the
public Internet.
STUN is a client-server protocol. It supports two types of
transactions. One is a request/response transaction in which a
client sends a request to a server, and the server returns a
response. The second is an indication transaction in which a client
sends an indication to the server and the server does not respond.
Both types of transactions include a transaction ID, which is a
randomly selected 96-bit number. For request/response transactions,
this transaction ID allows the client to associate the response with
the request that generated it; for indications, this simply serves as
a debugging aid.
All STUN messages start with a fixed header that includes a method, a
class, and the transaction ID. The method indicates which of the
various requests or indications this is; this specification defines
just one method, Binding, but other methods are expected to be
defined in other documents. The class indicates whether this is a
request, a (success) response, an error response, or an indication.
Following the fixed header comes zero or more attributes, which are
type-length-value extensions that convey additional information for
the specific message.
This document defines a single method called Binding. The Binding
method can be used either in request/response transactions or in
indication transactions. When used in request/response transactions,
the Binding method can be used to determine the particular "binding"
a NAT has allocated to a STUN client. When used in either request/
response or in indication transactions, the Binding method can also
be used to keep these "bindings" alive.
In the Binding request/response transaction, a Binding Request is
sent from a STUN client to a STUN server. When the Binding Request
arrives at the STUN server, it may have passed through one or more
NATs between the STUN client and the STUN server (in Figure 1, there
were two such NATs). As the Binding Request message passes through a
NAT, the NAT will modify the source transport address (that is, the
source IP address and the source port) of the packet. As a result,
the source transport address of the request received by the server
will be the public IP address and port created by the NAT closest to
the server. This is called a reflexive transport address. The STUN
server copies that source transport address into an XOR-MAPPED-
ADDRESS attribute in the STUN Binding Response and sends the Binding
Response back to the the STUN client. As this packet passes back
through a NAT, the NAT will modify the destination transport address,
but the transport address in the XOR-MAPPED-ADDRESS attribute within
the body of the STUN response will remain untouched. In this way,
the client can learn its reflexive transport address allocated by the
outermost NAT with respect to the STUN server.
In some usages, STUN must be multiplexed with other protocols (e.g.,
[I-D.ietf-mmusic-ice], [I-D.ietf-sip-outbound]). In these usages,
there must be a way to inspect a packet and determine if it is a STUN
packet or not. STUN provides two fields in the STUN header with
fixed values that can be used for this purpose. If this is not
sufficient, then STUN packets can also contain a FINGERPRINT value
which can further be used to distinguish the packets.
STUN has optional mechanisms for providing authentication and message
integrity when required. These mechanisms revolve around the use of
a username, password, and message-integrity value. Two of these
mechanisms, the long-term credential mechanism and the short-term
credential mechanism, are defined in this specification. Each usage
specifies the mechanisms allowed with that usage.
In the short-term credential mechanism, the client and the server
exchange a username and password through some out-of-band method
prior to the STUN exchange. For example, in the ICE usage
[I-D.ietf-mmusic-ice] the two endpoints use out-of-band signaling to
exchange a username and password. The client then includes the
username and a message-integrity value in the request message, where
the message-integrity value is computed as a cryptographic hash of
the message contents and the password. If the server replies with a
success response, then the response will include a message-integrity
value (computed using the same username and password), but the
username is not included. Error responses are not message-integrity
protected.
In the long-term credential mechanism, the client and server share a
pre-provisioned username and password and perform a digest challenge/
response exchange inspired by (but differing in details) to the one
defined for HTTP [RFC2617]. Initially, the client sends a request
message (e.g., a Binding Request) without any username or message-
integrity value included. The server replies with an error response
indicating that the request must be authenticated. This error
response includes a realm value and a nonce value. The client then
uses the realm value to help it select a username and password (for
example, the client might have a number of username and password
combinations stored, each one keyed by a different realm value). The
client then retries the request, this time including the realm, the
username, the nonce, and a message-integrity value in the request,
where the message-integrity value is computed as a cryptographic hash
of the message contents and the password. The nonce is provided by
the server and merely echoed by the client into the request. It is
chosen by the server such that it encodes information about the
client, the time-of-day, or other parameters. In this way, if an
attacker should attempt to replay the request, the server would find
the nonce invalid, and then reject the request. If the server
replies with a success response, then the response will include a
message-integrity value (computed using the same username and
password), but realm, username, and nonce are not included. Error
responses are not message-integrity protected. If the client has
further requests to send, it can try to reuse the same username,
realm, and nonce values. If the server does not accept them, it will
reply with an error response giving a realm and nonce value again.
4. Terminology
In this document, the key words "MUST", "MUST NOT", "REQUIRED", In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
[1] and indicate requirement levels for compliant STUN [RFC2119] and indicate requirement levels for compliant STUN
implementations. implementations.
4. Definitions 5. Definitions
STUN Client: A STUN client (also just referred to as a client) is an STUN Agent: An entity that implements the STUN protocol. Agents can
entity that generates STUN requests and receives STUN responses. act as STUN clients for some transactions and as STUN servers for
Clients can also generate STUN indications. other transactions.
STUN Server: A STUN Server (also just referred to as a server) is an STUN Client: A logical role in the STUN protocol. A STUN client
entity that receives STUN requests and sends STUN responses. sends STUN requests or STUN indications, and receives STUN
Servers also send STUN indications. responses. The term "STUN client" is also used colloquially to
refer to a STUN agent that only acts as a STUN client.
Transport Address: The combination of an IP address and transport STUN Server: A logical role in the STUN protocol. A STUN server
protocol (such as UDP or TCP) port. receives STUN requests or STUN indications and sends STUN
responses. The term "STUN server" is also used colloquially to
refer to a STUN agent that only acts as a STUN server.
Transport Address: The combination of an IP address and port number
(such as a UDP or TCP port number).
Reflexive Transport Address: A transport address learned by a client Reflexive Transport Address: A transport address learned by a client
that identifies that client as seen by another host on an IP that identifies that client as seen by another host on an IP
network, typically a STUN server. When there is an intervening network, typically a STUN server. When there is an intervening
NAT between the client and the other host, the reflexive transport NAT between the client and the other host, the reflexive transport
address represents the binding allocated to the client on the address represents the mapped address allocated to the client on
public side of the NAT. Reflexive transport addresses are learned the public side of the NAT. Reflexive transport addresses are
from the mapped address attribute (MAPPED-ADDRESS or XOR-MAPPED- learned from the mapped address attribute (MAPPED-ADDRESS or XOR-
ADDRESS) in STUN responses. MAPPED-ADDRESS) in STUN responses.
Mapped Address: The source IP address and port of the STUN Binding Mapped Address: Same meaning as Reflexive Address. This term is
Request packet received by the STUN server and inserted into the retained only for for historic reasons and due to the naming of
mapped address attribute (MAPPED-ADDRESS or XOR-MAPPED-ADDRESS) of the MAPPED-ADDRESS and XOR-MAPPED-ADDRESS attributes.
the Binding Response message.
Long Term Credential: A username and associated password that Long Term Credential: A username and associated password that
represent a shared secret between client and server. Long term represent a shared secret between client and server. Long term
credentials are generally granted to the client when a subscriber credentials are generally granted to the client when a subscriber
enrolles in a service and persist until the subscriber leaves the enrolls in a service and persist until the subscriber leaves the
service or explicitly changes the credential. service or explicitly changes the credential.
Long Term Password: The password from a long term credential. Long Term Password: The password from a long term credential.
Short Term Credential: A temporary username and associated password Short Term Credential: A temporary username and associated password
which represent a shared secret between client and server. A which represent a shared secret between client and server. Short
short term credential has an explicit temporal scope, which may be term credentials are obtained through some kind of protocol
based on a specific amount of time (such as 5 minutes) or on an mechanism between the client server, preceding the STUN exchange.
A short term credential has an explicit temporal scope, which may
be based on a specific amount of time (such as 5 minutes) or on an
event (such as termination of a SIP dialog). The specific scope event (such as termination of a SIP dialog). The specific scope
of a short term credential is defined by the application usage. A of a short term credential is defined by the application usage.
short term credential can be obtained from a Shared Secret
request, though other mechanisms are possible.
Short Term Password: The password component of a short term Short Term Password: The password component of a short term
credential. credential.
5. Overview of Operation STUN Indication: A STUN message that does not receive a response
This section is descriptive only. Normative behavior is described in
Section 8 and Section 9
/-----\
// STUN \\
| Server |
\\ //
\-----/
+--------------+ Public Internet
................| NAT 2 |.......................
+--------------+
+--------------+ Private NET 2
................| NAT 1 |.......................
+--------------+
/-----\
// STUN \\
| Client |
\\ // Private NET 1
\-----/
Figure 1: Typical STUN Server Configuration
The typical STUN configuration is shown in Figure 1. A STUN client
is connected to private network 1. This network connects to private
network 2 through NAT 1. Private network 2 connects to the public
Internet through NAT 2. The STUN server resides on the public
Internet.
STUN is a simple client-server protocol. It supports two types of
transactions. One is a request/response transaction in which client
sends a request to a server, and the server returns a response. The
second are indications that are initiated by the server or the client
and do not elicit a response. There are two types of requests
defined in this specification - Binding Requests and Shared Secret
Requests. There are no indications defined by this specification.
Binding Requests are sent from the client towards the server. When
the Binding Request arrives at the STUN server, it may have passed
through one or more NATs between the STUN client and the STUN server
(in Figure 1, there were two such NATs). As a result, the source
transport address of the request received by the server will be the
mapped address created by the NAT closest to the server. The STUN
server copies that source transport address into a STUN Binding
Response and sends it back to the source transport address of the
STUN request. Every type of NAT will route that response so that it
arrives at the STUN client. From this response, the client knows its
transport address allocated by the outermost NAT towards the STUN
server.
STUN provides several mechanisms for authentication and message
integrity. The client and server can share a pre-provisioned shared
secret, which is used for a digest challenge/response authentication
operation. This is known as a long-term credential or long-term
shared secret.
Alternatively, if the shared secret is obtained by some out-of-bands
means and has a lifetime that is temporally scoped, a simple HMAC is
provided, without a challenge operation. This is known as a short
term credential or short term password. Short-term passwords are
useful when there is no long-term relationship with a STUN server and
thus no long-term password is shared between the STUN client and STUN
server. Even if there is a long-term password, the issuance of a
short-term password is useful to prevent dictionary attacks.
STUN itself provides a mechanism for obtaining such short term
credentials, using the Shared Secret Request. Shared Secret requests
are sent over TLS [5] over TCP. Shared Secret Requests ask the
server to return a temporary username and password that can be used
in subsequent STUN requests.
There are many ways in which these basic mechanisms can be used to
accomplish a specific task. As a result, STUN has the notion of a
usage. A usage is a specific use case for the STUN protocol. The
usage will define what the client does with the mapped address it
receives, defines when the client would send Binding requests and
why, and would constrain the set of authentication mechanisms or
attributes that get used in that usage. STUN usages can also define
new attributes and message types, if needed. This specification
defines three STUN usages - binding discovery, NAT keepalives, and
short-term password.
The binding discovery usage is sometimes referred to as 'classic
STUN,' since it is the usage originally envisioned in RFC 3489 [15],
the predecessor to this specification. The purpose of the binding
discovery usage is for the client to obtain a transport address at
which it is reachable. The client can include these transport
addresses in application layer signaling messages such as the Session
Description Protocol (SDP) [19] (present in the body of SIP
messages), where it indicates where the client wants to receive Real
Time Transport Protocol (RTP [17]) traffic. In this usage, the STUN
server is typically located on the public Internet and run by the
service provider offering the application service (such as a SIP
provider), though this need not be the case. The client would
utilize the STUN request just prior to sending a protocol message
(such as a SIP INVITE request or 200 OK response) that requires the
client to embed its transport address.
In the binding keepalive usage, a client sends an application
protocol message (such as a SIP REGISTER message) to a server. The
server notes the source transport address of the request, and
remembers it. Later on, if it needs to reach the client, it sends a
message to that transport address. However, this message will only
be received by the client if the binding in the NAT is still alive.
Since bindings allocated by NAT expire unless refreshed, the client
must generate keepalive messages toward the server to refresh the
binding. Rather than use expensive application layer messages, a
STUN binding request is sent by the client to the server, and is sent
to the exact same transport address used by the server for the
application protocol. In the case of SIP, this would typically mean
port 5060 or 5061. This has the effect of keeping the bindings in
the NAT alive. The STUN binding responses also inform the client
that the server is still responsive, and also inform the client if
its transport address towards the server have changed (its reflexive
transport address), in which case it may need application layer
protocol messaging to update its transport address as seen by the
server. The binding keepalive usage is used by the SIP outbound
mechanism, for example [18].
These two usages all utilize the same Binding Request message, and
all require the same basic processing on the server. They differ
only in where the server is (a standalone server in the network, or
embedded in an application layer server), when the Binding Request is
used and what the client does with the mapped address that is
returned.
The short-term password usage makes use of the Shared Secret request
and response, and allows a client to obtain a temporary set of
credentials to authenticate itself with the STUN server. The
credentials obtained from this usage can be used in requests for any
other usage.
Some usages (such as the binding keepalive) require STUN messages to Attribute: The STUN term for a Type-Length-Value (TLV) object that
be sent on the same transport address as some application protocol, can be added to a STUN message. Attributes are divided into two
such as RTP or SIP. To facilitate the demultiplexing of the two, types: comprehension-required and comprehension-optional. STUN
STUN defines a special field in the message called the magic cookie, agents can safely ignore comprehension-optional attributes they
which is a fixed 32 bit value that identifies STUN traffic. STUN don't understand, but cannot successfully process a message if it
requests also contain a fingerprint, which is a cryptographic hash of contains comprehension-required attributes that are not
the message, that allow for validation that the message was a STUN understood.
request and not a data packet that happened to have the same 32 bit
value in the right place in the message.
STUN servers can be discovered through DNS, though this is not RTO: Retransmission TimeOut
necessary in all usages. For those usages where it is needed, STUN
makes use of SRV records [3] to facilitate discovery. This discovery
allows for different transport addresses to be found for different
usages.
6. STUN Message Structure 6. STUN Message Structure
STUN messages are TLV (type-length-value) encoded using big endian STUN messages are encoded in binary using network-oriented format
(network ordered) binary. STUN messages are encoded using binary (most significant byte or octet first, also commonly known as big-
fields. All integer fields are carried in network byte order, that endian). The transmission order is described in detail in Appendix B
is, most significant byte (octet) first. This byte order is commonly of RFC791 [RFC0791]. Unless otherwise noted, numeric constants are
known as big-endian. The transmission order is described in detail in decimal (base 10).
in Appendix B of RFC791 [2]. Unless otherwise noted, numeric
constants are in decimal (base 10). All STUN messages start with a
single STUN header followed by a STUN payload. The payload is a
series of STUN attributes, the set of which depends on the message
type. The STUN header contains a STUN message type, magic cookie,
transaction ID, and length. The length indicates the total length of
the STUN payload, not including the 20-byte header.
There are two types of transactions in STUN - request/response
transactions, which utilize a request message and a response message,
and indication transactions, which utilizes a single indication
message. Furthermore, responses are broken into two types - success
responses and error responses. Two bits in the message type field of
the STUN header indicate the class of the message - whether the
message is a request, a success response, an indication, or a failure
response. An additional 12 bits in the message type indicate the
method, which is the primary function of the message. This
specification defines two methods, Binding and Shared Secret.
STUN Requests are sent reliably. STUN can run over UDP, TCP or TCP/
TLS. When run over UDP, STUN requests are retransmitted in order to
achieve reliability. The transaction ID is used to correlate
requests and responses.
An indication message can be sent from the client to the server, or
from the server to the client. Indication messages can be sent over
TCP or UDP. STUN itself does not provide reliability for these
messages, though they will be delivered reliably when sent over TCP.
The transaction ID is used to distinguish indication messages.
All STUN messages consist of a 20 byte header: All STUN messages MUST start with a 20-byte header followed by zero
or more Attributes. The STUN header contains a STUN message type,
magic cookie, transaction ID, and message length.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0| STUN Message Type | Message Length | |0 0| STUN Message Type | Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic Cookie | | Magic Cookie |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Transaction ID (96 bits) |
Transaction ID | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 2: Format of STUN Message Header Figure 2: Format of STUN Message Header
The most significant two bits of every STUN message are both zeroes. The most significant two bits of every STUN message MUST be zeroes.
This, combined with the magic cookie and the fingerprint attribute, This can be used to differentiate STUN packets from other protocols
aid in differentiating STUN packets from other protocols when STUN is when STUN is multiplexed with other protocols on the same port.
multiplexed with other protocols on the same port.
The message type defines the message class (request, success
response, failure response, or indication) and the message method
(the primary function) of the STUN message. Although there are four
message classes, there are only two types of transactions in STUN:
request/response transactions (which consist of a request message and
a response message), and indication transactions (which consists a
single indication message). Response classes are split into error
and success responses to aid in quickly processing the STUN message.
The message type field is decomposed further into the following The message type field is decomposed further into the following
structure: structure:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +--+--+-+-+-+-+-+-+-+-+-+-+-+-+
|M|M|M|M|M|C|M|M|M|C|M|M|M|M| |M|M|M|M|M|C|M|M|M|C|M|M|M|M|
|1|1|9|8|7|1|6|5|4|0|3|2|1|0| |11|10|9|8|7|1|6|5|4|0|3|2|1|0|
|1|0| | | | | | | | | | | | | +--+--+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 3: Format of STUN Message Type Field Figure 3: Format of STUN Message Type Field
M11 through M0 represent a 12-bit encoding of the method. C1 through Here the bits in the message type field are shown as most-significant
C0 represent a 2 bit encoding of the class. A class of 0 is a (M11) through least-significant (M0). M11 through M0 represent a 12-
Request, a class of 1 is an indication, a class of 2 is a success bit encoding of the method. C1 and C0 represent a 2 bit encoding of
response, and a class of 3 is an error response. This specification the class. A class of 0b00 is a Request, a class of 0b01 is an
defines two methods, Binding and Shared Secret. Their method values indication, a class of 0b10 is a success response, and a class of
are enumerated in Section 15. 0b11 is an error response. This specification defines a single
method, Binding. The method and class are orthogonal, so that four
The message length is the size, in bytes, of the message not each method, a request, success response, error response and
including the 20 byte STUN header. indication are defined for that method.
The magic cookie is a fixed value, 0x2112A442. In the previous
version of this specification [15] this field was part of the
transaction ID. This fixed value is used as part of the
identification of a STUN message when STUN is multiplexed with other
protocols on the same port, as is done for example in [13] and [18].
The magic cookie additionally indicates the STUN client is compliant
with this specification. The magic cookie is present in all STUN
messages -- requests, success responses, error responses and
indications.
The transaction ID is a 96 bit identifier. STUN transactions are
identified by their unique 96-bit transaction ID. For request/
response transactions, the transaction ID is chosen by the STUN
client and MUST be unique for each new STUN transaction generated by
that STUN client. The transaction ID MUST be uniformly and randomly
distributed between 0 and 2**96 - 1. The large range is needed
because the transaction ID serves as a form of randomization, helping
to prevent replays of previously signed responses from the server. A
reponse to the STUN request, whether it be a success or error
response, carries the same transaction ID as the request.
Indications are also identified by their transaction ID. The
transaction ID there MUST also be uniformly and randomly distributed
between 0 and 2**96 - 1.As with requests, the value is chosen by the
server and MUST be unique for each unique indication generated by the
server. Unless a request or indication is bit-wise identical to a
previous request, and was sent to the same server from the same
transport address, a client MUST choose a new transaction ID for it.
After the STUN header are zero or more attributes. Each attribute is
TLV encoded, with a 16 bit type, 16 bit length, and variable value.
Each STUN attribute ends on a 32 bit boundary:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Value .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 4: Format of STUN Attributes
The Length refers to the length of the actual useful content of the For example, a Binding Request has class=0b00 (request) and
Value portion of the attribute, measured in bytes. Since STUN aligns method=0b000000000001 (Binding), and is encoded into the first 16
attributes on 32 bit boundaries, attributes whose content is not a bits as 0x0001. A Binding response has class=0b10 (success response)
multiple of 4 bytes are padded with 1, 2 or 3 bytes of padding so and method=0b000000000001, and is encoded into the first 16 bits as
that they are a multiple of 4 bytes. Such padding is only needed 0x0101.
with attributes that take freeform strings, such as USERNAME and
PASSWORD. For attributes that contain more structured data, the
attributes are constructed to align on 32 bit boundaries. The value
in the Length field refers to the length of the Value part of the
attribute prior to padding - i.e., the useful content. Consequently,
when parsing messages, implementations will need to round up the
Length field to the nearest multiple of four in order to find the
start of the next attribute.
The attribute types defined in this specification are in Section 11 . Note: This unfortunate encoding is due to assignment of values in
[RFC3489] which did not consider encoding Indications, Success,
and Errors using bit fields.
7. STUN Transactions The magic cookie field MUST contain the fixed value 0x2112A442 in
network byte order. In RFC 3489 [RFC3489], this field was part of
the transaction ID; placing the magic cookie in this location allows
a server to detect if the client will understand certain attributes
that were added in this revised specification. In addition, it aids
in distinguishing STUN packets from packets of other protocols when
STUN is multiplexed with those other protocols on the same port.
STUN defines two types of transactions - request/response The transaction ID is a 96 bit identifier, used to uniquely identify
transactions and indication transactions. STUN transactions. The transaction ID is chosen by the STUN client.
It primarily serves to correlate requests with responses, though it
also plays a small role in helping to prevent certain types of
attacks. As such, the transaction ID MUST be uniformly and randomly
chosen from the interval 0 .. 2**96-1. Resends of the same request
reuse the same transaction ID, but the client MUST choose a new
transaction ID for new transactions unless the new request is bit-
wise identical to the previous request and sent from the same
transport address to the same IP address. Success and error
responses MUST carry the same transaction ID as their corresponding
request. When an agent is acting as a STUN server and STUN client on
the same port, the transaction IDs in requests sent by the agent have
no relationship to the transaction IDs in requests received by the
agent.
7.1. Request/Response Transactions The message length MUST contain the size, in bytes, of the message
not including the 20 byte STUN header. Since all STUN attributes are
padded to a multiple of four bytes, the last two bits of this field
are always zero. This provides another way to distinguish STUN
packets from packets of other protocols.
STUN clients are allowed to pipeline STUN requests. That is, a STUN Following the STUN fixed portion of the header are zero or more
client MAY have multiple outstanding STUN requests with different attributes. Each attribute is TLV (type-length-value) encoded. The
transaction IDs and not wait for completion of a STUN request/ details of the encoding, and of the attributes themselves is given in
response exchange before sending another STUN request. Section 14.
When running STUN over UDP it is possible that the STUN request or 7. Base Protocol Procedures
its response might be dropped by the network. Reliability of STUN
request message types is accomplished through client retransmissions.
Clients SHOULD retransmit the request starting with an interval of
RTO, doubling after each retransmission. RTO is an estimate of the
round-trip-time, and is computed as described in RFC 2988 [8], with
two exceptions. First, the initial value for RTO SHOULD be
configurable (rather than the 3s recommended in RFC 2988). In fixed-
line access links, a value of 100ms is RECOMMENDED. Secondly, the
value of RTO MUST NOT be rounded up to the nearest second. Rather, a
1ms accuracy MUST be maintained. As with TCP, the usage of Karn's
algorithm is RECOMMENDED. When applied to STUN, it means that RTT
estimates SHOULD NOT be computed from STUN transactions which result
in the retransmission of a request.
The value for RTO SHOULD be cached by an agent after the completion This section defines the base procedures of the STUN protocol. It
of the transaction, and used as the starting value for RTO for the describes how messages are formed, how they are sent, and how they
next transaction to the same host (based on equality of IP address). are processed when they are received. It also defines the detailed
The value SHOULD be considered stale and discarded after 10 minutes. processing of the Binding method. Other sections in this document
describe optional procedures that a usage may elect to use in certain
situations. Other documents may define other extensions to STUN, by
adding new methods, new attributes, or new error response codes.
Retransmissions continue until a response is received, or a total of 7.1. Forming a Request or an Indication
7 requests have been sent. If no response is received by 1.6 seconds
after the last request has been sent, the client SHOULD consider the
transaction to have failed. A STUN transaction over UDP is also
considered failed if there has been a transport failure of some sort,
such as a fatal ICMP error. For example, assuming an RTO of 100ms,
requests would be sent at times 0ms, 100ms, 300ms, 700ms, 1500ms,
3100ms, and 6300ms. At 7900ms, the agent would consider the
transaction to have timed out if no response has been received.
When running STUN over TCP, TCP is responsible for ensuring delivery. When formulating a request or indication message, the client MUST
The STUN application SHOULD NOT retransmit STUN requests when running follow the rules in Section 6 when creating the header. In addition,
over TCP. If the client has not received a response after 7900ms, it the message class MUST be either "Request" or "Indication" (as
considers the transaction to have timed out. appropriate), and the method must be either Binding or some method
defined in another document.
Regardless of whether TCP or UDP was used for the transaction, if a The client then adds any attributes specified by the method or the
failure occurs and the client has other servers it can reach (as a usage. For example, some usages may specify that the client use an
consequence of an SRV query which provides a multiplicity of STUN authentication method (Section 10) or the FINGERPRINT attribute
servers Section 8.1, for example), the client SHOULD create a new (Section 8).
request, which is identical to the previous, but has a different
transaction ID (and consequently a different MESSAGE INTEGRITY and/or
FINGERPRINT attribute).
7.2. Indications For the Binding method with no authentication, no attributes are
required unless the usage specifies otherwise.
Indications are sent from the client to the server, or from the 7.2. Sending the Request or Indication
server to the client. Though no indications are used by this
specification, they are used by the STUN relay usage [16]. When sent
over UDP, there are no retransmissions, and reliability is not
provided. When sent over TCP, reliability is provided by TCP.
Regardless of whether TCP or UDP was used for the indication, if a The client then sends the request to the server. This document
failure occurs (due to a fatal ICMP error or TCP error), and the specifies how to send STUN messages over UDP, TCP, or TLS-over-TCP;
client has other servers it can reach (as a consequence of an SRV other transport protocols may be added in the future. The STUN usage
query which provides a multiplicity of STUN servers Section 8.1, for must specify which transport protocol is used, and how the client
example), the client SHOULD create a new indication, which is determines the IP address and port of the server. Section 9
identical to the previous, but has a different transaction ID (and describes a DNS-based method of determining the IP address and port
consequently a different MESSAGE INTEGRITY and/or FINGERPRINT of a server which a usage may elect to use.
attribute).
8. Client Behavior At any time, a client MAY have multiple outstanding STUN requests
with the same STUN server (that is, multiple transactions in
progress, with different transaction ids).
Client behavior can be broken down into several steps. The first is 7.2.1. Sending over UDP
discovery of the STUN server. The next is obtaining a shared secret.
For request/response transactions, the next steps are formulating the
request and processing the response. For indication transactions,
the next step is formulating the indication.
8.1. Discovery When running STUN over UDP it is possible that the STUN message might
be dropped by the network. Reliability of STUN request/response
transactions is accomplished through retransmissions of the request
message by the client application itself. STUN indications are not
retransmitted; thus indication transactions over UDP are not
reliable.
Unless stated otherwise by a STUN usage, DNS is used to discover the A client SHOULD retransmit a STUN request message starting with an
STUN server following these procedures. interval of RTO ("Retransmission TimeOut"), doubling after each
retransmission. The RTO is an estimate of the round-trip-time, and
is computed as described in RFC 2988 [RFC2988], with two exceptions.
First, the initial value for RTO SHOULD be configurable (rather than
the 3s recommended in RFC 2988). In fixed- line access links, a
value of 100ms is RECOMMENDED. Secondly, the value of RTO MUST NOT
be rounded up to the nearest second. Rather, a 1ms accuracy MUST be
maintained. As with TCP, the usage of Karn's algorithm is
RECOMMENDED. When applied to STUN, it means that RTT estimates
SHOULD NOT be computed from STUN transactions which result in the
retransmission of a request.
The client will be configured with a domain name of the provider of The value for RTO SHOULD be cached by an client after the completion
the STUN servers. This domain name is resolved to a transport of the transaction, and used as the starting value for RTO for the
address using the SRV procedures specified in RFC2782 [3]. The next transaction to the same server (based on equality of IP
mechanism for configuring the STUN client with the domain name to address). The value SHOULD be considered stale and discarded after
look up is not in scope of this document. 10 minutes.
The DNS SRV service name depends on the application usage. For the Retransmissions continue until a response is received, or until a
binding usage, the service name is "stun". The protocol can be "udp" total of 7 requests have been sent. If, after the last request, a
for UDP, "tcp" for TCP and "tls" for TLS over TCP. For the short duration equal to 16 times the RTO has passed without a response, the
term password application usage, the service name is "stun-pass". client SHOULD consider the transaction to have failed. A STUN
The protocol is always "tls" for TLS over TCP. The binding keepalive transaction over UDP is also considered failed if there has been a
usage always starts with a transport address, so no DNS SRV service transport failure of some sort, such as a fatal ICMP error. For
names are defined for it. New STUN usages MAY define additional DNS example, assuming an RTO of 100ms, requests would be sent at times
SRV service names. These SHOULD start with "stun". 0ms, 100ms, 300ms, 700ms, 1500ms, 3100ms, and 6300ms. If the client
has not received a response after 7900ms, the client will consider
the transaction to have timed out.
The procedures of RFC 2782 are followed to determine the server to 7.2.2. Sending over TCP or TLS-over-TCP
contact. RFC 2782 spells out the details of how a set of SRV records
are sorted and then tried. However, RFC2782 only states that the
client should "try to connect to the (protocol, address, service)"
without giving any details on what happens in the event of failure;
those details for STUN are described in Section 8.3.3.
A STUN server supporting multiple usages (such as the short term For TCP and TLS-over-TCP, the client opens a TCP connection to the
password and binding discovery usage) MAY use the same ports for server.
different usages, as long as ports are not needed to differentiate
the usages. Different ports are not needed to differentiate the
usages defined in this specification. Different ports SHOULD be used
for TCP and TCP/TLS, so that the server can determine whether the
first message it will receive after the TCP connection is set up is a
STUN message or a TLS message.
The default port for STUN requests is 3478, for both TCP and UDP. In some usage of STUN, STUN is sent as the only protocol over the TCP
There is no default port for STUN over TLS. Administrators SHOULD connection. In this case, it can be sent without the aid of any
use this port in their SRV records for UDP and TCP, but MAY use additional framing or demultiplexing. In other usages, or with other
others. If no SRV records were found, the client performs an A or extensions, it may be multiplexed with other data over a TCP
AAAA record lookup of the domain name. The result will be a list of connection. In that case, STUN MUST be run ontop of some kind of
IP addresses, each of which can be contacted at the default port framing protocol, specified by the usage or extension, which allows
using UDP or TCP, independent of the STUN usage. For usages that for the agent to extract complete STUN messages and complete
require TLS, such as the short term password usage, lack of SRV application layer messages.
records is equivalent to a failure of the transaction, since the
request or indication MUST NOT be sent unless SRV records provided a
transport address specifically for TLS.
8.2. Obtaining a Shared Secret For TLS-over-TCP, the TLS_RSA_WITH_AES_128_CBC_SHA ciphersuite MUST
be supported at a minimum. Implementations MAY also support any
other ciphersuite. When it receives the TLS Certificate message, the
client SHOULD verify the certificate and inspect the site identified
by the certificate. If the certificate is invalid, revoked, or if it
does not identify the appropriate party, the client MUST NOT send the
STUN message or otherwise proceed with the STUN transaction. The
client MUST verify the identity of the server. To do that, it
follows the identification procedures defined in Section 3.1 of RFC
2818 [RFC2818]. Those procedures assume the client is dereferencing
a URI. For purposes of usage with this specification, the client
treats the domain name or IP address used in Section 8.1 as the host
portion of the URI that has been dereferenced. If DNS was not used,
the client MUST be configured with a set of authorized domains whose
certificates will be accepted.
As discussed in Section 13, there are several attacks possible on Reliability of STUN over TCP and TLS-over-TCP is handled by TCP
STUN systems. Many of these attacks are prevented through integrity itself, and there are no retransmissions at the STUN protocol level.
protection of requests and responses. To provide that integrity, However, for a request/response transaction, if the client has not
STUN makes use of a shared secret between client and server which is received a response after 7900ms, it considers the transaction to
used as the keying material for the MESSAGE-INTEGRITY attribute in have timed out. This value has been chosen to equalize the TCP and
STUN messages. STUN allows for the shared secret to be obtained in UDP timeouts for the default initial RTO.
any way. The application usage defines the mechanism and required
implementation strength for shared secrets.
Some usages assume that out of band protocols are used to obtain the In addition, if the client is unable to establish the TCP connection,
necessary credentials. Other usages, such as binding keepalives, or the TCP connection is reset or fails before a response is
don't use authentication, as it is not required. Others, such as the received, any request/response transaction in progress is considered
binding discovery, allows for authentication using either a long term to have failed
shared secret or a short term shared secret. The latter can be
obtained by using the short term password usage to obtain a short
term shared secret.
Consequently, the STUN usages define rules for obtaining shared The client MAY send multiple transactions over a single TCP (or TLS-
secrets prior to sending a request. over-TCP) connection, and it MAY send another request before
receiving a response to the previous. The client SHOULD keep the
connection open until it
8.3. Request/Response Transactions o has no further STUN requests or indications to send over that
connection, and;
8.3.1. Formulating the Request Message o has no plans to use any resources (such as a mapped address
(MAPPED-ADDRESS or XOR-MAPPED-ADDRESS) or relayed address
[I-D.ietf-behave-turn]) that were learned though STUN requests
sent over that connection, and;
The client follows the syntax rules defined in Section 6 and the o if multiplexing other application protocols over that port, has
transmission rules of Section 7. The message class MUST be a finished using that other application, and;
request.
The client creates a STUN message following the STUN message o if using that learned port with a remote peer, has established
structure described in Section 6. The client SHOULD add a MESSAGE- communications with that remote peer, as is required by some TCP
INTEGRITY and USERNAME attribute to the Request message if the usage NAT traversal techniques (e.g., [I-D.ietf-mmusic-ice-tcp]).
employs authentication. The specific credentials to use are
described by the STUN usage, which can specify no credentials, a
short term credential, or a long term credential. The procedures for
each are:
1. If the STUN usage specifies that no credentials are used, the At the server end, the server SHOULD keep the connection open, and
message is sent without MESSAGE-INTEGRITY let the client close it. If a server becomes overloaded and needs to
close connections to free up resources, it SHOULD close an existing
connection rather than reject new connection requests. The server
SHOULD NOT close a connection if a request was received over that
connection for which a response was not sent. A server MUST NOT ever
open a connection back towards the client in order to send a
response.
2. If a short term credential is to be used, the STUN Request or 7.3. Receiving a STUN Message
STUN Indication would contain the USERNAME and MESSAGE-INTEGRITY
attributes. The message MUST NOT contain the REALM attribute.
The key for MESSAGE-INTEGRITY is the password.
3. If a long term credential is to be used, the STUN request This section specifies the processing of a STUN message. The
contains the USERNAME, REALM, and MESSAGE-INTEGRITY attributes. processing specified here is for STUN messages as defined in this
The 16-byte key for MESSAGE-INTEGRITY HMAC is formed by taking specification; additional rules for backwards compatibility are
the MD5 hash of the result of concatenating the following five defined in in Section 12. Those additional procedures are optional,
fields: (1) The username, with any quotes and trailing nulls and usages can elect to utilize them. First, a set of processing
removed, (2) A single colon, (3) The realm, with any quotes and operations are applied that are independent of the class. This is
trailing nulls removed, (4) A single colon, and (5) The password, followed by class-specific processing, described in the subsections
with any trailing nulls removed. For example, if the USERNAME which follow.
field were 'user', the REALM field were '"realm"', and the
PASSWORD field were 'pass', then the 16-byte HMAC key would be
the result of performing an MD5 hash on the string 'user:realm:
pass', or 0x8493fbc53ba582fb4c044c456bdc40eb. When a STUN agent receives a STUN message, it first checks that the
message obeys the rules of Section 6. It checks that the first two
bits are 0, that the magic cookie field has the correct value, that
the message length is sensible, and that the method value is a
supported method. If the message-class is Success Response or Error
Response, the agent checks that the transaction ID matches a
transaction that is still in progress. If the FINGERPRINT extension
is being used, the agent checks that the FINGERPRINT attribute is
present and contains the correct value. If any errors are detected,
the message is silently discarded. In the case when STUN is being
multiplexed with another protocol, an error may indicate that this is
not really a STUN message; in this case, the agent should try to
parse the message as a different protocol.
This format for the key was chosen so as to enable a common The STUN agent then does any checks that are required by a
authentication database for SIP, which uses digest authentication authentication mechanism that the usage has specified (see
as defined in RFC 2617 [7] and STUN, as it is expected that Section 10.
credentials are usually stored in their hashed forms.
The NONCE is included in the request only if a short or long term Once the authentication checks are done, the STUN agent checks for
credential is being used, and only if the STUN request is a retry as unknown attributes and known-but-unexpected attributes in the
a consequence of a previous error response which provided the client message. Unknown comprehension-optional attributes MUST be ignored
with a NONCE. by the agent. Known-but-unexpected attributes SHOULD be ignored by
the agent. Unknown comprehension-required attributes cause
processing that depends on the message-class and is described below.
For TCP and TLS-over-TCP, the client opens a TCP connection to the At this point, further processing depends on the message class of the
server. The TLS_RSA_WITH_AES_128_CBC_SHA ciphersuite MUST be request.
supported at a minimum by implementers when TLS is used with STUN.
Implementers MAY also support any other ciphersuite. When it
receives the TLS Certificate message, the client SHOULD verify the
certificate and inspect the site identified by the certificate. If
the certificate is invalid, revoked, or if it does not identify the
appropriate party, the client MUST NOT send the STUN message or
otherwise proceed with the STUN transaction. The client MUST verify
the identity of the server. To do that, it follows the
identification procedures defined in Section 3.1 of RFC 2818 [4].
Those procedures assume the client is dereferencing a URI. For
purposes of usage with this specification, the client treats the
domain name or IP address used in Section 8.1 as the host portion of
the URI that has been dereferenced. If DNS was not used, the client
MUST be configured with a set of authorized domains whose
certificates will be accepted.
When STUN is being multiplexed on the same transport address as 7.3.1. Processing a Request
application data, and there are valid application layer data packets
which could be confused with STUN packets (because, for example, bits
32 through 63 can contain an arbitrary binary value which might be
equal to 0x2112A442), the FINGERPRINT attribute MUST be present.
Otherwise, its inclusion is RECOMMENDED.
Next, the client sends the request. For UDP-based requests, If the request contains one or more unknown comprehension-required
reliability is accomplished through client retransmissions, following attributes, the server replies with an error response with an error
the procedure in Section 7.1. For TCP (including TLS over TCP), code of 420 Unknown attributes, and includes an UNKNOWN-ATTRIBUTES
there are no retransmissions. attribute in the response that lists the unknown comprehension-
required attributes.
For TCP and TLS over TCP, the client MAY send multiple requests on The server then does any additional checking that the method or the
the connection. When using TCP or TLS over TCP, the client SHOULD specific usage requires. If all the checks succeed, the server
keep the connection open until it has no further requests to send, formulates a success response as described below.
and has no plans to use any resources (such as a mapped address or
relayed address [16]) learned though STUN requests sent over that
connection.
Regardless of the transport protocol, a client MAY pipeline requests If the request uses UDP transport and is a retransmission of a
(that is, it can have multiple requests outstanding at the same request for which the server has already generated a success response
time). within the last 10 seconds, the server MUST retransmit the same
success response. One way for a server to do this is to remember all
transaction IDs received over UDP and their corresponding responses
in the last 10 seconds. Another way is to reprocess the request and
recompute the response. The latter technique MUST only be applied to
requests which are idempotent and result in the same success response
for the same request. The Binding method is considered to idempotent
in this way (even though certain rare network events could cause the
reflexive transport address value to change). Extensions to STUN
SHOULD state whether their request types have this property or not.
8.3.2. Processing Responses 7.3.1.1. Forming a Success or Error Response
Once the client has received a response to its request that it did When forming the response (success or error), the server follows the
not discard, it MUST discard any further responses for the same rules of section 6. The method of the response is the same as that
request. of the request, and the message class is either "Success Response" or
"Error Response".
All responses that were not discarded, whether success responses or For an error response, the server MUST add an ERROR-CODE attribute
error responses, MUST first be authenticated by the client. containing the error code specified in the processing above. The
Authentication is performed by first comparing the Transaction ID of reason phrase is not fixed, but SHOULD be something suitable for the
the response to an oustanding request. If there is no match, the error code. For certain errors, additional attributes are added to
client MUST discard the response. Then the client SHOULD check the the message. These attributes are spelled out in the description
response for a MESSAGE-INTEGRITY attribute. If not present, and the where the error code is specified. For example, for an error code of
client placed a MESSAGE-INTEGRITY attribute into the associated 420 Unknown Attribute, the server MUST include an UNKNOWN-ATTRIBUTES
request, it MUST discard the response. If MESSAGE-INTEGRITY is attribute. Certain authentication errors also cause attributes to be
present, the client computes the HMAC over the response as described added (see Section 10). Extensions may define other errors and/or
in Section 11.4. The key that is used MUST be same as used to additional attributes to add in error cases.
compute the MESSAGE-INTEGRITY attribute in the request. If the
client did not place a MESSAGE-INTEGRITY attribute into the request,
it MUST ignore the MESSAGE-INTEGRITY attribute in the response and
continue processing the response.
If the computed HMAC matches the one from the response, processing If the server authenticated the request using an authentication
continues. mechanism, then the server SHOULD add the appropriate authentication
attributes to the response (see Section 10).
If the response is an Error Response, the client checks the response The server also adds any attributes required by the specific method
code from the ERROR-CODE attribute of the response. For a 400 (Bad or usage. In addition, the server SHOULD add a SERVER attribute to
Request) response code, the client SHOULD display the reason phrase the message.
to the user. For a 420 (Unknown Attribute) response code, the client
SHOULD retry the request, this time omitting any attributes listed in
the UNKNOWN-ATTRIBUTES attribute of the response.
If the client receives a 401 (Unauthorized) response and had not For the Binding method, no additional checking is required unless the
included a MESSAGE-INTEGRITY attribute in the request, it is an usage specifies otherwise. When forming the success response, the
indication from the server that credentials are required. If the server adds a XOR-MAPPED-ADDRESS attribute to the response, where the
REALM attribute was present in the response, it is a signal to the contents of the attribute are the source transport address of the
client to use a long term shared secret and retry the request. The request message. For UDP, this is the source IP address and source
client SHOULD retry the request, using the username and password UDP port of the request message. For TCP and TLS-over-TCP, this is
associated with the REALM (this username and password are assumed to the source IP address and source TCP port of the TCP connection as
be pre-provisioned into the client through some other means). If the seen by the server.
REALM attribute was absent in the response, it is a signal to the
client to use a short term shared secret and retry the request. If
the client doesn't have a short term shared secret, it SHOULD use the
Shared Secret request to obtain one, and then retry the request with
the username and password obtained as a result.
If the client receives a 401 (Unauthorized) response but had included 7.3.1.2. Sending the Success or Error Response
a MESSAGE-INTEGRITY attribute in the request, there has been an
unrecoverable error. This shouldn't ever happen, but if it does, the
client SHOULD NOT retry the request.
If the client receives a 432 (Missing Username) response, and the The response (success or error) is sent over the same transport as
client had omitted the USERNAME from the request but included a the request was received on. If the request was received over UDP,
MESSAGE-INTEGRITY, the client SHOULD retry the request and include the destination IP address and port of the response is the source IP
both MESSAGE-INTEGRITY and USERNAME. If the client receives a 432 address and port of the received request message, and the source IP
(Missing Username) but had included both MESSAGE-INTEGRITY and address and port of the response is equal to the destination IP
USERNAME in the request, there has been an unrecoverable error. This address and port of the received request message. If the request was
shouldn't ever happen, but if it does, the client SHOULD NOT retry received over TCP or TLS-over-TCP, the response is sent back on the
the request. same TCP connection as the request was received on.
If the client receives a 435 (Missing Nonce) response, but had 7.3.2. Processing an Indication
included a NONCE in the request, an unrecoverable error has occurred
and the client SHOULD NOT retry. However, if it had omitted the
NONCE in the request and received a 435, or it had included the NONCE
but received a 438, it is a request from the server to retry using
the same credential, but with a different nonce. The client SHOULD
retry the request.
If the client receives a 430 (Stale Credentials) response, it means If the indication contains unknown comprehension-required attributes,
that the client used a short term credential that has expired. If the indication is discarded and processing ceases.
the client had submitted the request using a short term credential
obtained from a Shared Secret request, the client SHOULD generate a
new Shared Secret request to obtain a new short term credential and
then retry the request with that credential. Note that the Shared
Secret request may or may not go to the same server which generated
the 430 (Stale Credentials) response; the server that receives the
Shared Secret request is determined by the DNS procedures defined
above. If a 430 (Stale Credentials) response was received and the
client had used a short term credential provided through some other
means, the client SHOULD obtain a new short term credential using
that mechanism. If the client had not used a short term credential
in the request, the 430 (Stale Credentials) error is unrecoverable
and the request SHOULD NOT be retried.
For a 431 (Integrity Check Failure) response code, the client SHOULD The server then does any additional checking that the method or the
alert the user, and if a short term credential obtained from a Shared specific usage requires. If all the checks succeed, the server then
Secret request had been used previously, the client MAY try the processes the indication. No response is generated for an
request again after obtaining a new short term username and password. indication.
If the client receives a 433 (Use TLS) response, and the request was For the Binding method, no additional checking or processing is
a Shared Secret request which was not sent over TLS, the client required, unless the usage specifies otherwise. The mere receipt of
SHOULD retry the request, and MUST send it using TLS. If this the message by the server has refreshed the "bindings" in the
response is received to any other request except for a Shared Secret intervening NATs.
request, or if the client had sent the Shared Secret request over
TLS, it is an unrecoverable error and the client SHOULD NOT retry.
If the client receives a 434 (Missing Realm) response, and had Since indications are not re-transmitted over UDP (unlike requests),
omitted the REALM in the request, but had included MESSAGE-INTEGRITY, there is no need to handle re-transmissions of indications at the
it is an indication that, though a short-term credential was used for server.
the request, the server desires the client to use a long term
credential. The client SHOULD retry the request using the username
and password associated with the REALM. If the 434 (Missing Realm)
was received but the request had contained a REALM, and the REALM in
the response differs from the REALM in the request, the client SHOULD
retry using the username and password associated with the REALM in
the response. If the REALMS were equal, this is an unrecoverable
error and the client SHOULD NOT retry.
It the client receives a 436 (Unknown Username) response, it means 7.3.3. Processing a Success Response
that the username it provided in the request is unknown. For usages
where the username was collected from the user, the client SHOULD
alert the user. The client SHOULD NOT retry with the same username.
If the username was obtained using the Shared Secret request, the
client SHOULD obtain a new credential and retry. However, if the
retries are repeatedly rejected with a 436 (Unknown Username), it
SHOULD cease retrying.
For error responses which can contain a NONCE, if the error response If the success response contains unknown comprehension-required
results in a retry, the client MUST include the NONCE in a subsequent attributes, the response is discarded and the transaction is
retry. Furthermore, the client SHOULD cache the nonce, and continue considered to have failed.
using it in subsequent requests sent to the same server, identified
by transport address.
For a 300 (Try Alternate) response code, the client SHOULD attempt a The client then does any additional checking that the method or the
new transaction to the server indicated in the ALTERNATE-SERVER specific usage requires. If all the checks succeed, the client then
attribute. The client SHOULD reuse its credentials (username and processes the success response.
password) when retrying. This is useful for load balancing requests
across a STUN server cluster, when those requests require some amount
of resources to process. Though this specification allows the 300
(Try Alternate) response to be applied to Binding Requests, it is
generally not useful to do so, since the work of redirecting a
Binding Request is equal to, if not more than, the work of just
processing the Binding Request. Consequently, the 300 (Try
Alternate) response code is targeted for other usages of STUN, such
as the relay usage [16].
For a 500 (Server Error) response code, the client MAY wait several For the Binding method, the client checks that the XOR-MAPPED-ADDRESS
seconds and then retry the request on the same server. Or, if the attribute is present in the response. The client checks the address
server was learned through DNS SRV records, the client MAY try the family specified. If it is an unsupported address family, the
request on the next server in the list. The same username and attribute SHOULD be ignored. If it is an unexpected but supported
password MAY be used. For a 600 (Global Failure) response code, address family (for example, the Binding transaction was sent over
client MUST NOT retry the request on this server, or if the server IPv4, but the address family specified is IPv6), then the client MAY
was learned through DNS, any other server found through the DNS accept and use the value.
resolution procedures.
Unknown response codes between 300 and 399 are treated like a 300. 7.3.4. Processing an Error Response
Unknown response codes between 400 and 499 are treated like a 400,
unknown response codes between 500 and 599 are treated like a 500,
and unknown response codes between 600 and 699 are treated like a
600. Any response between 100 and 299 MUST result in the cessation
of request retransmissions, but otherwise is discarded.
Unknown optional attributes in a response (greater than 0x7FFF) MUST If the error response contains unknown comprehension-required
be ignored by the STUN client. Responses containing unknown attributes, or if the error response does not contain an ERROR-CODE
mandatory attributions (less than or equal to 0x7FFF) MUST be attribute, then the transaction is simply considered to have failed.
discarded and considered immediately as a failed transaction.
For a success response, the client SHOULD cache any nonce present in The client then does any processing specified by the authentication
the response, and continue using it in subsequent requests sent to mechanism (see Section 10). This may result in a new transaction
the same server, identified by transport address. attempt.
8.3.3. Timeouts The processing at this point depends on the error-code, the method,
and the usage; the following are the default rules:
If the STUN transaction times out without receipt of a response, the o If the error code is 300 through 399, the client SHOULD consider
client SHOULD consider it a failure and retry the request to the next the transaction as failed unless the ALTERNATE-SERVER extension is
server in the list of servers from the DNS SRV response, as specified being used. See Section 11.
in RFC 2782.
8.4. Indication Transactions o If the error code is 400 through 499, the client declares the
transaction failed; in the case of 420, the response should
contain a UNKNOWN-ATTRIBUTES attribute that gives additional
information.
This section applies to client and server behavior for sending an o If the error code is 500 through 599, the client MAY resend the
Indication message. request; clients that do so MUST limit the number of times they do
this. Any other error code causes the client to consider the
transaction failed.
The client or server follows the syntax rules defined in Section 6 8. FINGERPRINT Mechanism
and the transmission rules of Section 7. The message class MUST be
an indication.
Indication messages cannot be challenged or rejected. Consequently, This section describes an optional mechanism for STUN that aids in
they cannot be authenticated using long term credentials. If a STUN distinguishing STUN messages from packets of other protocols when the
usage specifies that authentication is needed for an indication two are multiplexed on the same transport address. This mechanism is
message, it can only be done using a short term credential. In that optional, and a STUN usage must describe if and when it is used.
case, the client or server MUST add a MESSAGE-INTEGRITY and USERNAME
attribute to the Request message. The key for MESSAGE-INTEGRITY is
the password.
When STUN is being multiplexed on the same transport address as In some usages, STUN messages are multiplexed on the same transport
application data, and there are valid application layer data packets address as other protocols, such as RTP. In order to apply the
which could be confused with STUN packets (because, for example, bits processing described in Section 7, STUN messages must first be
32 through 63 can contain an arbitrary binary value which might be separated from the application packets. Section 6 describes three
equal to 0x2112A442), the FINGERPRINT attribute MUST be present. fixed fields in the STUN header that can be used for this purpose.
However, in some cases, these three fixed fields may not be
sufficient.
Otherwise, its inclusion is RECOMMENDED. When the FINGERPRINT extension is used, an agent includes the
FINGERPRINT attribute in messages it sends to another agent.
Section 14.5 describes the placement and value of this attribute.
When the agent receives what it believes is a STUN message, then, in
addition to other basic checks, the agent also checks that the
message contains a FINGERPRINT attribute and that the attribute
contains the correct value (see Section 7.3. This additional check
helps the agent detect messages of other protocols that might
otherwise seem to be STUN messages.
Typically, indication messages are sent to the same transport 9. DNS Discovery of a Server
address, or over the same TCP connections as a previous request
message. However, a usage can specify that indication messages are
sent based on a DNS query, in which case the discovery procedures in
Section 8.1 are followed, along with the TCP/TLS connection
establishment procedures defined in Section 8.3.1.
Indication message types are not sent reliably, do not elicit a This section describes an optional procedure for STUN that allows a
response from the server, and are not retransmitted. client to use DNS to determine the IP address and port of a server.
A STUN usage must describe if and when this extension is used. To
use this procedure, the client must have a domain name and a service
name; the usage must also describe how the client obtains these.
For TCP and TLS over TCP, the client or server MAY send multiple When a client wishes to locate a STUN server in the public Internet
indications on the connection. When using TCP or TLS over TCP, the that accepts Binding Request/Response transactions, the SRV service
client SHOULD close the connection as soon as it determines it has no name is "stun". STUN usages MAY define additional DNS SRV service
further messages to send to the server. names.
By definition, since indications do not generate a response, they can The domain name is resolved to a transport address using the SRV
be pipelined, regardless of the transport protocol. procedures specified in [RFC2782]. The DNS SRV service name is the
service name provided as input to this procedure. The protocol in
the SRV lookup is the transport protocol the client will run STUN
over: "udp" for UDP, "tcp" for TCP, and "tls" for TLS-over-TCP. If,
in the future, additional SRV records are defined for TLS over other
transport protocols, those will need to utilize an SRV transport
token of the form "tls-foo" for transport protocol "foo".
9. Server Behavior The procedures of RFC 2782 are followed to determine the server to
contact. RFC 2782 spells out the details of how a set of SRV records
are sorted and then tried. However, RFC2782 only states that the
client should "try to connect to the (protocol, address, service)"
without giving any details on what happens in the event of failure.
When following these procedures, if the STUN transaction times out
without receipt of a response, the client SHOULD retry the request to
the next server in the list of servers from the DNS SRV response.
Such a retry is only possible for request/response transmissions,
since indication transactions generate no response or timeout.
As with clients, server behavior depends on whether it is a request/ The default port for STUN requests is 3478, for both TCP and UDP.
response transaction or indication. Administrators SHOULD use this port in their SRV records for UDP and
TCP, but MAY use others. There is no default port for STUN over TLS,
however a STUN server SHOULD use a port number for TLS different from
3478 so that the server can determine whether the first message it
will receive after the TCP connection is set up, is a STUN message or
a TLS message.
9.1. Request/Response Transactions If no SRV records were found, the client performs an A or AAAA record
lookup of the domain name. The result will be a list of IP
addresses, each of which can be contacted at the default port using
UDP or TCP, independent of the STUN usage. For usages that require
TLS, lack of SRV records is equivalent to a failure of the
transaction, since the request or indication MUST NOT be sent unless
SRV records provided a transport address specifically for TLS.
9.1.1. Receive Request Message 10. Authentication and Message-Integrity Mechanisms
A STUN server MUST be prepared to receive request messages on the This section defines two mechanisms for STUN that a client and server
transport address that will be discovered by the STUN client when the can use to provide authentication and message-integrity; these two
STUN client follows its discovery procedures described in mechanisms are known as the short-term credential mechanism and the
Section 8.1. Depending on the usage, the STUN server will listen for long-term credential mechanism. These two mechanisms are optional,
incoming UDP STUN messages, incoming TCP STUN messages, or incoming and each usage must specify if and when these mechanisms are used.
TLS exchanges followed by TCP STUN messages. An overview of these two mechanisms is given in .
If the request is a retransmission of a request for which the server Each mechanism specifies the additional processing required to use
has already generated a response within the last 10 seconds, the that mechanism, extending the processing specified in Section 7. The
server MUST retransmit the response. A server can do this either by additional processing occurs in three different places: when forming
remembering the response it transmitted, or by re-processing the a message; when receiving a message immediately after the the basic
request and computing the response. The latter technique can only be checks have been performed; and when doing the detailed processing of
applied to requests which are idempotent and would result in the same error responses.
response for the same request. This is the case for the Binding
Request, but not for the Shared Secret Request. Extensions to STUN
SHOULD state whether their request types have this property or not.
When a STUN request is received, the server determines the usage. 10.1. Short-Term Credential Mechanism
The usages describe how the STUN server makes this determination. The short-term credential mechanism assumes that, prior to the STUN
transaction, the client and server have used some other protocol to
exchange a credential in the form of a username and password. This
credential is time-limited. The time-limit is defined by the usage.
As an example, in the ICE usage [I-D.ietf-mmusic-ice], the two
endpoints use out-of-band signaling to agree on a username and
password, and this username and password is applicable for the
duration of the media session.
Based on the usage, the server determines whether the request This credential is used to form a message integrity check in each
requires any authentication and message integrity checks. It can request and in many responses. There is no challenge and response as
require none, short-term credential based authentication, or long- in the long term mechanism; consequently, replay is prevented by
term credential authentication. virtue of the time-limited nature of the credential.
If authentication is required, the server checks for the presence of 10.1.1. Forming a Request or Indication
the MESSAGE-INTEGRITY attribute. If not present, the server
generates an error response with an ERROR-CODE attribute and a
response code of 401 (Unauthorized). If the server wishes the client
to use a short term credential, the REALM is omitted from the
response. If the server wishes the client to use a long term
credential, the REALM is included in the response containing a realm
from which the username and password are scoped [7].
If the MESSAGE-INTEGRITY attribute was present, the server checks for For a request or indication message, the agent MUST include the
the existence of the USERNAME attribute. If it was not present, the USERNAME and MESSAGE-INTEGRITY attributes in the message. The HMAC
server MUST generate an error response. The error response MUST for the MESSAGE-INTEGRITY attribute is computed as described in
include an ERROR-CODE attribute with a response code of 432 (Missing Section 14.4. The key for the HMAC is the password. Note that the
Username). If the server is using a long term credential for password is never included in the request or indication.
authentication, the response MUST include a REALM. If the server is
using a short-term credential, it MUST NOT include a REALM in the
response.
If the server is using long term credentials for authentication, and 10.1.2. Receiving a Request or Indication
the request contained the MESSAGE-INTEGRITY and USERNAME attributes,
the server checks for the existence of the REALM attribute. If the
attribute is not present, the server MUST generate an error response.
That error response MUST include an ERROR-CODE attribute with
response code of 434 (Missing Realm). That error response MUST also
include a REALM attribute.
If the REALM attribute was present and the server is using a long After the agent has done the basic processing of a message, the agent
term credential for authentication, the server checks for the performs the checks listed below in order specified:
existence of the NONCE attribute. If the NONCE attribute is not
present, the server MUST generate an error response. That error
response MUST include an ERROR-CODE attribute with a response code of
435 (Missing Nonce). That error response MUST include a REALM
attribute. If the NONCE was absent and the server is authenticating
with short term credentials, the server MAY generate an error
response with an ERROR-CODE attribute with a response code of 435
(Missing Nonce). This response MUST include a NONCE. If the NONCE
was present in the request, but the server has determined it is
stale, the server MUST generate an error response with an ERROR-CODE
attribute with a response code of 438 (Stale Nonce).
If the server is authenticating the request with a short term o If the message does not contain both a MESSAGE-INTEGRITY and a
credential, it checks the value of the USERNAME field. If the USERNAME attribute:
USERNAME was previously valid but has expired, the server generates
an error response with an ERROR-CODE attribute with a response code
of 430 (Stale Credentials). If the server is authenticating with
either short or long term credentials, it determines whether the
USERNAME contains a known entity, and in the case of a long-term
credential, known within the realm of the REALM attribute of the
request. If the USERNAME is unknown, the server generates an error
response with an ERROR-CODE attribute with a response code of 436
(Unknown Username). For authentication using long-term credentials,
that error response MUST include a REALM attribute. For
authentication using short-term credentials, it MUST NOT include a
REALM.
At this point, if the server is doing authentication, the request * If the message is a request, the server MUST reject the request
contains everything needed for that purpose. The server computes the with an error response. This response MUST use an error code
HMAC over the request as described in Section 11.4. The key depends of 400.
on the credential. For short-term credentials, it equals the
password associated with the username. For long term credentials, it
is computed as described in Section 8.3.1.
If the computed HMAC differs from the one from the MESSAGE-INTEGRITY * If the message is an indication, the server MUST silently
attribute in the request, the server MUST generate an error response discard the indication.
with an ERROR-CODE attribute with a response code of 431 (Integrity
Check Failure). If long term credentials are being used for
authentication, this response MUST include a REALM attribute. If
short term credentials are being used, it MUST NOT include a REALM.
When an error response is to be generated by the server as a o If the USERNAME does not contain a username value currently valid
consequence of authentication problems (error codes 401, 432, 434, within the server:
435, 430 and 436, and the REALM is present in the response
(signifying the usage of a long term credential), the server MUST
include a NONCE attribute in the response. The nonce includes a
random value that the server wishes the client to reflect back in a
subsequent request (and therefore include in the message integrity
computation). When the REALM is absent in the response, the server
MAY include a NONCE in the response if it wishes to use nonces along
with short-term shared secrets (with the exception of 435, where
NONCE is mandatory even for short term credentials). However, there
is little reason to do so, since the short-term password is, by
definition, short-term, and thus additional temporal scoping through
the nonce is not needed.
At this point, the request has been authentication checked and * If the message is a request, the server MUST reject the request
integrity verified. with an error response. This response MUST use an error code
of 401.
If the method of the request is unknown to the server, it MUST * If the message is an indication, the server MUST silently
generate an error response which includes an ERROR-CORE attribute discard the indication.
with a 400 response code.
Next, the server MUST check for any mandatory attributes in the o Using the password associated with the username, compute the value
request (values less than or equal to 0x7fff) which it does not for the message-integrity as described in Section 14.4. If the
understand. If it encounters any, the server MUST generate an error resulting value does not match the contents of the MESSAGE-
response, and it MUST include an ERROR-CODE attribute with a 420 INTEGRITY attribute:
response code. Any attributes that are known, but are not supposed
to be present in a message (MAPPED-ADDRESS in a request, for example)
MUST be ignored.
9.1.2. Constructing the Response * If the message is a request, the server MUST reject the request
with an error response. This response MUST use an error code
of 431.
To construct the STUN Response the STUN server follows the message * If the message is an indication, the server MUST silently
structure described in Section 6. The message type MUST indicate discard the indication.
either a success response or error response class and MUST indicate
the same method as the request. The server MUST copy the transaction
ID from the request to the response.
The attributes that get added to the response depend on the type of If these checks pass, the server continues to process the request or
response. See Figure 5 for a summary. indication. Any response generated by the server MUST include the
MESSAGE-INTEGRITY attribute, computed using the username and password
utilized to authenticate the request.
If the response is a type which can carry either MAPPED-ADDRESS or If any of the checks fail, the server MUST NOT include a MESSAGE-
XOR-MAPPED-ADDRESS (the Binding Response as defined in this INTEGRITY or USERNAME attribute in the error response.
specification meets that criteria), the server examines the magic
cookie in the STUN header. If it has the value 0x2112A442, it
indicates that the client supports this version of the specification.
The server MUST insert a XOR-MAPPED-ADDRESS into the response,
carrying the exclusive-or of the source transport address and magic
cookie. If the magic cookie did not have this value, it indicates
that the client supports the previous version of this specification.
The server MUST insert a MAPPED-ADDRESS attribute into the response,
carrying the souce transport address from the request. Insertion of
either XOR-MAPPED-ADDRESS or MAPPED-ADDRESS happens regardless of the
transport protocol used for the request.
XOR-MAPPED-ADDRESS and MAPPED-ADDRESS differ only in their encoding 10.1.3. Receiving a Response
of the transport address. The former, as implied by the name,
encodes the transport address by exclusive-or'ing them with the magic
cookie. The latter encodes them directly in binary. RFC 3489
originally specified only MAPPED-ADDRESS. However, deployment
experience found that some NATs rewrite the 32-bit binary payloads
containing the NAT's public IP address, such as STUN's MAPPED-ADDRESS
attribute, in the well-meaning but misguided attempt at providing a
generic ALG function. Such behavior interferes with the operation of
STUN and also causes failure of STUN's message integrity checking.
If the request contained the MESSAGE-INTEGRITY attribute, the server The processing here takes place prior to the processing in
MUST include a MESSAGE-INTEGRITY attribute in a successful response. Section 7.3.3 or Section 7.3.4.
The MESSAGE-INTEGRITY attribute MUST use the same username and The client looks for the MESSAGE-INTEGRITY attribute in the response.
password used to authenticate the request. If long term credentials If present, the client computes the message integrity over the
were used, the response MUST include a NONCE. For short term response as defined in Section 14.4, using the same password it
credentials, a NONCE MAY be included. utilized for the request. If the resulting value matches the
contents of the MESSAGE-INTEGRITY attribute, the response is
considered authenticated. If the value does not match, or if
MESSAGE-INTEGRITY was absent, the response MUST be discarded, as if
it was never received. This means that retransmits, if applicable,
will continue.
The server SHOULD include a SERVER attribute in all responses, 10.2. Long-term Credential Mechanism
indicating the identity of the server generating the response. This
is useful for diagnostic purposes.
When STUN is being multiplexed on the same transport address as The long-term credential mechanism relies on a long term credential,
application data, and there are valid application layer data packets in the form of a username and password, that are shared between
which could be confused with STUN packets (because, for example, bits client and server. The credential is considered long-term since it
32 through 63 can contain an arbitrary binary value which might be is assumed that it is provisioned for a user, and remains in effect
equal to 0x2112A442), the FINGERPRINT attribute MUST be present in until the user is no longer a subscriber of the system, or is
the response. Otherwise, its inclusion is RECOMMENDED. changed. This is basically a traditional "log-in" username and
password given to users.
In cases where the server cannot handle the request, due to Because these usernames and passwords are expected to be valid for
exhaustion of resources, the server MAY generate a 300 response with extended periods of time, replay prevention is provided in the form
an ALTERNATE-SERVER attribute. This attribute identifies an of a digest challenge. In this mechanism, the client initially sends
alternate server which can service the requests. It is not expected a request, without offering any credentials or any integrity checks.
that 300 responses or this attribute would be used by the methods The server rejects this request, providing the user a realm (used to
defined in this specification. guide the user or agent in selection of a username and password) and
a nonce. The nonce provides the replay protection. It is a cookie,
selected by the server, and encoded in such a way as to indicate a
duration of validity or client identity from which it is valid. The
client retries the request, this time including its username, the
realm, and echoing the nonce provided by the server. The client also
includes a message-integrity, which provides an HMAC over the entire
request, including the nonce. The server validates the nonce, and
checks the message-integrity. If they match, the request is
authenticated. If the nonce is no longer valid, it is considered
"stale", and the server rejects the request, providing a new nonce.
9.1.3. Sending the Response In subsequent requests to the same server, the client reuses the
nonce, username, realm and password it used previously. In this way,
subsequent requests are not rejected until the nonce becomes invalid
by the server, in which case the rejection provides a new nonce to
the client.
All UDP response messages are sent to the transport address the Note that the long-term credential mechanism cannot be used to
associated Binding Request came from, and sent from the transport protect indications, since indications cannot be challenged. Usages
address the Binding Request was sent to. All TCP or TLS over TCP utilizing indications must either use a short-term credential, or
responses messages are sent on the TCP connections that the request omit authentication and message integrity for them.
arrived on.
9.2. Indication Transactions Since the long-term credential mechanism is susceptible to offline
dictionary attacks, deployments SHOULD utilize strong passwords.
Indication messages cause the server to change its state. Indication For STUN servers used in conjunction with SIP servers, it is
message types do not cause the server to send a response message. desirable to use the same credentials for authentication to the SIP
server and STUN server. Typically, SIP systems utilizing SIP's
digest authentication mechanism do not actually store the password in
the database. Rather, they store a value called H(A1), which is
computed as:
A STUN server MUST be prepared to receive indication messages on the H(A1) = MD5(username ":" realm ":" password)
transport address that will be discovered by the STUN client when the
STUN client follows its discovery procedures described in
Section 8.1. Depending on the usage, the STUN server will listen for
incoming UDP STUN messages, incoming TCP STUN messages, or incoming
TLS exchanges followed by TCP STUN messages.
When a STUN indication is received, the server determines the usage. If a system wishes to utilize this credential, the STUN password
The usages describe how the STUN server makes this determination. would be computed by taking the user-entered username and password,
and using H(A1) as the STUN password. It is RECOMMENDED that clients
utilize this construction for the STUN password.
Based on the usage, the server determines whether the indication 10.2.1. Forming a Request
requires any authentication and message integrity checks. It can
require none or short-term credential based authentication. If
short-term credentials are utilized, the server follows the same
procedures as defined in Section 9.1.1, but if those procedures
require transmission of an error response, the server MUST instead
silently discard the indication.
Once authenticated (if authentication was in use), the processing of There are two cases when forming a request. In the first case, this
the indication message depends on the method. This specification is the first request from the client to the server (as identified by
doesn't define any indication messages. its IP address and port). In the second case, the client is
submitting a subsequent request once a previous request/response
transaction has completed successfully.
10. Demultiplexing of STUN and Application Traffic 10.2.1.1. First Request
In the binding refresh usage, STUN traffic is multiplexed on the same If the client has not completed a successful request/response
transport address as application traffic, such as RTP. In order to transaction with the server, it SHOULD omit the USERNAME, MESSAGE-
apply the processing described in this specification, STUN messages INTEGRITY, REALM, and NONCE attributes. In other words, the very
must first be separated from the application packets. This first request is sent as if there were no authentication or message
disambiguation is done identically for all message types. integrity applied.
First, all STUN messages start with two bits equal to zero. If STUN 10.2.1.2. Subsequent Requests
is being multiplexed with application traffic where it is known that
the topmost two bits are never zeroes, the presence of these two
zeroes signals STUN traffic.
If this mechanism doesn't suffice, the magic cookie can be used. All Once a request/response transaction has completed successfully, the
STUN messages have the value 0x2112A442 as the second 32 bit word. client will have been been presented a realm and nonce by the server,
If the application traffic can not have this value as the second 32 and selected a username and password with which it authenticated.
bit word, then any packets with this value are STUN packets. Even if The client SHOULD cache the username, password, realm, and nonce for
the application packet can have this value (for example, in cases subsequent communications with the server. When the client sends a
where the application packets contain random binary data), there is subsequent request, it SHOULD include the USERNAME, REALM, and NONCE
only a one in 2^32 chance that an application packet will have a attributes with these cached values. It SHOULD include a MESSAGE-
value of 0x2112A442 in its second 32 bit word. If this probability INTEGRITY attributed, computed as described in Section 14.4 using the
is deemed sufficiently small for the application at hand (for cached password as the key.
example, it is considered adequate for Voice over IP applications),
then any packet with this value in its second 32 bit word is
processed as a STUN packet.
However, a mis-classification of 1 in 2^32 may still be too high for 10.2.2. Receiving a Request
some usages of STUN. Consequently, STUN messages can contain a
FINGERPRINT attribute. This is a cryptographic hash over the
message, covering everything prior to the attribute. This attribute
is different from MESSAGE-INTEGRITY. The latter uses a keyed HMAC,
and thus requires a shared secret. FINGERPRINT does not use a
password, and can be computed just by examining the STUN message.
Thus, if a packet appears to be a STUN message because it has a value
of 0x2112A442 in its second 32 bit word, a client or server then
assumes the message is a STUN message, and computes the value for the
fingerprint. It then looks for the FINGERPRINT attribute in the
message, and if the value equals the computed value, the message is
considered to be a STUN message. If not, it is considered to be an
application packet.
11. STUN Attributes After the server has done the basic processing of a request, it
performs the checks listed below in the order specified:
To allow future revisions of this specification to add new attributes o If the message:
if needed, the attribute space is divided into optional and mandatory
ones. Attributes with values greater than 0x7fff are optional, which
means that the message can be processed by the client or server even
though the attribute is not understood. Attributes with values less
than or equal to 0x7fff are mandatory to understand, which means that
the client or server cannot successfully process the message unless
it understands the attribute.
The values of the message attributes are enumerated in Section 15. * does not contain a MESSAGE-INTEGRITY attribute,
The following figure indicates which attributes are present in which * OR, it contains a USERNAME whose value is not a valid username,
messages. An M indicates that inclusion of the attribute in the
message is mandatory, O means its optional, C means it's conditional
based on some other aspect of the message, and - means that the
attribute is not applicable to that message type.
Error the server MUST generate an error response with an error code of
Attribute Request Response Response Indication 401. This response MUST include a REALM value. It is RECOMENDED
_______________________________________________________ that the REALM value by the domain name of the provider of the
MAPPED-ADDRESS - C - - STUN server. The response MUST include a NONCE, selected by the
USERNAME C - - O server.
PASSWORD - C - -
MESSAGE-INTEGRITY O C C O
ERROR-CODE - - M -
ALTERNATE-SERVER - - C -
REALM C - C -
NONCE C - C -
UNKNOWN-ATTRIBUTES - - C -
XOR-MAPPED-ADDRESS - C - -
SERVER - O O O
REFRESH-INTERVAL - O - -
FINGERPRINT O O O O
Figure 5: Mandatory Attributes and Message Types o If the message contains a MESSAGE-INTEGRITY attribute, but is
missing the USERNAME, REALM or NONCE attributes, the server MUST
generate an error response with an error code of 400.
11.1. MAPPED-ADDRESS o If the NONCE is no longer valid, the server MUST generate an error
response with an error code of 438 (Stale Nonce). This response
MUST include a NONCE and REALM attribute.
The MAPPED-ADDRESS attribute indicates the mapped transport address. o Using the password associated with the username in the USERNAME
It consists of an eight bit address family, and a sixteen bit port, attribute, compute the value for the message-integrity as
followed by a fixed length value representing the IP address. If the described in Section 14.4. If the resulting value does not match
address family is IPv4, the address is 32 bits, in network byte the contents of the MESSAGE-INTEGRITY attribute, the server MUST
order. If the address family is IPv6, the address is 128 bits in reject the request with an error response. This response MUST use
network byte order. an error code of 401. It MUST include a REALM and NONCE
attribute.
The format of the MAPPED-ADDRESS attribute is: If these checks pass, the server continues to process the request or
indication. Any response generated by the server MUST include the
MESSAGE-INTEGRITY attribute, computed using the username and password
utilized to authenticate the request. The REALM, NONCE, and USERNAME
attributes SHOULD NOT be included.
0 1 2 3 10.2.3. Receiving a Response
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|x x x x x x x x| Family | Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Address (variable)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 6: Format of MAPPED-ADDRESS attribute The processing here takes place prior to the processing in
Section 7.3.3 or Section 7.3.4.
The address family can take on the following values: If the response is an error response, with an error code of 401
(Unauthorized), the client SHOULD retry the request with a new
transaction. This request MUST contain a USERNAME, determined by the
client as the appropriate username for the REALM from the error
response. The request MUST contain the REALM, copied from the error
response. The request MUST contain the NONCE, copied from the error
response. The request MUST contain the MESSAGE-INTEGRITY attribute,
computed using the password associated with the username in the
USERNAME attribute. The client MUST NOT perform this retry if it is
not changing the USERNAME or REALM or its associated password, from
the previous attempt.
0x01:IPv4 If the response is an error response with an error code of 438, the
0x02:IPv6 client MUST retry the request, using the new NONCE supplied in the
438 response. This retry MUST also include the USERNAME, REALM and
MESSAGE-INTEGRITY.
The port is a network byte ordered representation of the port the The client looks for the MESSAGE-INTEGRITY attribute in the response
request arrived from. (either success or failure). If present, the client computes the
message integrity over the response as defined in Section 14.4, using
the same password it utilized for the request. If the resulting
value matches the contents of the MESSAGE-INTEGRITY attribute, the
response is considered authenticated. If the value does not match,
or if MESSAGE-INTEGRITY was absent, the response MUST be discarded,
as if it was never received. This means that retransmits, if
applicable, will continue.
The first 8 bits of the MAPPED-ADDRESS are ignored for the purposes 11. ALTERNATE-SERVER Mechanism
of aligning parameters on natural 32 bit boundaries.
It is possible for an IPv4 host to receive a MAPPED-ADDRESS This section describes a mechanism in STUN that allows a server to
containing an IPv6 address, or for an IPv6 host to receive a MAPPED- redirect a client to another server. This extension is optional, and
ADDRESS containing an IPv4 address. Clients MUST be prepared for a usage must define if and when this extension is used. To prevent
this case. denial-of-service attacks, this extension MUST only be used in
situations where the client and server are using an authentication
and message-integrity mechanism.
11.2. USERNAME A server using this extension redirects a client to another server by
replying to a request message with an error response message with an
error code of 300 (Try Alternate). The server MUST include a
ALTERNATE-SERVER attribute in the error response. The error response
message MUST be authenticated, which in practice means the request
message must have passed the authentication checks.
The USERNAME attribute is used for message integrity. It identifies A client using this extension handles a 300 (Try Alternate) error
the shared secret used in the message integrity check. Consequently, code as follows. If the error response has passed the authentication
the USERNAME MUST be included in any request that contains the checks, then the client looks for a ALTERNATE-SERVER attribute in the
MESSAGE-INTEGRITY attribute. error response. If one is found, then the client considers the
current transaction as failed, and re-attempts the request with the
server specified in the attribute. The client SHOULD reuse any
authentication credentials from the old request in the new
transaction.
The USERNAME is also always present in a Shared Secret Response, 12. Backwards Compatibility with RFC 3489
along with the PASSWORD, which informs a client of a short term
password.
The value of USERNAME is a variable length opaque value. Note that, This section define procedures that allow a degree of backwards
as described above, if the USERNAME is not a multiple of four bytes compatible with the original protocol defined in RFC 3489 [RFC3489].
it is padded for encoding into the STUN message, in which case the This mechanism is optional, meant to be utilized only in cases where
attribute length represents the length of the USERNAME prior to a new client can connect to an old server, or vice-a-versa. A usage
padding. must define if and when this procedure is used.
11.3. PASSWORD Section 18 lists all the changes between this specification and RFC
3489 [RFC3489]. However, not all of these differences are important,
because "classic STUN" was only used in a few specific ways. For the
purposes of this extension, the important changes are the following.
In RFC 3489:
If the message type is Shared Secret Response it MUST include the o UDP was the only supported transport;
PASSWORD attribute.
The value of PASSWORD is a variable length opaque value. The o The field that is now the Magic Cookie field was a part of the
password returned in the Shared Secret Response is used as the HMAC transaction id field, and transaction ids were 128 bits long;
key in the MESSAGE-INTEGRITY attribute of a subsequent STUN
transaction. Note that, as described above, if the USERNAME is not a
multiple of four bytes it is padded for encoding into the STUN
message, in which case the attribute length represents the length of
the USERNAME prior to padding.
11.4. MESSAGE-INTEGRITY o The XOR-MAPPED-ADDRESS attribute did not exist, and the Binding
method used the MAPPED-ADDRESS attribute instead
The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [10] of the o There were two comprehension-required attributes, RESPONSE-ADDRESS
STUN message. The MESSAGE-INTEGRITY attribute can be present in any and CHANGE-REQUEST, that have been removed from this
STUN message type. Since it uses the SHA1 hash, the HMAC will be 20 specification.
bytes. The text used as input to HMAC is the STUN message, including
the header, up to and including the attribute preceding the MESSAGE-
INTEGRITY attribute. That text is then padded with zeroes so as to
be a multiple of 64 bytes. As a result, the MESSAGE-INTEGRITY
attribute is either the last attribute, or the next to last attribute
in any STUN message (depending on whether FINGERPRINT is present).
With the exception of the FINGERPRINT attribute, which appears after
MESSAGE-INTEGRITY, elements MUST ignore all other attributes that
follow MESSAGE-INTEGRITY.
The key used as input to HMAC depends on the STUN usage and the * These attributes are now part of the NAT Behavior Discovery
shared secret mechanism. usage.
11.5. FINGERPRINT 12.1. Changes to Client Processing
The FINGERPRINT attribute can be present in all STUN messages. It is A client that wants to interoperate with a [RFC3489] server SHOULD
computed as the CRC-32 of the STUN message up to (but excluding) the send a request message that uses the Binding method, contains no
FINGERPRINT attribute itself, xor-d with the 32 bit value 0x5354554e attributes, and uses UDP as the transport protocol to the server. If
(the XOR helps in cases where an application packet is also using successful, the success response received from the server will
CRC-32 in it). The 32 bit CRC is the one defined in ITU V.42 [9], contain a MAPPED-ADDRESS attribute rather than an XOR-MAPPED-ADDRESS
which has a generator polynomial of x32+x26+x23+x22+x16+x12+x11+x10+ attribute; other than this change, the processing of the response is
x8+x7+x5+x4+x2+x+1. When present, the FINGERPRINT attribute MUST be identical to the procedures described above.
the last attribute in the message.
11.6. ERROR-CODE 12.2. Changes to Server Processing
The ERROR-CODE attribute is present in the Binding Error Response and A STUN server can detect when a given Binding Request message was
Shared Secret Error Response. It is a numeric value in the range of sent from an RFC 3489 [RFC3489] client by the absence of the correct
100 to 699 plus a textual reason phrase encoded in UTF-8, and is value in the Magic Cookie field. When the server detects an RFC 3489
consistent in its code assignments and semantics with SIP [11] and client, it SHOULD copy the value seen in the Magic Cookie field in
HTTP [12]. The reason phrase is meant for user consumption, and can the Binding Request to the Magic Cookie field in the Binding Response
be anything appropriate for the response code. Recommended reason message, and insert a MAPPED-ADDRESS attribute instead of an XOR-
phrases for the defined response codes are presented below. MAPPED-ADDRESS attribute.
To facilitate processing, the class of the error code (the hundreds The client might, in rare situations, include either the RESPONSE-
digit) is encoded separately from the rest of the code. ADDRESS or CHANGE-REQUEST attributes. In these situations, the
server will view these as unknown comprehension-required attributes
and reply with an error response. Since the mechanisms utilizing
those attributes are no longer supported, this behavior is
acceptable.
0 1 2 3 13. STUN Usages
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0 |Class| Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reason Phrase (variable) ..
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The class represents the hundreds digit of the response code. The STUN by itself is not a solution to the NAT traversal problem.
value MUST be between 1 and 6. The number represents the response Rather, STUN defines a toolkit of functions that can be used inside a
code modulo 100, and its value MUST be between 0 and 99. larger solution. The term "STUN Usage" is used for any solution that
uses STUN as a component.
If the reason phrase has a length that is not a multiple of four At the time of writing, three STUN usages are defined: Interactive
bytes, it is padded for encoding into the STUN message, in which case Connectivity Establishment (ICE) [I-D.ietf-mmusic-ice], Client-
the attribute length represents the length of the entire ERROR-CODE initiated connections for SIP [I-D.ietf-sip-outbound], and NAT
attribute (including the reason phrase) prior to padding. Behavior Discovery [I-D.ietf-behave-nat-behavior-discovery]. Other
STUN usages may be defined in the future.
The following response codes, along with their recommended reason A STUN usage defines how STUN is actually utilized - when to send
phrases (in brackets) are defined at this time: requests, what to do with the responses, and which optional
procedures defined here (or in an extension to STUN) are to be used.
A usage would also define:
300 (Try Alternate): The client should contact an alternate server o Which STUN methods are used;
for this request.
400 (Bad Request): The request was malformed. The client should not o What authentication and message integrity mechanisms are used;
retry the request without modification from the previous
attempt.
401 (Unauthorized): The request did not contain a MESSAGE-INTEGRITY o What mechanisms are used to distinguish STUN messages from other
attribute. messages. When STUN is run over TCP, a framing mechanism may be
required;
420 (Unknown Attribute): The server did not understand a mandatory o How a STUN client determines the IP address and port of the STUN
attribute in the request. server;
430 (Stale Credentials): The request did contain a MESSAGE-INTEGRITY o Whether backwards compatibility to RFC 3489 is required;
attribute, but it used a shared secret that has expired. The
client should obtain a new shared secret and try again.
431 (Integrity Check Failure): The request contained a MESSAGE- o What optional attributes defined here (such as FINGERPRINT and
INTEGRITY attribute, but the HMAC failed verification. This ALTERNATE-SERVER) or in other extensions are required.
could be a sign of a potential attack, or client implementation
error.
432 (Missing Username): The request contained a MESSAGE-INTEGRITY In addition, any STUN usage must consider the security implications
attribute, but not a USERNAME attribute. Both USERNAME and of using STUN in that usage. A number of attacks against STUN are
MESSAGE-INTEGRITY must be present for integrity checks. known (see the Security Considerations section in this document) and
any usage must consider how these attacks can be thwarted or
mitigated.
433 (Use TLS): The Shared Secret request has to be sent over TLS, Finally, a usage must consider whether its usage of STUN is an
but was not received over TLS. example of the Unilateral Self-Address Fixing approach to NAT
traversal, and if so, address the questions raised in RFC 3424.
434 (Missing Realm): The REALM attribute was not present in the 14. STUN Attributes
request.
435 (Missing Nonce): The NONCE attribute was not present in the After the STUN header are zero or more attributes. Each attribute
request. MUST be TLV encoded, with a 16 bit type, 16 bit length, and value.
Each STUN attribute MUST end on a 32 bit boundary. As mentioned
above, all fields in an attribute are transmitted most significant
bit first.
436 (Unknown Username): The USERNAME supplied in the request is not 0 1 2 3
known or is not known to the server. 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Value (variable) ....
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
438 (Stale Nonce): The NONCE attribute was present in the request Figure 5: Format of STUN Attributes
but wasn't valid.
500 (Server Error): The server has suffered a temporary error. The The value in the Length field MUST contain the length of the Value
client should try again. part of the attribute, prior to padding, measured in bytes. Since
STUN aligns attributes on 32 bit boundaries, attributes whose content
is not a multiple of 4 bytes are padded with 1, 2 or 3 bytes of
padding so that its value contains a multiple of 4 bytes. The
padding bits are ignored, and may be any value.
600 (Global Failure): The server is refusing to fulfill the request. Any attribute type MAY appear more than once in a STUN message.
The client should not retry. Unless specified otherwise, the order of appearance is significant:
only the first occurance needs to be processed by a receiver, and any
duplicates MAY be ignored by a receiver.
11.7. REALM To allow future revisions of this specification to add new attributes
if needed, the attribute space is divided into two ranges.
Attributes with type values between 0x0000 and 0x7FFF are
comprehension-required attributes, which means that the STUN agent
cannot successfully process the message unless it understands the
attribute. Attributes with type values between 0x8000 and 0xFFFF are
comprehension-optional attributes, which means that those attributes
can be ignored by the STUN agent if it does not understand them.
The REALM attribute is present in requests and responses. It The STUN Attribute types defined by this specification are:
contains text which meets the grammar for "realm" as described in RFC
3261 [11], and will thus contain a quoted string (including the
quotes).
Presence of the REALM attribute in a request indicates that long-term Comprehension-required range (0x0000-0x7FFF):
credentials are being used for authentication. Presence in certain 0x0000: (Reserved)
error responses indicates that the server wishes the client to use a 0x0001: MAPPED-ADDRESS
long-term credential for authentication. 0x0006: USERNAME
0x0007: (Reserved; was PASSWORD)
0x0008: MESSAGE-INTEGRITY
0x0009: ERROR-CODE
0x000A: UNKNOWN-ATTRIBUTES
0x0014: REALM
0x0015: NONCE
0x0020: XOR-MAPPED-ADDRESS
11.8. NONCE Comprehension-optional range (0x8000-0xFFFF)
0x8022: SERVER
0x8023: ALTERNATE-SERVER
0x8028: FINGERPRINT
The NONCE attribute is present in requests and in error responses. The rest of this section describes the format of the various
It contains a sequence of qdtext or quoted-pair, which are defined in attributes defined in this specification.
RFC 3261 [11]. See RFC 2617 [7] for guidance on selection of nonce
values in a server.
11.9. UNKNOWN-ATTRIBUTES 14.1. MAPPED-ADDRESS
The UNKNOWN-ATTRIBUTES attribute is present only in an error response The MAPPED-ADDRESS attribute indicates a reflexive transport address
when the response code in the ERROR-CODE attribute is 420. of the client. It consists of an eight bit address family, and a
sixteen bit port, followed by a fixed length value representing the
IP address. If the address family is IPv4, the address MUST be 32
bits. If the address family is IPv6, the address MUST be 128 bits.
All fields must be in network byte order.
The attribute contains a list of 16 bit values, each of which The format of the MAPPED-ADDRESS attribute is:
represents an attribute type that was not understood by the server.
If the number of unknown attributes is an odd number, one of the
attributes MUST be repeated in the list, so that the total length of
the list is a multiple of 4 bytes.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute 1 Type | Attribute 2 Type | |0 0 0 0 0 0 0 0| Family | Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute 3 Type | Attribute 4 Type ... | |
| Address (32 bits or 128 bits) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 9: Format of UNKNOWN-ATTRIBUTES attribute Figure 7: Format of MAPPED-ADDRESS attribute
The address family can take on the following values:
11.10. XOR-MAPPED-ADDRESS 0x01:IPv4
0x02:IPv6
The XOR-MAPPED-ADDRESS attribute is present in responses. It The first 8 bits of the MAPPED-ADDRESS MUST be set to 0 and MUST be
provides the same information that would present in the MAPPED- ignored by receivers. These bits are present for aligning parameters
ADDRESS attribute but because the NAT's public IP address is on natural 32 bit boundaries.
obfuscated through the XOR function, STUN messages are able to pass
through NATs which would otherwise interfere with STUN.
This attribute MUST always be present in a Binding Response and may This attribute is used only by servers for achieving backwards
be used in other responses as well. Usages defining new requests and compatibility with RFC 3489 [RFC3489] clients.
responses should specify if XOR-MAPPED-ADDRESS is applicable to their
responses. 14.2. XOR-MAPPED-ADDRESS
The XOR-MAPPED-ADDRESS attribute is identical to the MAPPED-ADDRESS
attribute, except that the reflexive transport address is obfuscated
through the XOR function.
The format of the XOR-MAPPED-ADDRESS is: The format of the XOR-MAPPED-ADDRESS is:
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|x x x x x x x x| Family | X-Port | |x x x x x x x x| Family | X-Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| X-Address (Variable) | X-Address (Variable)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 10: Format of XOR-MAPPED-ADDRESS Attribute Figure 9: Format of XOR-MAPPED-ADDRESS Attribute
The Family represents the IP address family, and is encoded The Family represents the IP address family, and is encoded
identically to the Family in MAPPED-ADDRESS. identically to the Family in MAPPED-ADDRESS.
X-Port is the mapped port, exclusive or'd with most significant 16 X-Port is the mapped port, exclusive or'd with most significant 16
bits of the magic cookie. If the IP address family is IPv4, bits of the magic cookie. If the IP address family is IPv4,
X-Address is the mapped IP address exclusive or'd with the magic X-Address is the mapped IP address exclusive or'd with the magic
cookie. If the IP address family is IPv6, the X-Address is the cookie. If the IP address family is IPv6, the X-Address is the
mapped IP address exclusively or'ed with the magic cookie and the 96- mapped IP address exclusively or'ed with the magic cookie and the 96-
bit transaction ID. bit transaction ID.
For example, using the "^" character to indicate exclusive or, if the For example, using the "^" character to indicate exclusive or, if the
IP address is 192.168.1.1 (0xc0a80101) and the port is 5555 (0x15B3), IP address is 192.168.1.1 (0xc0a80101) and the port is 5555 (0x15B3),
the X-Port would be 0x15B3 ^ 0x2112 = 0x34A1, and the X-Address would the X-Port would be 0x15B3 ^ 0x2112 = 0x34A1, and the X-Address would
be 0xc0a80101 ^ 0x2112A442 = 0xe1baa543. be 0xc0a80101 ^ 0x2112A442 = 0xe1baa543.
It is possible for an IPv4 host to receive a XOR-MAPPED-ADDRESS The rules for encoding and processing the first 8 bits of the
containing an IPv6 address, or for an IPv6 host to receive a XOR- attribute's value, the rules for handling multiple occurrences of the
MAPPED-ADDRESS containing an IPv4 address. Clients MUST be prepared attribute, and the rules for processing addresses families are the
for this case. same as for MAPPED-ADDRESS.
11.11. SERVER
The server attribute contains a textual description of the software
being used by the server, including manufacturer and version number.
The attribute has no impact on operation of the protocol, and serves
only as a tool for diagnostic and debugging purposes. The value of
SERVER is variable length. If the value of SERVER is not a multiple
of four bytes, it is padded for encoding into the STUN message, in
which case the attribute length represents the length of the USERNAME
prior to padding.
11.12. ALTERNATE-SERVER
The alternate server represents an alternate transport address for a
different STUN server to try. It is encoded in the same way as
MAPPED-ADDRESS.
This attribute MUST only appear in an error response.
11.13. REFRESH-INTERVAL
The REFRESH-INTERVAL indicates the number of milliseconds that the
server suggests the client should use between refreshes of the NAT
bindings between the client and server. Even though the server may
not know the binding lifetimes in intervening NATs, this attribute
serves as a useful configuration mechanism for suggesting a value for
use by the client. Furthermore, when the NAT Keepalive usage is
being used, the server may become overloaded with Binding Requests
that are being used for keepalives. The REFRESH-INTERVAL provies a
mechanism for the server to gradually reduce the load on itself by
pushing back on the client.
REFRESH-INTERVAL is specified as an unsigned 32 bit integer, and
represents an interval measured in millseconds. It can be present in
Binding Responses.
12. STUN Usages
STUN is a simple request/response protocol that provides a useful
capability in several situations. In this section, different usages
of STUN are described. Each usage may differ in how STUN servers are
discovered, when the STUN requests are sent, what message types are
used, what message attributes are used, and how authentication is
performed.
This specification defines the STUN usages for binding discovery
(Section 12.1), NAT keepalives (Section 12.2) and short-term password
(Section 12.3).
New STUN usages may be defined by other standards-track documents.
New STUN usages MUST describe their applicability, client discovery
of the STUN server, how the server determines the usage, new message
types (requests or indications), new message attributes, new error
response codes, and new client and server procedures.
12.1. Binding Discovery
The previous version of this specification, RFC3489 [15], described
only this binding discovery usage.
12.1.1. Applicability
Binding discovery is used to learn reflexive addresses from servers
on the network, generally the public Internet. That is, it is used
by a client to determine its dynamically-bound 'public' UDP transport
address that is assigned by a NAT between a STUN client and a STUN
server. This transport address will be present in the mapped address
of the STUN Binding Response.
The mapped address present in the binding response can be used by
clients to facilitate traversal of NATs for many applications. NAT
traversal is problematic for applications that require a client to
insert a transport address into a message, to which subsequent
messages will be delivered by other entities in a network. Normally,
the client would insert the transport address from a local interface
into the message. However, if the client is behind a NAT, this local
interface will be a private address. Clients within other address
realms will not be able to send messages to that address.
An example of a such an application is SIP, which requires a client
to include transport address information in several places, including
the Session Description Protocol (SDP [19]) body carried by SIP. The
transport address present in the SDP is used for receipt of media.
To use STUN as a technique for traversal of SIP and other protocols,
when the client wishes to send a protocol message, it figures out the
places in the protocol data unit where it is supposed to insert its
own transport address. Instead of directly using a port allocated
from a local interface, the client allocates a port from the local
interface, and from that port, generates a STUN Binding Request. The
mapped address in the Binding Response (XOR-MAPPED-ADDRESS or MAPPED-
ADDRESS) provides the client with an alternative transport address
that it can then include in the protocol payload. This transport
address may be within a different address family than the local
interfaces used by the client. This is not an error condition. In
such a case, the client would use the learned IP address and port as
if the client was a host with an interface within that address
family.
In the case of SIP, to populate the SDP appropriately, a client would
generate two STUN Binding Request messages at the time a call is
initiated or answered. One is used to obtain the transport address
for RTP, and the other, for the Real Time Control Protocol
(RTCP)[17]. The client might also need to use STUN to obtain
transport addresses for usage in other parts of the SIP message. The
detailed usage of STUN to facilitate SIP NAT traversal is outside the
scope of this specification.
As discussed above, the transport addresses learned by STUN may not
be usable with all entities with whom a client might wish to
communicate. The way in which this problem is handled depends on the
application protocol. The ideal solution is for a protocol to allow
a client to include a multiplicity of transport addresses in the PDU.
One of those can be the transport address determined from STUN, and
the others can include transport addresses learned from other
techniques. The application protocol would then provide a means for
dynamically detecting which one works. An example of such an an
approach is Interactive Connectivity Establishment (ICE [13]).
12.1.2. Client Discovery of Server
Clients SHOULD be configured with a domain name for a STUN server to
use. In cases where the client has no explicit configuration
mechanism for STUN, but knows the domain of its service provider, the
client SHOULD use that domain (in the case of SIP, this would be the
domain from their Address-of-Record). The discovery mechanisms
defined in Section 8.1 are then applied to that domain name.
12.1.3. Server Determination of Usage
It is anticipated that servers would advertise a specific port in the
DNS for the Binding Discovery usage. Thus, when a request arrives at
that particular port, the server knows that the binding usage is in
use. This fact is only needed for purposes of determining the
authentication and message integrity mechanism to apply.
12.1.4. New Requests or Indications
This usage does not define any new message types.
12.1.5. New Attributes
This usage does not define any new message attributes.
12.1.6. New Error Response Codes
This usage does not define any new error response codes.
12.1.7. Client Procedures
The binding discovery is utilized by a client just prior to
generating an application PDU that requires the client to include its
transport address. The client MAY first obtain a short term
credential using the short term password STUN usage. The credential
that is obtained is then using in Binding Request messages. A
Binding Request message is generated for each distinct transport
address that the client requires to formulate the application PDU.
A successful response message will carry either an XOR-MAPPED-ADDRESS
or MAPPED-ADDRESS attribute, depending on the version of the server.
A client SHOULD use the XOR-MAPPED-ADDRESS if present. If not, it
uses the MAPPED-ADDRESS.
12.1.8. Server Procedures
It is RECOMMENDED that servers utilize short term credentials,
obtained by the client from a Shared Secret request, for
authentication and message integrity. Consequently, if a Binding
Request is generated without a short term credential, the server
SHOULD challenge for one.
12.1.9. Security Considerations for Binding Discovery
There are no security considerations for this usage beyond those
described in Section 13.
12.2. NAT Keepalives
12.2.1. Applicability
In this STUN usage, a client is connected to a server for a
particular application protocol (for example, a SIP proxy server).
The connection is long-lived, allowing for asynchronous messaging
from the server to the client. The client is connected to the server
either using TCP, in which case there is a long-lived TCP connection
from the client to the server, or using UDP, in which case the server
stores the source transport address of a message from a client (such
as SIP REGISTER), and sends messages to the client using that
transport address.
Since the connection between the client and server is very-long
lived, the bindings established by that connection need to be
maintained in any intervening NATs. Rather than implement expensive
application-layer keepalives, the keepalives can be accomplished
using STUN Binding Requests. The client will periodically send a
Binding Request to the server, using the same transport addresses
used for the application protocol. These Binding Requests are
demultiplexed at the server using the magic cookie and possibly
FINGERPRINT. The response from the server informs the client that
the server is still alive. The STUN message also keeps the binding
active in intervening NATs. The client can also examine the mapped
address in the Binding Response. If it has changed, the client can
re-initiate application layer procedures to inform the server of its
new transport address.
12.2.2. Client Discovery of Server
In this usage, the STUN server and the application protocol are using
the same fixed port.
12.2.3. Server Determination of Usage
The server multiplexes both STUN and its application protocol on the
same port. The server knows it is has this usage because the URI
that gets resolved to this port indicates the server supports this
multiplexing.
12.2.4. New Requests or Indications
This usage does not define any new message types.
12.2.5. New Attributes
This usage does not define any new message attributes.
12.2.6. New Error Response Codes
This usage does not define any new error response codes.
12.2.7. Client Procedures
If the STUN Response indicates the client's mapped address has
changed from the client's expected mapped address, the client SHOULD
inform other applications of its new mapped address. For example, a
SIP client could use the binding discovery usage to obtain a new
mapped address, and then register it using SIP registration
procedures.
The client SHOULD NOT include a MESSAGE-INTEGRITY attribute unless NOTE: XOR-MAPPED-ADDRESS and MAPPED-ADDRESS differ only in their
prompted for one by the server, since authentication is not generally encoding of the transport address. The former encodes the transport
used with this STUN usage. address by exclusive-or'ing it with the magic cookie. The latter
encodes it directly in binary. RFC 3489 originally specified only
MAPPED-ADDRESS. However, deployment experience found that some NATs
rewrite the 32-bit binary payloads containing the NAT's public IP
address, such as STUN's MAPPED-ADDRESS attribute, in the well-meaning
but misguided attempt at providing a generic ALG function. Such
behavior interferes with the operation of STUN and also causes
failure of STUN's message integrity checking.
12.2.8. Server Procedures 14.3. USERNAME
The server SHOULD NOT authenticate the client or look for a MESSAGE- The USERNAME attribute is used for message integrity. It identifies
INTEGRITY attribute. Since the keepalives come with some regularity, the username and password combination used in the message integrity
and will come for each client that is connected to the server, the check.
processing cost associated with authenticating each request is very
high. Consequently, authentication should only be used by small
servers, for whom the processing cost is not an issue, or when used
with application protocols where the consequences of a fake response
are very significant.
12.2.9. Security Considerations for NAT Keepalives The value of USERNAME is a variable length value. It MUST contain a
UTF-8 encoded sequence of less than 128 characters.
This STUN usage does not recommend the usage of message integrity or 14.4. MESSAGE-INTEGRITY
authentication. This is because the client never actually uses the
mapped address from the STUN response. It merely treats a change in
that address as a hint that the client should re-apply application
layer procedures for connection establishment and registration.
An attacker could attempt to inject faked responses, or modify The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [RFC2104] of
responses in transit. Such an attack would require the attacker to the STUN message. The MESSAGE-INTEGRITY attribute can be present in
be on-path in order to determine the transaction ID. In the worst any STUN message type. Since it uses the SHA1 hash, the HMAC will be
case, the attack would cause the client to see a change in IP address 20 bytes. The text used as input to HMAC is the STUN message,
or port, and then perform an application layer re-registration. Such including the header, up to and including the attribute preceding the
a re-registration would not use the transport address obtained from MESSAGE-INTEGRITY attribute. With the exception of the FINGERPRINT
the Binding Response. Thus, the worst that the attacker can do is attribute, which appears after MESSAGE-INTEGRITY, agents MUST ignore
cause the client to re-register every half minute or so, when it all other attributes that follow MESSAGE-INTEGRITY.
otherwise wouldn't need to. Given the difficulty in launching this
attack (it requires the attacker to be on-path and to disrupt the
actual response from the server) compared to the benefit, there is
little motivation for authentication or integrity mechanisms.
When used with application protocols where the cost of "re- The key used as input to HMAC is the password.
registration" is in fact high, the keepalive usage can still be used
without authentication. However, the usage would serve ONLY to keep
NAT bindings alive; it would not be useful for detecting failures of
the server or of intervening NAT. In such a case, the client would
not perform any application layer processing based on the STUN
response, even if it indicated a change in transport address.
12.3. Short-Term Password Since the hash is computed over the entire STUN message, it includes
the length field from the STUN message header. This length indicates
the length of the entire message, including the MESSAGE-INTEGRITY
attribute itself. Consequently, the MESSAGE-INTEGRITY attribute MUST
be inserted into the message (with dummy content) prior to the
computation of the integrity check. Once the computation is
performed, the value of the attribute can be filled in. This ensures
the length has the correct value when the hash is performed.
Similarly, when validating the MESSAGE-INTEGRITY, the length field
should be adjusted to point to the end of the MESSAGE-INTEGRITY
attribute prior to calculating the HMAC. Such adjustment is
necessary when attributes, such as FINTERPRINT, appear after MESSAGE-
INTEGRITY.
In order to ensure interoperability, this usage describes a TLS-based 14.5. FINGERPRINT
mechanism to obtain a short-term credential. The usage makes use of
the Shared Secret Request and Response messages. It is defined as a
separate usage in order to allow it to run on a separate port, and to
allow it to be more easily separated from the different STUN usages,
only some of which require this mechanism.
12.3.1. Applicability The FINGERPRINT attribute may be present in all STUN messages. The
value of the attribute is computed as the CRC-32 of the STUN message
up to (but excluding) the FINGERPRINT attribute itself, xor-d with
the 32 bit value 0x5354554e (the XOR helps in cases where an
application packet is also using CRC-32 in it). The 32 bit CRC is
the one defined in ITU V.42 [ITU.V42.1994], which has a generator
polynomial of x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1.
When present, the FINGERPRINT attribute MUST be the last attribute in
the message, and thus will appear after MESSAGE-INTEGRITY.
To thwart some on-path attacks described in Section 13, it is The FINGERPRINT attribute can aid in distinguishing STUN packets from
necessary for the STUN client and STUN server to integrity protect packets of other protocols. See Section 8.
the information they exchange over UDP. In the absence of a long-
term secret (password) that is shared between them, a short-term
password can be obtained using the usage described in this section.
The username and password returned in the STUN Shared Secret Response When using the FINGERPRINT attribute in a message, the attribute is
are valid for use in subsequent STUN transactions for nine (9) first placed into the message with a dummy value, then the CRC is
minutes with any applicable hosts as described in Section 12.3.2. computed, and then the value of the attribute is updated. If the
The username and password obtained with this usage are used as the MESSAGE-INTEGRITY attribute is also present, then it must be present
USERNAME and in the HMAC for the MESSAGE-INTEGRITY in a subsequent with the correct message-integrity value before the CRC is computed,
STUN message, respectively. since the CRC is done over the value of the MESSAGE-INTEGRITY
attribute as well.
12.3.2. Client Discovery of Server 14.6. ERROR-CODE
The client follows the procedures in Section 8.1. The SRV protocol The ERROR-CODE attribute is used in Error Response messages. It
is "tls" and the service name "stun-pass". contains a numeric error code value in the range of 300 to 699 plus a
textual reason phrase encoded in UTF-8, and is consistent in its code
assignments and semantics with SIP [RFC3261] and HTTP [RFC2616]. The
reason phrase is meant for user consumption, and can be anything
appropriate for the error code. Recommended reason phrases for the
defined error codes are presented below. The reason phrase MUST be a
UTF-8 encoded sequence of less than 128 characters.
For example a client would look up "_stun-pass._tls.example.com" in To facilitate processing, the class of the error code (the hundreds
DNS. digit) is encoded separately from the rest of the code.
12.3.3. Server Determination of Usage 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved, should be 0 |Class| Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reason Phrase (variable) ..
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The server advertises this port in the DNS as capable of receiving The Reserved bits SHOULD be 0, and are for alignment on 32-bit
TLS over TCP connections, along with the Shared Secret messages that boundaries. Receivers MUST ignore these bits. The Class represents
run over it. The server MAY also advertise this same port in DNS for the hundreds digit of the error code. The value MUST be between 3
other TLS over TCP usages if the server is capable of multiplexing and 6. The number represents the error code modulo 100, and its
those different usages. For example, the server could advertise the value MUST be between 0 and 99.
short-term password and binding discovery usages on the same TLS/TCP
port.
12.3.4. New Requests or Indications The following error codes, along with their recommended reason
phrases (in brackets) are defined:
The message type Shared Secret Request and its associated Shared 300 Try Alternate: The client should contact an alternate server for
Secret Response and Shared Secret Error Response are defined in this this request. This error response MUST only be sent if the
section. Their values are enumerated in Section 15. request included a USERNAME attribute and a valid MESSAGE-
INTEGRITY attribute; otherwise it MUST NOT be sent and error
code 400 is suggested. This error response MUST be protected
with the MESSAGE-INTEGRITY attribute, and receivers MUST
validate the MESSAGE-INTEGRITY of this response before
redirecting themselves to an alternate server.
The following figure indicates which attributes are present in the Note: failure to generate and validate message-integrity
Shared Secret Request, Response, and Error Response. An M indicates for a 300 response allows an on-path attacker to falsify a
that inclusion of the attribute in the message is mandatory, O means 300 response thus causing subsequent STUN messages to be
its optional, C means it's conditional based on some other aspect of sent to a victim.
the message, and - means that the attribute is not applicable to that
message type. Attributes not listed are not applicable to Shared
Secret Request, Response, or Error Response.
Shared Shared Shared 400 Bad Request: The request was malformed. The client SHOULD NOT
Secret Secret Secret retry the request without modification from the previous
Attribute Request Response Error attempt. The server may not be able to generate a valid
Response MESSAGE-INTEGRITY for this error, so the client MUST NOT expect
_________________________________________________ a valid MESSAGE-INTEGRITY attribute on this response.
USERNAME O M -
PASSWORD - M -
MESSAGE-INTEGRITY O O O
ERROR-CODE - - M
ALTERNATE-SERVER - - C
UNKNOWN-ATTRIBUTES - - C
SERVER - O O
REALM C - C
NONCE C - C
The Shared Secret requests, like other STUN requests, can be 401 Unauthorized: The request did not contain the expected MESSAGE-
authenticated. However, since its purpose is to obtain a short-term INTEGRITY attribute. The server MAY include the MESSAGE-
credential, the Shared Secret request itself cannot be authenticated INTEGRITY attribute in its error response.
with a short-term credential. However, it can be authenticated with
a long-term credential.
12.3.5. New Attributes 420 Unknown Attribute: The server received STUN packet containing a
comprehension-required attribute which it did not understand.
The server MUST put this unknown attribute in the UNKNOWN-
ATTRIBUTE attribute of its error response.
No new attributes are defined by this usage. 438 Stale Nonce: The NONCE used by the client was no longer valid.
The client should retry, using the NONCE provided in the
response.
12.3.6. New Error Response Codes 500 Server Error: The server has suffered a temporary error. The
client should try again.
This usage defines the 433 error response. Only the MESSAGE- 14.7. REALM
INTEGRITY, ERROR-CODE and SERVER attributes are applicable to this
response.
12.3.7. Client Procedures The REALM attribute may be present in requests and responses. It
contains text which meets the grammar for "realm-value" as described
in RFC 3261 [RFC3261] but without the double quotes and their
surrounding whitespace. That is, it is an unquoted realm-value. It
MUST be a UTF-8 encoded sequence of less than 128 characters.
Shared Secret requests are formed like other STUN requests, with the Presence of the REALM attribute in a request indicates that long-term
following additions. Clients MUST NOT use a short-term credential credentials are being used for authentication. Presence in certain
with a Shared Secret request. They SHOULD send the request with no error responses indicates that the server wishes the client to use a
credentials (omitting MESSAGE-INTEGRITY and USERNAME). long-term credential for authentication.
Processing of the Shared Secret response follows that of any other 14.8. NONCE
STUN response. Note that clients MUST be prepared to be challenged
for a long-term credential.
If the response was a Shared Secret Response, it will contain a short The NONCE attribute may be present in requests and responses. It
lived username and password, encoded in the USERNAME and PASSWORD contains a sequence of qdtext or quoted-pair, which are defined in
attributes, respectively. A client SHOULD use these credentials RFC 3261 [RFC3261]. See RFC 2617 [RFC2617], Section 4.3, for
whenever short term credentials are needed for any server discovered guidance on selection of nonce values in a server. It MUST be less
using the same domain name as was used to discover the one which than 128 characters.
returned those credentials. For example, if a client used a domain
name of example.com, it would have looked up _stun-
pass._tls.example.com in DNS, found a server, and sent a Shared
Secret request that provided a credential to the client. The client
would use this credential with a server discovered by looking up
_stun._udp.example.com in the DNS.
If the response was a Shared Secret Error Response, and ERROR-CODE 14.9. UNKNOWN-ATTRIBUTES
attribute was present with a response code of 433, and the client had
not sent the request over TLS, the client SHOULD establish a TLS
connection to the server and retry the request over that connection.
If the client had used TLS, this error response is unrecoverable and
the client SHOULD NOT retry.
12.3.8. Server Procedures The UNKNOWN-ATTRIBUTES attribute is present only in an error response
when the response code in the ERROR-CODE attribute is 420.
The procedures for general processing of STUN requests apply to The attribute contains a list of 16 bit values, each of which
Shared Secret requests. Servers MAY challenge the client for a long- represents an attribute type that was not understood by the server.
term credential if one was not provided in a request. However, they
MUST NOT challenge the request for a short-term credential.
If the Shared Secret Request did not arrive over a TLS connection, 0 1 2 3
the server MUST generate a Shared Secret Error response with an 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
ERROR-CODE attribute that has a response code of 433. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute 1 Type | Attribute 2 Type |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute 3 Type | Attribute 4 Type ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
If the request is valid and authenticated (assuming the server is Figure 11: Format of UNKNOWN-ATTRIBUTES attribute
performing authentication), the server MUST create a short term
credential for the user. This credential consists of a username and
password. The credentials MUST be valid for a duration of at least
nine minutes, and SHOULD NOT be valid for a duration of longer than
thirty minutes. The username MUST be distinct, with extremely high
probabilities, from all usernames that have been handed out across
all servers that are returned from DNS SRV queries for the same
domain name. Extremely high probability means that the likelihood of
collision SHOULD be better than 1 in 2**64. The password for each
username MUST be cryptographically random with at least 128 bits of
entropy.
12.3.9. Security Considerations for Short-Term Password Note: In [RFC3489], this field was padded to 32 by duplicating the
last attribute. In this version of the specification, the normal
padding rules for attributes are used instead.
The security considerations in Section 13 do not apply to the Shared 14.10. SERVER
Secret request and response, since these messages do not make use of
mapped addresses, which is the primary source of security
consideration discussed there. Rather, shared secret requests are
used to obtain short term credentials that are used in the
authentication of other messages.
Because the Shared Secret response itself carries a credential, in The server attribute contains a textual description of the software
the form of a username and password, it must be sent encrypted. For being used by the server, including manufacturer and version number.
this reason, STUN servers MUST reject any Shared Secret request that The attribute has no impact on operation of the protocol, and serves
has not arrived over a TLS connection. only as a tool for diagnostic and debugging purposes. The value of
SERVER is variable length. It MUST be a UTF-8 encoded sequence of
less than 128 characters
Malicious clients could generate a multiplicity of Shared Secret 14.11. ALTERNATE-SERVER
requests, each of which causes the server to allocate shared secrets,
each of which might consume memory and processing resources. If
shared secret requests are not being authenticated, this leads to a
possible denial-of-service attack. Indeed, even if the requestor is
authenticated, attacks are still possible.
To prevent being swamped with traffic, a STUN server SHOULD limit the The alternate server represents an alternate transport address
number of simultaneous TLS connections it will hold open by dropping identifying a different STUN server which the STUN client should try.
an existing connection when a new connection request arrives (based
on an Least Recently Used (LRU) policy, for example).
Similarly, servers SHOULD allocate only a small number of shared It is encoded in the same way as MAPPED-ADDRESS, and thus refers to a
secrets to a host with a particular source transport address. single server by IP address. The IP address family MUST be identical
Requests from the same transport address which exceed this limit to that of the source IP address of the request.
SHOULD be rejected with a 600 response. Servers SHOULD also limit
the total number of shared secrets they will provide at a time across
all clients, based on the number of users and expected loads during
normal peak usage. If a Shared Secret request arrives and the server
has exceeded its limit, it SHOULD reject the request with a 500
response.
Furthermore, for servers that are not authenticating shared secret This attribute MUST only appear in an error response that contains a
requests, it is RECOMMENDED that short-term credentials be MESSAGE-INTEGRITY attribute. This prevents it from being used in
constructed in a way such that they do not require memory or disk to denial-of-service attacks.
store.
This can be done by intelligently computing the username and 15. Security Considerations
password. One approach is to construct the USERNAME as:
USERNAME = <prefix,rounded-time,hmac> 15.1. Attacks against the Protocol
Where prefix is some random text string (different for each shared 15.1.1. Outside Attacks
secret request), rounded-time is the current time modulo 20 minutes,
and hmac is an HMAC [13] over the prefix and rounded-time, using a
server private key.
The password is then computed as: An attacker can try to modify STUN messages in transit, in order to
cause a failure in STUN operation. These attacks are prevented for
both requests and responses through the message integrity mechanism,
using either a short term or long term credential.
password = <hmac(USERNAME,anotherprivatekey)> An attacker that can observe, but not modify STUN messages in-transit
(for example, an attacker present on a shared access medium, such as
Wi-Fi), can see a STUN request, and then immediately send a STUN
response, typically an error response, in order to disrupt STUN
processing. This attack is also prevented for messages that utilize
MESSAGE-INTEGRITY. However, some error responses, those related to
authentication in particular, cannot be protected by MESSAGE-
INTEGRITY. When STUN itself is run over a secure transport protocol
(e.g., TLS), these attacks are completely mitigated.
With this structure the server can verify that the username was not 15.1.2. Inside Attacks
tampered with using the hmac present in the username.
13. Security Considerations A rogue client may try to launch a DoS attack against a server by
sending it a large number of STUN requests. Fortunately, STUN
requests can be processed statelessly by a server, making such
attacks hard to launch.
Attacks on STUN systems vary depending on the usage. The short term 15.2. Attacks Affecting the Usage
password usage is quite different from the other usages defined here,
and its security considerations are unique to it and discussed as
part of the usage definition. However, all of the other usages are
very similar and share a similar set of security considerations as a
consequence of their usage of the mapped address from STUN Binding
Responses. Consequently, these security considerations apply to
usage of the mapped address.
13.1. Attacks on STUN This section lists attacks that might be launched against a usage of
STUN. Each STUN usage must consider whether these attacks are
applicable to it, and if so, discuss counter-measures.
Generally speaking, attacks on STUN can be classified into denial of Most of the attacks in this section revolve around an attacker
service attacks and eavesdropping attacks. Denial of service attacks modifying the reflexive address learned by a STUN client through a
can be launched against a STUN server itself or against other Binding Request/Binding Response transaction. Since the usage of the
elements using the STUN protocol. The attacks of greater interest reflexive address is a function of the usage, the applicability and
are those in which the STUN server and client are used to launch remediation of these attacks is usage-specific. In common
denial of service (DoS) attacks against other entities, including the situations, modification of the reflexive address by an on-path
client itself. Many of the attacks require the attacker to generate attacker is easy to do. Consider, for example, the common situation
a response to a legitimate STUN request, in order to provide the where STUN is run directly over UDP. In this case, an on-path
client with a faked mapped address. The attacks that can be launched attacker can modify the source IP address of the Binding Request
using such a technique include: before it arrives at the STUN server. The STUN server will then
return this IP address in the XOR-MAPPED-ADDRESS attribute to the
client. Protecting against this attack by using a message-integrity
check is impossible, since a message-integrity value cannot cover the
source IP address, since the intervening NAT must be able to modify
this value. Instead, one solution to preventing the attacks listed
below is for the client to verify the reflexive address learned, as
is done in ICE [I-D.ietf-mmusic-ice]. Other usages may use other
means to prevent these attacks.
13.1.1. Attack I: DDoS Against a Target 15.2.1. Attack I: DDoS Against a Target
In this case, the attacker provides a large number of clients with In this attack, the attacker provides one or more clients with the
the same faked mapped address that points to the intended target. same faked reflexive address that points to the intended target.
This will trick all the STUN clients into thinking that their This will trick the STUN clients into thinking that their reflexive
addresses are equal to that of the target. The clients then hand out addresses are equal to that of the target. If the clients hand out
that address in order to receive traffic on it (for example, in SIP that reflexive address in order to receive traffic on it (for
or H.323 messages). However, all of that traffic becomes focused at example, in SIP messages), the traffic will instead be sent to the
the intended target. The attack can provide substantial target. This attack can provide substantial amplification,
amplification, especially when used with clients that are using STUN especially when used with clients that are using STUN to enable
to enable multimedia applications. multimedia applications.
13.1.2. Attack II: Silencing a Client 15.2.2. Attack II: Silencing a Client
In this attack, the attacker seeks to deny a client access to In this attack, the attacker provides a STUN client with a faked
services enabled by STUN (for example, a client using STUN to enable reflexive address. The reflexive address it provides is a transport
SIP-based multimedia traffic). To do that, the attacker provides address that routes to nowhere. As a result, the client won't
that client with a faked mapped address. The mapped address it receive any of the packets it expects to receive when it hands out
provides is a transport address that routes to nowhere. As a result, the reflexive address. This exploitation is not very interesting for
the client won't receive any of the packets it expects to receive the attacker. It impacts a single client, which is frequently not
when it hands out the mapped address. This exploitation is not very the desired target. Moreover, any attacker that can mount the attack
interesting for the attacker. It impacts a single client, which is could also deny service to the client by other means, such as
frequently not the desired target. Moreover, any attacker that can preventing the client from receiving any response from the STUN
mount the attack could also deny service to the client by other server, or even a DHCP server.
means, such as preventing the client from receiving any response from
the STUN server, or even a DHCP server.
13.1.3. Attack III: Assuming the Identity of a Client 15.2.3. Attack III: Assuming the Identity of a Client
This attack is similar to attack II. However, the faked mapped This attack is similar to attack III. However, the faked reflexive
address points to the attacker themself. This allows the attacker to address points to the attacker itself. This allows the attacker to
receive traffic which was destined for the client. receive traffic which was destined for the client.
13.1.4. Attack IV: Eavesdropping 15.2.4. Attack IV: Eavesdropping
In this attack, the attacker forces the client to use a mapped In this attack, the attacker forces the client to use a reflexive
address that routes to itself. It then forwards any packets it address that routes to itself. It then forwards any packets it
receives to the client. This attack would allow the attacker to receives to the client. This attack would allow the attacker to
observe all packets sent to the client. However, in order to launch observe all packets sent to the client. However, in order to launch
the attack, the attacker must have already been able to observe the attack, the attacker must have already been able to observe
packets from the client to the STUN server. In most cases (such as packets from the client to the STUN server. In most cases (such as
when the attack is launched from an access network), this means that when the attack is launched from an access network), this means that
the attacker could already observe packets sent to the client. This the attacker could already observe packets sent to the client. This
attack is, as a result, only useful for observing traffic by attack is, as a result, only useful for observing traffic by
attackers on the path from the client to the STUN server, but not attackers on the path from the client to the STUN server, but not
generally on the path of packets being routed towards the client. generally on the path of packets being routed towards the client.
13.2. Launching the Attacks 15.3. Hash Agility Plan
It is important to note that attacks of this nature (injecting
responses with fake mapped addresses) require that the attacker be
capable of eavesdropping requests sent from the client to the server
(or to act as a man in the middle for such attacks). This is because
STUN requests contain a transaction identifier, selected by the
client, which is random with 96 bits of entropy. The server echoes
this value in the response, and the client ignores any responses that
don't have a matching transaction ID. Therefore, in order for an
attacker to provide a faked response that is accepted by the client,
the attacker needs to know the transaction ID of the request. The
large amount of randomness, combined with the need to know when the
client sends a request and the transport addresses used for that
request, precludes attacks that involve guessing the transaction ID.
Since all of the above attacks rely on this one primitive - injecting
a response with a faked mapped address - preventing the attacks is
accomplished by preventing this one operation. To prevent it, we
need to consider the various ways in which it can be accomplished.
There are several:
13.2.1. Approach I: Compromise a Legitimate STUN Server
In this attack, the attacker compromises a legitimate STUN server
through a virus or Trojan horse. Presumably, this would allow the
attacker to take over the STUN server, and control the types of
responses it generates. Compromise of a STUN server can also lead to
discovery of open ports. Knowledge of an open port creates an
opportunity for DoS attacks on those ports (or DDoS attacks if the
traversed NAT is a full cone NAT). Discovering open ports is already
fairly trivial using port probing, so this does not represent a major
threat.
13.2.2. Approach II: DNS Attacks
STUN servers are discovered using DNS SRV records. If an attacker
can compromise the DNS, it can inject fake records which map a domain
name to the IP address of a STUN server run by the attacker. This
will allow it to inject fake responses to launch any of the attacks
above. Clearly, this attack is only applicable for usages which
discover servers through DNS.
13.2.3. Approach III: Rogue Router or NAT
Rather than compromise the STUN server, an attacker can cause a STUN
server to generate responses with the wrong mapped address by
compromising a router or NAT on the path from the client to the STUN
server. When the STUN request passes through the rogue router or
NAT, it rewrites the source transport address of the packet to be
that of the desired mapped address. This address cannot be
arbitrary. If the attacker is on the public Internet (that is, there
are no NATs between it and the STUN server), and the attacker doesn't
modify the STUN request, the address has to have the property that
packets sent from the STUN server to that address would route through
the compromised router. This is because the STUN server will send
the responses back to the source transport address of the request.
With a modified source transport address, the only way they can reach
the client is if the compromised router directs them there.
If the attacker is on a private network (that is, there are NATs
between it and the STUN server), the attacker will not be able to
force the server to generate arbitrary mapped addresses in responses.
They will only be able force the STUN server to generate mapped
addresses which route to the private network. This is because the
NAT between the attacker and the STUN server will rewrite the source
transport address of the STUN request, mapping it to a public address
that routes to the private network. Because of this, the attacker
can only force the server to generate faked mapped addresses that
route to the private network. Unfortunately, it is possible that a
low quality NAT would be willing to map an allocated public address
to another public address (as opposed to an internal private
address), in which case the attacker could forge the source address
in a STUN request to be an arbitrary public address. This kind of
behavior from NATs does appear to be rare.
13.2.4. Approach IV: Man in the Middle
As an alternative to approach III (Section 13.2.3), if the attacker
can place an element on the path from the client to the server, the
element can act as a man-in-the-middle. In that case, it can
intercept a STUN request, and generate a STUN response directly with
any desired value of the mapped address field. Alternatively, it can
forward the STUN request to the server (after potential
modification), receive the response, and forward it to the client.
When forwarding the request and response, this attack is subject to
the same limitations on the mapped address described in Approach III
(Section 13.2.3).
13.2.5. Approach V: Response Injection Plus DoS
In this approach, the attacker does not need to be a MitM (as in
approaches III and IV). Rather, it only needs to be able to
eavesdrop onto a network segment that carries STUN requests. This is
easily done in multiple access networks such as ethernet or
unprotected 802.11. To inject the fake response, the attacker
listens on the network for a STUN request. When it sees one, it
simultaneously launches a DoS attack on the STUN server, and
generates its own STUN response with the desired mapped address
value. The STUN response generated by the attacker will reach the
client, and the DoS attack against the server is aimed at preventing
the legitimate response from the server from reaching the client.
Arguably, the attacker can do without the DoS attack on the server,
so long as the faked response beats the real response back to the
client, and the client uses the first response, and ignores the
second (even though it's different).
13.2.6. Approach VI: Duplication
This approach is similar to approach V (Section 13.2.5). The
attacker listens on the network for a STUN request. When it sees
one, it generates its own STUN request towards the server. This STUN
request is identical to the one it saw, but with a spoofed source IP
address. The spoofed address is equal to the one that the attacker
desires to have placed in the mapped address of the STUN response.
In fact, the attacker generates a flood of such packets. The STUN
server will receive the one original request, plus a flood of
duplicate fake ones. It generates responses to all of them. If the
flood is sufficiently large for the responses to congest routers or
some other equipment, there is a reasonable probability that the one
real response is lost (along with many of the faked ones), but the
net result is that only the faked responses are received by the STUN
client. These responses are all identical and all contain the mapped
address that the attacker wanted the client to use.
The flood of duplicate packets is not needed (that is, only one faked
request is sent), so long as the faked response beats the real
response back to the client, and the client uses the first response,
and ignores the second (even though it's different).
Note that, in this approach, launching a DoS attack against the STUN
server or the IP network, to prevent the valid response from being
sent or received, is problematic. The attacker needs the STUN server
to be available to handle its own request. Due to the periodic
retransmissions of the request from the client, this leaves a very
tiny window of opportunity. The attacker must start the DoS attack
immediately after the actual request from the client, causing the
correct response to be discarded, and then cease the DoS attack in
order to send its own request, all before the next retransmission
from the client. Due to the close spacing of the retransmits (100ms
to a few seconds), this is very difficult to do.
Besides DoS attacks, there may be other ways to prevent the actual
request from the client from reaching the server. Layer 2
manipulations, for example, might be able to accomplish it.
Fortunately, this approach is subject to the same limitations
documented in Approach III (Section 13.2.3), which limit the range of
mapped addresses the attacker can cause the STUN server to generate.
13.3. Countermeasures
STUN provides mechanisms to counter the approaches described above,
and additional, non-STUN techniques can be used as well.
First off, it is RECOMMENDED that networks with STUN clients
implement ingress source filtering [6]. This is particularly
important for the NATs themselves. As Section 13.2.3 explains, NATs
which do not perform this check can be used as "reflectors" in DDoS
attacks. Most NATs do perform this check as a default mode of
operation. We strongly advise people who purchase NATs to ensure
that this capability is present and enabled.
Secondly, for usages where the STUN server is not co-located with
some kind of application (such as the binding discovery usage), it is
RECOMMENDED that STUN servers be run on hosts dedicated to STUN, with
all UDP and TCP ports disabled except for the STUN ports. This is to
prevent viruses and Trojan horses from infecting STUN servers, in
order to prevent their compromise. This helps mitigate Approach I
(Section 13.2.1).
Thirdly, to prevent the DNS attack of Section 13.2.2, Section 8.2
recommends that the client verify the credentials provided by the
server with the name used in the DNS lookup.
Finally, all of the attacks above rely on the client taking the
mapped address it learned from STUN, and using it in application
layer protocols. If encryption and message integrity are provided
within those protocols, the eavesdropping and identity assumption
attacks can be prevented. As such, applications that make use of
STUN addresses in application protocols SHOULD use integrity and
encryption, even if a SHOULD level strength is not specified for that
protocol. For example, multimedia applications using STUN addresses
to receive RTP traffic would use secure RTP [23].
The above three techniques are non-STUN mechanisms. STUN itself
provides several countermeasures.
Approaches IV (Section 13.2.4), when generating the response locally,
and V (Section 13.2.5) require an attacker to generate a faked
response. A faked response must match the 96-bit transaction ID of
the request. The attack is further prevented by using the message
integrity mechanism provided in STUN, described in Section 11.4.
Approaches III (Section 13.2.3), IV (Section 13.2.4), when using the
relaying technique, and VI (Section 13.2.6), however, are not
preventable through server signatures. These three approaches are
functional when the attacker modifies nothing but the source address
of the STUN request. Sadly, this is the one thing that cannot be
protected through cryptographic means, as this is the change that
STUN itself is seeking to detect and report. It is therefore an
inherent weakness in NAT, and not fixable in STUN.
13.4. Residual Threats This specification uses SHA-1 for computation of the message
integrity. If, at a later time, SHA-1 is found to be compromised,
the following is the remedy that will be applied.
None of the countermeasures listed above can prevent the attacks We will define a STUN extension which introduces a new message
described in Section 13.2.3 if the attacker is in the appropriate integrity attribute, computed using a new hash. Clients would be
network paths. Specifically, consider the case in which the attacker required to include both the new and old message integrity attributes
wishes to convince client C that it has address V. The attacker needs in their requests or indications. A new server will utilize the new
to have a network element on the path between A and the server (in message integrity attribute, and an old one, the old. After a
order to modify the request) and on the path between the server and V transition period where mixed implementations are in deployment, the
so that it can forward the response to C. Furthermore, if there is a old message-integrity attribute will be deprecated by another
NAT between the attacker and the server, V must also be behind the specification, and clients will cease including it in requests.
same NAT. In such a situation, the attacker can either gain access
to all the application-layer traffic or mount the DDOS attack
described in Section 13.1.1. Note that any host which exists in the
correct topological relationship can be DDOSed. It need not be using
STUN.
14. IAB Considerations 16. IAB Considerations
The IAB has studied the problem of "Unilateral Self Address Fixing" The IAB has studied the problem of "Unilateral Self Address Fixing"
(UNSAF), which is the general process by which a client attempts to (UNSAF), which is the general process by which a client attempts to
determine its address in another realm on the other side of a NAT determine its address in another realm on the other side of a NAT
through a collaborative protocol reflection mechanism (RFC3424 [24]). through a collaborative protocol reflection mechanism (RFC3424
STUN is an example of a protocol that performs this type of function [RFC3424]). STUN can be used to perform this function using a
for the binding discovery usage. The IAB has mandated that any BindingRequest/BindingResponse transaction if one agent is behind a
protocols developed for this purpose document a specific set of NAT and the other is on the public side of the NAT.
considerations. This section meets those requirements for the
binding discovery usage.
14.1. Problem Definition
From RFC3424 [24], any UNSAF proposal must provide:
Precise definition of a specific, limited-scope problem that is to
be solved with the UNSAF proposal. A short term fix should not be
generalized to solve other problems; this is why "short term fixes
usually aren't".
The specific problem being solved by STUN is to provide the
functionality necessary to describe how to connect two endpoints
regardless of the location of type of NATs in the topology.
14.2. Exit Strategy
From RFC3424 [24], any UNSAF proposal must provide:
Description of an exit strategy/transition plan. The better short
term fixes are the ones that will naturally see less and less use
as the appropriate technology is deployed.
STUN by itself does not provide an exit strategy. This is provided
by techniques, such as Interactive Connectivity Establishment (ICE
[13]), that allow a client to determine whether addresses learned
from STUN are needed, or whether other addresses, such as the one on
the local interface, will work when communicating with another host.
With such a detection technique, as a client finds that the addresses
provided by STUN are never used, STUN queries can cease to be made,
thus allowing them to phase out.
14.3. Brittleness Introduced by STUN
From RFC3424 [24], any UNSAF proposal must provide:
Discussion of specific issues that may render systems more
"brittle". For example, approaches that involve using data at
multiple network layers create more dependencies, increase
debugging challenges, and make it harder to transition.
STUN introduces brittleness into the system in several ways:
o Transport addresses discovered by STUN in the Binding Discovery
usage will only be useful for receiving packets from a peer if the
NAT does not have address or address and port dependent mapping
properties. When this usage is used in isolation, this makes STUN
brittle, since its effectiveness depends on the type of NAT. This
brittleness is eliminated when the Binding Discovery usage is used
in concert with mechanisms which can verify the transport address
and use others if it doesn't work. ICE is an example of such a
mechanism.
o Transport addresses discovered by STUN in the Binding Discovery
usage will only be useful for receiving packets from a peer if the
STUN server subtends the address realm of the peer. For example,
consider client A and B, both of which have residential NAT
devices. Both devices connect them to their cable operators, but
both clients have different providers. Each provider has a NAT in
front of their entire network, connecting it to the public
Internet. If the STUN server used by A is in A's cable operator's
network, an address obtained by it will not be usable by B. The
STUN server must be in the network which is a common ancestor to
both - in this case, the public Internet. When this usage is used
in isolation, this makes STUN brittle, since its effectiveness
depends on the topological placement of the STUN server. This
brittleness is eliminated when the Binding Discovery usage is used
in concert with mechanisms which can verify the transport address
and use others if it doesn't work. ICE is an example of such a
mechanism.
o The bindings allocated from the NAT need to be continuously
refreshed. Since the timeouts for these bindings is very
implementation specific, the refresh interval cannot easily be
determined. When the binding is not being actively used to
receive traffic, but to wait for an incoming message, the binding
refresh will needlessly consume network bandwidth.
o The use of the STUN server in the Binding Discovery usage as an
additional network element introduces another point of potential
security attack. These attacks are largely prevented by the
security measures provided by STUN, but not entirely.
o The use of the STUN server as an additional network element
introduces another point of failure. If the client cannot locate
a STUN server, or if the server should be unavailable due to
failure, the application cannot function.
o The use of STUN to discover address bindings may result in an
increase in latency for applications.
o Transport addresses discovered by STUN in the Binding Discovery
usage will only be useful for receiving packets from a peer behind
the same NAT if the STUN server supports hairpinning [14]. When
this usage is used in isolation, this makes STUN brittle, since
its effectiveness depends on the topological placement of the STUN
server. This brittleness is eliminated when the Binding Discovery
usage is used in concert with mechanisms which can verify the
transport address and use others if it doesn't work. ICE is an
example of such a mechanism.
o Most significantly, STUN introduces potential security threats
which cannot be eliminated through cryptographic means. These
security problems are described fully in Section 13.
14.4. Requirements for a Long Term Solution
From RFC3424 [24], any UNSAF proposal must provide:
Identify requirements for longer term, sound technical solutions
-- contribute to the process of finding the right longer term
solution.
Our experience with STUN has led to the following requirements for a
long term solution to the NAT problem:
o Requests for bindings and control of other resources in a NAT need
to be explicit. Much of the brittleness in STUN derives from its
guessing at the parameters of the NAT, rather than telling the NAT
what parameters to use, or knowing what parameters the NAT will
use.
o Control needs to be in-band. There are far too many scenarios in
which the client will not know about the location of middleboxes
ahead of time. Instead, control of such boxes needs to occur in-
band, traveling along the same path as the data will itself
travel. This guarantees that the right set of middleboxes are
controlled.
o Control needs to be limited. Users will need to communicate
through NATs which are outside of their administrative control.
In order for providers to be willing to deploy NATs which can be
controlled by users in different domains, the scope of such
controls needs to be extremely limited - typically, allocating a
binding to reach the address where the control packets are coming
from.
o Simplicity is Paramount. The control protocol will need to be
implemented in very simple clients. The servers will need to
support extremely high loads. The protocol will need to be
extremely robust, being the precursor to a host of application
protocols. As such, simplicity is key.
14.5. Issues with Existing NAPT Boxes
From RFC3424 [24], any UNSAF proposal must provide:
Discussion of the impact of the noted practical issues with
existing, deployed NA[P]Ts and experience reports.
Originally, RFC 3489 was developed as a standalone solution for NAT The IAB has mandated that protocols developed for this purpose
traversal for several types of applications, including VoIP. document a specific set of considerations. Because some STUN usages
However, practical experience found that the limitations of its usage provide UNSAF functions (such as ICE [I-D.ietf-mmusic-ice] ), and
in isolation made it impractical as a complete solution. There were others do not (such as SIP Outbound [I-D.ietf-sip-outbound]), answers
too many NATs which didn't support hairpinning or which had address to these considerations need to be addressed by the usages
and port dependent mapping properties. themselves.
Consequently, STUN was revised to produce this specification, which 17. IANA Considerations
turns STUN into a tool that is used as part of a broader solution.
For multimedia communications protocols, this broader solution is
ICE. ICE uses the binding discovery usage and defines its own
connectivity check usage, and then utilizes them together. When done
this way, ICE eliminates almost all of the brittleness and issues
found with RFC 3489 alone.
15. IANA Considerations IANA is hereby requested to create three new registries: a STUN
methods registry, a STUN Attributes registry, and a STUN Error Codes
registry.
IANA is hereby requested to create two new registries - STUN methods 17.1. STUN Methods Registry
and STUN Attributes. IANA must assign the following values to both
registries before publication of this document as an RFC. New values
for both STUN methods and STUN attributes are assigned through the
IETF consensus process via RFCs approved by the IESG [25].
15.1. STUN Methods Registry A STUN method is a hex number in the range 0x000 - 0x3FF. The
encoding of STUN method into a STUN message is described in
Section 6.
The initial STUN methods are: The initial STUN methods are:
0x000: (Reserved)
0x001:Binding 0x001:Binding
0x002:Shared Secret 0x002: (Reserved; was SharedSecret)
15.2. STUN Attribute Registry STUN methods in the range 0x000 - 0x1FF are assigned by IETF
Consensus [RFC2434]. STUN methods in the range 0x200 - 0x3FF are
assigned on a First Come First Served basis [RFC2434]
STUN attributes values above 0x7FFF are considered optional 17.2. STUN Attribute Registry
attributes; attributes equal to 0x7FFF or below are considered
mandatory attributes. The STUN client and STUN server process
optional and mandatory attributes differently. IANA should assign
values based on the RFC consensus process.
The initial STUN Attributes are: A STUN Attribute type is a hex number in the range 0x0000 - 0xFFFF.
STUN attribute types in the range 0x0000 - 0x7FFF are considered
comprehension-required; STUN attribute types in the range 0x8000 -
0xFFFF are considered comprehension-optional. A STUN agent handles
unknown comprehension-required and comprehension-optional attributes
differently.
The initial STUN Attributes types are:
Comprehension-required range (0x0000-0x7FFF):
0x0000: (Reserved)
0x0001: MAPPED-ADDRESS 0x0001: MAPPED-ADDRESS
0x0006: USERNAME 0x0006: USERNAME
0x0007: PASSWORD 0x0007: (Reserved; was PASSWORD)
0x0008: MESSAGE-INTEGRITY 0x0008: MESSAGE-INTEGRITY
0x0009: ERROR-CODE 0x0009: ERROR-CODE
0x000A: UNKNOWN-ATTRIBUTES 0x000A: UNKNOWN-ATTRIBUTES
0x0014: REALM 0x0014: REALM
0x0015: NONCE 0x0015: NONCE
0x0020: XOR-MAPPED-ADDRESS 0x0020: XOR-MAPPED-ADDRESS
0x8023: FINGERPRINT
Comprehension-optional range (0x8000-0xFFFF)
0x8022: SERVER 0x8022: SERVER
0x8023: ALTERNATE-SERVER 0x8023: ALTERNATE-SERVER
0x8024: REFRESH-INTERVAL 0x8028: FINGERPRINT
16. Changes Since RFC 3489 STUN Attribute types in the first half of the comprehension-required
range (0x0000 - 0x3FFF) and in the first half of the comprehension-
optional range (0x8000 - 0xBFFF) are assigned by IETF Consensus
[RFC2434]. STUN Attribute types in the second half of the
comprehension-required range (0x4000 - 0x7FFF) and in the second half
of the comprehension-optional range (0xC000 - 0xFFFF) are assigned on
a First Come First Served basis [RFC2434].
This specification updates RFC3489 [15]. This specification differs 17.3. STUN Error Code Registry
from RFC3489 in the following ways:
A STUN Error code is a number in the range 0 - 699. STUN error codes
are accompanied by a textual reason phrase in UTF-8 which is intended
only for human consumption and can be anything appropriate; this
document proposes only suggested values.
STUN error codes are consistent in codepoint assignments and
semantics with SIP [RFC3261] and HTTP [RFC2616].
The initial values in this registry are given in Section 14.6.
New STUN error codes are assigned on a Specification-Required basis
[RFC2434]. The specification must carefully consider how clients
that do not understand this error code will process it before
granting the request. See the rules in Section 7.3.4.
18. Changes Since RFC 3489
This specification obsoletes RFC3489 [RFC3489]. This specification
differs from RFC3489 in the following ways:
o Removed the notion that STUN is a complete NAT traversal solution.
STUN is now a toolkit that can be used to produce a NAT traversal
solution. As a consequence, changed the name of the protocol to
Session Traversal Utilities for NAT.
o Introduced the concept of STUN usages, and described what a usage
of STUN must document.
o Removed the usage of STUN for NAT type detection and binding o Removed the usage of STUN for NAT type detection and binding
lifetime discovery. These techniques have proven overly brittle lifetime discovery. These techniques have proven overly brittle
due to wider variations in the types of NAT devices than described due to wider variations in the types of NAT devices than described
in this document. Removed the RESPONSE-ADDRESS, CHANGED-ADDRESS, in this document. Removed the RESPONSE-ADDRESS, CHANGED-ADDRESS,
CHANGE-REQUEST, SOURCE-ADDRESS, and REFLECTED-FROM attributes. CHANGE-REQUEST, SOURCE-ADDRESS, and REFLECTED-FROM attributes.
o Added a fixed 32-bit magic cookie and reduced length of o Added a fixed 32-bit magic cookie and reduced length of
transaction ID by 32 bits. The magic cookie begins at the same transaction ID by 32 bits. The magic cookie begins at the same
offset as the original transaction ID. offset as the original transaction ID.
skipping to change at page 57, line 5 skipping to change at page 41, line 40
o Introduced formal structure into the Message Type header field, o Introduced formal structure into the Message Type header field,
with an explicit pair of bits for indication of request, response, with an explicit pair of bits for indication of request, response,
error response or indication. Consequently, the message type error response or indication. Consequently, the message type
field is split into the class (one of the previous four) and field is split into the class (one of the previous four) and
method. method.
o Explicitly point out that the most significant two bits of STUN o Explicitly point out that the most significant two bits of STUN
are 0b00, allowing easy differentiation with RTP packets when used are 0b00, allowing easy differentiation with RTP packets when used
with ICE. with ICE.
o Added the FINGERPRINT attribute to provide a method of definitely
detecting the difference between STUN and another protocol when
the two protocols are multiplexed together.
o Added support for IPv6. Made it clear that an IPv4 client could o Added support for IPv6. Made it clear that an IPv4 client could
get a v6 mapped address, and vice-a-versa. get a v6 mapped address, and vice-a-versa.
o Added long-term credential-based authentication. o Added long-term credential-based authentication.
o Added the SERVER, REALM, NONCE, and ALTERNATE-SERVER attributes. o Added the SERVER, REALM, NONCE, and ALTERNATE-SERVER attributes.
o Removed the SharedSecret method, and thus the PASSWORD attribute.
This method was almost never implemented and is not needed with
current usages.
o Removed recommendation to continue listening for STUN Responses o Removed recommendation to continue listening for STUN Responses
for 10 seconds in an attempt to recognize an attack. for 10 seconds in an attempt to recognize an attack.
o Introduced the concept of STUN usages and defined three usages -
Binding Discovery, NAT Keepalive, and Short term password.
o Changed transaction timers to be more TCP friendly. o Changed transaction timers to be more TCP friendly.
o Removed the STUN example that centered around the separation of o Removed the STUN example that centered around the separation of
the control and media planes. Instead, provided more information the control and media planes. Instead, provided more information
on using STUN with protocols. on using STUN with protocols.
17. Acknowledgements o Defined a generic padding mechanism that changes the
interpretation of the length attribute. This would, in theory,
break backwards compatibility. However, the mechanism in RFC 3489
never worked for the few attributes that weren't aligned naturally
on 32 bit boundaries.
o REALM, USERNAME, SERVER, reason phrases and NONCE limited to 127
characters.
19. Acknowledgements
The authors would like to thank Cedric Aoun, Pete Cordell, Cullen The authors would like to thank Cedric Aoun, Pete Cordell, Cullen
Jennings, Bob Penfield, Xavier Marjou, Bruce Lowekamp and Chris Jennings, Bob Penfield, Xavier Marjou, Bruce Lowekamp and Chris
Sullivan for their comments, and Baruch Sterman and Alan Hawrylyshen Sullivan for their comments, and Baruch Sterman and Alan Hawrylyshen
for initial implementations. Thanks for Leslie Daigle, Allison for initial implementations. Thanks for Leslie Daigle, Allison
Mankin, Eric Rescorla, and Henning Schulzrinne for IESG and IAB input Mankin, Eric Rescorla, and Henning Schulzrinne for IESG and IAB input
on this work. on this work.
18. References 20. References
18.1. Normative References 20.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[2] Postel, J., "Internet Protocol", STD 5, RFC 791, [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791,
September 1981. September 1981.
[3] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782, specifying the location of services (DNS SRV)", RFC 2782,
February 2000. February 2000.
[4] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[5] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
[6] Ferguson, P. and D. Senie, "Network Ingress Filtering:
Defeating Denial of Service Attacks which employ IP Source
Address Spoofing", BCP 38, RFC 2827, May 2000.
[7] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Leach, P., Luotonen, A., and L. Stewart, "HTTP
Basic and Digest Access Authentication", RFC 2617, June 1999. Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[8] Paxson, V. and M. Allman, "Computing TCP's Retransmission [RFC2988] Paxson, V. and M. Allman, "Computing TCP's Retransmission
Timer", RFC 2988, November 2000. Timer", RFC 2988, November 2000.
[9] International Telecommunications Union, "Error-correcting [ITU.V42.1994]
International Telecommunications Union, "Error-correcting
Procedures for DCEs Using Asynchronous-to-Synchronous Procedures for DCEs Using Asynchronous-to-Synchronous
Conversion", ITU-T Recommendation V.42, 1994. Conversion", ITU-T Recommendation V.42, 1994.
18.2. Informational References 20.2. Informational References
[10] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-Hashing
for Message Authentication", RFC 2104, February 1997.
[11] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[12] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- Hashing for Message Authentication", RFC 2104,
HTTP/1.1", RFC 2616, June 1999. February 1997.
[13] Rosenberg, J., "Interactive Connectivity Establishment (ICE): A [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
Methodology for Network Address Translator (NAT) Traversal for A., Peterson, J., Sparks, R., Handley, M., and E.
Offer/Answer Protocols", draft-ietf-mmusic-ice-13 (work in Schooler, "SIP: Session Initiation Protocol", RFC 3261,
progress), January 2007. June 2002.
[14] Audet, F. and C. Jennings, "NAT Behavioral Requirements for [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Unicast UDP", draft-ietf-behave-nat-udp-08 (work in progress), Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
October 2006. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[15] Rosenberg, J., Weinberger, J., Huitema, C., and R. Mahy, "STUN [I-D.ietf-mmusic-ice]
- Simple Traversal of User Datagram Protocol (UDP) Through Rosenberg, J., "Interactive Connectivity Establishment
Network Address Translators (NATs)", RFC 3489, March 2003. (ICE): A Protocol for Network Address Translator (NAT)
Traversal for Offer/Answer Protocols",
draft-ietf-mmusic-ice-16 (work in progress), June 2007.
[16] Rosenberg, J., "Obtaining Relay Addresses from Simple Traversal [RFC3489] Rosenberg, J., Weinberger, J., Huitema, C., and R. Mahy,
Underneath NAT (STUN)", draft-ietf-behave-turn-02 (work in "STUN - Simple Traversal of User Datagram Protocol (UDP)
progress), October 2006. Through Network Address Translators (NATs)", RFC 3489,
March 2003.
[17] Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson, [I-D.ietf-behave-turn]
"RTP: A Transport Protocol for Real-Time Applications", Rosenberg, J., "Obtaining Relay Addresses from Simple
RFC 3550, July 2003. Traversal Underneath NAT (STUN)",
draft-ietf-behave-turn-03 (work in progress), March 2007.
[18] Jennings, C. and R. Mahy, "Managing Client Initiated [I-D.ietf-sip-outbound]
Jennings, C. and R. Mahy, "Managing Client Initiated
Connections in the Session Initiation Protocol (SIP)", Connections in the Session Initiation Protocol (SIP)",
draft-ietf-sip-outbound-07 (work in progress), January 2007. draft-ietf-sip-outbound-09 (work in progress), June 2007.
[19] Handley, M., Jacobson, V., and C. Perkins, "SDP: Session [I-D.ietf-behave-nat-behavior-discovery]
Description Protocol", RFC 4566, July 2006. MacDonald, D. and B. Lowekamp, "NAT Behavior Discovery
Using STUN", draft-ietf-behave-nat-behavior-discovery-00
(work in progress), February 2007.
[20] Senie, D., "Network Address Translator (NAT)-Friendly [I-D.ietf-mmusic-ice-tcp]
Application Design Guidelines", RFC 3235, January 2002. Rosenberg, J., "TCP Candidates with Interactive
Connectivity Establishment (ICE",
draft-ietf-mmusic-ice-tcp-03 (work in progress),
March 2007.
[21] Holdrege, M. and P. Srisuresh, "Protocol Complications with the [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
IP Network Address Translator", RFC 3027, January 2001. with Session Description Protocol (SDP)", RFC 3264,
June 2002.
[22] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with [RFC3424] Daigle, L. and IAB, "IAB Considerations for UNilateral
Session Description Protocol (SDP)", RFC 3264, June 2002. Self-Address Fixing (UNSAF) Across Network Address
Translation", RFC 3424, November 2002.
[23] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K. [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
Norrman, "The Secure Real-time Transport Protocol (SRTP)", IANA Considerations Section in RFCs", BCP 26, RFC 2434,
RFC 3711, March 2004. October 1998.
[24] Daigle, L. and IAB, "IAB Considerations for UNilateral Self- Appendix A. C Snippet to Determine STUN Message Types
Address Fixing (UNSAF) Across Network Address Translation",
RFC 3424, November 2002.
[25] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Given an 16-bit STUN message type value in host byte order in
Considerations Section in RFCs", BCP 26, RFC 2434, msg_type parameter, below are C macros to determine the STUN message
October 1998. types:
#define IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000)
#define IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010)
#define IS_SUCCESS_RESP(msg_type) (((msg_type) & 0x0110) == 0x0100)
#define IS_ERR_RESP(msg_type) (((msg_type) & 0x0110) == 0x0110)
Authors' Addresses Authors' Addresses
Jonathan Rosenberg Jonathan Rosenberg
Cisco Cisco
Edison, NJ Edison, NJ
US US
Email: jdrosen@cisco.com Email: jdrosen@cisco.com
URI: http://www.jdrosen.net URI: http://www.jdrosen.net
skipping to change at page 59, line 42 skipping to change at page 45, line 4
Authors' Addresses Authors' Addresses
Jonathan Rosenberg Jonathan Rosenberg
Cisco Cisco
Edison, NJ Edison, NJ
US US
Email: jdrosen@cisco.com Email: jdrosen@cisco.com
URI: http://www.jdrosen.net URI: http://www.jdrosen.net
Christian Huitema Christian Huitema
Microsoft Microsoft
One Microsoft Way One Microsoft Way
Redmond, WA 98052 Redmond, WA 98052
US US
Email: huitema@microsoft.com Email: huitema@microsoft.com
Rohan Mahy Rohan Mahy
Plantronics Plantronics
345 Encinal Street 345 Encinal Street
Santa Cruz, CA 95060 Santa Cruz, CA 95060
US US
Email: rohan@ekabal.com Email: rohan@ekabal.com
Philip Matthews
Avaya
1135 Innovation Drive
Ottawa, Ontario K2K 3G7
Canada
Phone: +1 613 592 4343 x224
Fax:
Email: philip_matthews@magma.ca
URI:
Dan Wing Dan Wing
Cisco Systems Cisco
771 Alder Drive 771 Alder Drive
San Jose, CA 95035 San Jose, CA 95035
US US
Email: dwing@cisco.com Email: dwing@cisco.com
Full Copyright Statement Full Copyright Statement
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
 End of changes. 335 change blocks. 
2231 lines changed or deleted 1530 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/