idnits 2.17.1 draft-ietf-tram-stunbis-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 15, 2016) is 2866 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.V42.2002' ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2460 (Obsoleted by RFC 8200) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7613 (Obsoleted by RFC 8265) == Outdated reference: A later version (-20) exists of draft-ietf-ice-rfc5245bis-01 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 3489 (Obsoleted by RFC 5389) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) -- Obsolete informational reference (is this intentional?): RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 7525 (Obsoleted by RFC 9325) Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TRAM M. Petit-Huguenin 3 Internet-Draft Impedance Mismatch 4 Obsoletes: 5389 (if approved) G. Salgueiro 5 Intended status: Standards Track J. Rosenberg 6 Expires: December 17, 2016 D. Wing 7 Cisco 8 R. Mahy 9 Plantronics 10 P. Matthews 11 Avaya 12 June 15, 2016 14 Session Traversal Utilities for NAT (STUN) 15 draft-ietf-tram-stunbis-08 17 Abstract 19 Session Traversal Utilities for NAT (STUN) is a protocol that serves 20 as a tool for other protocols in dealing with Network Address 21 Translator (NAT) traversal. It can be used by an endpoint to 22 determine the IP address and port allocated to it by a NAT. It can 23 also be used to check connectivity between two endpoints, and as a 24 keep-alive protocol to maintain NAT bindings. STUN works with many 25 existing NATs, and does not require any special behavior from them. 27 STUN is not a NAT traversal solution by itself. Rather, it is a tool 28 to be used in the context of a NAT traversal solution. 30 This document obsoletes RFC 5389. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on December 17, 2016. 49 Copyright Notice 51 Copyright (c) 2016 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 5 68 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 5. STUN Message Structure . . . . . . . . . . . . . . . . . . . 10 71 6. Base Protocol Procedures . . . . . . . . . . . . . . . . . . 12 72 6.1. Forming a Request or an Indication . . . . . . . . . . . 12 73 6.2. Sending the Request or Indication . . . . . . . . . . . . 13 74 6.2.1. Sending over UDP or DTLS-over-UDP . . . . . . . . . . 14 75 6.2.2. Sending over TCP or TLS-over-TCP . . . . . . . . . . 15 76 6.2.3. Sending over TLS-over-TCP or DTLS-over-UDP . . . . . 16 77 6.3. Receiving a STUN Message . . . . . . . . . . . . . . . . 17 78 6.3.1. Processing a Request . . . . . . . . . . . . . . . . 17 79 6.3.1.1. Forming a Success or Error Response . . . . . . . 18 80 6.3.1.2. Sending the Success or Error Response . . . . . . 19 81 6.3.2. Processing an Indication . . . . . . . . . . . . . . 19 82 6.3.3. Processing a Success Response . . . . . . . . . . . . 20 83 6.3.4. Processing an Error Response . . . . . . . . . . . . 20 84 7. FINGERPRINT Mechanism . . . . . . . . . . . . . . . . . . . . 21 85 8. DNS Discovery of a Server . . . . . . . . . . . . . . . . . . 21 86 8.1. STUN URI Scheme Semantics . . . . . . . . . . . . . . . . 22 87 9. Authentication and Message-Integrity Mechanisms . . . . . . . 23 88 9.1. Short-Term Credential Mechanism . . . . . . . . . . . . . 23 89 9.1.1. HMAC Key . . . . . . . . . . . . . . . . . . . . . . 23 90 9.1.2. Forming a Request or Indication . . . . . . . . . . . 24 91 9.1.3. Receiving a Request or Indication . . . . . . . . . . 24 92 9.1.4. Receiving a Response . . . . . . . . . . . . . . . . 25 93 9.1.5. Sending Subsequent Requests . . . . . . . . . . . . . 25 94 9.2. Long-Term Credential Mechanism . . . . . . . . . . . . . 26 95 9.2.1. Bid Down Attack Prevention . . . . . . . . . . . . . 27 96 9.2.2. HMAC Key . . . . . . . . . . . . . . . . . . . . . . 27 97 9.2.3. Forming a Request . . . . . . . . . . . . . . . . . . 28 98 9.2.3.1. First Request . . . . . . . . . . . . . . . . . . 28 99 9.2.3.2. Subsequent Requests . . . . . . . . . . . . . . . 28 100 9.2.4. Receiving a Request . . . . . . . . . . . . . . . . . 29 101 9.2.5. Receiving a Response . . . . . . . . . . . . . . . . 31 102 10. ALTERNATE-SERVER Mechanism . . . . . . . . . . . . . . . . . 32 103 11. Backwards Compatibility with RFC 3489 . . . . . . . . . . . . 33 104 12. Basic Server Behavior . . . . . . . . . . . . . . . . . . . . 33 105 13. STUN Usages . . . . . . . . . . . . . . . . . . . . . . . . . 34 106 14. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 35 107 14.1. MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . . . 36 108 14.2. XOR-MAPPED-ADDRESS . . . . . . . . . . . . . . . . . . . 36 109 14.3. USERNAME . . . . . . . . . . . . . . . . . . . . . . . . 37 110 14.4. USERHASH . . . . . . . . . . . . . . . . . . . . . . . . 38 111 14.5. MESSAGE-INTEGRITY . . . . . . . . . . . . . . . . . . . 38 112 14.6. MESSAGE-INTEGRITY-SHA256 . . . . . . . . . . . . . . . . 39 113 14.7. FINGERPRINT . . . . . . . . . . . . . . . . . . . . . . 40 114 14.8. ERROR-CODE . . . . . . . . . . . . . . . . . . . . . . . 40 115 14.9. REALM . . . . . . . . . . . . . . . . . . . . . . . . . 42 116 14.10. NONCE . . . . . . . . . . . . . . . . . . . . . . . . . 42 117 14.11. PASSWORD-ALGORITHMS . . . . . . . . . . . . . . . . . . 42 118 14.12. PASSWORD-ALGORITHM . . . . . . . . . . . . . . . . . . . 43 119 14.13. UNKNOWN-ATTRIBUTES . . . . . . . . . . . . . . . . . . . 44 120 14.14. SOFTWARE . . . . . . . . . . . . . . . . . . . . . . . . 44 121 14.15. ALTERNATE-SERVER . . . . . . . . . . . . . . . . . . . . 44 122 14.16. ALTERNATE-DOMAIN . . . . . . . . . . . . . . . . . . . . 44 123 15. Security Considerations . . . . . . . . . . . . . . . . . . . 45 124 15.1. Attacks against the Protocol . . . . . . . . . . . . . . 45 125 15.1.1. Outside Attacks . . . . . . . . . . . . . . . . . . 45 126 15.1.2. Inside Attacks . . . . . . . . . . . . . . . . . . . 46 127 15.2. Attacks Affecting the Usage . . . . . . . . . . . . . . 46 128 15.2.1. Attack I: Distributed DoS (DDoS) against a Target . 47 129 15.2.2. Attack II: Silencing a Client . . . . . . . . . . . 47 130 15.2.3. Attack III: Assuming the Identity of a Client . . . 47 131 15.2.4. Attack IV: Eavesdropping . . . . . . . . . . . . . . 47 132 15.3. Hash Agility Plan . . . . . . . . . . . . . . . . . . . 48 133 16. IAB Considerations . . . . . . . . . . . . . . . . . . . . . 48 134 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 135 17.1. STUN Security Features Registry . . . . . . . . . . . . 49 136 17.2. STUN Methods Registry . . . . . . . . . . . . . . . . . 49 137 17.3. STUN Attribute Registry . . . . . . . . . . . . . . . . 49 138 17.3.1. Updated Attributes . . . . . . . . . . . . . . . . . 49 139 17.3.2. New Attributes . . . . . . . . . . . . . . . . . . . 50 140 17.4. STUN Error Code Registry . . . . . . . . . . . . . . . . 50 141 17.5. Password Algorithm Registry . . . . . . . . . . . . . . 50 142 17.5.1. Password Algorithms . . . . . . . . . . . . . . . . 51 143 17.5.1.1. MD5 . . . . . . . . . . . . . . . . . . . . . . 51 144 17.5.1.2. SHA256 . . . . . . . . . . . . . . . . . . . . . 51 146 17.6. STUN UDP and TCP Port Numbers . . . . . . . . . . . . . 51 147 18. Changes since RFC 5389 . . . . . . . . . . . . . . . . . . . 51 148 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 149 19.1. Normative References . . . . . . . . . . . . . . . . . . 52 150 19.2. Informative References . . . . . . . . . . . . . . . . . 54 151 Appendix A. C Snippet to Determine STUN Message Types . . . . . 56 152 Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 56 153 B.1. Sample Request with Long-Term Authentication with 154 MESSAGE-INTEGRITY-SHA256 and USERHASH . . . . . . . . . . 57 155 Appendix C. Release notes . . . . . . . . . . . . . . . . . . . 59 156 C.1. Modifications between draft-ietf-tram-stunbis-08 and 157 draft-ietf-tram-stunbis-07 . . . . . . . . . . . . . . . 59 158 C.2. Modifications between draft-ietf-tram-stunbis-07 and 159 draft-ietf-tram-stunbis-06 . . . . . . . . . . . . . . . 59 160 C.3. Modifications between draft-ietf-tram-stunbis-06 and 161 draft-ietf-tram-stunbis-05 . . . . . . . . . . . . . . . 59 162 C.4. Modifications between draft-ietf-tram-stunbis-05 and 163 draft-ietf-tram-stunbis-04 . . . . . . . . . . . . . . . 60 164 C.5. Modifications between draft-ietf-tram-stunbis-04 and 165 draft-ietf-tram-stunbis-03 . . . . . . . . . . . . . . . 60 166 C.6. Modifications between draft-ietf-tram-stunbis-03 and 167 draft-ietf-tram-stunbis-02 . . . . . . . . . . . . . . . 60 168 C.7. Modifications between draft-ietf-tram-stunbis-02 and 169 draft-ietf-tram-stunbis-01 . . . . . . . . . . . . . . . 60 170 C.8. Modifications between draft-ietf-tram-stunbis-01 and 171 draft-ietf-tram-stunbis-00 . . . . . . . . . . . . . . . 61 172 C.9. Modifications between draft-salgueiro-tram-stunbis-02 and 173 draft-ietf-tram-stunbis-00 . . . . . . . . . . . . . . . 62 174 C.10. Modifications between draft-salgueiro-tram-stunbis-02 and 175 draft-salgueiro-tram-stunbis-01 . . . . . . . . . . . . . 62 176 C.11. Modifications between draft-salgueiro-tram-stunbis-01 and 177 draft-salgueiro-tram-stunbis-00 . . . . . . . . . . . . . 62 178 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 62 179 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 63 180 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63 182 1. Introduction 184 The protocol defined in this specification, Session Traversal 185 Utilities for NAT, provides a tool for dealing with NATs. It 186 provides a means for an endpoint to determine the IP address and port 187 allocated by a NAT that corresponds to its private IP address and 188 port. It also provides a way for an endpoint to keep a NAT binding 189 alive. With some extensions, the protocol can be used to do 190 connectivity checks between two endpoints [I-D.ietf-ice-rfc5245bis], 191 or to relay packets between two endpoints [RFC5766]. 193 In keeping with its tool nature, this specification defines an 194 extensible packet format, defines operation over several transport 195 protocols, and provides for two forms of authentication. 197 STUN is intended to be used in context of one or more NAT traversal 198 solutions. These solutions are known as STUN usages. Each usage 199 describes how STUN is utilized to achieve the NAT traversal solution. 200 Typically, a usage indicates when STUN messages get sent, which 201 optional attributes to include, what server is used, and what 202 authentication mechanism is to be used. Interactive Connectivity 203 Establishment (ICE) [I-D.ietf-ice-rfc5245bis] is one usage of STUN. 204 SIP Outbound [RFC5626] is another usage of STUN. In some cases, a 205 usage will require extensions to STUN. A STUN extension can be in 206 the form of new methods, attributes, or error response codes. More 207 information on STUN usages can be found in Section 13. 209 Implementations and deployments of a STUN usage using TLS or DTLS 210 should follow the recommendations in [RFC7525]. 212 2. Overview of Operation 214 This section is descriptive only. 216 /-----\ 217 // STUN \\ 218 | Server | 219 \\ // 220 \-----/ 222 +--------------+ Public Internet 223 ................| NAT 2 |....................... 224 +--------------+ 226 +--------------+ Private NET 2 227 ................| NAT 1 |....................... 228 +--------------+ 230 /-----\ 231 // STUN \\ 232 | Client | 233 \\ // Private NET 1 234 \-----/ 236 Figure 1: One Possible STUN Configuration 238 One possible STUN configuration is shown in Figure 1. In this 239 configuration, there are two entities (called STUN agents) that 240 implement the STUN protocol. The lower agent in the figure is the 241 client, and is connected to private network 1. This network connects 242 to private network 2 through NAT 1. Private network 2 connects to 243 the public Internet through NAT 2. The upper agent in the figure is 244 the server, and resides on the public Internet. 246 STUN is a client-server protocol. It supports two types of 247 transactions. One is a request/response transaction in which a 248 client sends a request to a server, and the server returns a 249 response. The second is an indication transaction in which either 250 agent -- client or server -- sends an indication that generates no 251 response. Both types of transactions include a transaction ID, which 252 is a randomly selected 96-bit number. For request/response 253 transactions, this transaction ID allows the client to associate the 254 response with the request that generated it; for indications, the 255 transaction ID serves as a debugging aid. 257 All STUN messages start with a fixed header that includes a method, a 258 class, and the transaction ID. The method indicates which of the 259 various requests or indications this is; this specification defines 260 just one method, Binding, but other methods are expected to be 261 defined in other documents. The class indicates whether this is a 262 request, a success response, an error response, or an indication. 263 Following the fixed header comes zero or more attributes, which are 264 Type-Length-Value extensions that convey additional information for 265 the specific message. 267 This document defines a single method called Binding. The Binding 268 method can be used either in request/response transactions or in 269 indication transactions. When used in request/response transactions, 270 the Binding method can be used to determine the particular "binding" 271 a NAT has allocated to a STUN client. When used in either request/ 272 response or in indication transactions, the Binding method can also 273 be used to keep these "bindings" alive. 275 In the Binding request/response transaction, a Binding request is 276 sent from a STUN client to a STUN server. When the Binding request 277 arrives at the STUN server, it may have passed through one or more 278 NATs between the STUN client and the STUN server (in Figure 1, there 279 were two such NATs). As the Binding request message passes through a 280 NAT, the NAT will modify the source transport address (that is, the 281 source IP address and the source port) of the packet. As a result, 282 the source transport address of the request received by the server 283 will be the public IP address and port created by the NAT closest to 284 the server. This is called a reflexive transport address. The STUN 285 server copies that source transport address into an XOR-MAPPED- 286 ADDRESS attribute in the STUN Binding response and sends the Binding 287 response back to the STUN client. As this packet passes back through 288 a NAT, the NAT will modify the destination transport address in the 289 IP header, but the transport address in the XOR-MAPPED-ADDRESS 290 attribute within the body of the STUN response will remain untouched. 291 In this way, the client can learn its reflexive transport address 292 allocated by the outermost NAT with respect to the STUN server. 294 In some usages, STUN must be multiplexed with other protocols (e.g., 295 [I-D.ietf-ice-rfc5245bis], [RFC5626]). In these usages, there must 296 be a way to inspect a packet and determine if it is a STUN packet or 297 not. STUN provides three fields in the STUN header with fixed values 298 that can be used for this purpose. If this is not sufficient, then 299 STUN packets can also contain a FINGERPRINT value, which can further 300 be used to distinguish the packets. 302 STUN defines a set of optional procedures that a usage can decide to 303 use, called mechanisms. These mechanisms include DNS discovery, a 304 redirection technique to an alternate server, a fingerprint attribute 305 for demultiplexing, and two authentication and message-integrity 306 exchanges. The authentication mechanisms revolve around the use of a 307 username, password, and message-integrity value. Two authentication 308 mechanisms, the long-term credential mechanism and the short-term 309 credential mechanism, are defined in this specification. Each usage 310 specifies the mechanisms allowed with that usage. 312 In the long-term credential mechanism, the client and server share a 313 pre-provisioned username and password and perform a digest challenge/ 314 response exchange inspired by (but differing in details) to the one 315 defined for HTTP [RFC2617]. In the short-term credential mechanism, 316 the client and the server exchange a username and password through 317 some out-of-band method prior to the STUN exchange. For example, in 318 the ICE usage [I-D.ietf-ice-rfc5245bis] the two endpoints use out-of- 319 band signaling to exchange a username and password. These are used 320 to integrity protect and authenticate the request and response. 321 There is no challenge or nonce used. 323 3. Terminology 325 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 326 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 327 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 328 [RFC2119] and indicate requirement levels for compliant STUN 329 implementations. 331 4. Definitions 333 STUN Agent: A STUN agent is an entity that implements the STUN 334 protocol. The entity can be either a STUN client or a STUN 335 server. 337 STUN Client: A STUN client is an entity that sends STUN requests and 338 receives STUN responses. A STUN client can also send indications. 339 In this specification, the terms STUN client and client are 340 synonymous. 342 STUN Server: A STUN server is an entity that receives STUN requests 343 and sends STUN responses. A STUN server can also send 344 indications. In this specification, the terms STUN server and 345 server are synonymous. 347 Transport Address: The combination of an IP address and port number 348 (such as a UDP or TCP port number). 350 Reflexive Transport Address: A transport address learned by a client 351 that identifies that client as seen by another host on an IP 352 network, typically a STUN server. When there is an intervening 353 NAT between the client and the other host, the reflexive transport 354 address represents the mapped address allocated to the client on 355 the public side of the NAT. Reflexive transport addresses are 356 learned from the mapped address attribute (MAPPED-ADDRESS or XOR- 357 MAPPED-ADDRESS) in STUN responses. 359 Mapped Address: Same meaning as reflexive address. This term is 360 retained only for historic reasons and due to the naming of the 361 MAPPED-ADDRESS and XOR-MAPPED-ADDRESS attributes. 363 Long-Term Credential: A username and associated password that 364 represent a shared secret between client and server. Long-term 365 credentials are generally granted to the client when a subscriber 366 enrolls in a service and persist until the subscriber leaves the 367 service or explicitly changes the credential. 369 Long-Term Password: The password from a long-term credential. 371 Short-Term Credential: A temporary username and associated password 372 that represent a shared secret between client and server. Short- 373 term credentials are obtained through some kind of protocol 374 mechanism between the client and server, preceding the STUN 375 exchange. A short-term credential has an explicit temporal scope, 376 which may be based on a specific amount of time (such as 5 377 minutes) or on an event (such as termination of a SIP dialog). 378 The specific scope of a short-term credential is defined by the 379 application usage. 381 Short-Term Password: The password component of a short-term 382 credential. 384 STUN Indication: A STUN message that does not receive a response. 386 Attribute: The STUN term for a Type-Length-Value (TLV) object that 387 can be added to a STUN message. Attributes are divided into two 388 types: comprehension-required and comprehension-optional. STUN 389 agents can safely ignore comprehension-optional attributes they 390 don't understand, but cannot successfully process a message if it 391 contains comprehension-required attributes that are not 392 understood. 394 RTO: Retransmission TimeOut, which defines the initial period of 395 time between transmission of a request and the first retransmit of 396 that request. 398 5. STUN Message Structure 400 STUN messages are encoded in binary using network-oriented format 401 (most significant byte or octet first, also commonly known as big- 402 endian). The transmission order is described in detail in Appendix B 403 of RFC 791 [RFC0791]. Unless otherwise noted, numeric constants are 404 in decimal (base 10). 406 All STUN messages MUST start with a 20-byte header followed by zero 407 or more Attributes. The STUN header contains a STUN message type, 408 magic cookie, transaction ID, and message length. 410 0 1 2 3 411 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 412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 413 |0 0| STUN Message Type | Message Length | 414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 415 | Magic Cookie | 416 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 417 | | 418 | Transaction ID (96 bits) | 419 | | 420 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 422 Figure 2: Format of STUN Message Header 424 The most significant 2 bits of every STUN message MUST be zeroes. 425 This can be used to differentiate STUN packets from other protocols 426 when STUN is multiplexed with other protocols on the same port. 428 The message type defines the message class (request, success 429 response, failure response, or indication) and the message method 430 (the primary function) of the STUN message. Although there are four 431 message classes, there are only two types of transactions in STUN: 432 request/response transactions (which consist of a request message and 433 a response message) and indication transactions (which consist of a 434 single indication message). Response classes are split into error 435 and success responses to aid in quickly processing the STUN message. 437 The message type field is decomposed further into the following 438 structure: 440 0 1 441 2 3 4 5 6 7 8 9 0 1 2 3 4 5 442 +--+--+-+-+-+-+-+-+-+-+-+-+-+-+ 443 |M |M |M|M|M|C|M|M|M|C|M|M|M|M| 444 |11|10|9|8|7|1|6|5|4|0|3|2|1|0| 445 +--+--+-+-+-+-+-+-+-+-+-+-+-+-+ 447 Figure 3: Format of STUN Message Type Field 449 Here the bits in the message type field are shown as most significant 450 (M11) through least significant (M0). M11 through M0 represent a 451 12-bit encoding of the method. C1 and C0 represent a 2-bit encoding 452 of the class. A class of 0b00 is a request, a class of 0b01 is an 453 indication, a class of 0b10 is a success response, and a class of 454 0b11 is an error response. This specification defines a single 455 method, Binding. The method and class are orthogonal, so that for 456 each method, a request, success response, error response, and 457 indication are possible for that method. Extensions defining new 458 methods MUST indicate which classes are permitted for that method. 460 For example, a Binding request has class=0b00 (request) and 461 method=0b000000000001 (Binding) and is encoded into the first 16 bits 462 as 0x0001. A Binding response has class=0b10 (success response) and 463 method=0b000000000001, and is encoded into the first 16 bits as 464 0x0101. 466 Note: This unfortunate encoding is due to assignment of values in 467 [RFC3489] that did not consider encoding Indications, Success, and 468 Errors using bit fields. 470 The magic cookie field MUST contain the fixed value 0x2112A442 in 471 network byte order. In RFC 3489 [RFC3489], this field was part of 472 the transaction ID; placing the magic cookie in this location allows 473 a server to detect if the client will understand certain attributes 474 that were added in this revised specification. In addition, it aids 475 in distinguishing STUN packets from packets of other protocols when 476 STUN is multiplexed with those other protocols on the same port. 478 The transaction ID is a 96-bit identifier, used to uniquely identify 479 STUN transactions. For request/response transactions, the 480 transaction ID is chosen by the STUN client for the request and 481 echoed by the server in the response. For indications, it is chosen 482 by the agent sending the indication. It primarily serves to 483 correlate requests with responses, though it also plays a small role 484 in helping to prevent certain types of attacks. The server also uses 485 the transaction ID as a key to identify each transaction uniquely 486 across all clients. As such, the transaction ID MUST be uniformly 487 and randomly chosen from the interval 0 .. 2**96-1, and SHOULD be 488 cryptographically random. Resends of the same request reuse the same 489 transaction ID, but the client MUST choose a new transaction ID for 490 new transactions unless the new request is bit-wise identical to the 491 previous request and sent from the same transport address to the same 492 IP address. Success and error responses MUST carry the same 493 transaction ID as their corresponding request. When an agent is 494 acting as a STUN server and STUN client on the same port, the 495 transaction IDs in requests sent by the agent have no relationship to 496 the transaction IDs in requests received by the agent. 498 The message length MUST contain the size, in bytes, of the message 499 not including the 20-byte STUN header. Since all STUN attributes are 500 padded to a multiple of 4 bytes, the last 2 bits of this field are 501 always zero. This provides another way to distinguish STUN packets 502 from packets of other protocols. 504 Following the STUN fixed portion of the header are zero or more 505 attributes. Each attribute is TLV (Type-Length-Value) encoded. The 506 details of the encoding, and of the attributes themselves are given 507 in Section 14. 509 6. Base Protocol Procedures 511 This section defines the base procedures of the STUN protocol. It 512 describes how messages are formed, how they are sent, and how they 513 are processed when they are received. It also defines the detailed 514 processing of the Binding method. Other sections in this document 515 describe optional procedures that a usage may elect to use in certain 516 situations. Other documents may define other extensions to STUN, by 517 adding new methods, new attributes, or new error response codes. 519 6.1. Forming a Request or an Indication 521 When formulating a request or indication message, the agent MUST 522 follow the rules in Section 5 when creating the header. In addition, 523 the message class MUST be either "Request" or "Indication" (as 524 appropriate), and the method must be either Binding or some method 525 defined in another document. 527 The agent then adds any attributes specified by the method or the 528 usage. For example, some usages may specify that the agent use an 529 authentication method (Section 9) or the FINGERPRINT attribute 530 (Section 7). 532 If the agent is sending a request, it SHOULD add a SOFTWARE attribute 533 to the request. Agents MAY include a SOFTWARE attribute in 534 indications, depending on the method. Extensions to STUN should 535 discuss whether SOFTWARE is useful in new indications. 537 For the Binding method with no authentication, no attributes are 538 required unless the usage specifies otherwise. 540 All STUN messages sent over UDP or DTLS-over-UDP [RFC6347] SHOULD be 541 less than the path MTU, if known. 543 If the path MTU is unknown for UDP, messages SHOULD be the smaller of 544 576 bytes and the first-hop MTU for IPv4 [RFC1122] and 1280 bytes for 545 IPv6 [RFC2460]. This value corresponds to the overall size of the IP 546 packet. Consequently, for IPv4, the actual STUN message would need 547 to be less than 548 bytes (576 minus 20-byte IP header, minus 8-byte 548 UDP header, assuming no IP options are used). 550 If the path MTU is unknown for DTLS-over-UDP, the rules described in 551 the previous paragraph need to be adjusted to take into account the 552 size of the (13-byte) DTLS Record header, the MAC size, and the 553 padding size. 555 STUN provides no ability to handle the case where the request is 556 under the MTU but the response would be larger than the MTU. It is 557 not envisioned that this limitation will be an issue for STUN. The 558 MTU limitation is a SHOULD, and not a MUST, to account for cases 559 where STUN itself is being used to probe for MTU characteristics 560 [RFC5780]. Outside of this or similar applications, the MTU 561 constraint MUST be followed. 563 6.2. Sending the Request or Indication 565 The agent then sends the request or indication. This document 566 specifies how to send STUN messages over UDP, TCP, TLS-over-TCP, or 567 DTLS-over-UDP; other transport protocols may be added in the future. 568 The STUN usage must specify which transport protocol is used, and how 569 the agent determines the IP address and port of the recipient. 570 Section 8 describes a DNS-based method of determining the IP address 571 and port of a server that a usage may elect to use. STUN may be used 572 with anycast addresses, but only with UDP and in usages where 573 authentication is not used. 575 At any time, a client MAY have multiple outstanding STUN requests 576 with the same STUN server (that is, multiple transactions in 577 progress, with different transaction IDs). Absent other limits to 578 the rate of new transactions (such as those specified by ICE for 579 connectivity checks or when STUN is run over TCP), a client SHOULD 580 limit itself to ten outstanding transactions to the same server. 582 6.2.1. Sending over UDP or DTLS-over-UDP 584 When running STUN over UDP or STUN over DTLS-over-UDP [RFC7350], it 585 is possible that the STUN message might be dropped by the network. 586 Reliability of STUN request/response transactions is accomplished 587 through retransmissions of the request message by the client 588 application itself. STUN indications are not retransmitted; thus, 589 indication transactions over UDP or DTLS-over-UDP are not reliable. 591 A client SHOULD retransmit a STUN request message starting with an 592 interval of RTO ("Retransmission TimeOut"), doubling after each 593 retransmission. The RTO is an estimate of the round-trip time (RTT), 594 and is computed as described in RFC 6298 [RFC6298], with two 595 exceptions. First, the initial value for RTO SHOULD be greater than 596 500 ms. The exception cases for this "SHOULD" are when other 597 mechanisms are used to derive congestion thresholds (such as the ones 598 defined in ICE for fixed rate streams), or when STUN is used in non- 599 Internet environments with known network capacities. In fixed-line 600 access links, a value of 500 ms is RECOMMENDED. Second, the value of 601 RTO SHOULD NOT be rounded up to the nearest second. Rather, a 1 ms 602 accuracy SHOULD be maintained. As with TCP, the usage of Karn's 603 algorithm is RECOMMENDED [KARN87]. When applied to STUN, it means 604 that RTT estimates SHOULD NOT be computed from STUN transactions that 605 result in the retransmission of a request. 607 The value for RTO SHOULD be cached by a client after the completion 608 of the transaction, and used as the starting value for RTO for the 609 next transaction to the same server (based on equality of IP 610 address). The value SHOULD be considered stale and discarded after 611 10 minutes without any transactions to the same server. 613 Retransmissions continue until a response is received, or until a 614 total of Rc requests have been sent. Rc SHOULD be configurable and 615 SHOULD have a default of 7. If, after the last request, a duration 616 equal to Rm times the RTO has passed without a response (providing 617 ample time to get a response if only this final request actually 618 succeeds), the client SHOULD consider the transaction to have failed. 619 Rm SHOULD be configurable and SHOULD have a default of 16. A STUN 620 transaction over UDP or DTLS-over-UDP is also considered failed if 621 there has been a hard ICMP error [RFC1122]. For example, assuming an 622 RTO of 500ms, requests would be sent at times 0 ms, 500 ms, 1500 ms, 623 3500 ms, 7500 ms, 15500 ms, and 31500 ms. If the client has not 624 received a response after 39500 ms, the client will consider the 625 transaction to have timed out. 627 6.2.2. Sending over TCP or TLS-over-TCP 629 For TCP and TLS-over-TCP [RFC5246], the client opens a TCP connection 630 to the server. 632 In some usages of STUN, STUN is sent as the only protocol over the 633 TCP connection. In this case, it can be sent without the aid of any 634 additional framing or demultiplexing. In other usages, or with other 635 extensions, it may be multiplexed with other data over a TCP 636 connection. In that case, STUN MUST be run on top of some kind of 637 framing protocol, specified by the usage or extension, which allows 638 for the agent to extract complete STUN messages and complete 639 application layer messages. The STUN service running on the well- 640 known port or ports discovered through the DNS procedures in 641 Section 8 is for STUN alone, and not for STUN multiplexed with other 642 data. Consequently, no framing protocols are used in connections to 643 those servers. When additional framing is utilized, the usage will 644 specify how the client knows to apply it and what port to connect to. 645 For example, in the case of ICE connectivity checks, this information 646 is learned through out-of-band negotiation between client and server. 648 Reliability of STUN over TCP and TLS-over-TCP is handled by TCP 649 itself, and there are no retransmissions at the STUN protocol level. 650 However, for a request/response transaction, if the client has not 651 received a response by Ti seconds after it sent the SYN to establish 652 the connection, it considers the transaction to have timed out. Ti 653 SHOULD be configurable and SHOULD have a default of 39.5s. This 654 value has been chosen to equalize the TCP and UDP timeouts for the 655 default initial RTO. 657 In addition, if the client is unable to establish the TCP connection, 658 or the TCP connection is reset or fails before a response is 659 received, any request/response transaction in progress is considered 660 to have failed. 662 The client MAY send multiple transactions over a single TCP (or TLS- 663 over-TCP) connection, and it MAY send another request before 664 receiving a response to the previous. The client SHOULD keep the 665 connection open until it: 667 o has no further STUN requests or indications to send over that 668 connection, and 670 o has no plans to use any resources (such as a mapped address 671 (MAPPED-ADDRESS or XOR-MAPPED-ADDRESS) or relayed address 672 [RFC5766]) that were learned though STUN requests sent over that 673 connection, and 675 o if multiplexing other application protocols over that port, has 676 finished using that other application, and 678 o if using that learned port with a remote peer, has established 679 communications with that remote peer, as is required by some TCP 680 NAT traversal techniques (e.g., [RFC6544]). 682 At the server end, the server SHOULD keep the connection open, and 683 let the client close it, unless the server has determined that the 684 connection has timed out (for example, due to the client 685 disconnecting from the network). Bindings learned by the client will 686 remain valid in intervening NATs only while the connection remains 687 open. Only the client knows how long it needs the binding. The 688 server SHOULD NOT close a connection if a request was received over 689 that connection for which a response was not sent. A server MUST NOT 690 ever open a connection back towards the client in order to send a 691 response. Servers SHOULD follow best practices regarding connection 692 management in cases of overload. 694 6.2.3. Sending over TLS-over-TCP or DTLS-over-UDP 696 When STUN is run by itself over TLS-over-TCP or DTLS-over-UDP, the 697 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 and 698 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 cipher suites MUST be 699 implemented and other cipher suites MAY be implemented. Perfect 700 Forward Secrecy (PFS) cipher suites MUST be preferred over non-PFS 701 cipher suites. Cipher suites with known weaknesses, such as those 702 based on (single) DES and RC4, MUST NOT be used. Implementations 703 MUST disable TLS-level compression. 705 When it receives the TLS Certificate message, the client SHOULD 706 verify the certificate and inspect the site identified by the 707 certificate. If the certificate is invalid or revoked, or if it does 708 not identify the appropriate party, the client MUST NOT send the STUN 709 message or otherwise proceed with the STUN transaction. The client 710 MUST verify the identity of the server. To do that, it follows the 711 identification procedures defined in Section 3.1 of RFC 2818 712 [RFC2818]. Alternatively, a client MAY be configured with a set of 713 domains or IP addresses that are trusted; if a certificate is 714 received that identifies one of those domains or IP addresses, the 715 client considers the identity of the server to be verified. 717 When STUN is run multiplexed with other protocols over a TLS-over-TCP 718 connection or a DTLS-over-UDP association, the mandatory ciphersuites 719 and TLS handling procedures operate as defined by those protocols. 721 6.3. Receiving a STUN Message 723 This section specifies the processing of a STUN message. The 724 processing specified here is for STUN messages as defined in this 725 specification; additional rules for backwards compatibility are 726 defined in Section 11. Those additional procedures are optional, and 727 usages can elect to utilize them. First, a set of processing 728 operations is applied that is independent of the class. This is 729 followed by class-specific processing, described in the subsections 730 that follow. 732 When a STUN agent receives a STUN message, it first checks that the 733 message obeys the rules of Section 5. It checks that the first two 734 bits are 0, that the magic cookie field has the correct value, that 735 the message length is sensible, and that the method value is a 736 supported method. It checks that the message class is allowed for 737 the particular method. If the message class is "Success Response" or 738 "Error Response", the agent checks that the transaction ID matches a 739 transaction that is still in progress. If the FINGERPRINT extension 740 is being used, the agent checks that the FINGERPRINT attribute is 741 present and contains the correct value. If any errors are detected, 742 the message is silently discarded. In the case when STUN is being 743 multiplexed with another protocol, an error may indicate that this is 744 not really a STUN message; in this case, the agent should try to 745 parse the message as a different protocol. 747 The STUN agent then does any checks that are required by a 748 authentication mechanism that the usage has specified (see 749 Section 9). 751 Once the authentication checks are done, the STUN agent checks for 752 unknown attributes and known-but-unexpected attributes in the 753 message. Unknown comprehension-optional attributes MUST be ignored 754 by the agent. Known-but-unexpected attributes SHOULD be ignored by 755 the agent. Unknown comprehension-required attributes cause 756 processing that depends on the message class and is described below. 758 At this point, further processing depends on the message class of the 759 request. 761 6.3.1. Processing a Request 763 If the request contains one or more unknown comprehension-required 764 attributes, the server replies with an error response with an error 765 code of 420 (Unknown Attribute), and includes an UNKNOWN-ATTRIBUTES 766 attribute in the response that lists the unknown comprehension- 767 required attributes. 769 The server then does any additional checking that the method or the 770 specific usage requires. If all the checks succeed, the server 771 formulates a success response as described below. 773 When run over UDP or DTLS-over-UDP, a request received by the server 774 could be the first request of a transaction, or a retransmission. 775 The server MUST respond to retransmissions such that the following 776 property is preserved: if the client receives the response to the 777 retransmission and not the response that was sent to the original 778 request, the overall state on the client and server is identical to 779 the case where only the response to the original retransmission is 780 received, or where both responses are received (in which case the 781 client will use the first). The easiest way to meet this requirement 782 is for the server to remember all transaction IDs received over UDP 783 or DTLS-over-UDP and their corresponding responses in the last 40 784 seconds. However, this requires the server to hold state, and will 785 be inappropriate for any requests which are not authenticated. 786 Another way is to reprocess the request and recompute the response. 787 The latter technique MUST only be applied to requests that are 788 idempotent (a request is considered idempotent when the same request 789 can be safely repeated without impacting the overall state of the 790 system) and result in the same success response for the same request. 791 The Binding method is considered to be idempotent. Note that there 792 are certain rare network events that could cause the reflexive 793 transport address value to change, resulting in a different mapped 794 address in different success responses. Extensions to STUN MUST 795 discuss the implications of request retransmissions on servers that 796 do not store transaction state. 798 6.3.1.1. Forming a Success or Error Response 800 When forming the response (success or error), the server follows the 801 rules of Section 6. The method of the response is the same as that 802 of the request, and the message class is either "Success Response" or 803 "Error Response". 805 For an error response, the server MUST add an ERROR-CODE attribute 806 containing the error code specified in the processing above. The 807 reason phrase is not fixed, but SHOULD be something suitable for the 808 error code. For certain errors, additional attributes are added to 809 the message. These attributes are spelled out in the description 810 where the error code is specified. For example, for an error code of 811 420 (Unknown Attribute), the server MUST include an UNKNOWN- 812 ATTRIBUTES attribute. Certain authentication errors also cause 813 attributes to be added (see Section 9). Extensions may define other 814 errors and/or additional attributes to add in error cases. 816 If the server authenticated the request using an authentication 817 mechanism, then the server SHOULD add the appropriate authentication 818 attributes to the response (see Section 9). 820 The server also adds any attributes required by the specific method 821 or usage. In addition, the server SHOULD add a SOFTWARE attribute to 822 the message. 824 For the Binding method, no additional checking is required unless the 825 usage specifies otherwise. When forming the success response, the 826 server adds a XOR-MAPPED-ADDRESS attribute to the response, where the 827 contents of the attribute are the source transport address of the 828 request message. For UDP or DTLS-over-UDP this is the source IP 829 address and source UDP port of the request message. For TCP and TLS- 830 over-TCP, this is the source IP address and source TCP port of the 831 TCP connection as seen by the server. 833 6.3.1.2. Sending the Success or Error Response 835 The response (success or error) is sent over the same transport as 836 the request was received on. If the request was received over UDP or 837 DTLS-over-UDP the destination IP address and port of the response are 838 the source IP address and port of the received request message, and 839 the source IP address and port of the response are equal to the 840 destination IP address and port of the received request message. If 841 the request was received over TCP or TLS-over-TCP, the response is 842 sent back on the same TCP connection as the request was received on. 844 6.3.2. Processing an Indication 846 If the indication contains unknown comprehension-required attributes, 847 the indication is discarded and processing ceases. 849 The agent then does any additional checking that the method or the 850 specific usage requires. If all the checks succeed, the agent then 851 processes the indication. No response is generated for an 852 indication. 854 For the Binding method, no additional checking or processing is 855 required, unless the usage specifies otherwise. The mere receipt of 856 the message by the agent has refreshed the "bindings" in the 857 intervening NATs. 859 Since indications are not re-transmitted over UDP or DTLS-over-UDP 860 (unlike requests), there is no need to handle re-transmissions of 861 indications at the sending agent. 863 6.3.3. Processing a Success Response 865 If the success response contains unknown comprehension-required 866 attributes, the response is discarded and the transaction is 867 considered to have failed. 869 The client then does any additional checking that the method or the 870 specific usage requires. If all the checks succeed, the client then 871 processes the success response. 873 For the Binding method, the client checks that the XOR-MAPPED-ADDRESS 874 attribute is present in the response. The client checks the address 875 family specified. If it is an unsupported address family, the 876 attribute SHOULD be ignored. If it is an unexpected but supported 877 address family (for example, the Binding transaction was sent over 878 IPv4, but the address family specified is IPv6), then the client MAY 879 accept and use the value. 881 6.3.4. Processing an Error Response 883 If the error response contains unknown comprehension-required 884 attributes, or if the error response does not contain an ERROR-CODE 885 attribute, then the transaction is simply considered to have failed. 887 The client then does any processing specified by the authentication 888 mechanism (see Section 9). This may result in a new transaction 889 attempt. 891 The processing at this point depends on the error code, the method, 892 and the usage; the following are the default rules: 894 o If the error code is 300 through 399, the client SHOULD consider 895 the transaction as failed unless the ALTERNATE-SERVER extension is 896 being used. See Section 10. 898 o If the error code is 400 through 499, the client declares the 899 transaction failed; in the case of 420 (Unknown Attribute), the 900 response should contain a UNKNOWN-ATTRIBUTES attribute that gives 901 additional information. 903 o If the error code is 500 through 599, the client MAY resend the 904 request; clients that do so MUST limit the number of times they do 905 this. 907 Any other error code causes the client to consider the transaction 908 failed. 910 7. FINGERPRINT Mechanism 912 This section describes an optional mechanism for STUN that aids in 913 distinguishing STUN messages from packets of other protocols when the 914 two are multiplexed on the same transport address. This mechanism is 915 optional, and a STUN usage must describe if and when it is used. The 916 FINGERPRINT mechanism is not backwards compatible with RFC3489, and 917 cannot be used in environments where such compatibility is required. 919 In some usages, STUN messages are multiplexed on the same transport 920 address as other protocols, such as the Real Time Transport Protocol 921 (RTP). In order to apply the processing described in Section 6, STUN 922 messages must first be separated from the application packets. 924 Section 5 describes three fixed fields in the STUN header that can be 925 used for this purpose. However, in some cases, these three fixed 926 fields may not be sufficient. 928 When the FINGERPRINT extension is used, an agent includes the 929 FINGERPRINT attribute in messages it sends to another agent. 930 Section 14.7 describes the placement and value of this attribute. 932 When the agent receives what it believes is a STUN message, then, in 933 addition to other basic checks, the agent also checks that the 934 message contains a FINGERPRINT attribute and that the attribute 935 contains the correct value. Section 6.3 describes when in the 936 overall processing of a STUN message the FINGERPRINT check is 937 performed. This additional check helps the agent detect messages of 938 other protocols that might otherwise seem to be STUN messages. 940 8. DNS Discovery of a Server 942 This section describes an optional procedure for STUN that allows a 943 client to use DNS to determine the IP address and port of a server. 944 A STUN usage must describe if and when this extension is used. To 945 use this procedure, the client must know a STUN URI [RFC7064]; the 946 usage must also describe how the client obtains this URI. Hard- 947 coding a STUN URI into software is NOT RECOMMENDED in case the domain 948 name is lost or needs to change for legal or other reasons. 950 When a client wishes to locate a STUN server on the public Internet 951 that accepts Binding request/response transactions, the STUN URI 952 scheme is "stun". When it wishes to locate a STUN server that 953 accepts Binding request/response transactions over a TLS, or DTLS 954 session, the URI scheme is "stuns". 956 The syntax of the "stun" and "stuns" URIs are defined in Section 3.1 957 of [RFC7064]. STUN usages MAY define additional URI schemes. 959 8.1. STUN URI Scheme Semantics 961 If the part contains an IP address, then this IP address is 962 used directly to contact the server. A "stuns" URI containing an IP 963 address MUST be rejected, unless the domain name is provided by the 964 same mechanism that provided the STUN URI, and that domain name can 965 be passed to the verification code. 967 If the URI does not contain an IP address, the domain name contained 968 in the part is resolved to a transport address using the SRV 969 procedures specified in [RFC2782]. The DNS SRV service name is the 970 content of the part. The protocol in the SRV lookup is the 971 transport protocol the client will run STUN over: "udp" for UDP and 972 "tcp" for TCP. 974 The procedures of RFC 2782 are followed to determine the server to 975 contact. RFC 2782 spells out the details of how a set of SRV records 976 is sorted and then tried. However, RFC 2782 only states that the 977 client should "try to connect to the (protocol, address, service)" 978 without giving any details on what happens in the event of failure. 979 When following these procedures, if the STUN transaction times out 980 without receipt of a response, the client SHOULD retry the request to 981 the next server in the ordered defined by RFC 2782. Such a retry is 982 only possible for request/response transmissions, since indication 983 transactions generate no response or timeout. 985 The default port for STUN requests is 3478, for both TCP and UDP. 986 The default port for STUN over TLS and STUN over DTLS requests is 987 5349. Servers can run STUN over DTLS on the same port as STUN over 988 UDP if the server software supports determining whether the initial 989 message is a DTLS or STUN message. Servers can run STUN over TLS on 990 the same port as STUN over TCP if the server software supports 991 determining whether the initial message is a TLS or STUN message. 993 Administrators of STUN servers SHOULD use these ports in their SRV 994 records for UDP and TCP. In all cases, the port in DNS MUST reflect 995 the one on which the server is listening. 997 If no SRV records were found, the client performs an A or AAAA record 998 lookup of the domain name. The result will be a list of IP 999 addresses, each of which can be contacted at the default port using 1000 UDP or TCP, independent of the STUN usage. For usages that require 1001 TLS, the client connects to one of the IP addresses using the default 1002 STUN over TLS port. For usages that require DTLS, the client 1003 connects to one of the IP addresses using the default STUN over DTLS 1004 port. 1006 9. Authentication and Message-Integrity Mechanisms 1008 This section defines two mechanisms for STUN that a client and server 1009 can use to provide authentication and message integrity; these two 1010 mechanisms are known as the short-term credential mechanism and the 1011 long-term credential mechanism. These two mechanisms are optional, 1012 and each usage must specify if and when these mechanisms are used. 1013 Consequently, both clients and servers will know which mechanism (if 1014 any) to follow based on knowledge of which usage applies. For 1015 example, a STUN server on the public Internet supporting ICE would 1016 have no authentication, whereas the STUN server functionality in an 1017 agent supporting connectivity checks would utilize short-term 1018 credentials. An overview of these two mechanisms is given in 1019 Section 2. 1021 Each mechanism specifies the additional processing required to use 1022 that mechanism, extending the processing specified in Section 6. The 1023 additional processing occurs in three different places: when forming 1024 a message, when receiving a message immediately after the basic 1025 checks have been performed, and when doing the detailed processing of 1026 error responses. 1028 9.1. Short-Term Credential Mechanism 1030 The short-term credential mechanism assumes that, prior to the STUN 1031 transaction, the client and server have used some other protocol to 1032 exchange a credential in the form of a username and password. This 1033 credential is time-limited. The time limit is defined by the usage. 1034 As an example, in the ICE usage [I-D.ietf-ice-rfc5245bis], the two 1035 endpoints use out-of-band signaling to agree on a username and 1036 password, and this username and password are applicable for the 1037 duration of the media session. 1039 This credential is used to form a message-integrity check in each 1040 request and in many responses. There is no challenge and response as 1041 in the long-term mechanism; consequently, replay is prevented by 1042 virtue of the time-limited nature of the credential. 1044 9.1.1. HMAC Key 1046 For short-term credentials the HMAC key is defined as follow: 1048 key = OpaqueString(password) 1050 where the OpaqueString profile is defined in [RFC7613]. 1052 9.1.2. Forming a Request or Indication 1054 For a request or indication message, the agent MUST include the 1055 USERNAME, MESSAGE-INTEGRITY-SHA256, and MESSAGE-INTEGRITY attributes 1056 in the message unless the agent knows from an external indication 1057 which message integrity algorithm is supported by both agents. In 1058 this case either MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 MUST 1059 be included in addition to USERNAME. The HMAC for the MESSAGE- 1060 INTEGRITY attribute is computed as described in Section 14.5 and the 1061 HMAC for the MESSAGE-INTEGRITY-SHA256 attributes is computed as 1062 described in Section 14.6. Note that the password is never included 1063 in the request or indication. 1065 9.1.3. Receiving a Request or Indication 1067 After the agent has done the basic processing of a message, the agent 1068 performs the checks listed below in order specified: 1070 o If the message does not contain 1) a MESSAGE-INTEGRITY or a 1071 MESSAGE-INTEGRITY-SHA256 attribute and 2) a USERNAME attribute: 1073 * If the message is a request, the server MUST reject the request 1074 with an error response. This response MUST use an error code 1075 of 400 (Bad Request). 1077 * If the message is an indication, the agent MUST silently 1078 discard the indication. 1080 o If the USERNAME does not contain a username value currently valid 1081 within the server: 1083 * If the message is a request, the server MUST reject the request 1084 with an error response. This response MUST use an error code 1085 of 401 (Unauthorized). 1087 * If the message is an indication, the agent MUST silently 1088 discard the indication. 1090 o If the MESSAGE-INTEGRITY-SHA256 attribute is present compute the 1091 value for the message integrity as described in Section 14.6, 1092 using the password associated with the username. If the MESSAGE- 1093 INTEGRITY-SHA256 attribute is not present, and using the same 1094 password, compute the value for the message integrity as described 1095 in Section 14.5. If the resulting value does not match the 1096 contents of the corresponding attribute (MESSAGE-INTEGRITY-SHA256 1097 or MESSAGE-INTEGRITY): 1099 * If the message is a request, the server MUST reject the request 1100 with an error response. This response MUST use an error code 1101 of 401 (Unauthorized). 1103 * If the message is an indication, the agent MUST silently 1104 discard the indication. 1106 If these checks pass, the agent continues to process the request or 1107 indication. Any response generated by a server to a request that 1108 contains a MESSAGE-INTEGRITY-SHA256 attribute MUST include the 1109 MESSAGE-INTEGRITY-SHA256 attribute, computed using the password 1110 utilized to authenticate the request. Any response generated by a 1111 server to a request that contains only a MESSAGE-INTEGRITY attribute 1112 MUST include the MESSAGE-INTEGRITY attribute, computed using the 1113 password utilized to authenticate the request. This means that only 1114 one of these attributes can appear in a response. The response MUST 1115 NOT contain the USERNAME attribute. 1117 If any of the checks fail, a server MUST NOT include a MESSAGE- 1118 INTEGRITY-SHA256, MESSAGE-INTEGRITY, or USERNAME attribute in the 1119 error response. This is because, in these failure cases, the server 1120 cannot determine the shared secret necessary to compute the MESSAGE- 1121 INTEGRITY-SHA256 or MESSAGE-INTEGRITY attributes. 1123 9.1.4. Receiving a Response 1125 The client looks for the MESSAGE-INTEGRITY or the MESSAGE-INTEGRITY- 1126 SHA256 attribute in the response. If present, the client computes 1127 the message integrity over the response as defined in Section 14.5 or 1128 Section 14.6, respectively, using the same password it utilized for 1129 the request. If the resulting value matches the contents of the 1130 MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 attribute, 1131 respectively, the response is considered authenticated. If the value 1132 does not match, or if both MESSAGE-INTEGRITY and MESSAGE-INTEGRITY- 1133 SHA256 were absent, the response MUST be discarded, as if it was 1134 never received. This means that retransmits, if applicable, will 1135 continue. 1137 If the client only sent one algorithm in the request (because of the 1138 external indication in section Section 9.2.3, or this being a 1139 subsequent request as defined in Section 9.1.5) the algorithm in the 1140 response has to match otherwise the response MUST be discarded. 1142 9.1.5. Sending Subsequent Requests 1144 A client sending subsequent requests to the same server MAY choose to 1145 send only the MESSAGE-INTEGRITY-SHA256 or the MESSAGE-INTEGRITY 1146 attribute depending upon the attribute that was received in the 1147 response to the initial request. Here same server means same IP 1148 address and port number, not just the same URL or SRV lookup result. 1150 9.2. Long-Term Credential Mechanism 1152 The long-term credential mechanism relies on a long-term credential, 1153 in the form of a username and password that are shared between client 1154 and server. The credential is considered long-term since it is 1155 assumed that it is provisioned for a user, and remains in effect 1156 until the user is no longer a subscriber of the system, or is 1157 changed. This is basically a traditional "log-in" username and 1158 password given to users. 1160 Because these usernames and passwords are expected to be valid for 1161 extended periods of time, replay prevention is provided in the form 1162 of a digest challenge. In this mechanism, the client initially sends 1163 a request, without offering any credentials or any integrity checks. 1164 The server rejects this request, providing the user a realm (used to 1165 guide the user or agent in selection of a username and password) and 1166 a nonce. The nonce provides the replay protection. It is a cookie, 1167 selected by the server, and encoded in such a way as to indicate a 1168 duration of validity or client identity from which it is valid. The 1169 client retries the request, this time including its username and the 1170 realm, and echoing the nonce provided by the server. The client also 1171 includes a message-integrity, which provides an HMAC over the entire 1172 request, including the nonce. The server validates the nonce and 1173 checks the message integrity. If they match, the request is 1174 authenticated. If the nonce is no longer valid, it is considered 1175 "stale", and the server rejects the request, providing a new nonce. 1177 In subsequent requests to the same server, the client reuses the 1178 nonce, username, realm, and password it used previously. In this 1179 way, subsequent requests are not rejected until the nonce becomes 1180 invalid by the server, in which case the rejection provides a new 1181 nonce to the client. 1183 Note that the long-term credential mechanism cannot be used to 1184 protect indications, since indications cannot be challenged. Usages 1185 utilizing indications must either use a short-term credential or omit 1186 authentication and message integrity for them. 1188 Since the long-term credential mechanism is susceptible to offline 1189 dictionary attacks, deployments SHOULD utilize passwords that are 1190 difficult to guess. In cases where the credentials are not entered 1191 by the user, but are rather placed on a client device during device 1192 provisioning, the password SHOULD have at least 128 bits of 1193 randomness. In cases where the credentials are entered by the user, 1194 they should follow best current practices around password structure. 1196 9.2.1. Bid Down Attack Prevention 1198 This document introduces two new security features that provide the 1199 ability to choose the algorithm used for password protection as well 1200 as the ability to use an anonymous username. Both of these 1201 capabilities are optional in order to remain backwards compatible 1202 with previous versions of the STUN protocol. 1204 These new capabilities are subject to bid down attacks whereby an 1205 attacker in the message path can remove these capabilities and force 1206 weaker security properties. To prevent these kinds of attacks from 1207 going undetected, the nonce is enhanced with additional information. 1209 If the server uses one of the security features subject to bid down 1210 attack protection it MUST prepend the NONCE attribute value with the 1211 character string composed of "obMatJos2" concatenated with the Base64 1212 encoding of the 24 bit STUN Security Features as defined in 1213 Section 17.1. The 24 bit Security Feature set is encoded as a 24 bit 1214 integer in network order. For the remainder of this document the 1215 term "nonce cookie" will refer to the complete 13 character string 1216 prepended to the NONCE attribute value. 1218 The value of the "nonce cookie" will vary based on the specific STUN 1219 Security Features bit values selected. When this document makes 1220 reference to the "nonce cookie" in a section discussing a specific 1221 STUN Security Feature it is understood that the corresponding STUN 1222 Security Feature bit in the "nonce cookie" is set to 1. 1224 For example, in Section 9.2.4 discussing the PASSWORD-ALGORITHMS 1225 security feature, it is implied that the "Password algorithms" bit, 1226 as defined in Section 17.1, is set to 1 in the "nonce cookie". 1228 9.2.2. HMAC Key 1230 For long-term credentials that do not use a different algorithm, as 1231 specified by the PASSWORD-ALGORITHM attribute, the key is 16 bytes: 1233 key = MD5(username ":" realm ":" OpaqueString(password)) 1235 Where MD5 is defined in RFC 1321 [RFC1321] and the OpaqueString 1236 profile is defined in [RFC7613]. 1238 The 16-byte key is formed by taking the MD5 hash of the result of 1239 concatenating the following five fields: (1) the username, with any 1240 quotes and trailing nulls removed, as taken from the USERNAME 1241 attribute (in which case OpaqueString has already been applied); (2) 1242 a single colon; (3) the realm, with any quotes and trailing nulls 1243 removed; (4) a single colon; and (5) the password, with any trailing 1244 nulls removed and after processing using OpaqueString. For example, 1245 if the username was 'user', the realm was 'realm', and the password 1246 was 'pass', then the 16-byte HMAC key would be the result of 1247 performing an MD5 hash on the string 'user:realm:pass', the resulting 1248 hash being 0x8493fbc53ba582fb4c044c456bdc40eb. 1250 The structure of the key when used with long-term credentials 1251 facilitates deployment in systems that also utilize SIP. Typically, 1252 SIP systems utilizing SIP's digest authentication mechanism do not 1253 actually store the password in the database. Rather, they store a 1254 value called H(A1), which is equal to the key defined above. 1256 When a PASSWORD-ALGORITHM is used, the key length and algorithm to 1257 use are described in Section 17.5.1. 1259 9.2.3. Forming a Request 1261 There are two cases when forming a request. In the first case, this 1262 is the first request from the client to the server (as identified by 1263 its IP address and port). In the second case, the client is 1264 submitting a subsequent request once a previous request/response 1265 transaction has completed successfully. Forming a request as a 1266 consequence of a 401 or 438 error response is covered in 1267 Section 9.2.5 and is not considered a "subsequent request" and thus 1268 does not utilize the rules described in Section 9.2.3.2. 1270 9.2.3.1. First Request 1272 If the client has not completed a successful request/response 1273 transaction with the server (as identified by hostname, if the DNS 1274 procedures of Section 8 are used, else IP address if not), it SHOULD 1275 omit the USERNAME, USERHASH, MESSAGE-INTEGRITY, MESSAGE-INTEGRITY- 1276 SHA256, REALM, NONCE, PASSWORD-ALGORITHMS, and PASSWORD-ALGORITHM 1277 attributes. In other words, the very first request is sent as if 1278 there were no authentication or message integrity applied. 1280 9.2.3.2. Subsequent Requests 1282 Once a request/response transaction has completed successfully, the 1283 client will have been presented a realm and nonce by the server, and 1284 selected a username and password with which it authenticated. The 1285 client SHOULD cache the username, password, realm, and nonce for 1286 subsequent communications with the server. When the client sends a 1287 subsequent request, it SHOULD include either the USERNAME or 1288 USERHASH, REALM, NONCE, and PASSWORD-ALGORITHM attributes with these 1289 cached values. It SHOULD include a MESSAGE-INTEGRITY attribute or a 1290 MESSAGE-INTEGRITY-SHA256 attribute, computed as described in 1291 Section 14.5 and Section 14.6 using the cached password. The choice 1292 between the two attributes depends on the attribute received in the 1293 response to the first request. 1295 9.2.4. Receiving a Request 1297 After the server has done the basic processing of a request, it 1298 performs the checks listed below in the order specified: 1300 o If the message does not contain a MESSAGE-INTEGRITY or MESSAGE- 1301 INTEGRITY-SHA256 attribute, the server MUST generate an error 1302 response with an error code of 401 (Unauthorized). This response 1303 MUST include a REALM value. It is RECOMMENDED that the REALM 1304 value be the domain name of the provider of the STUN server. The 1305 response MUST include a NONCE, selected by the server. The server 1306 MUST ensure that the same NONCE cannot be selected for clients 1307 that use different IP addresses and/or different ports. The 1308 server MAY support alternate password algorithms, in which case it 1309 can list them in preferential order in a PASSWORD-ALGORITHMS 1310 attribute. If the server adds a PASSWORD-ALGORITHMS attribute it 1311 MUST prepend the NONCE attribute value with the "nonce cookie". 1312 The server MAY support anonymous username, in which case it can 1313 prepend the NONCE attribute value with the "nonce cookie" that has 1314 the STUN Security Feature "Anonymous username" bit set to 1. The 1315 response SHOULD NOT contain a USERNAME, USERHASH, MESSAGE- 1316 INTEGRITY or MESSAGE-INTEGRITY-SHA256 attribute. 1318 Note: Sharing a NONCE is no longer permitted, so trying to share one 1319 will result in a wasted transaction. 1321 o If the message contains a MESSAGE-INTEGRITY or a MESSAGE- 1322 INTEGRITY-SHA256 attribute, but is missing either the USERNAME or 1323 USERHASH, REALM, or NONCE attribute, the server MUST generate an 1324 error response with an error code of 400 (Bad Request). This 1325 response SHOULD NOT include a USERNAME, USERHASH, NONCE, REALM, 1326 MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 attribute. 1328 o If the NONCE attribute starts with the "nonce cookie" with the 1329 STUN Security Feature "Password algorithm" bit set to 1 but 1330 PASSWORD-ALGORITHMS does not match the value sent in the response 1331 that sent this NONCE, then the server MUST generate an error 1332 response with an error code of 400 (Bad Request). 1334 o If the NONCE attribute starts with the "nonce cookie" with the 1335 STUN Security Feature "Password algorithm" bit set to 1 but the 1336 request contains neither PASSWORD-ALGORITHMS nor PASSWORD- 1337 ALGORITHM, then the request is processed as though PASSWORD- 1338 ALGORITHM were MD5 (Note that if the original PASSWORD-ALGORITHMS 1339 attribute did not contain MD5, this will result in a 400 Bad 1340 Request in a later step below). 1342 o If the NONCE attribute starts with the "nonce cookie" with the 1343 STUN Security Feature "Password algorithm" bit set to 1 but only 1344 one of PASSWORD-ALGORITHM or PASSWORD-ALGORITHMS is present, then 1345 the server MUST generate an error response with an error code of 1346 400 (Bad Request). 1348 o If the NONCE attribute starts with the "nonce cookie" with the 1349 STUN Security Feature "Password algorithm" bit set to 1 but 1350 PASSWORD-ALGORITHM does not match one of the entries in PASSWORD- 1351 ALGORITHMS, then the server MUST generate an error response with 1352 an error code of 400 (Bad Request). 1354 o If the NONCE is no longer valid, the server MUST generate an error 1355 response with an error code of 438 (Stale Nonce). This response 1356 MUST include NONCE, REALM, and PASSWORD-ALGORITHMS attributes and 1357 SHOULD NOT include the USERNAME, USERHASH, MESSAGE-INTEGRITY, or 1358 MESSAGE-INTEGRITY-SHA256 attribute. Servers can invalidate nonces 1359 in order to provide additional security. See Section 4.3 of 1360 [RFC2617] for guidelines. 1362 o If the username in the USERNAME or USERHASH attribute is not 1363 valid, the server MUST generate an error response with an error 1364 code of 401 (Unauthorized). This response MUST include a REALM 1365 value. It is RECOMMENDED that the REALM value be the domain name 1366 of the provider of the STUN server. The response MUST include a 1367 NONCE, selected by the server. The response MUST include a 1368 PASSWORD-ALGORITHMS attribute. The response SHOULD NOT contain a 1369 USERNAME, USERHASH, MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 1370 attribute. 1372 o If the MESSAGE-INTEGRITY-SHA256 attribute is present compute the 1373 value for the message integrity as described in Section 14.6, 1374 using the password associated with the username. Else, using the 1375 same password, compute the value for the message integrity as 1376 described in Section 14.5. If the resulting value does not match 1377 the contents of the MESSAGE-INTEGRITY attribute or the MESSAGE- 1378 INTEGRITY-SHA256 attribute, the server MUST reject the request 1379 with an error response. This response MUST use an error code of 1380 401 (Unauthorized). It MUST include REALM and NONCE attributes 1381 and SHOULD NOT include the USERNAME, USERHASH, MESSAGE-INTEGRITY, 1382 or MESSAGE-INTEGRITY-SHA256 attribute. 1384 For the responses sent by the steps above, the MESSAGE-INTEGRITY- 1385 SHA256 attribute cannot be added. 1387 If these checks pass, the server continues to process the request. 1388 Any response generated by the server MUST include MESSAGE-INTEGRITY- 1389 SHA256 attribute, computed using the username and password utilized 1390 to authenticate the request, unless the request was processed as 1391 though PASSWORD-ALGORITHM was MD5 (because the request contained 1392 neither PASSWORD-ALGORITHMS nor PASSWORD-ALGORITHM). In that case 1393 the MESSAGE-INTEGRITY attribute MUST be used instead of the MESSAGE- 1394 INTEGRITY-SHA256 attribute. The REALM, NONCE, USERNAME and USERHASH 1395 attributes SHOULD NOT be included. 1397 9.2.5. Receiving a Response 1399 If the response is an error response with an error code of 401 1400 (Unauthorized) or 438 (Stale Nonce), the client MUST test if the 1401 NONCE attribute value starts with the "nonce cookie". If the test 1402 succeeds and the "nonce cookie" has the STUN Security Feature 1403 "Password algorithm" bit set to 1 but no PASSWORD-ALGORITHMS 1404 attribute is present, then the client MUST NOT retry the request with 1405 a new transaction. If the test succeeds and the "nonce cookie" has 1406 the STUN Security Feature "Username anonymity" bit set to 1 but no 1407 USERHASH attribute is present, then the client MUST NOT retry the 1408 request with a new transaction. 1410 If the response is an error response with an error code of 401 1411 (Unauthorized), the client SHOULD retry the request with a new 1412 transaction. This request MUST contain a USERNAME or a USERHASH, 1413 determined by the client as the appropriate username for the REALM 1414 from the error response. If the "nonce cookie" was present and had 1415 the STUN Security Feature "Username anonymity" bit set to 1 then the 1416 USERHASH attribute MUST be used, else the USERNAME attribute MUST be 1417 used. The request MUST contain the REALM, copied from the error 1418 response. The request MUST contain the NONCE, copied from the error 1419 response. If the response contains a PASSWORD-ALGORITHMS attribute, 1420 the request MUST contain the PASSWORD-ALGORITHMS attribute with the 1421 same content. If the response contains a PASSWORD-ALGORITHMS 1422 attribute, and this attribute contains at least one algorithm that is 1423 supported by the client then the request MUST contain a PASSWORD- 1424 ALGORITHM attribute with the first algorithm supported on the list. 1425 If the response contains a PASSWORD-ALGORITHMS attribute, and this 1426 attribute does not contain any algorithm that is supported by the 1427 client, then the client MUST NOT retry the request with a new 1428 transaction. The client MUST NOT perform this retry if it is not 1429 changing the USERNAME or USERHASH or REALM or its associated 1430 password, from the previous attempt. 1432 If the response is an error response with an error code of 438 (Stale 1433 Nonce), the client MUST retry the request, using the new NONCE 1434 attribute supplied in the 438 (Stale Nonce) response. This retry 1435 MUST also include either the USERNAME or USERHASH, REALM and either 1436 the MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 attributes. 1438 For all other responses, if the NONCE attribute starts with the 1439 "nonce cookie" with the STUN Security Feature "Password algorithm" 1440 bit set to 1 but PASSWORD-ALGORITHMS is not present, the response 1441 MUST be ignored. For all other responses, if the NONCE attribute 1442 starts with the "nonce cookie" with the STUN Security Feature "User 1443 anonymity" bit set to 1 but USERHASH is not present, the response 1444 MUST be ignored. 1446 The client looks for the MESSAGE-INTEGRITY or MESSAGE-INTEGRITY- 1447 SHA256 attribute in the response (either success or failure). If 1448 present, the client computes the message integrity over the response 1449 as defined in Section 14.5 or Section 14.6, using the same password 1450 it utilized for the request. If the resulting value matches the 1451 contents of the MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 1452 attribute, the response is considered authenticated. If the value 1453 does not match, or if both MESSAGE-INTEGRITY and MESSAGE-INTEGRITY- 1454 SHA256 were absent, the response MUST be discarded, as if it was 1455 never received. This means that retransmits, if applicable, will 1456 continue. 1458 If the response contains a PASSWORD-ALGORITHMS attribute, the 1459 subsequent request MUST be authenticated using MESSAGE-INTEGRITY- 1460 SHA256 only. 1462 10. ALTERNATE-SERVER Mechanism 1464 This section describes a mechanism in STUN that allows a server to 1465 redirect a client to another server. This extension is optional, and 1466 a usage must define if and when this extension is used. 1468 A server using this extension redirects a client to another server by 1469 replying to a request message with an error response message with an 1470 error code of 300 (Try Alternate). The server MUST include an 1471 ALTERNATE-SERVER attribute in the error response. The error response 1472 message MAY be authenticated; however, there are uses cases for 1473 ALTERNATE-SERVER where authentication of the response is not possible 1474 or practical. If the transaction uses TLS or DTLS and if the 1475 transaction is authenticated by a MESSAGE-INTEGRITY-SHA256 attribute 1476 and if the server wants to redirect to a server that uses a different 1477 certificate, then it MUST include an ALTERNATE-DOMAIN attribute 1478 containing the subjectAltName of that certificate. 1480 A client using this extension handles a 300 (Try Alternate) error 1481 code as follows. The client looks for an ALTERNATE-SERVER attribute 1482 in the error response. If one is found, then the client considers 1483 the current transaction as failed, and reattempts the request with 1484 the server specified in the attribute, using the same transport 1485 protocol used for the previous request. That request, if 1486 authenticated, MUST utilize the same credentials that the client 1487 would have used in the request to the server that performed the 1488 redirection. If the transport protocol uses TLS or DTLS, then the 1489 client looks for an ALTERNATE-DOMAIN attribute. If the attribute is 1490 found, the domain MUST be used to validate the cartificate. If the 1491 attribute is not found, the same domain that was used for the 1492 original request MUST be used to validate the certificate. If the 1493 client has been redirected to a server on which it has already tried 1494 this request within the last five minutes, it MUST ignore the 1495 redirection and consider the transaction to have failed. This 1496 prevents infinite ping-ponging between servers in case of redirection 1497 loops. 1499 11. Backwards Compatibility with RFC 3489 1501 In addition to the backward compatibility already described in 1502 Section 12 of [RFC5389], DTLS MUST NOT be used with RFC 3489 STUN 1503 [RFC3489] (also referred to as "classic STUN"). Any STUN request or 1504 indication without the magic cookie (see Section 6 of [RFC5389]) over 1505 DTLS MUST always result in an error. 1507 12. Basic Server Behavior 1509 This section defines the behavior of a basic, stand-alone STUN 1510 server. A basic STUN server provides clients with server reflexive 1511 transport addresses by receiving and replying to STUN Binding 1512 requests. 1514 The STUN server MUST support the Binding method. It SHOULD NOT 1515 utilize the short-term or long-term credential mechanism. This is 1516 because the work involved in authenticating the request is more than 1517 the work in simply processing it. It SHOULD NOT utilize the 1518 ALTERNATE-SERVER mechanism for the same reason. It MUST support UDP 1519 and TCP. It MAY support STUN over TCP/TLS or STUN over UDP/DTLS; 1520 however, DTLS and TLS provide minimal security benefits in this basic 1521 mode of operation. It MAY utilize the FINGERPRINT mechanism but MUST 1522 NOT require it. Since the stand-alone server only runs STUN, 1523 FINGERPRINT provides no benefit. Requiring it would break 1524 compatibility with RFC 3489, and such compatibility is desirable in a 1525 stand-alone server. Stand-alone STUN servers SHOULD support 1526 backwards compatibility with [RFC3489] clients, as described in 1527 Section 11. 1529 It is RECOMMENDED that administrators of STUN servers provide DNS 1530 entries for those servers as described in Section 8. 1532 A basic STUN server is not a solution for NAT traversal by itself. 1533 However, it can be utilized as part of a solution through STUN 1534 usages. This is discussed further in Section 13. 1536 13. STUN Usages 1538 STUN by itself is not a solution to the NAT traversal problem. 1539 Rather, STUN defines a tool that can be used inside a larger 1540 solution. The term "STUN usage" is used for any solution that uses 1541 STUN as a component. 1543 A STUN usage defines how STUN is actually utilized -- when to send 1544 requests, what to do with the responses, and which optional 1545 procedures defined here (or in an extension to STUN) are to be used. 1546 A usage would also define: 1548 o Which STUN methods are used. 1550 o What transports are used. If DTLS-over-UDP is used then 1551 implementing the denial-of-service countermeasure described in 1552 Section 4.2.1 of [RFC6347] is mandatory. 1554 o What authentication and message-integrity mechanisms are used. 1556 o The considerations around manual vs. automatic key derivation for 1557 the integrity mechanism, as discussed in [RFC4107]. 1559 o What mechanisms are used to distinguish STUN messages from other 1560 messages. When STUN is run over TCP, a framing mechanism may be 1561 required. 1563 o How a STUN client determines the IP address and port of the STUN 1564 server. 1566 o Whether backwards compatibility to RFC 3489 is required. 1568 o What optional attributes defined here (such as FINGERPRINT and 1569 ALTERNATE-SERVER) or in other extensions are required. 1571 In addition, any STUN usage must consider the security implications 1572 of using STUN in that usage. A number of attacks against STUN are 1573 known (see the Security Considerations section in this document), and 1574 any usage must consider how these attacks can be thwarted or 1575 mitigated. 1577 Finally, a usage must consider whether its usage of STUN is an 1578 example of the Unilateral Self-Address Fixing approach to NAT 1579 traversal, and if so, address the questions raised in RFC 3424 1580 [RFC3424]. 1582 14. STUN Attributes 1584 After the STUN header are zero or more attributes. Each attribute 1585 MUST be TLV encoded, with a 16-bit type, 16-bit length, and value. 1586 Each STUN attribute MUST end on a 32-bit boundary. As mentioned 1587 above, all fields in an attribute are transmitted most significant 1588 bit first. 1590 0 1 2 3 1591 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 1592 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1593 | Type | Length | 1594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1595 | Value (variable) .... 1596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1598 Figure 4: Format of STUN Attributes 1600 The value in the length field MUST contain the length of the Value 1601 part of the attribute, prior to padding, measured in bytes. Since 1602 STUN aligns attributes on 32-bit boundaries, attributes whose content 1603 is not a multiple of 4 bytes are padded with 1, 2, or 3 bytes of 1604 padding so that its value contains a multiple of 4 bytes. The 1605 padding bits are ignored, and may be any value. 1607 Any attribute type MAY appear more than once in a STUN message. 1608 Unless specified otherwise, the order of appearance is significant: 1609 only the first occurrence needs to be processed by a receiver, and 1610 any duplicates MAY be ignored by a receiver. 1612 To allow future revisions of this specification to add new attributes 1613 if needed, the attribute space is divided into two ranges. 1614 Attributes with type values between 0x0000 and 0x7FFF are 1615 comprehension-required attributes, which means that the STUN agent 1616 cannot successfully process the message unless it understands the 1617 attribute. Attributes with type values between 0x8000 and 0xFFFF are 1618 comprehension-optional attributes, which means that those attributes 1619 can be ignored by the STUN agent if it does not understand them. 1621 The set of STUN attribute types is maintained by IANA. The initial 1622 set defined by this specification is found in Section 17.3. 1624 The rest of this section describes the format of the various 1625 attributes defined in this specification. 1627 14.1. MAPPED-ADDRESS 1629 The MAPPED-ADDRESS attribute indicates a reflexive transport address 1630 of the client. It consists of an 8-bit address family and a 16-bit 1631 port, followed by a fixed-length value representing the IP address. 1632 If the address family is IPv4, the address MUST be 32 bits. If the 1633 address family is IPv6, the address MUST be 128 bits. All fields 1634 must be in network byte order. 1636 The format of the MAPPED-ADDRESS attribute is: 1638 0 1 2 3 1639 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 1640 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1641 |0 0 0 0 0 0 0 0| Family | Port | 1642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1643 | | 1644 | Address (32 bits or 128 bits) | 1645 | | 1646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1648 Figure 5: Format of MAPPED-ADDRESS Attribute 1650 The address family can take on the following values: 1652 0x01:IPv4 1653 0x02:IPv6 1655 The first 8 bits of the MAPPED-ADDRESS MUST be set to 0 and MUST be 1656 ignored by receivers. These bits are present for aligning parameters 1657 on natural 32-bit boundaries. 1659 This attribute is used only by servers for achieving backwards 1660 compatibility with RFC 3489 [RFC3489] clients. 1662 14.2. XOR-MAPPED-ADDRESS 1664 The XOR-MAPPED-ADDRESS attribute is identical to the MAPPED-ADDRESS 1665 attribute, except that the reflexive transport address is obfuscated 1666 through the XOR function. 1668 The format of the XOR-MAPPED-ADDRESS is: 1670 0 1 2 3 1671 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 1672 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1673 |0 0 0 0 0 0 0 0| Family | X-Port | 1674 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1675 | X-Address (Variable) 1676 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1678 Figure 6: Format of XOR-MAPPED-ADDRESS Attribute 1680 The Family represents the IP address family, and is encoded 1681 identically to the Family in MAPPED-ADDRESS. 1683 X-Port is computed by taking the mapped port in host byte order, 1684 XOR'ing it with the most significant 16 bits of the magic cookie, and 1685 then the converting the result to network byte order. If the IP 1686 address family is IPv4, X-Address is computed by taking the mapped IP 1687 address in host byte order, XOR'ing it with the magic cookie, and 1688 converting the result to network byte order. If the IP address 1689 family is IPv6, X-Address is computed by taking the mapped IP address 1690 in host byte order, XOR'ing it with the concatenation of the magic 1691 cookie and the 96-bit transaction ID, and converting the result to 1692 network byte order. 1694 The rules for encoding and processing the first 8 bits of the 1695 attribute's value, the rules for handling multiple occurrences of the 1696 attribute, and the rules for processing address families are the same 1697 as for MAPPED-ADDRESS. 1699 Note: XOR-MAPPED-ADDRESS and MAPPED-ADDRESS differ only in their 1700 encoding of the transport address. The former encodes the transport 1701 address by exclusive-or'ing it with the magic cookie. The latter 1702 encodes it directly in binary. RFC 3489 originally specified only 1703 MAPPED-ADDRESS. However, deployment experience found that some NATs 1704 rewrite the 32-bit binary payloads containing the NAT's public IP 1705 address, such as STUN's MAPPED-ADDRESS attribute, in the well-meaning 1706 but misguided attempt at providing a generic ALG function. Such 1707 behavior interferes with the operation of STUN and also causes 1708 failure of STUN's message-integrity checking. 1710 14.3. USERNAME 1712 The USERNAME attribute is used for message integrity. It identifies 1713 the username and password combination used in the message-integrity 1714 check. 1716 The value of USERNAME is a variable-length value. It MUST contain a 1717 UTF-8 [RFC3629] encoded sequence of less than 513 bytes, and MUST 1718 have been processed using the OpaqueString profile [RFC7613]. 1720 14.4. USERHASH 1722 The USERHASH attribute is used as a replacement for the USERNAME 1723 attribute when username anonymity is supported. 1725 The value of USERHASH has a fixed length of 32 bytes. The username 1726 MUST have been processed using the OpaqueString profile [RFC7613] 1727 before hashing. 1729 The following is the operation that the client will perform to hash 1730 the username: 1732 userhash = SHA256(username ":" realm) 1734 14.5. MESSAGE-INTEGRITY 1736 The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [RFC2104] of 1737 the STUN message. The MESSAGE-INTEGRITY attribute can be present in 1738 any STUN message type. Since it uses the SHA1 hash, the HMAC will be 1739 at most 20 bytes. The HMAC MUST NOT be truncated below a minimum 1740 size of 4. If truncation is employed then the HMAC size MUST be a 1741 multiple of XX. Truncation MUST be done from the most significant 1742 byte to the least significant byte. STUN Usages can define their own 1743 truncation limits, as long as they adhere to the guidelines 1744 specificed above. 1746 Note: We don't know what we're doing, we need a cryptographer to 1747 weigh in on the above text. 1749 The text used as input to HMAC is the STUN message, including the 1750 header, up to and including the attribute preceding the MESSAGE- 1751 INTEGRITY attribute. With the exception of the MESSAGE-INTEGRITY- 1752 SHA256 and FINGERPRINT attributes, which appear after MESSAGE- 1753 INTEGRITY, agents MUST ignore all other attributes that follow 1754 MESSAGE-INTEGRITY. 1756 The key for the HMAC depends on which credential mechanism is in use. 1757 Section 9.1.1 defines the key for the short-term credential mechanism 1758 and Section 9.2.2 defines the key for the long-term credential 1759 mechanism. Other credential mechanisms MUST define the key that is 1760 used for the HMAC. 1762 Based on the rules above, the hash used to construct MESSAGE- 1763 INTEGRITY includes the length field from the STUN message header. 1765 Prior to performing the hash, the MESSAGE-INTEGRITY attribute MUST be 1766 inserted into the message (with dummy content). The length MUST then 1767 be set to point to the length of the message up to, and including, 1768 the MESSAGE-INTEGRITY attribute itself, but excluding any attributes 1769 after it. Once the computation is performed, the value of the 1770 MESSAGE-INTEGRITY attribute can be filled in, and the value of the 1771 length in the STUN header can be set to its correct value -- the 1772 length of the entire message. Similarly, when validating the 1773 MESSAGE-INTEGRITY, the length field should be adjusted to point to 1774 the end of the MESSAGE-INTEGRITY attribute prior to calculating the 1775 HMAC. Such adjustment is necessary when attributes, such as 1776 FINGERPRINT, appear after MESSAGE-INTEGRITY. 1778 14.6. MESSAGE-INTEGRITY-SHA256 1780 The MESSAGE-INTEGRITY-SHA256 attribute contains an HMAC-SHA-256 1781 [RFC2104] of the STUN message. The MESSAGE-INTEGRITY-SHA256 1782 attribute can be present in any STUN message type. Since it uses the 1783 SHA1 hash, the HMAC will be at most 32 bytes. The HMAC MUST NOT be 1784 truncated below a minimum size of 4. If truncation is employed then 1785 the HMAC size MUST be a multiple of XX. Truncation MUST be done from 1786 the most significant byte to the least significant byte. STUN Usages 1787 can define their own truncation limits, as long as they adhere to the 1788 guidelines specificed above. 1790 Note: We don't know what we're doing, we need a cryptographer to 1791 weigh in on the above text. 1793 The text used as input to HMAC is the STUN message, including the 1794 header, up to and including the attribute preceding the MESSAGE- 1795 INTEGRITY-SHA256 attribute. With the exception of the FINGERPRINT 1796 attribute, which appears after MESSAGE-INTEGRITY-SHA256, agents MUST 1797 ignore all other attributes that follow MESSAGE-INTEGRITY-SHA256. 1799 The key for the HMAC depends on which credential mechanism is in use. 1800 Section 9.1.1 defines the key for the short-term credential mechanism 1801 and Section 9.2.2 defines the key for the long-term credential 1802 mechanism. Other credential mechanism MUST define the key that is 1803 used for the HMAC. 1805 Based on the rules above, the hash used to construct MESSAGE- 1806 INTEGRITY-SHA256 includes the length field from the STUN message 1807 header. Prior to performing the hash, the MESSAGE-INTEGRITY-SHA256 1808 attribute MUST be inserted into the message (with dummy content). 1809 The length MUST then be set to point to the length of the message up 1810 to, and including, the MESSAGE-INTEGRITY-SHA256 attribute itself, but 1811 excluding any attributes after it. Once the computation is 1812 performed, the value of the MESSAGE-INTEGRITY-SHA256 attribute can be 1813 filled in, and the value of the length in the STUN header can be set 1814 to its correct value -- the length of the entire message. Similarly, 1815 when validating the MESSAGE-INTEGRITY-SHA256, the length field should 1816 be adjusted to point to the end of the MESSAGE-INTEGRITY-SHA256 1817 attribute prior to calculating the HMAC. Such adjustment is 1818 necessary when attributes, such as FINGERPRINT, appear after MESSAGE- 1819 INTEGRITY-SHA256. 1821 14.7. FINGERPRINT 1823 The FINGERPRINT attribute MAY be present in all STUN messages. The 1824 value of the attribute is computed as the CRC-32 of the STUN message 1825 up to (but excluding) the FINGERPRINT attribute itself, XOR'ed with 1826 the 32-bit value 0x5354554e (the XOR helps in cases where an 1827 application packet is also using CRC-32 in it). The 32-bit CRC is 1828 the one defined in ITU V.42 [ITU.V42.2002], which has a generator 1829 polynomial of x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1. 1830 When present, the FINGERPRINT attribute MUST be the last attribute in 1831 the message, and thus will appear after MESSAGE-INTEGRITY. 1833 The FINGERPRINT attribute can aid in distinguishing STUN packets from 1834 packets of other protocols. See Section 7. 1836 As with MESSAGE-INTEGRITY, the CRC used in the FINGERPRINT attribute 1837 covers the length field from the STUN message header. Therefore, 1838 this value must be correct and include the CRC attribute as part of 1839 the message length, prior to computation of the CRC. When using the 1840 FINGERPRINT attribute in a message, the attribute is first placed 1841 into the message with a dummy value, then the CRC is computed, and 1842 then the value of the attribute is updated. If the MESSAGE-INTEGRITY 1843 attribute is also present, then it must be present with the correct 1844 message-integrity value before the CRC is computed, since the CRC is 1845 done over the value of the MESSAGE-INTEGRITY attribute as well. 1847 14.8. ERROR-CODE 1849 The ERROR-CODE attribute is used in error response messages. It 1850 contains a numeric error code value in the range of 300 to 699 plus a 1851 textual reason phrase encoded in UTF-8 [RFC3629], and is consistent 1852 in its code assignments and semantics with SIP [RFC3261] and HTTP 1853 [RFC2616]. The reason phrase is meant for user consumption, and can 1854 be anything appropriate for the error code. Recommended reason 1855 phrases for the defined error codes are included in the IANA registry 1856 for error codes. The reason phrase MUST be a UTF-8 [RFC3629] encoded 1857 sequence of less than 128 characters (which can be as long as 763 1858 bytes). 1860 0 1 2 3 1861 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 1862 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1863 | Reserved, should be 0 |Class| Number | 1864 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1865 | Reason Phrase (variable) .. 1866 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1868 Figure 7: ERROR-CODE Attribute 1870 To facilitate processing, the class of the error code (the hundreds 1871 digit) is encoded separately from the rest of the code, as shown in 1872 Figure 7. 1874 The Reserved bits SHOULD be 0, and are for alignment on 32-bit 1875 boundaries. Receivers MUST ignore these bits. The Class represents 1876 the hundreds digit of the error code. The value MUST be between 3 1877 and 6. The Number represents the error code modulo 100, and its 1878 value MUST be between 0 and 99. 1880 The following error codes, along with their recommended reason 1881 phrases, are defined: 1883 300 Try Alternate: The client should contact an alternate server for 1884 this request. This error response MUST only be sent if the 1885 request included either a USERNAME or USERHASH attribute and a 1886 valid MESSAGE-INTEGRITY attribute; otherwise, it MUST NOT be sent 1887 and error code 400 (Bad Request) is suggested. This error 1888 response MUST be protected with the MESSAGE-INTEGRITY attribute, 1889 and receivers MUST validate the MESSAGE-INTEGRITY of this response 1890 before redirecting themselves to an alternate server. 1892 Note: Failure to generate and validate message integrity for a 300 1893 response allows an on-path attacker to falsify a 300 response thus 1894 causing subsequent STUN messages to be sent to a victim. 1896 400 Bad Request: The request was malformed. The client SHOULD NOT 1897 retry the request without modification from the previous attempt. 1898 The server may not be able to generate a valid MESSAGE-INTEGRITY 1899 for this error, so the client MUST NOT expect a valid MESSAGE- 1900 INTEGRITY attribute on this response. 1902 401 Unauthorized: The request did not contain the correct 1903 credentials to proceed. The client should retry the request with 1904 proper credentials. 1906 420 Unknown Attribute: The server received a STUN packet containing 1907 a comprehension-required attribute that it did not understand. 1909 The server MUST put this unknown attribute in the UNKNOWN- 1910 ATTRIBUTE attribute of its error response. 1912 438 Stale Nonce: The NONCE used by the client was no longer valid. 1913 The client should retry, using the NONCE provided in the response. 1915 500 Server Error: The server has suffered a temporary error. The 1916 client should try again. 1918 14.9. REALM 1920 The REALM attribute may be present in requests and responses. It 1921 contains text that meets the grammar for "realm-value" as described 1922 in RFC 3261 [RFC3261] but without the double quotes and their 1923 surrounding whitespace. That is, it is an unquoted realm-value (and 1924 is therefore a sequence of qdtext or quoted-pair). It MUST be a 1925 UTF-8 [RFC3629] encoded sequence of less than 128 characters (which 1926 can be as long as 763 bytes), and MUST have been processed using the 1927 OpaqueString profile [RFC7613]. 1929 Presence of the REALM attribute in a request indicates that long-term 1930 credentials are being used for authentication. Presence in certain 1931 error responses indicates that the server wishes the client to use a 1932 long-term credential for authentication. 1934 14.10. NONCE 1936 The NONCE attribute may be present in requests and responses. It 1937 contains a sequence of qdtext or quoted-pair, which are defined in 1938 RFC 3261 [RFC3261]. Note that this means that the NONCE attribute 1939 will not contain actual quote characters. See RFC 2617 [RFC2617], 1940 Section 4.3, for guidance on selection of nonce values in a server. 1941 It MUST be less than 128 characters (which can be as long as 763 1942 bytes). 1944 14.11. PASSWORD-ALGORITHMS 1946 The PASSWORD-ALGORITHMS attribute may be present in requests and 1947 responses. It contains the list of algorithms that the server can 1948 use to derive the long-term password. 1950 The set of known algorithms is maintained by IANA. The initial set 1951 defined by this specification is found in Section 17.5. 1953 The attribute contains a list of algorithm numbers and variable 1954 length parameters. The algorithm number is a 16-bit value as defined 1955 in Section 17.5. The parameters start with the actual length of the 1956 parameters as a 16-bit value, followed by the parameters that are 1957 specific to each algorithm. The parameters are padded to a 32-bit 1958 boundary, in the same manner as an attribute. 1960 0 1 2 3 1961 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 1962 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1963 | Algorithm 1 | Algorithm 1 Parameters Length | 1964 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1965 | Algorithm 1 Parameters (variable) 1966 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1967 | Algorithm 2 | Algorithm 2 Parameters Length | 1968 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1969 | Algorithm 2 Parameter (variable) 1970 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1971 | ... 1973 Figure 8: Format of PASSWORD-ALGORITHMS Attribute 1975 14.12. PASSWORD-ALGORITHM 1977 The PASSWORD-ALGORITHM attribute is present only in requests. It 1978 contains the algorithms that the server must use to derive the long- 1979 term password. 1981 The set of known algorithms is maintained by IANA. The initial set 1982 defined by this specification is found in Section 17.5. 1984 The attribute contains an algorithm number and variable length 1985 parameters. The algorithm number is a 16-bit value as defined in 1986 Section 17.5. The parameters starts with the actual length of the 1987 parameters as a 16-bit value, followed by the parameters that are 1988 specific to the algorithm. The parameters are padded to a 32-bit 1989 boundary, in the same manner as an attribute. 1991 0 1 2 3 1992 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 1993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1994 | Algorithm | Algorithm Parameters Length | 1995 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1996 | Algorithm Parameters (variable) 1997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1999 Figure 9: Format of PASSWORD-ALGORITHM Attribute 2001 14.13. UNKNOWN-ATTRIBUTES 2003 The UNKNOWN-ATTRIBUTES attribute is present only in an error response 2004 when the response code in the ERROR-CODE attribute is 420. 2006 The attribute contains a list of 16-bit values, each of which 2007 represents an attribute type that was not understood by the server. 2009 0 1 2 3 2010 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 2011 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2012 | Attribute 1 Type | Attribute 2 Type | 2013 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2014 | Attribute 3 Type | Attribute 4 Type ... 2015 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2017 Figure 10: Format of UNKNOWN-ATTRIBUTES Attribute 2019 Note: In [RFC3489], this field was padded to 32 by duplicating the 2020 last attribute. In this version of the specification, the normal 2021 padding rules for attributes are used instead. 2023 14.14. SOFTWARE 2025 The SOFTWARE attribute contains a textual description of the software 2026 being used by the agent sending the message. It is used by clients 2027 and servers. Its value SHOULD include manufacturer and version 2028 number. The attribute has no impact on operation of the protocol, 2029 and serves only as a tool for diagnostic and debugging purposes. The 2030 value of SOFTWARE is variable length. It MUST be a UTF-8 [RFC3629] 2031 encoded sequence of less than 128 characters (which can be as long as 2032 763 bytes). 2034 14.15. ALTERNATE-SERVER 2036 The alternate server represents an alternate transport address 2037 identifying a different STUN server that the STUN client should try. 2039 It is encoded in the same way as MAPPED-ADDRESS, and thus refers to a 2040 single server by IP address. The IP address family MUST be identical 2041 to that of the source IP address of the request. 2043 14.16. ALTERNATE-DOMAIN 2045 The alternate domain represents the domain name that is used to 2046 verify the IP address in the ALTERNATE-SERVER attribute when the 2047 transport protocol uses TLS or DTLS. 2049 The value of ALTERNATE-DOMAIN is variable length. It MUST be a UTF-8 2050 [RFC3629] encoded sequence of less than 128 characters (which can be 2051 as long as 763 bytes). 2053 15. Security Considerations 2055 15.1. Attacks against the Protocol 2057 15.1.1. Outside Attacks 2059 An attacker can try to modify STUN messages in transit, in order to 2060 cause a failure in STUN operation. These attacks are detected for 2061 both requests and responses through the message-integrity mechanism, 2062 using either a short-term or long-term credential. Of course, once 2063 detected, the manipulated packets will be dropped, causing the STUN 2064 transaction to effectively fail. This attack is possible only by an 2065 on-path attacker. 2067 An attacker that can observe, but not modify, STUN messages in- 2068 transit (for example, an attacker present on a shared access medium, 2069 such as Wi-Fi), can see a STUN request, and then immediately send a 2070 STUN response, typically an error response, in order to disrupt STUN 2071 processing. This attack is also prevented for messages that utilize 2072 MESSAGE-INTEGRITY. However, some error responses, those related to 2073 authentication in particular, cannot be protected by MESSAGE- 2074 INTEGRITY. When STUN itself is run over a secure transport protocol 2075 (e.g., TLS), these attacks are completely mitigated. 2077 Depending on the STUN usage, these attacks may be of minimal 2078 consequence and thus do not require message integrity to mitigate. 2079 For example, when STUN is used to a basic STUN server to discover a 2080 server reflexive candidate for usage with ICE, authentication and 2081 message integrity are not required since these attacks are detected 2082 during the connectivity check phase. The connectivity checks 2083 themselves, however, require protection for proper operation of ICE 2084 overall. As described in Section 13, STUN usages describe when 2085 authentication and message integrity are needed. 2087 Since STUN uses the HMAC of a shared secret for authentication and 2088 integrity protection, it is subject to offline dictionary attacks. 2089 When authentication is utilized, it SHOULD be with a strong password 2090 that is not readily subject to offline dictionary attacks. 2091 Protection of the channel itself, using TLS or DTLS, mitigates these 2092 attacks. 2094 STUN supports both MESSAGE-INTEGRITY and MESSAGE-INTEGRITY-SHA256, 2095 which is subject to bid down attacks by an on-path attacker. 2096 Protection of the channel itself, using TLS or DTLS, mitigates these 2097 attacks. Timely removal of the support of MESSAGE-INTEGRITY in a 2098 future version of STUN is necessary. 2100 15.1.2. Inside Attacks 2102 A rogue client may try to launch a DoS attack against a server by 2103 sending it a large number of STUN requests. Fortunately, STUN 2104 requests can be processed statelessly by a server, making such 2105 attacks hard to launch. 2107 A rogue client may use a STUN server as a reflector, sending it 2108 requests with a falsified source IP address and port. In such a 2109 case, the response would be delivered to that source IP and port. 2110 There is no amplification of the number of packets with this attack 2111 (the STUN server sends one packet for each packet sent by the 2112 client), though there is a small increase in the amount of data, 2113 since STUN responses are typically larger than requests. This attack 2114 is mitigated by ingress source address filtering. 2116 Revealing the specific software version of the agent through the 2117 SOFTWARE attribute might allow them to become more vulnerable to 2118 attacks against software that is known to contain security holes. 2119 Implementers SHOULD make usage of the SOFTWARE attribute a 2120 configurable option. 2122 15.2. Attacks Affecting the Usage 2124 This section lists attacks that might be launched against a usage of 2125 STUN. Each STUN usage must consider whether these attacks are 2126 applicable to it, and if so, discuss counter-measures. 2128 Most of the attacks in this section revolve around an attacker 2129 modifying the reflexive address learned by a STUN client through a 2130 Binding request/response transaction. Since the usage of the 2131 reflexive address is a function of the usage, the applicability and 2132 remediation of these attacks are usage-specific. In common 2133 situations, modification of the reflexive address by an on-path 2134 attacker is easy to do. Consider, for example, the common situation 2135 where STUN is run directly over UDP. In this case, an on-path 2136 attacker can modify the source IP address of the Binding request 2137 before it arrives at the STUN server. The STUN server will then 2138 return this IP address in the XOR-MAPPED-ADDRESS attribute to the 2139 client, and send the response back to that (falsified) IP address and 2140 port. If the attacker can also intercept this response, it can 2141 direct it back towards the client. Protecting against this attack by 2142 using a message-integrity check is impossible, since a message- 2143 integrity value cannot cover the source IP address, since the 2144 intervening NAT must be able to modify this value. Instead, one 2145 solution to preventing the attacks listed below is for the client to 2146 verify the reflexive address learned, as is done in ICE 2147 [I-D.ietf-ice-rfc5245bis]. Other usages may use other means to 2148 prevent these attacks. 2150 15.2.1. Attack I: Distributed DoS (DDoS) against a Target 2152 In this attack, the attacker provides one or more clients with the 2153 same faked reflexive address that points to the intended target. 2154 This will trick the STUN clients into thinking that their reflexive 2155 addresses are equal to that of the target. If the clients hand out 2156 that reflexive address in order to receive traffic on it (for 2157 example, in SIP messages), the traffic will instead be sent to the 2158 target. This attack can provide substantial amplification, 2159 especially when used with clients that are using STUN to enable 2160 multimedia applications. However, it can only be launched against 2161 targets for which packets from the STUN server to the target pass 2162 through the attacker, limiting the cases in which it is possible. 2164 15.2.2. Attack II: Silencing a Client 2166 In this attack, the attacker provides a STUN client with a faked 2167 reflexive address. The reflexive address it provides is a transport 2168 address that routes to nowhere. As a result, the client won't 2169 receive any of the packets it expects to receive when it hands out 2170 the reflexive address. This exploitation is not very interesting for 2171 the attacker. It impacts a single client, which is frequently not 2172 the desired target. Moreover, any attacker that can mount the attack 2173 could also deny service to the client by other means, such as 2174 preventing the client from receiving any response from the STUN 2175 server, or even a DHCP server. As with the attack in Section 15.2.1, 2176 this attack is only possible when the attacker is on path for packets 2177 sent from the STUN server towards this unused IP address. 2179 15.2.3. Attack III: Assuming the Identity of a Client 2181 This attack is similar to attack II. However, the faked reflexive 2182 address points to the attacker itself. This allows the attacker to 2183 receive traffic that was destined for the client. 2185 15.2.4. Attack IV: Eavesdropping 2187 In this attack, the attacker forces the client to use a reflexive 2188 address that routes to itself. It then forwards any packets it 2189 receives to the client. This attack would allow the attacker to 2190 observe all packets sent to the client. However, in order to launch 2191 the attack, the attacker must have already been able to observe 2192 packets from the client to the STUN server. In most cases (such as 2193 when the attack is launched from an access network), this means that 2194 the attacker could already observe packets sent to the client. This 2195 attack is, as a result, only useful for observing traffic by 2196 attackers on the path from the client to the STUN server, but not 2197 generally on the path of packets being routed towards the client. 2199 15.3. Hash Agility Plan 2201 This specification uses both HMAC-SHA-1 and HMAC-SHA-256 for 2202 computation of the message integrity. If, at a later time, HMAC- 2203 SHA-256 is found to be compromised, the following is the remedy that 2204 will be applied. 2206 We will define a STUN extension that introduces a new message- 2207 integrity attribute, computed using a new hash. Clients would be 2208 required to include both the new and old message-integrity attributes 2209 in their requests or indications. A new server will utilize the new 2210 message-integrity attribute, and an old one, the old. After a 2211 transition period where mixed implementations are in deployment, the 2212 old message-integrity attribute will be deprecated by another 2213 specification, and clients will cease including it in requests. 2215 After a transition period, a new document updating this document will 2216 remove the usage of HMAC-SHA-1 for computation of the message- 2217 integrity. 2219 16. IAB Considerations 2221 The IAB has studied the problem of Unilateral Self-Address Fixing 2222 (UNSAF), which is the general process by which a client attempts to 2223 determine its address in another realm on the other side of a NAT 2224 through a collaborative protocol reflection mechanism (RFC3424 2225 [RFC3424]). STUN can be used to perform this function using a 2226 Binding request/response transaction if one agent is behind a NAT and 2227 the other is on the public side of the NAT. 2229 The IAB has suggested that protocols developed for this purpose 2230 document a specific set of considerations. Because some STUN usages 2231 provide UNSAF functions (such as ICE [I-D.ietf-ice-rfc5245bis] ), and 2232 others do not (such as SIP Outbound [RFC5626]), answers to these 2233 considerations need to be addressed by the usages themselves. 2235 17. IANA Considerations 2236 17.1. STUN Security Features Registry 2238 A STUN Security Feature set is a 24 bit value. 2240 IANA is requested to create a new registry containing the STUN 2241 Security Features that are protected by the bid down attack 2242 prevention mechanism described in section Section 9.2.1. 2244 The initial STUN Security Features are: 2246 0x000000: Reserved 2247 0x000001: Password algorithms 2248 0x000002: Username anonymity 2250 New Security Features are assigned by a Standard Action [RFC5226]. 2252 17.2. STUN Methods Registry 2254 IANA is requested to update the reference from RFC 5389 to RFC-to-be 2255 for the following STUN methods: 2257 0x000: (Reserved) 2258 0x001: Binding 2259 0x002: (Reserved; was SharedSecret) 2261 17.3. STUN Attribute Registry 2263 17.3.1. Updated Attributes 2265 IANA is requested to update the reference from RFC 5389 to RFC-to-be 2266 for the following STUN methods: 2268 Comprehension-required range (0x0000-0x7FFF): 2269 0x0000: (Reserved) 2270 0x0001: MAPPED-ADDRESS 2271 0x0002: (Reserved; was RESPONSE-ADDRESS) 2272 0x0003: (Reserved; was CHANGE-REQUEST) 2273 0x0004: (Reserved; was SOURCE-ADDRESS) 2274 0x0005: (Reserved; was CHANGED-ADDRESS) 2275 0x0006: USERNAME 2276 0x0007: (Reserved; was PASSWORD) 2277 0x0008: MESSAGE-INTEGRITY 2278 0x0009: ERROR-CODE 2279 0x000A: UNKNOWN-ATTRIBUTES 2280 0x000B: (Reserved; was REFLECTED-FROM) 2281 0x0014: REALM 2282 0x0015: NONCE 2283 0x0020: XOR-MAPPED-ADDRESS 2285 Comprehension-optional range (0x8000-0xFFFF) 2286 0x8022: SOFTWARE 2287 0x8023: ALTERNATE-SERVER 2288 0x8028: FINGERPRINT 2290 17.3.2. New Attributes 2292 IANA is requested to add the following attribute to the STUN 2293 Attribute Registry: 2295 Comprehension-required range (0x0000-0x7FFF): 2296 0xXXXX: MESSAGE-INTEGRITY-SHA256 2297 0xXXXX: PASSWORD-ALGORITHM 2298 0xXXXX: USERHASH 2300 Comprehension-optional range (0x8000-0xFFFF) 2301 0xXXXX: PASSSORD-ALGORITHMS 2302 0xXXXX: ALTERNATE-DOMAIN 2304 17.4. STUN Error Code Registry 2306 IANA is requested to update the reference from RFC 5389 to RFC-to-be 2307 for the Error Codes given in Section 14.8. 2309 17.5. Password Algorithm Registry 2311 IANA is requested to create a new registry for Password Algorithm. 2313 A Password Algorithm is a hex number in the range 0x0000 - 0xFFFF. 2315 The initial Password Algorithms are: 2317 0x0001: MD5 2318 0x0002: SHA256 2320 Password Algorithms in the first half of the range (0x0000 - 0x7FFF) 2321 are assigned by IETF Review [RFC5226]. Password Algorithms in the 2322 second half of the range (0x8000 - 0xFFFF) are assigned by Designated 2323 Expert [RFC5226]. 2325 17.5.1. Password Algorithms 2327 17.5.1.1. MD5 2329 This password algorithm is taken from [RFC1321]. 2331 The key length is 20 bytes and the parameters value is empty. 2333 Note: This algorithm MUST only be used for compatibility with legacy 2334 systems. 2336 key = MD5(username ":" realm ":" OpaqueString(password)) 2338 17.5.1.2. SHA256 2340 This password algorithm is taken from [RFC7616]. 2342 The key length is 32 bytes and the parameters value is empty. 2344 key = SHA256(username ":" realm ":" OpaqueString(password)) 2346 17.6. STUN UDP and TCP Port Numbers 2348 IANA is requested to update the reference from RFC 5389 to RFC-to-be 2349 for the following ports: 2351 stun 3478/tcp Session Traversal Utilities for NAT (STUN) port 2352 stun 3478/udp Session Traversal Utilities for NAT (STUN) port 2353 stuns 5349/tcp Session Traversal Utilities for NAT (STUN) port 2355 18. Changes since RFC 5389 2357 This specification obsoletes RFC 5389 [RFC5389]. This specification 2358 differs from RFC 5389 in the following ways: 2360 o Added support for DTLS-over-UDP (RFC 6347). 2362 o Made clear that the RTO is considered stale if there is no 2363 transactions with the server. 2365 o Aligned the RTO calculation with RFC 6298. 2367 o Updated the cipher suites for TLS. 2369 o Added support for STUN URI (RFC 7064). 2371 o Added support for SHA256 message integrity. 2373 o Updated the PRECIS support to RFC 7613. 2375 o Added protocol and registry to choose the password encryption 2376 algorithm. 2378 o Added support for anonymous username. 2380 o Added protocol and registry for preventing biddown attacks. 2382 o Sharing a NONCE is no longer permitted. 2384 o Added the possibility of using a domain name in the alternate 2385 server mechanism. 2387 o Added more C snippets. 2389 19. References 2391 19.1. Normative References 2393 [ITU.V42.2002] 2394 International Telecommunications Union, "Error-correcting 2395 Procedures for DCEs Using Asynchronous-to-Synchronous 2396 Conversion", ITU-T Recommendation V.42, 2002. 2398 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 2399 DOI 10.17487/RFC0791, September 1981, 2400 . 2402 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2403 Communication Layers", STD 3, RFC 1122, 2404 DOI 10.17487/RFC1122, October 1989, 2405 . 2407 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2408 DOI 10.17487/RFC1321, April 1992, 2409 . 2411 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2412 Hashing for Message Authentication", RFC 2104, 2413 DOI 10.17487/RFC2104, February 1997, 2414 . 2416 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2417 Requirement Levels", BCP 14, RFC 2119, 2418 DOI 10.17487/RFC2119, March 1997, 2419 . 2421 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 2422 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 2423 December 1998, . 2425 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2426 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2427 Authentication: Basic and Digest Access Authentication", 2428 RFC 2617, DOI 10.17487/RFC2617, June 1999, 2429 . 2431 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 2432 specifying the location of services (DNS SRV)", RFC 2782, 2433 DOI 10.17487/RFC2782, February 2000, 2434 . 2436 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2437 DOI 10.17487/RFC2818, May 2000, 2438 . 2440 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2441 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2442 2003, . 2444 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2445 (TLS) Protocol Version 1.2", RFC 5246, 2446 DOI 10.17487/RFC5246, August 2008, 2447 . 2449 [RFC6298] Paxson, V., Allman, M., Chu, J., and M. Sargent, 2450 "Computing TCP's Retransmission Timer", RFC 6298, 2451 DOI 10.17487/RFC6298, June 2011, 2452 . 2454 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2455 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2456 January 2012, . 2458 [RFC7064] Nandakumar, S., Salgueiro, G., Jones, P., and M. Petit- 2459 Huguenin, "URI Scheme for the Session Traversal Utilities 2460 for NAT (STUN) Protocol", RFC 7064, DOI 10.17487/RFC7064, 2461 November 2013, . 2463 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 2464 Layer Security (DTLS) as Transport for Session Traversal 2465 Utilities for NAT (STUN)", RFC 7350, DOI 10.17487/RFC7350, 2466 August 2014, . 2468 [RFC7613] Saint-Andre, P. and A. Melnikov, "Preparation, 2469 Enforcement, and Comparison of Internationalized Strings 2470 Representing Usernames and Passwords", RFC 7613, 2471 DOI 10.17487/RFC7613, August 2015, 2472 . 2474 19.2. Informative References 2476 [I-D.ietf-ice-rfc5245bis] 2477 Keranen, A. and J. Rosenberg, "Interactive Connectivity 2478 Establishment (ICE): A Protocol for Network Address 2479 Translator (NAT) Traversal", draft-ietf-ice-rfc5245bis-01 2480 (work in progress), December 2015. 2482 [KARN87] Karn, P. and C. Partridge, "Improving Round-Trip Time 2483 Estimates in Reliable Transport Protocols", SIGCOMM 1987, 2484 August 1987. 2486 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2487 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2488 Transfer Protocol -- HTTP/1.1", RFC 2616, 2489 DOI 10.17487/RFC2616, June 1999, 2490 . 2492 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2493 A., Peterson, J., Sparks, R., Handley, M., and E. 2494 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2495 DOI 10.17487/RFC3261, June 2002, 2496 . 2498 [RFC3424] Daigle, L., Ed. and IAB, "IAB Considerations for 2499 UNilateral Self-Address Fixing (UNSAF) Across Network 2500 Address Translation", RFC 3424, DOI 10.17487/RFC3424, 2501 November 2002, . 2503 [RFC3489] Rosenberg, J., Weinberger, J., Huitema, C., and R. Mahy, 2504 "STUN - Simple Traversal of User Datagram Protocol (UDP) 2505 Through Network Address Translators (NATs)", RFC 3489, 2506 DOI 10.17487/RFC3489, March 2003, 2507 . 2509 [RFC4107] Bellovin, S. and R. Housley, "Guidelines for Cryptographic 2510 Key Management", BCP 107, RFC 4107, DOI 10.17487/RFC4107, 2511 June 2005, . 2513 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2514 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2515 DOI 10.17487/RFC5226, May 2008, 2516 . 2518 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2519 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2520 DOI 10.17487/RFC5389, October 2008, 2521 . 2523 [RFC5626] Jennings, C., Ed., Mahy, R., Ed., and F. Audet, Ed., 2524 "Managing Client-Initiated Connections in the Session 2525 Initiation Protocol (SIP)", RFC 5626, 2526 DOI 10.17487/RFC5626, October 2009, 2527 . 2529 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 2530 Relays around NAT (TURN): Relay Extensions to Session 2531 Traversal Utilities for NAT (STUN)", RFC 5766, 2532 DOI 10.17487/RFC5766, April 2010, 2533 . 2535 [RFC5769] Denis-Courmont, R., "Test Vectors for Session Traversal 2536 Utilities for NAT (STUN)", RFC 5769, DOI 10.17487/RFC5769, 2537 April 2010, . 2539 [RFC5780] MacDonald, D. and B. Lowekamp, "NAT Behavior Discovery 2540 Using Session Traversal Utilities for NAT (STUN)", 2541 RFC 5780, DOI 10.17487/RFC5780, May 2010, 2542 . 2544 [RFC6544] Rosenberg, J., Keranen, A., Lowekamp, B., and A. Roach, 2545 "TCP Candidates with Interactive Connectivity 2546 Establishment (ICE)", RFC 6544, DOI 10.17487/RFC6544, 2547 March 2012, . 2549 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2550 "Recommendations for Secure Use of Transport Layer 2551 Security (TLS) and Datagram Transport Layer Security 2552 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2553 2015, . 2555 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 2556 Digest Access Authentication", RFC 7616, 2557 DOI 10.17487/RFC7616, September 2015, 2558 . 2560 Appendix A. C Snippet to Determine STUN Message Types 2562 Given a 16-bit STUN message type value in host byte order in msg_type 2563 parameter, below are C macros to determine the STUN message types: 2565 #define IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000) 2566 #define IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010) 2567 #define IS_SUCCESS_RESP(msg_type) (((msg_type) & 0x0110) == 0x0100) 2568 #define IS_ERR_RESP(msg_type) (((msg_type) & 0x0110) == 0x0110) 2570 A function to convert method and class into a message type: 2572 int type(int method, int cls) { 2573 return (method & 0x0F80) << 9 | (method & 0x0070) << 5 2574 | (method & 0x000F) | (cls & 0x0002) << 8 2575 | (cls & 0x0001) << 4; 2576 } 2578 A function to extract the method from the message type: 2580 int method(int type) { 2581 return (type & 0x3E00) >> 2 | (type & 0x00E0) >> 1 2582 | (type & 0x000F); 2583 } 2585 A function to extract the class from the message type: 2587 int cls(int type) { 2588 return (type & 0x0100) >> 7 | (type & 0x0010) >> 4; 2589 } 2591 Appendix B. Test Vectors 2593 This section augments the list of test vectors defined in [RFC5769] 2594 with MESSAGE-INTEGRITY-SHA256. All the formats and definitions 2595 listed in Section 2 of [RFC5769] apply here. 2597 B.1. Sample Request with Long-Term Authentication with MESSAGE- 2598 INTEGRITY-SHA256 and USERHASH 2600 This request uses the following parameters: 2602 Username: "" (without 2603 quotes) unaffected by OpaqueString [RFC7613] processing 2605 Password: "TheMtr" and "TheMatrIX" (without 2606 quotes) respectively before and after OpaqueString processing 2608 Nonce: "obMatJos2AAACf//499k954d6OL34oL9FSTvy64sA" (without quotes) 2610 Realm: "example.org" (without quotes) 2611 00 01 00 9c Request type and message length 2612 21 12 a4 42 Magic cookie 2613 78 ad 34 33 } 2614 c6 ad 72 c0 } Transaction ID 2615 29 da 41 2e } 2616 XX XX 00 20 USERHASH attribute header 2617 4a 3c f3 8f } 2618 ef 69 92 bd } 2619 a9 52 c6 78 } 2620 04 17 da 0f } Userhash value (32 bytes) 2621 24 81 94 15 } 2622 56 9e 60 b2 } 2623 05 c4 6e 41 } 2624 40 7f 17 04 } 2625 00 15 00 29 NONCE attribute header 2626 6f 62 4d 61 } 2627 74 4a 6f 73 } 2628 32 41 41 41 } 2629 43 66 2f 2f } 2630 34 39 39 6b } Nonce value and padding (3 bytes) 2631 39 35 34 64 } 2632 36 4f 4c 33 } 2633 34 6f 4c 39 } 2634 46 53 54 76 } 2635 79 36 34 73 } 2636 41 00 00 00 } 2637 00 14 00 0b REALM attribute header 2638 65 78 61 6d } 2639 70 6c 65 2e } Realm value (11 bytes) and padding (1 byte) 2640 6f 72 67 00 } 2641 XX XX 00 20 MESSAGE-INTEGRITY-SHA256 attribute header 2642 c4 ec a2 b6 } 2643 24 6f 26 be } 2644 bc 2f 77 49 } 2645 07 c2 00 a3 } HMAC-SHA256 value 2646 76 c7 c2 8e } 2647 b4 d1 26 60 } 2648 bb fe 9f 28 } 2649 0e 85 71 f2 } 2651 Note: Before publication, the XX XX placeholder must be replaced by 2652 the value assigned to MESSAGE-INTEGRITY-SHA256 and USERHASH by 2653 IANA. The MESSAGE-INTEGRITY-SHA256 attribute value will need to 2654 be updated after this. 2656 Appendix C. Release notes 2658 This section must be removed before publication as an RFC. 2660 C.1. Modifications between draft-ietf-tram-stunbis-08 and draft-ietf- 2661 tram-stunbis-07 2663 o Updated list of changes since RFC 5389. 2665 o More examples are automatically generated. 2667 o Message integrity truncation is fixed at a multiple of 4 bytes, 2668 because the padding will not decrease by more than this. 2670 o USERHASH contains the 32 bytes of the hash, not a character 2671 string. 2673 o Updated the example to use the USERHASH attribuet and the modified 2674 NONCE attribute. 2676 o Updated ICEbis reference. 2678 C.2. Modifications between draft-ietf-tram-stunbis-07 and draft-ietf- 2679 tram-stunbis-06 2681 o Add USERHASH attribute to carry the hashed version of the 2682 username. 2684 o Add IANA registry and nonce encoding for Security Features that 2685 need to be protected from bid down attacks. 2687 o Modified MESSAGE-INTEGRITY and MESSAGE-INTEGRITY-SHA256 to support 2688 truncation limits (pending cryptographic review), 2690 C.3. Modifications between draft-ietf-tram-stunbis-06 and draft-ietf- 2691 tram-stunbis-05 2693 o Changed I-D references to RFC references. 2695 o Changed CHANGE-ADDRESS to CHANGE-REQUEST (Errata #4233). 2697 o Added test vector for MESSAGE-INTEGRITY-SHA256. 2699 o Address additional review comments from Jonathan Lennox and 2700 Brandon Williams. 2702 C.4. Modifications between draft-ietf-tram-stunbis-05 and draft-ietf- 2703 tram-stunbis-04 2705 o Address review comments from Jonathan Lennox and Brandon Williams. 2707 C.5. Modifications between draft-ietf-tram-stunbis-04 and draft-ietf- 2708 tram-stunbis-03 2710 o Remove SCTP. 2712 o Remove DANE. 2714 o s/MESSAGE-INTEGRITY2/MESSAGE-INTEGRITY-SHA256/ 2716 o Remove Salted SHA256 password hash. 2718 o The RTO delay between transactions is removed. 2720 o Make clear that reusing NONCE will trigger a wasted round trip. 2722 C.6. Modifications between draft-ietf-tram-stunbis-03 and draft-ietf- 2723 tram-stunbis-02 2725 o SCTP prefix is now 0b00000101 instead of 0x11. 2727 o Add SCTP at various places it was needed. 2729 o Update the hash agility plan to take in account HMAC-SHA-256. 2731 o Adds the bid down attack on message-integrity in the security 2732 section. 2734 C.7. Modifications between draft-ietf-tram-stunbis-02 and draft-ietf- 2735 tram-stunbis-01 2737 o STUN hash algorithm agility (currently only SHA-1 is allowed). 2739 o Clarify terminology, text and guidance for STUN fragmentation. 2741 o Clarify whether it's valid to share nonces across TURN 2742 allocations. 2744 o Prevent the server to allocate the same NONCE to clients with 2745 different IP address and/or different port. This prevent sharing 2746 the nonce between TURN allocations in TURN. 2748 o Add reference to draft-ietf-uta-tls-bcp 2749 o Add a new attribute ALTERNATE-DOMAIN to verify the certificate of 2750 the ALTERNATE-SERVER after a 300 over (D)TLS. 2752 o The RTP delay between transactions applies only to parallel 2753 transactions, not to serial transactions. That prevents a 3RTT 2754 delay between the first transaction and the second transaction 2755 with long term authentication. 2757 o Add text saying ORIGIN can increase a request size beyond the MTU 2758 and so require an SCTPoUDP transport. 2760 o Move the Acknowledgments and Contributor sections to the end of 2761 the document, in accordance with RFC 7322 section 4. 2763 C.8. Modifications between draft-ietf-tram-stunbis-01 and draft-ietf- 2764 tram-stunbis-00 2766 o Add negotiation mechanism for new password algorithms. 2768 o Describe the MESSAGE-INTEGRITY/MESSAGE-INTEGRITY2 protocol. 2770 o Add support for SCTP to solve the fragmentation problem. 2772 o Merge RFC 7350: 2774 * Split the "Sending over..." sections in 3. 2776 * Add DTLS-over-UDP as transport. 2778 * Update the cipher suites and cipher/compression restrictions. 2780 * A stuns uri with an IP address is rejected. 2782 * Replace most of the RFC 3489 compatibility by a reference to 2783 the section in RFC 5389. 2785 * Update the STUN Usages list with transport applicability. 2787 o Merge RFC 7064: 2789 * DNS discovery is done from the URI. 2791 * Reorganized the text about default ports. 2793 o Add more C snippets. 2795 o Make clear that the cached RTO is discarded only if there is no 2796 new transations for 10 minutes. 2798 C.9. Modifications between draft-salgueiro-tram-stunbis-02 and draft- 2799 ietf-tram-stunbis-00 2801 o Draft adopted as WG item. 2803 C.10. Modifications between draft-salgueiro-tram-stunbis-02 and draft- 2804 salgueiro-tram-stunbis-01 2806 o Add definition of MESSAGE-INTEGRITY2. 2808 o Update text and reference from RFC 2988 to RFC 6298. 2810 o s/The IAB has mandated/The IAB has suggested/ (Errata #3737). 2812 o Fix the figure for the UNKNOWN-ATTRIBUTES (Errata #2972). 2814 o Fix section number and make clear that the original domain name is 2815 used for the server certificate verification. This is consistent 2816 with what RFC 5922 (section 4) is doing. (Errata #2010) 2818 o Remove text transitioning from RFC 3489. 2820 o Add definition of MESSAGE-INTEGRITY2. 2822 o Update text and reference from RFC 2988 to RFC 6298. 2824 o s/The IAB has mandated/The IAB has suggested/ (Errata #3737). 2826 o Fix the figure for the UNKNOWN-ATTRIBUTES (Errata #2972). 2828 o Fix section number and make clear that the original domain name is 2829 used for the server certificate verification. This is consistent 2830 with what RFC 5922 (section 4) is doing. (Errata #2010) 2832 C.11. Modifications between draft-salgueiro-tram-stunbis-01 and draft- 2833 salgueiro-tram-stunbis-00 2835 o Restore the RFC 5389 text. 2837 o Add list of open issues. 2839 Acknowledgements 2841 Thanks to Michael Tuexen, Tirumaleswar Reddy, Oleg Moskalenko, Simon 2842 Perreault, Benjamin Schwartz, Rifaat Shekh-Yusef, Alan Johnston, 2843 Jonathan Lennox and Brandon Williams for the comments, suggestions, 2844 and questions that helped improve this document. 2846 The authors of RFC 5389 would like to thank Cedric Aoun, Pete 2847 Cordell, Cullen Jennings, Bob Penfield, Xavier Marjou, Magnus 2848 Westerlund, Miguel Garcia, Bruce Lowekamp, and Chris Sullivan for 2849 their comments, and Baruch Sterman and Alan Hawrylyshen for initial 2850 implementations. Thanks for Leslie Daigle, Allison Mankin, Eric 2851 Rescorla, and Henning Schulzrinne for IESG and IAB input on this 2852 work. 2854 Contributors 2856 Christian Huitema and Joel Weinberger were original co-authors of RFC 2857 3489. 2859 Authors' Addresses 2861 Marc Petit-Huguenin 2862 Impedance Mismatch 2864 Email: marc@petit-huguenin.org 2866 Gonzalo Salgueiro 2867 Cisco 2868 7200-12 Kit Creek Road 2869 Research Triangle Park, NC 27709 2870 US 2872 Email: gsalguei@cisco.com 2874 Jonathan Rosenberg 2875 Cisco 2876 Edison, NJ 2877 US 2879 Email: jdrosen@cisco.com 2880 URI: http://www.jdrosen.net 2882 Dan Wing 2883 Cisco 2884 771 Alder Drive 2885 San Jose, CA 95035 2886 US 2888 Email: dwing@cisco.com 2889 Rohan Mahy 2890 Plantronics 2891 345 Encinal Street 2892 Santa Cruz, CA 95060 2893 US 2895 Email: rohan@ekabal.com 2897 Philip Matthews 2898 Avaya 2899 1135 Innovation Drive 2900 Ottawa, Ontario K2K 3G7 2901 Canada 2903 Phone: +1 613 592 4343 x224 2904 Email: philip_matthews@magma.ca