idnits 2.17.1 draft-ietf-tram-turnbis-28.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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? -- The draft header indicates that this document obsoletes RFC6156, but the abstract doesn't seem to directly say this. It does mention RFC6156 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 22, 2019) is 1733 days in the past. Is this intentional? 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. 'Protocol-Numbers' ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-17) exists of draft-ietf-intarea-frag-fragile-15 == Outdated reference: A later version (-39) exists of draft-ietf-mmusic-ice-sip-sdp-36 == Outdated reference: A later version (-20) exists of draft-ietf-tram-stun-pmtud-10 == Outdated reference: A later version (-32) exists of draft-ietf-tsvwg-udp-options-07 -- Obsolete informational reference (is this intentional?): RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 6156 (Obsoleted by RFC 8656) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TRAM WG T. Reddy, Ed. 3 Internet-Draft McAfee 4 Obsoletes: 5766, 6156 (if approved) A. Johnston, Ed. 5 Intended status: Standards Track Villanova University 6 Expires: January 23, 2020 P. Matthews 7 Alcatel-Lucent 8 J. Rosenberg 9 jdrosen.net 10 July 22, 2019 12 Traversal Using Relays around NAT (TURN): Relay Extensions to Session 13 Traversal Utilities for NAT (STUN) 14 draft-ietf-tram-turnbis-28 16 Abstract 18 If a host is located behind a NAT, then in certain situations it can 19 be impossible for that host to communicate directly with other hosts 20 (peers). In these situations, it is necessary for the host to use 21 the services of an intermediate node that acts as a communication 22 relay. This specification defines a protocol, called TURN (Traversal 23 Using Relays around NAT), that allows the host to control the 24 operation of the relay and to exchange packets with its peers using 25 the relay. TURN differs from other relay control protocols in that 26 it allows a client to communicate with multiple peers using a single 27 relay address. 29 The TURN protocol was designed to be used as part of the ICE 30 (Interactive Connectivity Establishment) approach to NAT traversal, 31 though it also can be used without ICE. 33 This document obsoletes RFC 5766 and RFC 6156. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on January 23, 2020. 51 Copyright Notice 53 Copyright (c) 2019 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 3. Overview of Operation . . . . . . . . . . . . . . . . . . . . 8 71 3.1. Transports . . . . . . . . . . . . . . . . . . . . . . . 11 72 3.2. Allocations . . . . . . . . . . . . . . . . . . . . . . . 12 73 3.3. Permissions . . . . . . . . . . . . . . . . . . . . . . . 14 74 3.4. Send Mechanism . . . . . . . . . . . . . . . . . . . . . 15 75 3.5. Channels . . . . . . . . . . . . . . . . . . . . . . . . 17 76 3.6. Unprivileged TURN Servers . . . . . . . . . . . . . . . . 19 77 3.7. Avoiding IP Fragmentation . . . . . . . . . . . . . . . . 19 78 3.8. RTP Support . . . . . . . . . . . . . . . . . . . . . . . 21 79 3.9. Happy Eyeballs for TURN . . . . . . . . . . . . . . . . . 21 80 4. Discovery of TURN server . . . . . . . . . . . . . . . . . . 22 81 4.1. TURN URI Scheme Semantics . . . . . . . . . . . . . . . . 22 82 5. General Behavior . . . . . . . . . . . . . . . . . . . . . . 23 83 6. Allocations . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 7. Creating an Allocation . . . . . . . . . . . . . . . . . . . 26 85 7.1. Sending an Allocate Request . . . . . . . . . . . . . . . 26 86 7.2. Receiving an Allocate Request . . . . . . . . . . . . . . 28 87 7.3. Receiving an Allocate Success Response . . . . . . . . . 33 88 7.4. Receiving an Allocate Error Response . . . . . . . . . . 34 89 8. Refreshing an Allocation . . . . . . . . . . . . . . . . . . 36 90 8.1. Sending a Refresh Request . . . . . . . . . . . . . . . . 37 91 8.2. Receiving a Refresh Request . . . . . . . . . . . . . . . 37 92 8.3. Receiving a Refresh Response . . . . . . . . . . . . . . 38 93 9. Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 38 94 10. CreatePermission . . . . . . . . . . . . . . . . . . . . . . 40 95 10.1. Forming a CreatePermission Request . . . . . . . . . . . 40 96 10.2. Receiving a CreatePermission Request . . . . . . . . . . 40 97 10.3. Receiving a CreatePermission Response . . . . . . . . . 41 98 11. Send and Data Methods . . . . . . . . . . . . . . . . . . . . 41 99 11.1. Forming a Send Indication . . . . . . . . . . . . . . . 41 100 11.2. Receiving a Send Indication . . . . . . . . . . . . . . 42 101 11.3. Receiving a UDP Datagram . . . . . . . . . . . . . . . . 42 102 11.4. Receiving a Data Indication . . . . . . . . . . . . . . 43 103 11.5. Receiving an ICMP Packet . . . . . . . . . . . . . . . . 43 104 11.6. Receiving a Data Indication with an ICMP attribute . . . 44 105 12. Channels . . . . . . . . . . . . . . . . . . . . . . . . . . 45 106 12.1. Sending a ChannelBind Request . . . . . . . . . . . . . 47 107 12.2. Receiving a ChannelBind Request . . . . . . . . . . . . 48 108 12.3. Receiving a ChannelBind Response . . . . . . . . . . . . 49 109 12.4. The ChannelData Message . . . . . . . . . . . . . . . . 49 110 12.5. Sending a ChannelData Message . . . . . . . . . . . . . 50 111 12.6. Receiving a ChannelData Message . . . . . . . . . . . . 50 112 12.7. Relaying Data from the Peer . . . . . . . . . . . . . . 51 113 13. Packet Translations . . . . . . . . . . . . . . . . . . . . . 51 114 13.1. IPv4-to-IPv6 Translations . . . . . . . . . . . . . . . 52 115 13.2. IPv6-to-IPv6 Translations . . . . . . . . . . . . . . . 53 116 13.3. IPv6-to-IPv4 Translations . . . . . . . . . . . . . . . 55 117 14. UDP-to-UDP relay . . . . . . . . . . . . . . . . . . . . . . 55 118 15. TCP-to-UDP relay . . . . . . . . . . . . . . . . . . . . . . 57 119 16. UDP-to-TCP relay . . . . . . . . . . . . . . . . . . . . . . 59 120 17. STUN Methods . . . . . . . . . . . . . . . . . . . . . . . . 60 121 18. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 60 122 18.1. CHANNEL-NUMBER . . . . . . . . . . . . . . . . . . . . . 61 123 18.2. LIFETIME . . . . . . . . . . . . . . . . . . . . . . . . 61 124 18.3. XOR-PEER-ADDRESS . . . . . . . . . . . . . . . . . . . . 61 125 18.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 61 126 18.5. XOR-RELAYED-ADDRESS . . . . . . . . . . . . . . . . . . 62 127 18.6. REQUESTED-ADDRESS-FAMILY . . . . . . . . . . . . . . . . 62 128 18.7. EVEN-PORT . . . . . . . . . . . . . . . . . . . . . . . 62 129 18.8. REQUESTED-TRANSPORT . . . . . . . . . . . . . . . . . . 63 130 18.9. DONT-FRAGMENT . . . . . . . . . . . . . . . . . . . . . 63 131 18.10. RESERVATION-TOKEN . . . . . . . . . . . . . . . . . . . 63 132 18.11. ADDITIONAL-ADDRESS-FAMILY . . . . . . . . . . . . . . . 64 133 18.12. ADDRESS-ERROR-CODE . . . . . . . . . . . . . . . . . . . 64 134 18.13. ICMP . . . . . . . . . . . . . . . . . . . . . . . . . . 65 135 19. STUN Error Response Codes . . . . . . . . . . . . . . . . . . 65 136 20. Detailed Example . . . . . . . . . . . . . . . . . . . . . . 66 137 21. Security Considerations . . . . . . . . . . . . . . . . . . . 74 138 21.1. Outsider Attacks . . . . . . . . . . . . . . . . . . . . 74 139 21.1.1. Obtaining Unauthorized Allocations . . . . . . . . . 74 140 21.1.2. Offline Dictionary Attacks . . . . . . . . . . . . . 74 141 21.1.3. Faked Refreshes and Permissions . . . . . . . . . . 75 142 21.1.4. Fake Data . . . . . . . . . . . . . . . . . . . . . 75 143 21.1.5. Impersonating a Server . . . . . . . . . . . . . . . 76 144 21.1.6. Eavesdropping Traffic . . . . . . . . . . . . . . . 76 145 21.1.7. TURN Loop Attack . . . . . . . . . . . . . . . . . . 77 146 21.2. Firewall Considerations . . . . . . . . . . . . . . . . 78 147 21.2.1. Faked Permissions . . . . . . . . . . . . . . . . . 79 148 21.2.2. Blacklisted IP Addresses . . . . . . . . . . . . . . 79 149 21.2.3. Running Servers on Well-Known Ports . . . . . . . . 79 150 21.3. Insider Attacks . . . . . . . . . . . . . . . . . . . . 79 151 21.3.1. DoS against TURN Server . . . . . . . . . . . . . . 80 152 21.3.2. Anonymous Relaying of Malicious Traffic . . . . . . 80 153 21.3.3. Manipulating Other Allocations . . . . . . . . . . . 80 154 21.4. Tunnel Amplification Attack . . . . . . . . . . . . . . 80 155 21.5. Other Considerations . . . . . . . . . . . . . . . . . . 82 156 22. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 82 157 23. IAB Considerations . . . . . . . . . . . . . . . . . . . . . 83 158 24. Changes since RFC 5766 . . . . . . . . . . . . . . . . . . . 84 159 25. Updates to RFC 6156 . . . . . . . . . . . . . . . . . . . . . 85 160 26. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85 161 27. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 162 27.1. Normative References . . . . . . . . . . . . . . . . . . 85 163 27.2. Informative References . . . . . . . . . . . . . . . . . 87 164 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 92 166 1. Introduction 168 A host behind a NAT may wish to exchange packets with other hosts, 169 some of which may also be behind NATs. To do this, the hosts 170 involved can use "hole punching" techniques (see [RFC5128]) in an 171 attempt discover a direct communication path; that is, a 172 communication path that goes from one host to another through 173 intervening NATs and routers, but does not traverse any relays. 175 As described in [RFC5128] and [RFC4787], hole punching techniques 176 will fail if both hosts are behind NATs that are not well behaved. 177 For example, if both hosts are behind NATs that have a mapping 178 behavior of "address-dependent mapping" or "address- and port- 179 dependent mapping" (Section 4.1 in [RFC4787]), then hole punching 180 techniques generally fail. 182 When a direct communication path cannot be found, it is necessary to 183 use the services of an intermediate host that acts as a relay for the 184 packets. This relay typically sits in the public Internet and relays 185 packets between two hosts that both sit behind NATs. 187 In many enterprise networks, direct UDP transmissions are not 188 permitted between clients on the internal networks and external IP 189 addresses. To permit media sessions in such a situation to use UDP 190 and to avoid forcing the media sessions through TCP, an Enterprise 191 Firewall can be configured to allow UDP traffic relayed through an 192 Enterprise relay server. This scenario is required to be supported 193 by the WebRTC requirements (Section 2.3.5.1 in [RFC7478]). In 194 addition, in a SIP or WebRTC call, if the user wants IP location 195 privacy from the peer then the client can select a relay server 196 offering IP location privacy and only convey the relayed candidates 197 to the peer for ICE connectivity checks (see Section 4.2.4 in 198 [I-D.ietf-rtcweb-security]). 200 This specification defines a protocol, called TURN, that allows a 201 host behind a NAT (called the TURN client) to request that another 202 host (called the TURN server) act as a relay. The client can arrange 203 for the server to relay packets to and from certain other hosts 204 (called peers) and can control aspects of how the relaying is done. 205 The client does this by obtaining an IP address and port on the 206 server, called the relayed transport address. When a peer sends a 207 packet to the relayed transport address, the server relays the 208 transport protocol data from the packet to the client. The client 209 knows the peer from which the transport protocol data was relayed by 210 the server. If the server receives an ICMP error packet, the server 211 also relays certain layer 3/4 header fields from the ICMP header to 212 the client. When the client sends a packet to the server, the server 213 relays the transport protocol data from the packet to the intended 214 peer using the relayed transport address as the source. 216 A client using TURN must have some way to communicate the relayed 217 transport address to its peers, and to learn each peer's IP address 218 and port (more precisely, each peer's server-reflexive transport 219 address, see Section 3). How this is done is out of the scope of the 220 TURN protocol. One way this might be done is for the client and 221 peers to exchange email messages. Another way is for the client and 222 its peers to use a special-purpose "introduction" or "rendezvous" 223 protocol (see [RFC5128] for more details). 225 If TURN is used with ICE [RFC8445], then the relayed transport 226 address and the IP addresses and ports of the peers are included in 227 the ICE candidate information that the rendezvous protocol must 228 carry. For example, if TURN and ICE are used as part of a multimedia 229 solution using SIP [RFC3261], then SIP serves the role of the 230 rendezvous protocol, carrying the ICE candidate information inside 231 the body of SIP messages [I-D.ietf-mmusic-ice-sip-sdp]. If TURN and 232 ICE are used with some other rendezvous protocol, then ICE provides 233 guidance on the services the rendezvous protocol must perform. 235 Though the use of a TURN server to enable communication between two 236 hosts behind NATs is very likely to work, it comes at a high cost to 237 the provider of the TURN server, since the server typically needs a 238 high-bandwidth connection to the Internet. As a consequence, it is 239 best to use a TURN server only when a direct communication path 240 cannot be found. When the client and a peer use ICE to determine the 241 communication path, ICE will use hole punching techniques to search 242 for a direct path first and only use a TURN server when a direct path 243 cannot be found. 245 TURN was originally invented to support multimedia sessions signaled 246 using SIP. Since SIP supports forking, TURN supports multiple peers 247 per relayed transport address; a feature not supported by other 248 approaches (e.g., SOCKS [RFC1928]). However, care has been taken to 249 make sure that TURN is suitable for other types of applications. 251 TURN was designed as one piece in the larger ICE approach to NAT 252 traversal. Implementors of TURN are urged to investigate ICE and 253 seriously consider using it for their application. However, it is 254 possible to use TURN without ICE. 256 TURN is an extension to the STUN (Session Traversal Utilities for 257 NAT) protocol [I-D.ietf-tram-stunbis]. Most, though not all, TURN 258 messages are STUN-formatted messages. A reader of this document 259 should be familiar with STUN. 261 The TURN specification was originally published as [RFC5766], which 262 was updated by [RFC6156] to add IPv6 support. This document 263 supersedes and obsoletes both [RFC5766] and [RFC6156]. 265 2. Terminology 267 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 268 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 269 "OPTIONAL" in this document are to be interpreted as described in BCP 270 14 [RFC2119][RFC8174] when, and only when, they appear in all 271 capitals, as shown here. 273 Readers are expected to be familiar with [I-D.ietf-tram-stunbis] and 274 the terms defined there. 276 The following terms are used in this document: 278 TURN: The protocol spoken between a TURN client and a TURN server. 279 It is an extension to the STUN protocol [I-D.ietf-tram-stunbis]. 280 The protocol allows a client to allocate and use a relayed 281 transport address. 283 TURN client: A STUN client that implements this specification. 285 TURN server: A STUN server that implements this specification. It 286 relays data between a TURN client and its peer(s). 288 Peer: A host with which the TURN client wishes to communicate. The 289 TURN server relays traffic between the TURN client and its 290 peer(s). The peer does not interact with the TURN server using 291 the protocol defined in this document; rather, the peer receives 292 data sent by the TURN server and the peer sends data towards the 293 TURN server. 295 Transport Address: The combination of an IP address and a port. 297 Host Transport Address: A transport address on a client or a peer. 299 Server-Reflexive Transport Address: A transport address on the 300 "external side" of a NAT. This address is allocated by the NAT to 301 correspond to a specific host transport address. 303 Relayed Transport Address: A transport address on the TURN server 304 that is used for relaying packets between the client and a peer. 305 A peer sends to this address on the TURN server, and the packet is 306 then relayed to the client. 308 TURN Server Transport Address: A transport address on the TURN 309 server that is used for sending TURN messages to the server. This 310 is the transport address that the client uses to communicate with 311 the server. 313 Peer Transport Address: The transport address of the peer as seen by 314 the server. When the peer is behind a NAT, this is the peer's 315 server-reflexive transport address. 317 Allocation: The relayed transport address granted to a client 318 through an Allocate request, along with related state, such as 319 permissions and expiration timers. 321 5-tuple: The combination (client IP address and port, server IP 322 address and port, and transport protocol (currently one of UDP, 323 TCP, DTLS/UDP or TLS/TCP) used to communicate between the client 324 and the server. The 5-tuple uniquely identifies this 325 communication stream. The 5-tuple also uniquely identifies the 326 Allocation on the server. 328 Transport Protocol: The protocols above IP that carries TURN 329 Requests, Responses, and Indications as well as providing 330 identifiable flows using a 5-tuple. In this specification, UDP 331 and TCP are defined as transport protocols, as well as their 332 combination with a security layer using DTLS and TLS respectively. 334 Channel: A channel number and associated peer transport address. 335 Once a channel number is bound to a peer's transport address, the 336 client and server can use the more bandwidth-efficient ChannelData 337 message to exchange data. 339 Permission: The IP address and transport protocol (but not the port) 340 of a peer that is permitted to send traffic to the TURN server and 341 have that traffic relayed to the TURN client. The TURN server 342 will only forward traffic to its client from peers that match an 343 existing permission. 345 Realm: A string used to describe the server or a context within the 346 server. The realm tells the client which username and password 347 combination to use to authenticate requests. 349 Nonce: A string chosen at random by the server and included in the 350 server response. To prevent replay attacks, the server should 351 change the nonce regularly. 353 (D)TLS: This term is used for statements that apply to both 354 Transport Layer Security [RFC8446] and Datagram Transport Layer 355 Security [RFC6347]. 357 3. Overview of Operation 359 This section gives an overview of the operation of TURN. It is non- 360 normative. 362 In a typical configuration, a TURN client is connected to a private 363 network [RFC1918] and through one or more NATs to the public 364 Internet. On the public Internet is a TURN server. Elsewhere in the 365 Internet are one or more peers with which the TURN client wishes to 366 communicate. These peers may or may not be behind one or more NATs. 367 The client uses the server as a relay to send packets to these peers 368 and to receive packets from these peers. 370 Peer A 371 Server-Reflexive +---------+ 372 Transport Address | | 373 192.0.2.150:32102 | | 374 | /| | 375 TURN | / ^| Peer A | 376 Client's Server | / || | 377 Host Transport Transport | // || | 378 Address Address | // |+---------+ 379 198.51.100.2:49721 192.0.2.15:3478 |+-+ // Peer A 380 | | ||N| / Host Transport 381 | +-+ | ||A|/ Address 382 | | | | v|T| 203.0.113.2:49582 383 | | | | /+-+ 384 +---------+| | | |+---------+ / +---------+ 385 | || |N| || | // | | 386 | TURN |v | | v| TURN |/ | | 387 | Client |----|A|----------| Server |------------------| Peer B | 388 | | | |^ | |^ ^| | 389 | | |T|| | || || | 390 +---------+ | || +---------+| |+---------+ 391 | || | | 392 | || | | 393 +-+| | | 394 | | | 395 | | | 396 Client's | Peer B 397 Server-Reflexive Relayed Transport 398 Transport Address Transport Address Address 399 192.0.2.1:7000 192.0.2.15:50000 192.0.2.210:49191 401 Figure 1 403 Figure 1 shows a typical deployment. In this figure, the TURN client 404 and the TURN server are separated by a NAT, with the client on the 405 private side and the server on the public side of the NAT. This NAT 406 is assumed to be a "bad" NAT; for example, it might have a mapping 407 property of "address-and-port-dependent mapping" (see [RFC4787]). 409 The client talks to the server from a (IP address, port) combination 410 called the client's HOST TRANSPORT ADDRESS. (The combination of an 411 IP address and port is called a TRANSPORT ADDRESS.) 413 The client sends TURN messages from its host transport address to a 414 transport address on the TURN server that is known as the TURN SERVER 415 TRANSPORT ADDRESS. The client learns the TURN server transport 416 address through some unspecified means (e.g., configuration), and 417 this address is typically used by many clients simultaneously. 419 Since the client is behind a NAT, the server sees packets from the 420 client as coming from a transport address on the NAT itself. This 421 address is known as the client's SERVER-REFLEXIVE transport address; 422 packets sent by the server to the client's server-reflexive transport 423 address will be forwarded by the NAT to the client's host transport 424 address. 426 The client uses TURN commands to create and manipulate an ALLOCATION 427 on the server. An allocation is a data structure on the server. 428 This data structure contains, amongst other things, the RELAYED 429 TRANSPORT ADDRESS for the allocation. The relayed transport address 430 is the transport address on the server that peers can use to have the 431 server relay data to the client. An allocation is uniquely 432 identified by its relayed transport address. 434 Once an allocation is created, the client can send application data 435 to the server along with an indication of to which peer the data is 436 to be sent, and the server will relay this data to the intended peer. 437 The client sends the application data to the server inside a TURN 438 message; at the server, the data is extracted from the TURN message 439 and sent to the peer in a UDP datagram. In the reverse direction, a 440 peer can send application data in a UDP datagram to the relayed 441 transport address for the allocation; the server will then 442 encapsulate this data inside a TURN message and send it to the client 443 along with an indication of which peer sent the data. Since the TURN 444 message always contains an indication of which peer the client is 445 communicating with, the client can use a single allocation to 446 communicate with multiple peers. 448 When the peer is behind a NAT, then the client must identify the peer 449 using its server-reflexive transport address rather than its host 450 transport address. For example, to send application data to Peer A 451 in the example above, the client must specify 192.0.2.150:32102 (Peer 452 A's server-reflexive transport address) rather than 203.0.113.2:49582 453 (Peer A's host transport address). 455 Each allocation on the server belongs to a single client and has 456 exactly one or two relayed transport addresses that is used only by 457 that allocation. Thus, when a packet arrives at a relayed transport 458 address on the server, the server knows for which client the data is 459 intended. 461 The client may have multiple allocations on a server at the same 462 time. 464 3.1. Transports 466 TURN, as defined in this specification, always uses UDP between the 467 server and the peer. However, this specification allows the use of 468 any one of UDP, TCP, Transport Layer Security (TLS) over TCP or 469 Datagram Transport Layer Security (DTLS) over UDP to carry the TURN 470 messages between the client and the server. 472 +----------------------------+---------------------+ 473 | TURN client to TURN server | TURN server to peer | 474 +----------------------------+---------------------+ 475 | UDP | UDP | 476 | TCP | UDP | 477 | TLS-over-TCP | UDP | 478 | DTLS-over-UDP | UDP | 479 +----------------------------+---------------------+ 481 If TCP or TLS-over-TCP is used between the client and the server, 482 then the server will convert between these transports and UDP 483 transport when relaying data to/from the peer. 485 Since this version of TURN only supports UDP between the server and 486 the peer, it is expected that most clients will prefer to use UDP 487 between the client and the server as well. That being the case, some 488 readers may wonder: Why also support TCP and TLS-over-TCP? 490 TURN supports TCP transport between the client and the server because 491 some firewalls are configured to block UDP entirely. These firewalls 492 block UDP but not TCP, in part because TCP has properties that make 493 the intention of the nodes being protected by the firewall more 494 obvious to the firewall. For example, TCP has a three-way handshake 495 that makes in clearer that the protected node really wishes to have 496 that particular connection established, while for UDP the best the 497 firewall can do is guess which flows are desired by using filtering 498 rules. Also, TCP has explicit connection teardown; while for UDP, 499 the firewall has to use timers to guess when the flow is finished. 501 TURN supports TLS-over-TCP transport and DTLS-over-UDP transport 502 between the client and the server because (D)TLS provides additional 503 security properties not provided by TURN's default digest 504 authentication; properties that some clients may wish to take 505 advantage of. In particular, (D)TLS provides a way for the client to 506 ascertain that it is talking to the correct server, and provides for 507 confidentiality of TURN control messages. If (D)TLS transport is 508 used between the TURN client and the TURN server, the cipher suites, 509 server certificate validation and authentication of TURN server are 510 discussed in Section 6.2.3 of [I-D.ietf-tram-stunbis]. The guidance 511 given in [RFC7525] MUST be followed to avoid attacks on (D)TLS. TURN 512 does not require (D)TLS because the overhead of using (D)TLS is 513 higher than that of digest authentication; for example, using (D)TLS 514 likely means that most application data will be doubly encrypted 515 (once by (D)TLS and once to ensure it is still encrypted in the UDP 516 datagram). 518 There is an extension to TURN for TCP transport between the server 519 and the peers [RFC6062]. For this reason, allocations that use UDP 520 between the server and the peers are known as UDP allocations, while 521 allocations that use TCP between the server and the peers are known 522 as TCP allocations. This specification describes only UDP 523 allocations. 525 In some applications for TURN, the client may send and receive 526 packets other than TURN packets on the host transport address it uses 527 to communicate with the server. This can happen, for example, when 528 using TURN with ICE. In these cases, the client can distinguish TURN 529 packets from other packets by examining the source address of the 530 arriving packet: those arriving from the TURN server will be TURN 531 packets. The algorithm of demultiplexing packets received from 532 multiple protocols on the host transport address is discussed in 533 [RFC7983]. 535 3.2. Allocations 537 To create an allocation on the server, the client uses an Allocate 538 transaction. The client sends an Allocate request to the server, and 539 the server replies with an Allocate success response containing the 540 allocated relayed transport address. The client can include 541 attributes in the Allocate request that describe the type of 542 allocation it desires (e.g., the lifetime of the allocation). Since 543 relaying data has security implications, the server requires that the 544 client authenticate itself, typically using STUN's long-term 545 credential mechanism or the STUN Extension for Third-Party 546 Authorization [RFC7635], to show that it is authorized to use the 547 server. 549 Once a relayed transport address is allocated, a client must keep the 550 allocation alive. To do this, the client periodically sends a 551 Refresh request to the server. TURN deliberately uses a different 552 method (Refresh rather than Allocate) for refreshes to ensure that 553 the client is informed if the allocation vanishes for some reason. 555 The frequency of the Refresh transaction is determined by the 556 lifetime of the allocation. The default lifetime of an allocation is 557 10 minutes -- this value was chosen to be long enough so that 558 refreshing is not typically a burden on the client, while expiring 559 allocations where the client has unexpectedly quit in a timely 560 manner. However, the client can request a longer lifetime in the 561 Allocate request and may modify its request in a Refresh request, and 562 the server always indicates the actual lifetime in the response. The 563 client must issue a new Refresh transaction within "lifetime" seconds 564 of the previous Allocate or Refresh transaction. Once a client no 565 longer wishes to use an allocation, it should delete the allocation 566 using a Refresh request with a requested lifetime of 0. 568 Both the server and client keep track of a value known as the 569 5-TUPLE. At the client, the 5-tuple consists of the client's host 570 transport address, the server transport address, and the transport 571 protocol used by the client to communicate with the server. At the 572 server, the 5-tuple value is the same except that the client's host 573 transport address is replaced by the client's server-reflexive 574 address, since that is the client's address as seen by the server. 576 Both the client and the server remember the 5-tuple used in the 577 Allocate request. Subsequent messages between the client and the 578 server use the same 5-tuple. In this way, the client and server know 579 which allocation is being referred to. If the client wishes to 580 allocate a second relayed transport address, it must create a second 581 allocation using a different 5-tuple (e.g., by using a different 582 client host address or port). 584 NOTE: While the terminology used in this document refers to 585 5-tuples, the TURN server can store whatever identifier it likes 586 that yields identical results. Specifically, an implementation 587 may use a file-descriptor in place of a 5-tuple to represent a TCP 588 connection. 590 TURN TURN Peer Peer 591 client server A B 592 |-- Allocate request --------------->| | | 593 | (invalid or missing credentials) | | | 594 | | | | 595 |<--------------- Allocate failure --| | | 596 | (401 Unauthenticated) | | | 597 | | | | 598 |-- Allocate request --------------->| | | 599 | (valid credentials) | | | 600 | | | | 601 |<---------- Allocate success resp --| | | 602 | (192.0.2.15:50000) | | | 603 // // // // 604 | | | | 605 |-- Refresh request ---------------->| | | 606 | | | | 607 |<----------- Refresh success resp --| | | 608 | | | | 610 Figure 2 612 In Figure 2, the client sends an Allocate request to the server with 613 invalid or missing credentials. Since the server requires that all 614 requests be authenticated using STUN's long-term credential 615 mechanism, the server rejects the request with a 401 (Unauthorized) 616 error code. The client then tries again, this time including 617 credentials. This time, the server accepts the Allocate request and 618 returns an Allocate success response containing (amongst other 619 things) the relayed transport address assigned to the allocation. 620 Sometime later, the client decides to refresh the allocation and thus 621 sends a Refresh request to the server. The refresh is accepted and 622 the server replies with a Refresh success response. 624 3.3. Permissions 626 To ease concerns amongst enterprise IT administrators that TURN could 627 be used to bypass corporate firewall security, TURN includes the 628 notion of permissions. TURN permissions mimic the address-restricted 629 filtering mechanism of NATs that comply with [RFC4787]. 631 An allocation can have zero or more permissions. Each permission 632 consists of an IP address and a lifetime. When the server receives a 633 UDP datagram on the allocation's relayed transport address, it first 634 checks the list of permissions. If the source IP address of the 635 datagram matches a permission, the application data is relayed to the 636 client, otherwise the UDP datagram is silently discarded. 638 A permission expires after 5 minutes if it is not refreshed, and 639 there is no way to explicitly delete a permission. This behavior was 640 selected to match the behavior of a NAT that complies with [RFC4787]. 642 The client can install or refresh a permission using either a 643 CreatePermission request or a ChannelBind request. Using the 644 CreatePermission request, multiple permissions can be installed or 645 refreshed with a single request -- this is important for applications 646 that use ICE. For security reasons, permissions can only be 647 installed or refreshed by transactions that can be authenticated; 648 thus, Send indications and ChannelData messages (which are used to 649 send data to peers) do not install or refresh any permissions. 651 Note that permissions are within the context of an allocation, so 652 adding or expiring a permission in one allocation does not affect 653 other allocations. 655 3.4. Send Mechanism 657 There are two mechanisms for the client and peers to exchange 658 application data using the TURN server. The first mechanism uses the 659 Send and Data methods, the second mechanism uses channels. Common to 660 both mechanisms is the ability of the client to communicate with 661 multiple peers using a single allocated relayed transport address; 662 thus, both mechanisms include a means for the client to indicate to 663 the server which peer should receive the data, and for the server to 664 indicate to the client which peer sent the data. 666 The Send mechanism uses Send and Data indications. Send indications 667 are used to send application data from the client to the server, 668 while Data indications are used to send application data from the 669 server to the client. 671 When using the Send mechanism, the client sends a Send indication to 672 the TURN server containing (a) an XOR-PEER-ADDRESS attribute 673 specifying the (server-reflexive) transport address of the peer and 674 (b) a DATA attribute holding the application data. When the TURN 675 server receives the Send indication, it extracts the application data 676 from the DATA attribute and sends it in a UDP datagram to the peer, 677 using the allocated relay address as the source address. Note that 678 there is no need to specify the relayed transport address, since it 679 is implied by the 5-tuple used for the Send indication. 681 In the reverse direction, UDP datagrams arriving at the relayed 682 transport address on the TURN server are converted into Data 683 indications and sent to the client, with the server-reflexive 684 transport address of the peer included in an XOR-PEER-ADDRESS 685 attribute and the data itself in a DATA attribute. Since the relayed 686 transport address uniquely identified the allocation, the server 687 knows which client should receive the data. 689 Some ICMP (Internet Control Message Protocol) packets arriving at the 690 relayed transport address on the TURN server may be converted into 691 Data indications and sent to the client, with the transport address 692 of the peer included in an XOR-PEER-ADDRESS attribute and the ICMP 693 type and code in a ICMP attribute. ICMP attribute forwarding always 694 uses Data indications containing the XOR-PEER-ADDRESS and ICMP 695 attributes, even when using the channel mechanism to forward UDP 696 data. 698 Send and Data indications cannot be authenticated, since the long- 699 term credential mechanism of STUN does not support authenticating 700 indications. This is not as big an issue as it might first appear, 701 since the client-to-server leg is only half of the total path to the 702 peer. Applications that want end-to-end security should encrypt the 703 data sent between the client and a peer. 705 Because Send indications are not authenticated, it is possible for an 706 attacker to send bogus Send indications to the server, which will 707 then relay these to a peer. To partly mitigate this attack, TURN 708 requires that the client install a permission towards a peer before 709 sending data to it using a Send indication. The technique to fully 710 mitigate the attack is discussed in Section 21.1.4. 712 TURN TURN Peer Peer 713 client server A B 714 | | | | 715 |-- CreatePermission req (Peer A) -->| | | 716 |<-- CreatePermission success resp --| | | 717 | | | | 718 |--- Send ind (Peer A)-------------->| | | 719 | |=== data ===>| | 720 | | | | 721 | |<== data ====| | 722 |<-------------- Data ind (Peer A) --| | | 723 | | | | 724 | | | | 725 |--- Send ind (Peer B)-------------->| | | 726 | | dropped | | 727 | | | | 728 | |<== data ==================| 729 | dropped | | | 730 | | | | 732 Figure 3 734 In Figure 3, the client has already created an allocation and now 735 wishes to send data to its peers. The client first creates a 736 permission by sending the server a CreatePermission request 737 specifying Peer A's (server-reflexive) IP address in the XOR-PEER- 738 ADDRESS attribute; if this was not done, the server would not relay 739 data between the client and the server. The client then sends data 740 to Peer A using a Send indication; at the server, the application 741 data is extracted and forwarded in a UDP datagram to Peer A, using 742 the relayed transport address as the source transport address. When 743 a UDP datagram from Peer A is received at the relayed transport 744 address, the contents are placed into a Data indication and forwarded 745 to the client. Later, the client attempts to exchange data with Peer 746 B; however, no permission has been installed for Peer B, so the Send 747 indication from the client and the UDP datagram from the peer are 748 both dropped by the server. 750 3.5. Channels 752 For some applications (e.g., Voice over IP), the 36 bytes of overhead 753 that a Send indication or Data indication adds to the application 754 data can substantially increase the bandwidth required between the 755 client and the server. To remedy this, TURN offers a second way for 756 the client and server to associate data with a specific peer. 758 This second way uses an alternate packet format known as the 759 ChannelData message. The ChannelData message does not use the STUN 760 header used by other TURN messages, but instead has a 4-byte header 761 that includes a number known as a channel number. Each channel 762 number in use is bound to a specific peer and thus serves as a 763 shorthand for the peer's host transport address. 765 To bind a channel to a peer, the client sends a ChannelBind request 766 to the server, and includes an unbound channel number and the 767 transport address of the peer. Once the channel is bound, the client 768 can use a ChannelData message to send the server data destined for 769 the peer. Similarly, the server can relay data from that peer 770 towards the client using a ChannelData message. 772 Channel bindings last for 10 minutes unless refreshed -- this 773 lifetime was chosen to be longer than the permission lifetime. 774 Channel bindings are refreshed by sending another ChannelBind request 775 rebinding the channel to the peer. Like permissions (but unlike 776 allocations), there is no way to explicitly delete a channel binding; 777 the client must simply wait for it to time out. 779 TURN TURN Peer Peer 780 client server A B 781 | | | | 782 |-- ChannelBind req ---------------->| | | 783 | (Peer A to 0x4001) | | | 784 | | | | 785 |<---------- ChannelBind succ resp --| | | 786 | | | | 787 |-- (0x4001) data ------------------>| | | 788 | |=== data ===>| | 789 | | | | 790 | |<== data ====| | 791 |<------------------ (0x4001) data --| | | 792 | | | | 793 |--- Send ind (Peer A)-------------->| | | 794 | |=== data ===>| | 795 | | | | 796 | |<== data ====| | 797 |<------------------ (0x4001) data --| | | 798 | | | | 800 Figure 4 802 Figure 4 shows the channel mechanism in use. The client has already 803 created an allocation and now wishes to bind a channel to Peer A. To 804 do this, the client sends a ChannelBind request to the server, 805 specifying the transport address of Peer A and a channel number 806 (0x4001). After that, the client can send application data 807 encapsulated inside ChannelData messages to Peer A: this is shown as 808 "(0x4001) data" where 0x4001 is the channel number. When the 809 ChannelData message arrives at the server, the server transfers the 810 data to a UDP datagram and sends it to Peer A (which is the peer 811 bound to channel number 0x4001). 813 In the reverse direction, when Peer A sends a UDP datagram to the 814 relayed transport address, this UDP datagram arrives at the server on 815 the relayed transport address assigned to the allocation. Since the 816 UDP datagram was received from Peer A, which has a channel number 817 assigned to it, the server encapsulates the data into a ChannelData 818 message when sending the data to the client. 820 Once a channel has been bound, the client is free to intermix 821 ChannelData messages and Send indications. In the figure, the client 822 later decides to use a Send indication rather than a ChannelData 823 message to send additional data to Peer A. The client might decide 824 to do this, for example, so it can use the DONT-FRAGMENT attribute 825 (see the next section). However, once a channel is bound, the server 826 will always use a ChannelData message, as shown in the call flow. 828 Note that ChannelData messages can only be used for peers to which 829 the client has bound a channel. In the example above, Peer A has 830 been bound to a channel, but Peer B has not, so application data to 831 and from Peer B would use the Send mechanism. 833 3.6. Unprivileged TURN Servers 835 This version of TURN is designed so that the server can be 836 implemented as an application that runs in user space under commonly 837 available operating systems without requiring special privileges. 838 This design decision was made to make it easy to deploy a TURN 839 server: for example, to allow a TURN server to be integrated into a 840 peer-to-peer application so that one peer can offer NAT traversal 841 services to another peer and to use (D)TLS to secure the TURN 842 connection. 844 This design decision has the following implications for data relayed 845 by a TURN server: 847 o The value of the Diffserv field may not be preserved across the 848 server; 850 o The Time to Live (TTL) field may be reset, rather than 851 decremented, across the server; 853 o The Explicit Congestion Notification (ECN) field may be reset by 854 the server; 856 o There is no end-to-end fragmentation, since the packet is re- 857 assembled at the server. 859 Future work may specify alternate TURN semantics that address these 860 limitations. 862 3.7. Avoiding IP Fragmentation 864 For reasons described in [Frag-Harmful], applications, especially 865 those sending large volumes of data, should avoid having their 866 packets fragmented. [I-D.ietf-intarea-frag-fragile] discusses issues 867 associated with IP fragmentation and proposes alternatives to IP 868 fragmentation. Applications using TCP can more or less ignore this 869 issue because fragmentation avoidance is now a standard part of TCP, 870 but applications using UDP (and thus any application using this 871 version of TURN) need to avoid IP fragmentation by sending 872 sufficiently small messages or use UDP fragmentation 873 [I-D.ietf-tsvwg-udp-options]. Note that the UDP fragmentation option 874 needs to be supported by both endpoints, and at the time of writing 875 of this document, UDP fragmentation support is under discussion and 876 is not deployed. 878 The application running on the client and the peer can take one of 879 two approaches to avoid IP fragmentation until UDP fragmentation 880 support is available. The first uses messages that are limited to a 881 predetermined fixed maximum and the second relies on network feedback 882 to adapt that maximum. 884 The first approach is to avoid sending large amounts of application 885 data in the TURN messages/UDP datagrams exchanged between the client 886 and the peer. This is the approach taken by most VoIP (Voice-over- 887 IP) applications. In this approach, the application MUST assume a 888 PMTU of 1280 bytes, as IPv6 requires that every link in the Internet 889 have an MTU of 1280 octets or greater as specified in [RFC8200]. If 890 IPv4 support on legacy or otherwise unusual networks is a 891 consideration, the application MAY assume on an effective MTU of 576 892 bytes for IPv4 datagrams, as every IPv4 host must be capable of 893 receiving a packet whose length is equal to 576 bytes as discussed in 894 [RFC0791] and [RFC1122]. 896 The exact amount of application data that can be included while 897 avoiding fragmentation depends on the details of the TURN session 898 between the client and the server: whether UDP, TCP, or (D)TLS 899 transport is used, whether ChannelData messages or Send/Data 900 indications are used, and whether any additional attributes (such as 901 the DONT-FRAGMENT attribute) are included. Another factor, which is 902 hard to determine, is whether the MTU is reduced somewhere along the 903 path for other reasons, such as the use of IP-in-IP tunneling. 905 As a guideline, sending a maximum of 500 bytes of application data in 906 a single TURN message (by the client on the client-to-server leg) or 907 a UDP datagram (by the peer on the peer-to-server leg) will generally 908 avoid IP fragmentation. To further reduce the chance of 909 fragmentation, it is recommended that the client use ChannelData 910 messages when transferring significant volumes of data, since the 911 overhead of the ChannelData message is less than Send and Data 912 indications. 914 The second approach the client and peer can take to avoid 915 fragmentation is to use a path MTU discovery algorithm to determine 916 the maximum amount of application data that can be sent without 917 fragmentation. The classic path MTU discovery algorithm defined in 918 [RFC1191] may not be able to discover the MTU of the transmission 919 path between the client and the peer since: 921 - a probe packet with DF bit in the IPv4 header set to test a path 922 for a larger MTU can be dropped by routers, or 923 - ICMP error messages can be dropped by middle boxes. 925 As a result, the client and server need to use a path MTU discovery 926 algorithm that does not require ICMP messages. The Packetized Path 927 MTU Discovery algorithm defined in [RFC4821] is one such algorithm. 929 [I-D.ietf-tram-stun-pmtud] is an implementation of [RFC4821] that 930 uses STUN to discover the path MTU, and so might be a suitable 931 approach to be used in conjunction with a TURN server that supports 932 the DONT-FRAGMENT attribute. When the client includes the DONT- 933 FRAGMENT attribute in a Send indication, this tells the server to set 934 the DF bit in the resulting UDP datagram that it sends to the peer. 935 Since some servers may be unable to set the DF bit, the client should 936 also include this attribute in the Allocate request -- any server 937 that does not support the DONT-FRAGMENT attribute will indicate this 938 by rejecting the Allocate request. If the TURN server carrying out 939 packet translation from IPv4-to-IPv6 is unable to access the state of 940 Don't Fragment (DF) bit in the IPv4 header, it MUST reject the 941 Allocate request with DONT-FRAGMENT attribute. 943 3.8. RTP Support 945 One of the envisioned uses of TURN is as a relay for clients and 946 peers wishing to exchange real-time data (e.g., voice or video) using 947 RTP. To facilitate the use of TURN for this purpose, TURN includes 948 some special support for older versions of RTP. 950 Old versions of RTP [RFC3550] required that the RTP stream be on an 951 even port number and the associated RTP Control Protocol (RTCP) 952 stream, if present, be on the next highest port. To allow clients to 953 work with peers that still require this, TURN allows the client to 954 request that the server allocate a relayed transport address with an 955 even port number, and to optionally request the server reserve the 956 next-highest port number for a subsequent allocation. 958 3.9. Happy Eyeballs for TURN 960 If an IPv4 path to reach a TURN server is found, but the TURN 961 server's IPv6 path is not working, a dual-stack TURN client can 962 experience a significant connection delay compared to an IPv4-only 963 TURN client. To overcome these connection setup problems, the TURN 964 client needs to query both A and AAAA records for the TURN server 965 specified using a domain name and try connecting to the TURN server 966 using both IPv6 and IPv4 addresses in a fashion similar to the Happy 967 Eyeballs mechanism defined in [RFC8305]. The TURN client performs 968 the following steps based on the transport protocol being used to 969 connect to the TURN server. 971 o For TCP or TLS-over-TCP, the results of the Happy Eyeballs 972 procedure [RFC8305] are used by the TURN client for sending its 973 TURN messages to the server. 975 o For clear text UDP, send TURN Allocate requests to both IP address 976 families as discussed in [RFC8305], without authentication 977 information. If the TURN server requires authentication, it will 978 send back a 401 unauthenticated response and the TURN client uses 979 the first UDP connection on which a 401 error response is 980 received. If a 401 error response is received from both IP 981 address families then the TURN client can silently abandon the UDP 982 connection on the IP address family with lower precedence. If the 983 TURN server does not require authentication (as described in 984 Section 9 of [RFC8155]), it is possible for both Allocate requests 985 to succeed. In this case, the TURN client sends a Refresh with 986 LIFETIME value of 0 on the allocation using the IP address family 987 with lower precedence to delete the allocation. 989 o For DTLS over UDP, initiate DTLS handshake to both IP address 990 families as discussed in [RFC8305] and use the first DTLS session 991 that is established. If the DTLS session is established on both 992 IP address families then the client sends DTLS close_notify alert 993 to terminate the DTLS session using the IP address family with 994 lower precedence. If TURN over DTLS server has been configured to 995 require a cookie exchange (Section 4.2 in [RFC6347]) and 996 HelloVerifyRequest is received from the TURN servers on both IP 997 address families then the client can silently abandon the 998 connection on the IP address family with lower precedence. 1000 4. Discovery of TURN server 1002 Methods of TURN server discovery, including using anycast, are 1003 described in [RFC8155]. If a host with multiple interfaces discovers 1004 a TURN server in each interface, the mechanism described in [RFC7982] 1005 can be used by the TURN client to influence the TURN server 1006 selection. The syntax of the "turn" and "turns" URIs are defined in 1007 Section 3.1 of [RFC7065]. DTLS as a transport protocol for TURN is 1008 defined in [RFC7350]. 1010 4.1. TURN URI Scheme Semantics 1012 The "turn" and "turns" URI schemes are used to designate a TURN 1013 server (also known as a relay) on Internet hosts accessible using the 1014 TURN protocol. The TURN protocol supports sending messages over UDP, 1015 TCP, TLS-over-TCP or DTLS-over-UDP. The "turns" URI scheme MUST be 1016 used when TURN is run over TLS-over-TCP or in DTLS-over-UDP, and the 1017 "turn" scheme MUST be used otherwise. The required part of 1018 the "turn" URI denotes the TURN server host. The part, if 1019 present, denotes the port on which the TURN server is awaiting 1020 connection requests. If it is absent, the default port is 3478 for 1021 both UDP and TCP. The default port for TURN over TLS and TURN over 1022 DTLS is 5349. 1024 5. General Behavior 1026 This section contains general TURN processing rules that apply to all 1027 TURN messages. 1029 TURN is an extension to STUN. All TURN messages, with the exception 1030 of the ChannelData message, are STUN-formatted messages. All the 1031 base processing rules described in [I-D.ietf-tram-stunbis] apply to 1032 STUN-formatted messages. This means that all the message-forming and 1033 message-processing descriptions in this document are implicitly 1034 prefixed with the rules of [I-D.ietf-tram-stunbis]. 1036 [I-D.ietf-tram-stunbis] specifies an authentication mechanism called 1037 the long-term credential mechanism. TURN servers and clients MUST 1038 implement this mechanism, and the authentication options are 1039 discussed in Section 7.2. 1041 Note that the long-term credential mechanism applies only to requests 1042 and cannot be used to authenticate indications; thus, indications in 1043 TURN are never authenticated. If the server requires requests to be 1044 authenticated, then the server's administrator MUST choose a realm 1045 value that will uniquely identify the username and password 1046 combination that the client must use, even if the client uses 1047 multiple servers under different administrations. The server's 1048 administrator MAY choose to allocate a unique username to each 1049 client, or MAY choose to allocate the same username to more than one 1050 client (for example, to all clients from the same department or 1051 company). For each Allocate request, the server SHOULD generate a 1052 new random nonce when the allocation is first attempted following the 1053 randomness recommendations in [RFC4086] and SHOULD expire the nonce 1054 at least once every hour during the lifetime of the allocation. To 1055 indicate that the server supports [I-D.ietf-tram-stunbis], the server 1056 prepends the NONCE attribute value with the "nonce cookie" 1057 (Section 9.2 of [I-D.ietf-tram-stunbis]). 1059 All requests after the initial Allocate must use the same username as 1060 that used to create the allocation, to prevent attackers from 1061 hijacking the client's allocation. Specifically, if the server 1062 requires the use of the long-term credential mechanism, and if a non- 1063 Allocate request passes authentication under this mechanism, and if 1064 the 5-tuple identifies an existing allocation, but the request does 1065 not use the same username as used to create the allocation, then the 1066 request MUST be rejected with a 441 (Wrong Credentials) error. 1068 When a TURN message arrives at the server from the client, the server 1069 uses the 5-tuple in the message to identify the associated 1070 allocation. For all TURN messages (including ChannelData) EXCEPT an 1071 Allocate request, if the 5-tuple does not identify an existing 1072 allocation, then the message MUST either be rejected with a 437 1073 Allocation Mismatch error (if it is a request) or silently ignored 1074 (if it is an indication or a ChannelData message). A client 1075 receiving a 437 error response to a request other than Allocate MUST 1076 assume the allocation no longer exists. 1078 [I-D.ietf-tram-stunbis] defines a number of attributes, including the 1079 SOFTWARE and FINGERPRINT attributes. The client SHOULD include the 1080 SOFTWARE attribute in all Allocate and Refresh requests and MAY 1081 include it in any other requests or indications. The server SHOULD 1082 include the SOFTWARE attribute in all Allocate and Refresh responses 1083 (either success or failure) and MAY include it in other responses or 1084 indications. The client and the server MAY include the FINGERPRINT 1085 attribute in any STUN-formatted messages defined in this document. 1087 TURN does not use the backwards-compatibility mechanism described in 1088 [I-D.ietf-tram-stunbis]. 1090 TURN, as defined in this specification, supports both IPv4 and IPv6. 1091 IPv6 support in TURN includes IPv4-to-IPv6, IPv6-to-IPv6, and IPv6- 1092 to-IPv4 relaying. When only a single address type is desired, the 1093 REQUESTED-ADDRESS-FAMILY attribute is used to explicitly request the 1094 address type the TURN server will allocate (e.g., an IPv4-only node 1095 may request the TURN server to allocate an IPv6 address). If both 1096 IPv4 and IPv6 are desired, the single ADDITIONAL-ADDRESS-FAMILY 1097 attribute indicates a request to the server to allocate one IPv4 and 1098 one IPv6 relay address in a single Allocate request. This saves 1099 local ports on the client and reduces the number of messages sent 1100 between the client and the TURN server. 1102 By default, TURN runs on the same ports as STUN: 3478 for TURN over 1103 UDP and TCP, and 5349 for TURN over (D)TLS. However, TURN has its 1104 own set of Service Record (SRV) names: "turn" for UDP and TCP, and 1105 "turns" for (D)TLS. Either the DNS resolution procedures or the 1106 ALTERNATE-SERVER procedures, both described in Section 7, can be used 1107 to run TURN on a different port. 1109 To ensure interoperability, a TURN server MUST support the use of UDP 1110 transport between the client and the server, and SHOULD support the 1111 use of TCP, TLS-over-TCP and DTLS-over-UDP transports. 1113 When UDP or DTLS-over-UDP transport is used between the client and 1114 the server, the client will retransmit a request if it does not 1115 receive a response within a certain timeout period. Because of this, 1116 the server may receive two (or more) requests with the same 5-tuple 1117 and same transaction id. STUN requires that the server recognize 1118 this case and treat the request as idempotent (see 1119 [I-D.ietf-tram-stunbis]). Some implementations may choose to meet 1120 this requirement by remembering all received requests and the 1121 corresponding responses for 40 seconds (Section 6.3.1 in 1122 [I-D.ietf-tram-stunbis]). Other implementations may choose to 1123 reprocess the request and arrange that such reprocessing returns 1124 essentially the same response. To aid implementors who choose the 1125 latter approach (the so-called "stateless stack approach"), this 1126 specification includes some implementation notes on how this might be 1127 done. Implementations are free to choose either approach or choose 1128 some other approach that gives the same results. 1130 To mitigate either intentional or unintentional denial-of-service 1131 attacks against the server by clients with valid usernames and 1132 passwords, it is RECOMMENDED that the server impose limits on both 1133 the number of allocations active at one time for a given username and 1134 on the amount of bandwidth those allocations can use. The server 1135 should reject new allocations that would exceed the limit on the 1136 allowed number of allocations active at one time with a 486 1137 (Allocation Quota Exceeded) (see Section 7.2), and since UDP does not 1138 include a congestion control mechanism, it should discard application 1139 data traffic that exceeds the bandwidth quota. 1141 6. Allocations 1143 All TURN operations revolve around allocations, and all TURN messages 1144 are associated with either a single or dual allocation. An 1145 allocation conceptually consists of the following state data: 1147 o the relayed transport address or addresses; 1149 o the 5-tuple: (client's IP address, client's port, server IP 1150 address, server port, transport protocol); 1152 o the authentication information; 1154 o the time-to-expiry for each relayed transport address; 1156 o a list of permissions for each relayed transport address; 1158 o a list of channel to peer bindings for each relayed transport 1159 address. 1161 The relayed transport address is the transport address allocated by 1162 the server for communicating with peers, while the 5-tuple describes 1163 the communication path between the client and the server. On the 1164 client, the 5-tuple uses the client's host transport address; on the 1165 server, the 5-tuple uses the client's server-reflexive transport 1166 address. The relayed transport address MUST be unique across all 1167 allocations so it can be used to uniquely identify the allocation, 1168 and an allocation in this context can be either a single or dual 1169 allocation. 1171 The authentication information (e.g., username, password, realm, and 1172 nonce) is used to both verify subsequent requests and to compute the 1173 message integrity of responses. The username, realm, and nonce 1174 values are initially those used in the authenticated Allocate request 1175 that creates the allocation, though the server can change the nonce 1176 value during the lifetime of the allocation using a 438 (Stale Nonce) 1177 reply. For security reasons, the server MUST NOT store the password 1178 explicitly and MUST store the key value, which is a cryptographic 1179 hash over the username, realm, and password (see Section 16.1.3 in 1180 [I-D.ietf-tram-stunbis]). 1182 Note that if the response contains a PASSWORD-ALGORITHMS attribute 1183 and this attribute contains both MD5 and SHA-256 algorithms, and the 1184 client also supports both the algorithms, the request MUST contain a 1185 PASSWORD-ALGORITHM attribute with the SHA-256 algorithm. 1187 The time-to-expiry is the time in seconds left until the allocation 1188 expires. Each Allocate or Refresh transaction sets this timer, which 1189 then ticks down towards 0. By default, each Allocate or Refresh 1190 transaction resets this timer to the default lifetime value of 600 1191 seconds (10 minutes), but the client can request a different value in 1192 the Allocate and Refresh request. Allocations can only be refreshed 1193 using the Refresh request; sending data to a peer does not refresh an 1194 allocation. When an allocation expires, the state data associated 1195 with the allocation can be freed. 1197 The list of permissions is described in Section 9 and the list of 1198 channels is described in Section 12. 1200 7. Creating an Allocation 1202 An allocation on the server is created using an Allocate transaction. 1204 7.1. Sending an Allocate Request 1206 The client forms an Allocate request as follows. 1208 The client first picks a host transport address. It is RECOMMENDED 1209 that the client picks a currently unused transport address, typically 1210 by allowing the underlying OS to pick a currently unused port. 1212 The client then picks a transport protocol that the client supports 1213 to use between the client and the server based on the transport 1214 protocols supported by the server. Since this specification only 1215 allows UDP between the server and the peers, it is RECOMMENDED that 1216 the client pick UDP unless it has a reason to use a different 1217 transport. One reason to pick a different transport would be that 1218 the client believes, either through configuration or discovery or by 1219 experiment, that it is unable to contact any TURN server using UDP. 1220 See Section 3.1 for more discussion. 1222 The client also picks a server transport address, which SHOULD be 1223 done as follows. The client uses one or more procedures described in 1224 [RFC8155] to discover a TURN server and uses the TURN server 1225 resolution mechanism defined in [RFC5928] and [RFC7350] to get a list 1226 of server transport addresses that can be tried to create a TURN 1227 allocation. 1229 The client MUST include a REQUESTED-TRANSPORT attribute in the 1230 request. This attribute specifies the transport protocol between the 1231 server and the peers (note that this is NOT the transport protocol 1232 that appears in the 5-tuple). In this specification, the REQUESTED- 1233 TRANSPORT type is always UDP. This attribute is included to allow 1234 future extensions to specify other protocols. 1236 If the client wishes to obtain a relayed transport address of a 1237 specific address type then it includes a REQUESTED-ADDRESS-FAMILY 1238 attribute in the request. This attribute indicates the specific 1239 address type the client wishes the TURN server to allocate. Clients 1240 MUST NOT include more than one REQUESTED-ADDRESS-FAMILY attribute in 1241 an Allocate request. Clients MUST NOT include a REQUESTED-ADDRESS- 1242 FAMILY attribute in an Allocate request that contains a RESERVATION- 1243 TOKEN attribute, for the reason that the server uses the previously 1244 reserved transport address corresponding to the included token and 1245 the client cannot obtain a relayed transport address of a specific 1246 address type. 1248 If the client wishes to obtain one IPv6 and one IPv4 relayed 1249 transport address then it includes an ADDITIONAL-ADDRESS-FAMILY 1250 attribute in the request. This attribute specifies that the server 1251 must allocate both address types. The attribute value in the 1252 ADDITIONAL-ADDRESS-FAMILY MUST be set to 0x02 (IPv6 address family). 1253 Clients MUST NOT include REQUESTED-ADDRESS-FAMILY and ADDITIONAL- 1254 ADDRESS-FAMILY attributes in the same request. Clients MUST NOT 1255 include ADDITIONAL-ADDRESS-FAMILY attribute in a Allocate request 1256 that contains a RESERVATION-TOKEN attribute. Clients MUST NOT 1257 include ADDITIONAL-ADDRESS-FAMILY attribute in a Allocate request 1258 that contains an EVEN-PORT attribute with the R bit set to 1. The 1259 reason behind the restriction is if EVEN-PORT with R bit set to 1 is 1260 allowed with the ADDITIONAL-ADDRESS-FAMILY attribute, two tokens will 1261 have to be returned in success response and requires changes to the 1262 way RESERVATION-TOKEN is handled. 1264 If the client wishes the server to initialize the time-to-expiry 1265 field of the allocation to some value other than the default 1266 lifetime, then it MAY include a LIFETIME attribute specifying its 1267 desired value. This is just a hint, and the server may elect to use 1268 a different value. Note that the server will ignore requests to 1269 initialize the field to less than the default value. 1271 If the client wishes to later use the DONT-FRAGMENT attribute in one 1272 or more Send indications on this allocation, then the client SHOULD 1273 include the DONT-FRAGMENT attribute in the Allocate request. This 1274 allows the client to test whether this attribute is supported by the 1275 server. 1277 If the client requires the port number of the relayed transport 1278 address be even, the client includes the EVEN-PORT attribute. If 1279 this attribute is not included, then the port can be even or odd. By 1280 setting the R bit in the EVEN-PORT attribute to 1, the client can 1281 request that the server reserve the next highest port number (on the 1282 same IP address) for a subsequent allocation. If the R bit is 0, no 1283 such request is made. 1285 The client MAY also include a RESERVATION-TOKEN attribute in the 1286 request to ask the server to use a previously reserved port for the 1287 allocation. If the RESERVATION-TOKEN attribute is included, then the 1288 client MUST omit the EVEN-PORT attribute. 1290 Once constructed, the client sends the Allocate request on the 1291 5-tuple. 1293 7.2. Receiving an Allocate Request 1295 When the server receives an Allocate request, it performs the 1296 following checks: 1298 1. The TURN server provided by the local or access network MAY 1299 allow unauthenticated request in order to accept Allocation 1300 requests from new and/or guest users in the network who do not 1301 necessarily possess long term credentials for STUN 1302 authentication. Making STUN authentication optional and its 1303 security implications are discussed in [RFC8155]. Otherwise, 1304 the server MUST require that the request be authenticated. If 1305 the request is authenticated, the authentication MUST be done 1306 either using the long-term credential mechanism of 1307 [I-D.ietf-tram-stunbis] or the STUN Extension for Third-Party 1308 Authorization [RFC7635] unless the client and server agree to 1309 use another mechanism through some procedure outside the scope 1310 of this document. 1312 2. The server checks if the 5-tuple is currently in use by an 1313 existing allocation. If yes, the server rejects the request 1314 with a 437 (Allocation Mismatch) error. 1316 3. The server checks if the request contains a REQUESTED-TRANSPORT 1317 attribute. If the REQUESTED-TRANSPORT attribute is not included 1318 or is malformed, the server rejects the request with a 400 (Bad 1319 Request) error. Otherwise, if the attribute is included but 1320 specifies a protocol other than UDP that is not supported by the 1321 server, the server rejects the request with a 442 (Unsupported 1322 Transport Protocol) error. 1324 4. The request may contain a DONT-FRAGMENT attribute. If it does, 1325 but the server does not support sending UDP datagrams with the 1326 DF bit set to 1 (see Section 14 and Section 15), then the server 1327 treats the DONT-FRAGMENT attribute in the Allocate request as an 1328 unknown comprehension-required attribute. 1330 5. The server checks if the request contains a RESERVATION-TOKEN 1331 attribute. If yes, and the request also contains an EVEN-PORT 1332 or REQUESTED-ADDRESS-FAMILY or ADDITIONAL-ADDRESS-FAMILY 1333 attribute, the server rejects the request with a 400 (Bad 1334 Request) error. Otherwise, it checks to see if the token is 1335 valid (i.e., the token is in range and has not expired and the 1336 corresponding relayed transport address is still available). If 1337 the token is not valid for some reason, the server rejects the 1338 request with a 508 (Insufficient Capacity) error. 1340 6. The server checks if the request contains both REQUESTED- 1341 ADDRESS-FAMILY and ADDITIONAL-ADDRESS-FAMILY attributes. If 1342 yes, then the server rejects the request with a 400 (Bad 1343 Request) error. 1345 7. If the server does not support the address family requested by 1346 the client in REQUESTED-ADDRESS-FAMILY or if the allocation of 1347 the requested address family is disabled by local policy, it 1348 MUST generate an Allocate error response, and it MUST include an 1349 ERROR-CODE attribute with the 440 (Address Family not Supported) 1350 response code. If the REQUESTED-ADDRESS-FAMILY attribute is 1351 absent and the server does not support IPv4 address family, the 1352 server MUST include an ERROR-CODE attribute with the 440 1353 (Address Family not Supported) response code. If the REQUESTED- 1354 ADDRESS-FAMILY attribute is absent and the server supports IPv4 1355 address family, the server MUST allocate an IPv4 relayed 1356 transport address for the TURN client. 1358 8. The server checks if the request contains an EVEN-PORT attribute 1359 with the R bit set to 1. If yes, and the request also contains 1360 an ADDITIONAL-ADDRESS-FAMILY attribute, the server rejects the 1361 request with a 400 (Bad Request) error. Otherwise, the server 1362 checks if it can satisfy the request (i.e., can allocate a 1363 relayed transport address as described below). If the server 1364 cannot satisfy the request, then the server rejects the request 1365 with a 508 (Insufficient Capacity) error. 1367 9. The server checks if the request contains an ADDITIONAL-ADDRESS- 1368 FAMILY attribute. If yes, and the attribute value is 0x01 (IPv4 1369 address family), then the server rejects the request with a 400 1370 (Bad Request) error. Otherwise, the server checks if it can 1371 allocate relayed transport addresses of both address types. If 1372 the server cannot satisfy the request, then the server rejects 1373 the request with a 508 (Insufficient Capacity) error. If the 1374 server can partially meet the request, i.e. if it can only 1375 allocate one relayed transport address of a specific address 1376 type, then it includes ADDRESS-ERROR-CODE attribute in the 1377 success response to inform the client the reason for partial 1378 failure of the request. The error code value signaled in the 1379 ADDRESS-ERROR-CODE attribute could be 440 (Address Family not 1380 Supported) or 508 (Insufficient Capacity). If the server can 1381 fully meet the request, then the server allocates one IPv4 and 1382 one IPv6 relay address, and returns an Allocate success response 1383 containing the relayed transport addresses assigned to the dual 1384 allocation in two XOR-RELAYED-ADDRESS attributes. 1386 10. At any point, the server MAY choose to reject the request with a 1387 486 (Allocation Quota Reached) error if it feels the client is 1388 trying to exceed some locally defined allocation quota. The 1389 server is free to define this allocation quota any way it 1390 wishes, but SHOULD define it based on the username used to 1391 authenticate the request, and not on the client's transport 1392 address. 1394 11. Also at any point, the server MAY choose to reject the request 1395 with a 300 (Try Alternate) error if it wishes to redirect the 1396 client to a different server. The use of this error code and 1397 attribute follow the specification in [I-D.ietf-tram-stunbis]. 1399 If all the checks pass, the server creates the allocation. The 1400 5-tuple is set to the 5-tuple from the Allocate request, while the 1401 list of permissions and the list of channels are initially empty. 1403 The server chooses a relayed transport address for the allocation as 1404 follows: 1406 o If the request contains a RESERVATION-TOKEN attribute, the server 1407 uses the previously reserved transport address corresponding to 1408 the included token (if it is still available). Note that the 1409 reservation is a server-wide reservation and is not specific to a 1410 particular allocation, since the Allocate request containing the 1411 RESERVATION-TOKEN uses a different 5-tuple than the Allocate 1412 request that made the reservation. The 5-tuple for the Allocate 1413 request containing the RESERVATION-TOKEN attribute can be any 1414 allowed 5-tuple; it can use a different client IP address and 1415 port, a different transport protocol, and even different server IP 1416 address and port (provided, of course, that the server IP address 1417 and port are ones on which the server is listening for TURN 1418 requests). 1420 o If the request contains an EVEN-PORT attribute with the R bit set 1421 to 0, then the server allocates a relayed transport address with 1422 an even port number. 1424 o If the request contains an EVEN-PORT attribute with the R bit set 1425 to 1, then the server looks for a pair of port numbers N and N+1 1426 on the same IP address, where N is even. Port N is used in the 1427 current allocation, while the relayed transport address with port 1428 N+1 is assigned a token and reserved for a future allocation. The 1429 server MUST hold this reservation for at least 30 seconds, and MAY 1430 choose to hold longer (e.g., until the allocation with port N 1431 expires). The server then includes the token in a RESERVATION- 1432 TOKEN attribute in the success response. 1434 o Otherwise, the server allocates any available relayed transport 1435 address. 1437 In all cases, the server SHOULD only allocate ports from the range 1438 49152 - 65535 (the Dynamic and/or Private Port range [Port-Numbers]), 1439 unless the TURN server application knows, through some means not 1440 specified here, that other applications running on the same host as 1441 the TURN server application will not be impacted by allocating ports 1442 outside this range. This condition can often be satisfied by running 1443 the TURN server application on a dedicated machine and/or by 1444 arranging that any other applications on the machine allocate ports 1445 before the TURN server application starts. In any case, the TURN 1446 server SHOULD NOT allocate ports in the range 0 - 1023 (the Well- 1447 Known Port range) to discourage clients from using TURN to run 1448 standard services. 1450 NOTE: The use of randomized port assignments to avoid certain 1451 types of attacks is described in [RFC6056]. It is RECOMMENDED 1452 that a TURN server implement a randomized port assignment 1453 algorithm from [RFC6056]. This is especially applicable to 1454 servers that choose to pre-allocate a number of ports from the 1455 underlying OS and then later assign them to allocations; for 1456 example, a server may choose this technique to implement the EVEN- 1457 PORT attribute. 1459 The server determines the initial value of the time-to-expiry field 1460 as follows. If the request contains a LIFETIME attribute, then the 1461 server computes the minimum of the client's proposed lifetime and the 1462 server's maximum allowed lifetime. If this computed value is greater 1463 than the default lifetime, then the server uses the computed lifetime 1464 as the initial value of the time-to-expiry field. Otherwise, the 1465 server uses the default lifetime. It is RECOMMENDED that the server 1466 use a maximum allowed lifetime value of no more than 3600 seconds (1 1467 hour). Servers that implement allocation quotas or charge users for 1468 allocations in some way may wish to use a smaller maximum allowed 1469 lifetime (perhaps as small as the default lifetime) to more quickly 1470 remove orphaned allocations (that is, allocations where the 1471 corresponding client has crashed or terminated or the client 1472 connection has been lost for some reason). Also, note that the time- 1473 to-expiry is recomputed with each successful Refresh request, and 1474 thus the value computed here applies only until the first refresh. 1476 Once the allocation is created, the server replies with a success 1477 response. The success response contains: 1479 o An XOR-RELAYED-ADDRESS attribute containing the relayed transport 1480 address or two XOR-RELAYED-ADDRESS attributes containing the 1481 relayed transport addresses. 1483 o A LIFETIME attribute containing the current value of the time-to- 1484 expiry timer. 1486 o A RESERVATION-TOKEN attribute (if a second relayed transport 1487 address was reserved). 1489 o An XOR-MAPPED-ADDRESS attribute containing the client's IP address 1490 and port (from the 5-tuple). 1492 NOTE: The XOR-MAPPED-ADDRESS attribute is included in the response 1493 as a convenience to the client. TURN itself does not make use of 1494 this value, but clients running ICE can often need this value and 1495 can thus avoid having to do an extra Binding transaction with some 1496 STUN server to learn it. 1498 The response (either success or error) is sent back to the client on 1499 the 5-tuple. 1501 NOTE: When the Allocate request is sent over UDP, 1502 [I-D.ietf-tram-stunbis] requires that the server handle the 1503 possible retransmissions of the request so that retransmissions do 1504 not cause multiple allocations to be created. Implementations may 1505 achieve this using the so-called "stateless stack approach" as 1506 follows. To detect retransmissions when the original request was 1507 successful in creating an allocation, the server can store the 1508 transaction id that created the request with the allocation data 1509 and compare it with incoming Allocate requests on the same 1510 5-tuple. Once such a request is detected, the server can stop 1511 parsing the request and immediately generate a success response. 1512 When building this response, the value of the LIFETIME attribute 1513 can be taken from the time-to-expiry field in the allocate state 1514 data, even though this value may differ slightly from the LIFETIME 1515 value originally returned. In addition, the server may need to 1516 store an indication of any reservation token returned in the 1517 original response, so that this may be returned in any 1518 retransmitted responses. 1520 For the case where the original request was unsuccessful in 1521 creating an allocation, the server may choose to do nothing 1522 special. Note, however, that there is a rare case where the 1523 server rejects the original request but accepts the retransmitted 1524 request (because conditions have changed in the brief intervening 1525 time period). If the client receives the first failure response, 1526 it will ignore the second (success) response and believe that an 1527 allocation was not created. An allocation created in this matter 1528 will eventually timeout, since the client will not refresh it. 1529 Furthermore, if the client later retries with the same 5-tuple but 1530 different transaction id, it will receive a 437 (Allocation 1531 Mismatch), which will cause it to retry with a different 5-tuple. 1532 The server may use a smaller maximum lifetime value to minimize 1533 the lifetime of allocations "orphaned" in this manner. 1535 7.3. Receiving an Allocate Success Response 1537 If the client receives an Allocate success response, then it MUST 1538 check that the mapped address and the relayed transport address or 1539 addresses are part of an address family or families that the client 1540 understands and is prepared to handle. If these addresses are not 1541 part of an address family or families which the client is prepared to 1542 handle, then the client MUST delete the allocation (Section 8) and 1543 MUST NOT attempt to create another allocation on that server until it 1544 believes the mismatch has been fixed. 1546 Otherwise, the client creates its own copy of the allocation data 1547 structure to track what is happening on the server. In particular, 1548 the client needs to remember the actual lifetime received back from 1549 the server, rather than the value sent to the server in the request. 1550 The client must also remember the 5-tuple used for the request and 1551 the username and password it used to authenticate the request to 1552 ensure that it reuses them for subsequent messages. The client also 1553 needs to track the channels and permissions it establishes on the 1554 server. 1556 If the client receives an Allocate success response but with ADDRESS- 1557 ERROR-CODE attribute in the response and the error code value 1558 signaled in the ADDRESS-ERROR-CODE attribute is 440 (Address Family 1559 not Supported), the client MUST NOT retry its request for the 1560 rejected address type. If the client receives an ADDRESS-ERROR-CODE 1561 attribute in the response and the error code value signaled in the 1562 ADDRESS-ERROR-CODE attribute is 508 (Insufficient Capacity), the 1563 client SHOULD wait at least 1 minute before trying to request any 1564 more allocations on this server for the rejected address type. 1566 The client will probably wish to send the relayed transport address 1567 to peers (using some method not specified here) so the peers can 1568 communicate with it. The client may also wish to use the server- 1569 reflexive address it receives in the XOR-MAPPED-ADDRESS attribute in 1570 its ICE processing. 1572 7.4. Receiving an Allocate Error Response 1574 If the client receives an Allocate error response, then the 1575 processing depends on the actual error code returned: 1577 o (Request timed out): There is either a problem with the server, or 1578 a problem reaching the server with the chosen transport. The 1579 client considers the current transaction as having failed but MAY 1580 choose to retry the Allocate request using a different transport 1581 (e.g., TCP instead of UDP). 1583 o 300 (Try Alternate): The server would like the client to use the 1584 server specified in the ALTERNATE-SERVER attribute instead. The 1585 client considers the current transaction as having failed, but 1586 SHOULD try the Allocate request with the alternate server before 1587 trying any other servers (e.g., other servers discovered using the 1588 DNS resolution procedures). When trying the Allocate request with 1589 the alternate server, the client follows the ALTERNATE-SERVER 1590 procedures specified in [I-D.ietf-tram-stunbis]. 1592 o 400 (Bad Request): The server believes the client's request is 1593 malformed for some reason. The client considers the current 1594 transaction as having failed. The client MAY notify the user or 1595 operator and SHOULD NOT retry the request with this server until 1596 it believes the problem has been fixed. 1598 o 401 (Unauthorized): If the client has followed the procedures of 1599 the long-term credential mechanism and still gets this error, then 1600 the server is not accepting the client's credentials. In this 1601 case, the client considers the current transaction as having 1602 failed and SHOULD notify the user or operator. The client SHOULD 1603 NOT send any further requests to this server until it believes the 1604 problem has been fixed. 1606 o 403 (Forbidden): The request is valid, but the server is refusing 1607 to perform it, likely due to administrative restrictions. The 1608 client considers the current transaction as having failed. The 1609 client MAY notify the user or operator and SHOULD NOT retry the 1610 same request with this server until it believes the problem has 1611 been fixed. 1613 o 420 (Unknown Attribute): If the client included a DONT-FRAGMENT 1614 attribute in the request and the server rejected the request with 1615 a 420 error code and listed the DONT-FRAGMENT attribute in the 1616 UNKNOWN-ATTRIBUTES attribute in the error response, then the 1617 client now knows that the server does not support the DONT- 1618 FRAGMENT attribute. The client considers the current transaction 1619 as having failed but MAY choose to retry the Allocate request 1620 without the DONT-FRAGMENT attribute. 1622 o 437 (Allocation Mismatch): This indicates that the client has 1623 picked a 5-tuple that the server sees as already in use. One way 1624 this could happen is if an intervening NAT assigned a mapped 1625 transport address that was used by another client that recently 1626 crashed. The client considers the current transaction as having 1627 failed. The client SHOULD pick another client transport address 1628 and retry the Allocate request (using a different transaction id). 1629 The client SHOULD try three different client transport addresses 1630 before giving up on this server. Once the client gives up on the 1631 server, it SHOULD NOT try to create another allocation on the 1632 server for 2 minutes. 1634 o 438 (Stale Nonce): See the procedures for the long-term credential 1635 mechanism [I-D.ietf-tram-stunbis]. 1637 o 440 (Address Family not Supported): The server does not support 1638 the address family requested by the client. If the client 1639 receives an Allocate error response with the 440 (Unsupported 1640 Address Family) error code, the client MUST NOT retry the request. 1642 o 441 (Wrong Credentials): The client should not receive this error 1643 in response to a Allocate request. The client MAY notify the user 1644 or operator and SHOULD NOT retry the same request with this server 1645 until it believes the problem has been fixed. 1647 o 442 (Unsupported Transport Address): The client should not receive 1648 this error in response to a request for a UDP allocation. The 1649 client MAY notify the user or operator and SHOULD NOT reattempt 1650 the request with this server until it believes the problem has 1651 been fixed. 1653 o 486 (Allocation Quota Reached): The server is currently unable to 1654 create any more allocations with this username. The client 1655 considers the current transaction as having failed. The client 1656 SHOULD wait at least 1 minute before trying to create any more 1657 allocations on the server. 1659 o 508 (Insufficient Capacity): The server has no more relayed 1660 transport addresses available, or has none with the requested 1661 properties, or the one that was reserved is no longer available. 1662 The client considers the current operation as having failed. If 1663 the client is using either the EVEN-PORT or the RESERVATION-TOKEN 1664 attribute, then the client MAY choose to remove or modify this 1665 attribute and try again immediately. Otherwise, the client SHOULD 1666 wait at least 1 minute before trying to create any more 1667 allocations on this server. 1669 Note that the error code values 486 and 508 indicate to a 1670 eavesdropper that several other users are using the server at this 1671 time, similar to that of the HTTP error response code 503, but does 1672 not reveal any information about the users using the TURN server. 1674 An unknown error response MUST be handled as described in 1675 [I-D.ietf-tram-stunbis]. 1677 8. Refreshing an Allocation 1679 A Refresh transaction can be used to either (a) refresh an existing 1680 allocation and update its time-to-expiry or (b) delete an existing 1681 allocation. 1683 If a client wishes to continue using an allocation, then the client 1684 MUST refresh it before it expires. It is suggested that the client 1685 refresh the allocation roughly 1 minute before it expires. If a 1686 client no longer wishes to use an allocation, then it SHOULD 1687 explicitly delete the allocation. A client MAY refresh an allocation 1688 at any time for other reasons. 1690 8.1. Sending a Refresh Request 1692 If the client wishes to immediately delete an existing allocation, it 1693 includes a LIFETIME attribute with a value of 0. All other forms of 1694 the request refresh the allocation. 1696 When refreshing a dual allocation, the client includes REQUESTED- 1697 ADDRESS-FAMILY attribute indicating the address family type that 1698 should be refreshed. If no REQUESTED-ADDRESS-FAMILY is included then 1699 the request should be treated as applying to all current allocations. 1700 The client MUST only include the family type it previously allocated 1701 and has not yet deleted. This process can also be used to delete an 1702 allocation of a specific address type, by setting the lifetime of 1703 that refresh request to 0. Deleting a single allocation destroys any 1704 permissions or channels associated with that particular allocation; 1705 it MUST NOT affect any permissions or channels associated with 1706 allocations for the other address family. 1708 The Refresh transaction updates the time-to-expiry timer of an 1709 allocation. If the client wishes the server to set the time-to- 1710 expiry timer to something other than the default lifetime, it 1711 includes a LIFETIME attribute with the requested value. The server 1712 then computes a new time-to-expiry value in the same way as it does 1713 for an Allocate transaction, with the exception that a requested 1714 lifetime of 0 causes the server to immediately delete the allocation. 1716 8.2. Receiving a Refresh Request 1718 When the server receives a Refresh request, it processes the request 1719 as per Section 5 plus the specific rules mentioned here. 1721 If the server receives a Refresh Request with a REQUESTED-ADDRESS- 1722 FAMILY attribute and the attribute value does not match the address 1723 family of the allocation, the server MUST reply with a 443 (Peer 1724 Address Family Mismatch) Refresh error response. 1726 The server computes a value called the "desired lifetime" as follows: 1727 if the request contains a LIFETIME attribute and the attribute value 1728 is 0, then the "desired lifetime" is 0. Otherwise, if the request 1729 contains a LIFETIME attribute, then the server computes the minimum 1730 of the client's requested lifetime and the server's maximum allowed 1731 lifetime. If this computed value is greater than the default 1732 lifetime, then the "desired lifetime" is the computed value. 1733 Otherwise, the "desired lifetime" is the default lifetime. 1735 Subsequent processing depends on the "desired lifetime" value: 1737 o If the "desired lifetime" is 0, then the request succeeds and the 1738 allocation is deleted. 1740 o If the "desired lifetime" is non-zero, then the request succeeds 1741 and the allocation's time-to-expiry is set to the "desired 1742 lifetime". 1744 If the request succeeds, then the server sends a success response 1745 containing: 1747 o A LIFETIME attribute containing the current value of the time-to- 1748 expiry timer. 1750 NOTE: A server need not do anything special to implement 1751 idempotency of Refresh requests over UDP using the "stateless 1752 stack approach". Retransmitted Refresh requests with a non-zero 1753 "desired lifetime" will simply refresh the allocation. A 1754 retransmitted Refresh request with a zero "desired lifetime" will 1755 cause a 437 (Allocation Mismatch) response if the allocation has 1756 already been deleted, but the client will treat this as equivalent 1757 to a success response (see below). 1759 8.3. Receiving a Refresh Response 1761 If the client receives a success response to its Refresh request with 1762 a non-zero lifetime, it updates its copy of the allocation data 1763 structure with the time-to-expiry value contained in the response. 1764 If the client receives a 437 (Allocation Mismatch) error response to 1765 its request to refresh the allocation, it should consider the 1766 allocation no longer exists. If the client receives a 438 (Stale 1767 Nonce) error to its request to refresh the allocation, it should 1768 reattempt the request with the new nonce value. 1770 If the client receives a 437 (Allocation Mismatch) error response to 1771 a request to delete the allocation, then the allocation no longer 1772 exists and it should consider its request as having effectively 1773 succeeded. 1775 9. Permissions 1777 For each allocation, the server keeps a list of zero or more 1778 permissions. Each permission consists of an IP address and an 1779 associated time-to-expiry. While a permission exists, all peers 1780 using the IP address in the permission are allowed to send data to 1781 the client. The time-to-expiry is the number of seconds until the 1782 permission expires. Within the context of an allocation, a 1783 permission is uniquely identified by its associated IP address. 1785 By sending either CreatePermission requests or ChannelBind requests, 1786 the client can cause the server to install or refresh a permission 1787 for a given IP address. This causes one of two things to happen: 1789 o If no permission for that IP address exists, then a permission is 1790 created with the given IP address and a time-to-expiry equal to 1791 Permission Lifetime. 1793 o If a permission for that IP address already exists, then the time- 1794 to-expiry for that permission is reset to Permission Lifetime. 1796 The Permission Lifetime MUST be 300 seconds (= 5 minutes). 1798 Each permission's time-to-expiry decreases down once per second until 1799 it reaches 0; at which point, the permission expires and is deleted. 1801 CreatePermission and ChannelBind requests may be freely intermixed on 1802 a permission. A given permission may be initially installed and/or 1803 refreshed with a CreatePermission request, and then later refreshed 1804 with a ChannelBind request, or vice versa. 1806 When a UDP datagram arrives at the relayed transport address for the 1807 allocation, the server extracts the source IP address from the IP 1808 header. The server then compares this address with the IP address 1809 associated with each permission in the list of permissions for the 1810 allocation. Note that only addresses are compared and port numbers 1811 are not considered. If no match is found, relaying is not permitted, 1812 and the server silently discards the UDP datagram. If an exact match 1813 is found, the permission check is considered to have succeeded and 1814 the server continues to process the UDP datagram as specified 1815 elsewhere (Section 11.3). 1817 The permissions for one allocation are totally unrelated to the 1818 permissions for a different allocation. If an allocation expires, 1819 all its permissions expire with it. 1821 NOTE: Though TURN permissions expire after 5 minutes, many NATs 1822 deployed at the time of publication expire their UDP bindings 1823 considerably faster. Thus, an application using TURN will 1824 probably wish to send some sort of keep-alive traffic at a much 1825 faster rate. Applications using ICE should follow the keep-alive 1826 guidelines of ICE [RFC8445], and applications not using ICE are 1827 advised to do something similar. 1829 10. CreatePermission 1831 TURN supports two ways for the client to install or refresh 1832 permissions on the server. This section describes one way: the 1833 CreatePermission request. 1835 A CreatePermission request may be used in conjunction with either the 1836 Send mechanism in Section 11 or the Channel mechanism in Section 12. 1838 10.1. Forming a CreatePermission Request 1840 The client who wishes to install or refresh one or more permissions 1841 can send a CreatePermission request to the server. 1843 When forming a CreatePermission request, the client MUST include at 1844 least one XOR-PEER-ADDRESS attribute, and MAY include more than one 1845 such attribute. The IP address portion of each XOR-PEER-ADDRESS 1846 attribute contains the IP address for which a permission should be 1847 installed or refreshed. The port portion of each XOR-PEER-ADDRESS 1848 attribute will be ignored and can be any arbitrary value. The 1849 various XOR-PEER-ADDRESS attributes MAY appear in any order. The 1850 client MUST only include XOR-PEER-ADDRESS attributes with addresses 1851 of the same address family as that of the relayed transport address 1852 for the allocation. For dual allocations obtained using the 1853 ADDITIONAL-ADDRESS-FAMILY attribute, the client MAY include XOR-PEER- 1854 ADDRESS attributes with addresses of IPv4 and IPv6 address families. 1856 10.2. Receiving a CreatePermission Request 1858 When the server receives the CreatePermission request, it processes 1859 as per Section 5 plus the specific rules mentioned here. 1861 The message is checked for validity. The CreatePermission request 1862 MUST contain at least one XOR-PEER-ADDRESS attribute and MAY contain 1863 multiple such attributes. If no such attribute exists, or if any of 1864 these attributes are invalid, then a 400 (Bad Request) error is 1865 returned. If the request is valid, but the server is unable to 1866 satisfy the request due to some capacity limit or similar, then a 508 1867 (Insufficient Capacity) error is returned. 1869 If an XOR-PEER-ADDRESS attribute contains an address of an address 1870 family that is not the same as that of a relayed transport address 1871 for the allocation, the server MUST generate an error response with 1872 the 443 (Peer Address Family Mismatch) response code. 1874 The server MAY impose restrictions on the IP address allowed in the 1875 XOR-PEER-ADDRESS attribute -- if a value is not allowed, the server 1876 rejects the request with a 403 (Forbidden) error. 1878 If the message is valid and the server is capable of carrying out the 1879 request, then the server installs or refreshes a permission for the 1880 IP address contained in each XOR-PEER-ADDRESS attribute as described 1881 in Section 9. The port portion of each attribute is ignored and may 1882 be any arbitrary value. 1884 The server then responds with a CreatePermission success response. 1885 There are no mandatory attributes in the success response. 1887 NOTE: A server need not do anything special to implement 1888 idempotency of CreatePermission requests over UDP using the 1889 "stateless stack approach". Retransmitted CreatePermission 1890 requests will simply refresh the permissions. 1892 10.3. Receiving a CreatePermission Response 1894 If the client receives a valid CreatePermission success response, 1895 then the client updates its data structures to indicate that the 1896 permissions have been installed or refreshed. 1898 11. Send and Data Methods 1900 TURN supports two mechanisms for sending and receiving data from 1901 peers. This section describes the use of the Send and Data 1902 mechanisms, while Section 12 describes the use of the Channel 1903 mechanism. 1905 11.1. Forming a Send Indication 1907 The client can use a Send indication to pass data to the server for 1908 relaying to a peer. A client may use a Send indication even if a 1909 channel is bound to that peer. However, the client MUST ensure that 1910 there is a permission installed for the IP address of the peer to 1911 which the Send indication is being sent; this prevents a third party 1912 from using a TURN server to send data to arbitrary destinations. 1914 When forming a Send indication, the client MUST include an XOR-PEER- 1915 ADDRESS attribute and a DATA attribute. The XOR-PEER-ADDRESS 1916 attribute contains the transport address of the peer to which the 1917 data is to be sent, and the DATA attribute contains the actual 1918 application data to be sent to the peer. 1920 The client MAY include a DONT-FRAGMENT attribute in the Send 1921 indication if it wishes the server to set the DF bit on the UDP 1922 datagram sent to the peer. 1924 11.2. Receiving a Send Indication 1926 When the server receives a Send indication, it processes as per 1927 Section 5 plus the specific rules mentioned here. 1929 The message is first checked for validity. The Send indication MUST 1930 contain both an XOR-PEER-ADDRESS attribute and a DATA attribute. If 1931 one of these attributes is missing or invalid, then the message is 1932 discarded. Note that the DATA attribute is allowed to contain zero 1933 bytes of data. 1935 The Send indication may also contain the DONT-FRAGMENT attribute. If 1936 the server is unable to set the DF bit on outgoing UDP datagrams when 1937 this attribute is present, then the server acts as if the DONT- 1938 FRAGMENT attribute is an unknown comprehension-required attribute 1939 (and thus the Send indication is discarded). 1941 The server also checks that there is a permission installed for the 1942 IP address contained in the XOR-PEER-ADDRESS attribute. If no such 1943 permission exists, the message is discarded. Note that a Send 1944 indication never causes the server to refresh the permission. 1946 The server MAY impose restrictions on the IP address and port values 1947 allowed in the XOR-PEER-ADDRESS attribute -- if a value is not 1948 allowed, the server silently discards the Send indication. 1950 If everything is OK, then the server forms a UDP datagram as follows: 1952 o the source transport address is the relayed transport address of 1953 the allocation, where the allocation is determined by the 5-tuple 1954 on which the Send indication arrived; 1956 o the destination transport address is taken from the XOR-PEER- 1957 ADDRESS attribute; 1959 o the data following the UDP header is the contents of the value 1960 field of the DATA attribute. 1962 The handling of the DONT-FRAGMENT attribute (if present), is 1963 described in Section 14 and Section 15. 1965 The resulting UDP datagram is then sent to the peer. 1967 11.3. Receiving a UDP Datagram 1969 When the server receives a UDP datagram at a currently allocated 1970 relayed transport address, the server looks up the allocation 1971 associated with the relayed transport address. The server then 1972 checks to see whether the set of permissions for the allocation allow 1973 the relaying of the UDP datagram as described in Section 9. 1975 If relaying is permitted, then the server checks if there is a 1976 channel bound to the peer that sent the UDP datagram (see 1977 Section 12). If a channel is bound, then processing proceeds as 1978 described in Section 12.7. 1980 If relaying is permitted but no channel is bound to the peer, then 1981 the server forms and sends a Data indication. The Data indication 1982 MUST contain both an XOR-PEER-ADDRESS and a DATA attribute. The DATA 1983 attribute is set to the value of the 'data octets' field from the 1984 datagram, and the XOR-PEER-ADDRESS attribute is set to the source 1985 transport address of the received UDP datagram. The Data indication 1986 is then sent on the 5-tuple associated with the allocation. 1988 11.4. Receiving a Data Indication 1990 When the client receives a Data indication, it checks that the Data 1991 indication contains an XOR-PEER-ADDRESS attribute, and discards the 1992 indication if it does not. The client SHOULD also check that the 1993 XOR-PEER-ADDRESS attribute value contains an IP address with which 1994 the client believes there is an active permission, and discard the 1995 Data indication otherwise. 1997 NOTE: The latter check protects the client against an attacker who 1998 somehow manages to trick the server into installing permissions 1999 not desired by the client. 2001 If the XOR-PEER-ADDRESS is present and valid, the client checks that 2002 the Data indication contains either a DATA attribute or an ICMP 2003 attribute and discards the indication if it does not. Note that a 2004 DATA attribute is allowed to contain zero bytes of data. Processing 2005 of Data indications with an ICMP attribute is described in 2006 Section 11.6. 2008 If the Data indication passes the above checks, the client delivers 2009 the data octets inside the DATA attribute to the application, along 2010 with an indication that they were received from the peer whose 2011 transport address is given by the XOR-PEER-ADDRESS attribute. 2013 11.5. Receiving an ICMP Packet 2015 When the server receives an ICMP packet, the server verifies that the 2016 type is either 3 or 11 for an ICMPv4 [RFC0792] packet or either 1, 2, 2017 or 3 for an ICMPv6 [RFC4443] packet. It also verifies that the IP 2018 packet in the ICMP packet payload contains a UDP header, and if a UDP 2019 header is present, the server extracts the UDP source and destination 2020 IP address and port information. If either of these conditions fail, 2021 then the ICMP packet is silently dropped. 2023 The server looks up the allocation whose relayed transport address 2024 corresponds to the encapsulated packet's source IP address and UDP 2025 port. If no such allocation exists, the packet is silently dropped. 2026 The server then checks to see whether the set of permissions for the 2027 allocation allows the relaying of the ICMP packet. For ICMP packets, 2028 the source IP address MUST NOT be checked against the permissions 2029 list as it would be for UDP packets. Instead, the server extracts 2030 the destination IP address from the encapsulated IP header. The 2031 server then compares this address with the IP address associated with 2032 each permission in the list of permissions for the allocation. If no 2033 match is found, relaying is not permitted, and the server silently 2034 discards the ICMP packet. Note that only addresses are compared and 2035 port numbers are not considered. 2037 If relaying is permitted then the server forms and sends a Data 2038 indication. The Data indication MUST contain both an XOR-PEER- 2039 ADDRESS and an ICMP attribute. The ICMP attribute is set to the 2040 value of the type and code fields from the ICMP packet. The IP 2041 address portion of XOR-PEER-ADDRESS attribute is set to the 2042 destination IP address in the encapsulated IP header. At the time of 2043 writing of this specification, Socket APIs on some operating systems 2044 do not deliver the destination port in the encapsulated UDP header to 2045 applications without superuser privileges. If destination port in 2046 the encapsulated UDP header is available to the server then the port 2047 portion of XOR-PEER-ADDRESS attribute is set to the destination port 2048 otherwise the port portion is set to 0. The Data indication is then 2049 sent on the 5-tuple associated with the allocation. 2051 Implementation Note: New ICMP types or codes can be defined in future 2052 specifications. If the server receives an ICMP error packet, and the 2053 new type or code field can help the client to make use of the ICMP 2054 error notification and generate feedback to the application layer, 2055 the server sends the Data indication with an ICMP attribute conveying 2056 the new ICMP type or code. 2058 11.6. Receiving a Data Indication with an ICMP attribute 2060 When the client receives a Data indication with an ICMP attribute, it 2061 checks that the Data indication contains an XOR-PEER-ADDRESS 2062 attribute, and discards the indication if it does not. The client 2063 SHOULD also check that the XOR-PEER-ADDRESS attribute value contains 2064 an IP address with an active permission, and discard the Data 2065 indication otherwise. 2067 If the Data indication passes the above checks, the client signals 2068 the application of the error condition, along with an indication that 2069 it was received from the peer whose transport address is given by the 2070 XOR-PEER-ADDRESS attribute. The application can make sense of the 2071 meaning of the type and code values in the ICMP attribute by using 2072 the family field in the XOR-PEER-ADDRESS attribute. 2074 12. Channels 2076 Channels provide a way for the client and server to send application 2077 data using ChannelData messages, which have less overhead than Send 2078 and Data indications. 2080 The ChannelData message (see Section 12.4) starts with a two-byte 2081 field that carries the channel number. The values of this field are 2082 allocated as follows: 2084 0x0000 through 0x3FFF: These values can never be used for channel 2085 numbers. 2087 0x4000 through 0x4FFF: These values are the allowed channel 2088 numbers (4096 possible values). 2090 0x5000-0xFFFF: Reserved (For DTLS-SRTP multiplexing collision 2091 avoidance, see [RFC7983]. 2093 Note that the channel number range is not backwards compatible with 2094 [RFC5766], and cannot be used in environments where such 2095 compatibility is required. 2097 According to [RFC7983], ChannelData messages can be distinguished 2098 from other multiplexed protocols by examining the first byte of the 2099 message: 2101 +------------+------------------------------+ 2102 | [0..3] | STUN | 2103 | | | 2104 +-------------------------------------------+ 2105 | [16..19] | ZRTP | 2106 | | | 2107 +-------------------------------------------+ 2108 | [20..63] | DTLS | 2109 | | | 2110 +-------------------------------------------+ 2111 | [64..79] | TURN Channel | 2112 | | | 2113 +-------------------------------------------+ 2114 | [128..191] | RTP/RTCP | 2115 | | | 2116 +-------------------------------------------+ 2117 | Others | Reserved, MUST be dropped | 2118 | | and an alert MAY be logged | 2119 +-------------------------------------------+ 2121 Figure 5 2123 Reserved values may be used in the future by other protocols. When 2124 the client uses channel binding, it MUST comply with the 2125 demultiplexing scheme discussed above. 2127 Channel bindings are always initiated by the client. The client can 2128 bind a channel to a peer at any time during the lifetime of the 2129 allocation. The client may bind a channel to a peer before 2130 exchanging data with it, or after exchanging data with it (using Send 2131 and Data indications) for some time, or may choose never to bind a 2132 channel to it. The client can also bind channels to some peers while 2133 not binding channels to other peers. 2135 Channel bindings are specific to an allocation, so that the use of a 2136 channel number or peer transport address in a channel binding in one 2137 allocation has no impact on their use in a different allocation. If 2138 an allocation expires, all its channel bindings expire with it. 2140 A channel binding consists of: 2142 o a channel number; 2144 o a transport address (of the peer); and 2146 o A time-to-expiry timer. 2148 Within the context of an allocation, a channel binding is uniquely 2149 identified either by the channel number or by the peer's transport 2150 address. Thus, the same channel cannot be bound to two different 2151 transport addresses, nor can the same transport address be bound to 2152 two different channels. 2154 A channel binding lasts for 10 minutes unless refreshed. Refreshing 2155 the binding (by the server receiving a ChannelBind request rebinding 2156 the channel to the same peer) resets the time-to-expiry timer back to 2157 10 minutes. 2159 When the channel binding expires, the channel becomes unbound. Once 2160 unbound, the channel number can be bound to a different transport 2161 address, and the transport address can be bound to a different 2162 channel number. To prevent race conditions, the client MUST wait 5 2163 minutes after the channel binding expires before attempting to bind 2164 the channel number to a different transport address or the transport 2165 address to a different channel number. 2167 When binding a channel to a peer, the client SHOULD be prepared to 2168 receive ChannelData messages on the channel from the server as soon 2169 as it has sent the ChannelBind request. Over UDP, it is possible for 2170 the client to receive ChannelData messages from the server before it 2171 receives a ChannelBind success response. 2173 In the other direction, the client MAY elect to send ChannelData 2174 messages before receiving the ChannelBind success response. Doing 2175 so, however, runs the risk of having the ChannelData messages dropped 2176 by the server if the ChannelBind request does not succeed for some 2177 reason (e.g., packet lost if the request is sent over UDP, or the 2178 server being unable to fulfill the request). A client that wishes to 2179 be safe should either queue the data or use Send indications until 2180 the channel binding is confirmed. 2182 12.1. Sending a ChannelBind Request 2184 A channel binding is created or refreshed using a ChannelBind 2185 transaction. A ChannelBind transaction also creates or refreshes a 2186 permission towards the peer (see Section 9). 2188 To initiate the ChannelBind transaction, the client forms a 2189 ChannelBind request. The channel to be bound is specified in a 2190 CHANNEL-NUMBER attribute, and the peer's transport address is 2191 specified in an XOR-PEER-ADDRESS attribute. Section 12.2 describes 2192 the restrictions on these attributes. The client MUST only include 2193 an XOR-PEER-ADDRESS attribute with an address of the same address 2194 family as that of a relayed transport address for the allocation. 2196 Rebinding a channel to the same transport address that it is already 2197 bound to provides a way to refresh a channel binding and the 2198 corresponding permission without sending data to the peer. Note 2199 however, that permissions need to be refreshed more frequently than 2200 channels. 2202 12.2. Receiving a ChannelBind Request 2204 When the server receives a ChannelBind request, it processes as per 2205 Section 5 plus the specific rules mentioned here. 2207 The server checks the following: 2209 o The request contains both a CHANNEL-NUMBER and an XOR-PEER-ADDRESS 2210 attribute; 2212 o The channel number is in the range 0x4000 through 0x4FFF 2213 (inclusive); 2215 o The channel number is not currently bound to a different transport 2216 address (same transport address is OK); 2218 o The transport address is not currently bound to a different 2219 channel number. 2221 If any of these tests fail, the server replies with a 400 (Bad 2222 Request) error. If the XOR-PEER-ADDRESS attribute contains an 2223 address of an address family that is not the same as that of a 2224 relayed transport address for the allocation, the server MUST 2225 generate an error response with the 443 (Peer Address Family 2226 Mismatch) response code. 2228 The server MAY impose restrictions on the IP address and port values 2229 allowed in the XOR-PEER-ADDRESS attribute -- if a value is not 2230 allowed, the server rejects the request with a 403 (Forbidden) error. 2232 If the request is valid, but the server is unable to fulfill the 2233 request due to some capacity limit or similar, the server replies 2234 with a 508 (Insufficient Capacity) error. 2236 Otherwise, the server replies with a ChannelBind success response. 2237 There are no required attributes in a successful ChannelBind 2238 response. 2240 If the server can satisfy the request, then the server creates or 2241 refreshes the channel binding using the channel number in the 2242 CHANNEL-NUMBER attribute and the transport address in the XOR-PEER- 2243 ADDRESS attribute. The server also installs or refreshes a 2244 permission for the IP address in the XOR-PEER-ADDRESS attribute as 2245 described in Section 9. 2247 NOTE: A server need not do anything special to implement 2248 idempotency of ChannelBind requests over UDP using the "stateless 2249 stack approach". Retransmitted ChannelBind requests will simply 2250 refresh the channel binding and the corresponding permission. 2251 Furthermore, the client must wait 5 minutes before binding a 2252 previously bound channel number or peer address to a different 2253 channel, eliminating the possibility that the transaction would 2254 initially fail but succeed on a retransmission. 2256 12.3. Receiving a ChannelBind Response 2258 When the client receives a ChannelBind success response, it updates 2259 its data structures to record that the channel binding is now active. 2260 It also updates its data structures to record that the corresponding 2261 permission has been installed or refreshed. 2263 If the client receives a ChannelBind failure response that indicates 2264 that the channel information is out-of-sync between the client and 2265 the server (e.g., an unexpected 400 "Bad Request" response), then it 2266 is RECOMMENDED that the client immediately delete the allocation and 2267 start afresh with a new allocation. 2269 12.4. The ChannelData Message 2271 The ChannelData message is used to carry application data between the 2272 client and the server. It has the following format: 2274 0 1 2 3 2275 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 2276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2277 | Channel Number | Length | 2278 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2279 | | 2280 / Application Data / 2281 / / 2282 | | 2283 | +-------------------------------+ 2284 | | 2285 +-------------------------------+ 2287 The Channel Number field specifies the number of the channel on which 2288 the data is traveling, and thus the address of the peer that is 2289 sending or is to receive the data. 2291 The Length field specifies the length in bytes of the application 2292 data field (i.e., it does not include the size of the ChannelData 2293 header). Note that 0 is a valid length. 2295 The Application Data field carries the data the client is trying to 2296 send to the peer, or that the peer is sending to the client. 2298 12.5. Sending a ChannelData Message 2300 Once a client has bound a channel to a peer, then when the client has 2301 data to send to that peer it may use either a ChannelData message or 2302 a Send indication; that is, the client is not obligated to use the 2303 channel when it exists and may freely intermix the two message types 2304 when sending data to the peer. The server, on the other hand, MUST 2305 use the ChannelData message if a channel has been bound to the peer. 2306 The server uses a Data indication to signal the XOR-PEER-ADDRESS and 2307 ICMP attributes to the client even if a channel has been bound to the 2308 peer. 2310 The fields of the ChannelData message are filled in as described in 2311 Section 12.4. 2313 Over TCP and TLS-over-TCP, the ChannelData message MUST be padded to 2314 a multiple of four bytes in order to ensure the alignment of 2315 subsequent messages. The padding is not reflected in the length 2316 field of the ChannelData message, so the actual size of a ChannelData 2317 message (including padding) is (4 + Length) rounded up to the nearest 2318 multiple of 4 (See section 14 in [I-D.ietf-tram-stunbis]). Over UDP, 2319 the padding is not required but MAY be included. 2321 The ChannelData message is then sent on the 5-tuple associated with 2322 the allocation. 2324 12.6. Receiving a ChannelData Message 2326 The receiver of the ChannelData message uses the first byte to 2327 distinguish it from other multiplexed protocols, as described in 2328 Figure 5. If the message uses a value in the reserved range (0x5000 2329 through 0xFFFF), then the message is silently discarded. 2331 If the ChannelData message is received in a UDP datagram, and if the 2332 UDP datagram is too short to contain the claimed length of the 2333 ChannelData message (i.e., the UDP header length field value is less 2334 than the ChannelData header length field value + 4 + 8), then the 2335 message is silently discarded. 2337 If the ChannelData message is received over TCP or over TLS-over-TCP, 2338 then the actual length of the ChannelData message is as described in 2339 Section 12.5. 2341 If the ChannelData message is received on a channel that is not bound 2342 to any peer, then the message is silently discarded. 2344 On the client, it is RECOMMENDED that the client discard the 2345 ChannelData message if the client believes there is no active 2346 permission towards the peer. On the server, the receipt of a 2347 ChannelData message MUST NOT refresh either the channel binding or 2348 the permission towards the peer. 2350 On the server, if no errors are detected, the server relays the 2351 application data to the peer by forming a UDP datagram as follows: 2353 o the source transport address is the relayed transport address of 2354 the allocation, where the allocation is determined by the 5-tuple 2355 on which the ChannelData message arrived; 2357 o the destination transport address is the transport address to 2358 which the channel is bound; 2360 o the data following the UDP header is the contents of the data 2361 field of the ChannelData message. 2363 The resulting UDP datagram is then sent to the peer. Note that if 2364 the Length field in the ChannelData message is 0, then there will be 2365 no data in the UDP datagram, but the UDP datagram is still formed and 2366 sent (Section 4.1 in [RFC6263]). 2368 12.7. Relaying Data from the Peer 2370 When the server receives a UDP datagram on the relayed transport 2371 address associated with an allocation, the server processes it as 2372 described in Section 11.3. If that section indicates that a 2373 ChannelData message should be sent (because there is a channel bound 2374 to the peer that sent to the UDP datagram), then the server forms and 2375 sends a ChannelData message as described in Section 12.5. 2377 When the server receives an ICMP packet, the server processes it as 2378 described in Section 11.5. 2380 13. Packet Translations 2382 This section addresses IPv4-to-IPv6, IPv6-to-IPv4, and IPv6-to-IPv6 2383 translations. Requirements for translation of the IP addresses and 2384 port numbers of the packets are described above. The following 2385 sections specify how to translate other header fields. 2387 As discussed in Section 3.6, translations in TURN are designed so 2388 that a TURN server can be implemented as an application that runs in 2389 user space under commonly available operating systems and that does 2390 not require special privileges. The translations specified in the 2391 following sections follow this principle. 2393 The descriptions below have two parts: a preferred behavior and an 2394 alternate behavior. The server SHOULD implement the preferred 2395 behavior, but if that is not possible for a particular field, the 2396 server MUST implement the alternate behavior and MUST NOT do anything 2397 else for the reasons detailed in [RFC7915]. The TURN server solely 2398 relies on the DF bit in the IPv4 header and Fragmentation header in 2399 IPv6 header to handle fragmentation and does not rely on the DONT- 2400 FRAGMENT attribute. 2402 13.1. IPv4-to-IPv6 Translations 2404 Time to Live (TTL) field 2406 Preferred Behavior: As specified in Section 4 of [RFC7915]. 2408 Alternate Behavior: Set the outgoing value to the default for 2409 outgoing packets. 2411 Traffic Class 2413 Preferred behavior: As specified in Section 4 of [RFC7915]. 2415 Alternate behavior: The TURN server sets the Traffic Class to the 2416 default value for outgoing packets. 2418 Flow Label 2420 Preferred behavior: The TURN server can use the 5-tuple of relayed 2421 transport address, peer transport address and UDP protocol number 2422 to identify each flow, generate and set the flow label value in 2423 the IPv6 packet as discussed in Section 3 of [RFC6437]. If the 2424 TURN server is incapable of generating the flow label value from 2425 the IPv6 packet's 5-tuple, it sets the Flow label to 0. 2427 Alternate behavior: The TURN server sets the Flow label to the 2428 default value of zero for outgoing packets. 2430 Hop Limit 2431 Preferred behavior: As specified in Section 4 of [RFC7915]. 2433 Alternate behavior: The TURN server sets the Hop Limit to the 2434 default value for outgoing packets. 2436 Fragmentation 2438 Preferred behavior: As specified in Section 4 of [RFC7915]. 2440 Alternate behavior: The TURN server assembles incoming fragments. 2441 The TURN server follows its default behavior to send outgoing 2442 packets. 2444 For both preferred and alternate behavior, the DONT-FRAGMENT 2445 attribute MUST be ignored by the server. 2447 Extension Headers 2449 Preferred behavior: The outgoing packet uses the system defaults 2450 for IPv6 extension headers, with the exception of the 2451 Fragmentation header as described above. 2453 Alternate behavior: Same as preferred. 2455 13.2. IPv6-to-IPv6 Translations 2457 Flow Label 2459 The TURN server should consider that it is handling two different 2460 IPv6 flows. Therefore, the Flow label [RFC6437] SHOULD NOT be copied 2461 as part of the translation. 2463 Preferred behavior: The TURN server can use the 5-tuple of relayed 2464 transport address, peer transport address and UDP protocol number 2465 to identify each flow, generate and set the flow label value in 2466 the IPv6 packet as discussed in Section 3 of [RFC6437]. If the 2467 TURN server is incapable of generating the flow label value from 2468 the IPv6 packet's 5-tuple, it sets the Flow label to 0. 2470 Alternate behavior: The TURN server sets the Flow label to the 2471 default value of zero for outgoing packets. 2473 Hop Limit 2475 Preferred behavior: The TURN server acts as a regular router with 2476 respect to decrementing the Hop Limit and generating an ICMPv6 2477 error if it reaches zero. 2479 Alternate behavior: The TURN server sets the Hop Limit to the 2480 default value for outgoing packets. 2482 Fragmentation 2484 Preferred behavior: If the incoming packet did not include a 2485 Fragment header and the outgoing packet size does not exceed the 2486 outgoing link's MTU, the TURN server sends the outgoing packet 2487 without a Fragment header. 2489 If the incoming packet did not include a Fragment header and the 2490 outgoing packet size exceeds the outgoing link's MTU, the TURN 2491 server drops the outgoing packet and send an ICMP message of type 2492 2 code 0 ("Packet too big") to the sender of the incoming packet. 2493 If the ICMPv6 packet ("Packet too big") is being sent to the peer, 2494 the TURN server reduces the MTU reported in the ICMP message by 48 2495 bytes to allow room for the overhead of a Data indication. 2497 If the incoming packet included a Fragment header and the outgoing 2498 packet size (with a Fragment header included) does not exceed the 2499 outgoing link's MTU, the TURN server sends the outgoing packet 2500 with a Fragment header. The TURN server sets the fields of the 2501 Fragment header as appropriate for a packet originating from the 2502 server. 2504 If the incoming packet included a Fragment header and the outgoing 2505 packet size exceeds the outgoing link's MTU, the TURN server MUST 2506 fragment the outgoing packet into fragments of no more than 1280 2507 bytes. The TURN server sets the fields of the Fragment header as 2508 appropriate for a packet originating from the server. 2510 Alternate behavior: The TURN server assembles incoming fragments. 2511 The TURN server follows its default behavior to send outgoing 2512 packets. 2514 For both preferred and alternate behavior, the DONT-FRAGMENT 2515 attribute MUST be ignored by the server. 2517 Extension Headers 2519 Preferred behavior: The outgoing packet uses the system defaults 2520 for IPv6 extension headers, with the exception of the 2521 Fragmentation header as described above. 2523 Alternate behavior: Same as preferred. 2525 13.3. IPv6-to-IPv4 Translations 2527 Type of Service and Precedence 2529 Preferred behavior: As specified in Section 5 of [RFC7915]. 2531 Alternate behavior: The TURN server sets the Type of Service and 2532 Precedence to the default value for outgoing packets. 2534 Time to Live 2536 Preferred behavior: As specified in Section 5 of [RFC7915]. 2538 Alternate behavior: The TURN server sets the Time to Live to the 2539 default value for outgoing packets. 2541 Fragmentation 2543 Preferred behavior: As specified in Section 5 of [RFC7915]. 2544 Additionally, when the outgoing packet's size exceeds the outgoing 2545 link's MTU, the TURN server needs to generate an ICMP error 2546 (ICMPv6 Packet Too Big) reporting the MTU size. If the ICMPv4 2547 packet (Destination Unreachable (Type 3) with Code 4) is being 2548 sent to the peer, the TURN server SHOULD reduce the MTU reported 2549 in the ICMP message by 48 bytes to allow room for the overhead of 2550 a Data indication. 2552 Alternate behavior: The TURN server assembles incoming fragments. 2553 The TURN server follows its default behavior to send outgoing 2554 packets. 2556 For both preferred and alternate behavior, the DONT-FRAGMENT 2557 attribute MUST be ignored by the server. 2559 14. UDP-to-UDP relay 2561 This section describes how the server sets various fields in the IP 2562 header for UDP-to-UDP relay from the client to the peer or vice 2563 versa. The descriptions in this section apply: (a) when the server 2564 sends a UDP datagram to the peer, or (b) when the server sends a Data 2565 indication or ChannelData message to the client over UDP transport. 2566 The descriptions in this section do not apply to TURN messages sent 2567 over TCP or TLS transport from the server to the client. 2569 The descriptions below have two parts: a preferred behavior and an 2570 alternate behavior. The server SHOULD implement the preferred 2571 behavior, but if that is not possible for a particular field, then it 2572 SHOULD implement the alternative behavior. 2574 Differentiated Services Code Point (DSCP) field [RFC2474] 2576 Preferred Behavior: Set the outgoing value to the incoming value, 2577 unless the server includes a differentiated services classifier 2578 and marker [RFC2474]. 2580 Alternate Behavior: Set the outgoing value to a fixed value, which 2581 by default is Best Effort unless configured otherwise. 2583 In both cases, if the server is immediately adjacent to a 2584 differentiated services classifier and marker, then DSCP MAY be 2585 set to any arbitrary value in the direction towards the 2586 classifier. 2588 Explicit Congestion Notification (ECN) field [RFC3168] 2590 Preferred Behavior: Set the outgoing value to the incoming value. 2591 The server may perform Active Queue Management, in which case it 2592 SHOULD behave as a ECN aware router [RFC3168] and can mark traffic 2593 with Congestion Experienced (CE) instead of dropping the packet. 2594 The use of ECT(1) is subject to experimental usage [RFC8311]. 2596 Alternate Behavior: Set the outgoing value to Not-ECT (=0b00). 2598 IPv4 Fragmentation fields 2600 Preferred Behavior: When the server sends a packet to a peer in 2601 response to a Send indication containing the DONT-FRAGMENT 2602 attribute, then set the outgoing UDP packet to not fragment. In 2603 all other cases when sending an outgoing packet containing 2604 application data (e.g., Data indication, ChannelData message, or 2605 DONT-FRAGMENT attribute not included in the Send indication), copy 2606 the DF bit from the DF bit of the incoming packet that contained 2607 the application data. 2609 Set the other fragmentation fields (Identification, More 2610 Fragments, Fragment Offset) as appropriate for a packet 2611 originating from the server. 2613 Alternate Behavior: As described in the Preferred Behavior, except 2614 always assume the incoming DF bit is 0. 2616 In both the Preferred and Alternate Behaviors, the resulting 2617 packet may be too large for the outgoing link. If this is the 2618 case, then the normal fragmentation rules apply [RFC1122]. 2620 IPv4 Options 2622 Preferred Behavior: The outgoing packet uses the system defaults 2623 for IPv4 options. 2625 Alternate Behavior: Same as preferred. 2627 15. TCP-to-UDP relay 2629 This section describes how the server sets various fields in the IP 2630 header for TCP-to-UDP relay from the client to the peer. The 2631 descriptions in this section apply when the server sends a UDP 2632 datagram to the peer. Note that the server does not perform per- 2633 packet translation for TCP-to-UDP relaying. 2635 Multipath TCP [I-D.ietf-mptcp-rfc6824bis] is not supported by this 2636 version of TURN because TCP multi-path is not used by both SIP and 2637 WebRTC protocols [RFC7478] for media and non-media data. TCP 2638 connection between the TURN client and server can use TCP-AO 2639 [RFC5925] but UDP does not provide a similar type of authentication 2640 until UDP supports a similar authentication option 2641 [I-D.ietf-tsvwg-udp-options]. Even if both TCP-AO and UDP 2642 authentication would be used between TURN client and server, it would 2643 not change the end-to-end security properties of the application 2644 payload being relayed. Therefore applications using TURN will need 2645 to secure their application data end-to-end appropriately, e.g., SRTP 2646 for RTP applications. Note that TCP-AO option obsoletes TCP MD5 2647 option. Unlike UDP, TCP without the TCP Fast Open extension 2648 [RFC7413] does not support 0-RTT session resumption. The TCP user 2649 timeout [RFC5482] equivalent for application data relayed by the TURN 2650 is the use of RTP control protocol (RTCP). As a reminder, RTCP is a 2651 fundamental and integral part of RTP. 2653 The descriptions below have two parts: a preferred behavior and an 2654 alternate behavior. The server SHOULD implement the preferred 2655 behavior, but if that is not possible for a particular field, then it 2656 SHOULD implement the alternative behavior. 2658 For the UDP datagram sent to the peer based on Send Indication or 2659 ChannelData message arriving at the TURN server over a TCP Transport, 2660 the server sets various fields in the IP header as follows: 2662 Differentiated Services Code Point (DSCP) field [RFC2474] 2664 Preferred Behavior: The TCP connection can only use a single DSCP 2665 code point so inter flow differentiation is not possible, see 2666 Section 5.1 of [RFC7657]. The server sets the outgoing value to 2667 the DSCP code point used by the TCP connection, unless the server 2668 includes a differentiated services classifier and marker 2669 [RFC2474]. 2671 Alternate Behavior: Set the outgoing value to a fixed value, which 2672 by default is Best Effort unless configured otherwise. 2674 In both cases, if the server is immediately adjacent to a 2675 differentiated services classifier and marker, then DSCP MAY be 2676 set to any arbitrary value in the direction towards the 2677 classifier. 2679 Explicit Congestion Notification (ECN) field [RFC3168] 2681 Preferred Behavior: No mechanism is defined to indicate what ECN 2682 value should be used for the outgoing UDP datagrams of an 2683 allocation, therefore set the outgoing value to Not-ECT (=0b00). 2685 Alternate Behavior: Same as preferred. 2687 IPv4 Fragmentation fields 2689 Preferred Behavior: When the server sends a packet to a peer in 2690 response to a Send indication containing the DONT-FRAGMENT 2691 attribute, then set the outgoing UDP packet to not fragment. In 2692 all other cases when sending an outgoing UDP packet containing 2693 application data (e.g., Data indication, ChannelData message, or 2694 DONT-FRAGMENT attribute not included in the Send indication), set 2695 the DF bit in the outgoing IP header to 0. 2697 Alternate Behavior: Same as preferred. 2699 IPv6 Fragmentation fields 2701 Preferred Behavior: If the TCP traffic arrives over IPv6, the 2702 server relies on the presence of DONT-FRAGMENT attribute in the 2703 send indication to set the outgoing UDP packet to not fragment. 2705 Alternate Behavior: Same as preferred. 2707 IPv4 Options 2709 Preferred Behavior: The outgoing packet uses the system defaults 2710 for IPv4 options. 2712 Alternate Behavior: Same as preferred. 2714 16. UDP-to-TCP relay 2716 This section describes how the server sets various fields in the IP 2717 header for UDP-to-TCP relay from the peer to the client. The 2718 descriptions in this section apply when the server sends a Data 2719 indication or ChannelData message to the client over TCP or TLS 2720 transport. Note that the server does not perform per-packet 2721 translation for UDP-to-TCP relaying. 2723 The descriptions below have two parts: a preferred behavior and an 2724 alternate behavior. The server SHOULD implement the preferred 2725 behavior, but if that is not possible for a particular field, then it 2726 SHOULD implement the alternative behavior. 2728 The TURN server sets IP header fields in the TCP packets on a per- 2729 connection basis for the TCP connection as follows: 2731 Differentiated Services Code Point (DSCP) field [RFC2474] 2733 Preferred Behavior: Ignore the incoming DSCP value. When TCP is 2734 used between the client and the server, a single DSCP should be 2735 used for all traffic on that TCP connection. Note, TURN/ICE 2736 occurs before application data is exchanged. 2738 Alternate Behavior: Same as preferred. 2740 Explicit Congestion Notification (ECN) field [RFC3168] 2742 Preferred Behavior: Ignore, ECN signals are dropped in the TURN 2743 server for the incoming UDP datagrams from the peer. 2745 Alternate Behavior: Same as preferred. 2747 Fragmentation 2749 Preferred Behavior: Any fragmented packets are reassembled in the 2750 server and then forwarded to the client over the TCP connection. 2751 ICMP messages resulting from the UDP datagrams sent to the peer 2752 are processed by the server as described in Section 11.5 and 2753 forwarded to the client using TURN's mechanism for relevant ICMP 2754 types and codes. 2756 Alternate Behavior: Same as preferred. 2758 Extension Headers 2759 Preferred behavior: The outgoing packet uses the system defaults 2760 for IPv6 extension headers. 2762 Alternate behavior: Same as preferred. 2764 IPv4 Options 2766 Preferred Behavior: The outgoing packet uses the system defaults 2767 for IPv4 options. 2769 Alternate Behavior: Same as preferred. 2771 17. STUN Methods 2773 This section lists the codepoints for the STUN methods defined in 2774 this specification. See elsewhere in this document for the semantics 2775 of these methods. 2777 0x003 : Allocate (only request/response semantics defined) 2778 0x004 : Refresh (only request/response semantics defined) 2779 0x006 : Send (only indication semantics defined) 2780 0x007 : Data (only indication semantics defined) 2781 0x008 : CreatePermission (only request/response semantics defined 2782 0x009 : ChannelBind (only request/response semantics defined) 2784 18. STUN Attributes 2786 This STUN extension defines the following attributes: 2788 0x000C: CHANNEL-NUMBER 2789 0x000D: LIFETIME 2790 0x0010: Reserved (was BANDWIDTH) 2791 0x0012: XOR-PEER-ADDRESS 2792 0x0013: DATA 2793 0x0016: XOR-RELAYED-ADDRESS 2794 0x0017: REQUESTED-ADDRESS-FAMILY 2795 0x0018: EVEN-PORT 2796 0x0019: REQUESTED-TRANSPORT 2797 0x001A: DONT-FRAGMENT 2798 0x0021: Reserved (was TIMER-VAL) 2799 0x0022: RESERVATION-TOKEN 2800 TBD-CA: ADDITIONAL-ADDRESS-FAMILY 2801 TBD-CA: ADDRESS-ERROR-CODE 2802 TBD-CA: ICMP 2804 Some of these attributes have lengths that are not multiples of 4. 2805 By the rules of STUN, any attribute whose length is not a multiple of 2806 4 bytes MUST be immediately followed by 1 to 3 padding bytes to 2807 ensure the next attribute (if any) would start on a 4-byte boundary 2808 (see [I-D.ietf-tram-stunbis]). 2810 18.1. CHANNEL-NUMBER 2812 The CHANNEL-NUMBER attribute contains the number of the channel. The 2813 value portion of this attribute is 4 bytes long and consists of a 2814 16-bit unsigned integer, followed by a two-octet RFFU (Reserved For 2815 Future Use) field, which MUST be set to 0 on transmission and MUST be 2816 ignored on reception. 2818 0 1 2 3 2819 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 2820 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2821 | Channel Number | RFFU = 0 | 2822 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2824 18.2. LIFETIME 2826 The LIFETIME attribute represents the duration for which the server 2827 will maintain an allocation in the absence of a refresh. The TURN 2828 client can include the LIFETIME attribute with the desired lifetime 2829 in Allocate and Refresh requests. The value portion of this 2830 attribute is 4-bytes long and consists of a 32-bit unsigned integral 2831 value representing the number of seconds remaining until expiration. 2833 18.3. XOR-PEER-ADDRESS 2835 The XOR-PEER-ADDRESS specifies the address and port of the peer as 2836 seen from the TURN server. (For example, the peer's server-reflexive 2837 transport address if the peer is behind a NAT.) It is encoded in the 2838 same way as XOR-MAPPED-ADDRESS [I-D.ietf-tram-stunbis]. 2840 18.4. DATA 2842 The DATA attribute is present in all Send indications. If the ICMP 2843 attribute is not present in a Data indication, it contains a DATA 2844 attribute. The value portion of this attribute is variable length 2845 and consists of the application data (that is, the data that would 2846 immediately follow the UDP header if the data was been sent directly 2847 between the client and the peer). The application data is equivalent 2848 to the "UDP user data" and does not include the "surplus area" 2849 defined in Section 4 of [I-D.ietf-tsvwg-udp-options]. If the length 2850 of this attribute is not a multiple of 4, then padding must be added 2851 after this attribute. 2853 18.5. XOR-RELAYED-ADDRESS 2855 The XOR-RELAYED-ADDRESS is present in Allocate responses. It 2856 specifies the address and port that the server allocated to the 2857 client. It is encoded in the same way as XOR-MAPPED-ADDRESS 2858 [I-D.ietf-tram-stunbis]. 2860 18.6. REQUESTED-ADDRESS-FAMILY 2862 This attribute is used in Allocate and Refresh requests to specify 2863 the address type requested by the client. The value of this 2864 attribute is 4 bytes with the following format: 2866 0 1 2 3 2867 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 2868 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2869 | Family | Reserved | 2870 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2872 Family: there are two values defined for this field and specified in 2873 [I-D.ietf-tram-stunbis], Section 14.1: 0x01 for IPv4 addresses and 2874 0x02 for IPv6 addresses. 2876 Reserved: at this point, the 24 bits in the Reserved field MUST be 2877 set to zero by the client and MUST be ignored by the server. 2879 18.7. EVEN-PORT 2881 This attribute allows the client to request that the port in the 2882 relayed transport address be even, and (optionally) that the server 2883 reserve the next-higher port number. The value portion of this 2884 attribute is 1 byte long. Its format is: 2886 0 2887 0 1 2 3 4 5 6 7 2888 +-+-+-+-+-+-+-+-+ 2889 |R| RFFU | 2890 +-+-+-+-+-+-+-+-+ 2892 The value contains a single 1-bit flag: 2894 R: If 1, the server is requested to reserve the next-higher port 2895 number (on the same IP address) for a subsequent allocation. If 2896 0, no such reservation is requested. 2898 RFFU: Reserved For Future Use. 2900 The RFFU field must be set to zero on transmission and ignored on 2901 reception. 2903 Since the length of this attribute is not a multiple of 4, padding 2904 must immediately follow this attribute. 2906 18.8. REQUESTED-TRANSPORT 2908 This attribute is used by the client to request a specific transport 2909 protocol for the allocated transport address. The value of this 2910 attribute is 4 bytes with the following format: 2912 0 1 2 3 2913 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 2914 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2915 | Protocol | RFFU | 2916 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2918 The Protocol field specifies the desired protocol. The codepoints 2919 used in this field are taken from those allowed in the Protocol field 2920 in the IPv4 header and the NextHeader field in the IPv6 header 2921 [Protocol-Numbers]. This specification only allows the use of 2922 codepoint 17 (User Datagram Protocol). 2924 The RFFU field MUST be set to zero on transmission and MUST be 2925 ignored on reception. It is reserved for future uses. 2927 18.9. DONT-FRAGMENT 2929 This attribute is used by the client to request that the server set 2930 the DF (Don't Fragment) bit in the IP header when relaying the 2931 application data onward to the peer, and for determining the server 2932 capability in Allocate requests. This attribute has no value part 2933 and thus the attribute length field is 0. 2935 18.10. RESERVATION-TOKEN 2937 The RESERVATION-TOKEN attribute contains a token that uniquely 2938 identifies a relayed transport address being held in reserve by the 2939 server. The server includes this attribute in a success response to 2940 tell the client about the token, and the client includes this 2941 attribute in a subsequent Allocate request to request the server use 2942 that relayed transport address for the allocation. 2944 The attribute value is 8 bytes and contains the token value. 2946 18.11. ADDITIONAL-ADDRESS-FAMILY 2948 This attribute is used by clients to request the allocation of a IPv4 2949 and IPv6 address type from a server. It is encoded in the same way 2950 as REQUESTED-ADDRESS-FAMILY Section 18.6. The ADDITIONAL-ADDRESS- 2951 FAMILY attribute MAY be present in Allocate request. The attribute 2952 value of 0x02 (IPv6 address) is the only valid value in Allocate 2953 request. 2955 18.12. ADDRESS-ERROR-CODE 2957 This attribute is used by servers to signal the reason for not 2958 allocating the requested address family. The value portion of this 2959 attribute is variable length with the following format: 2961 0 1 2 3 2962 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 2963 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2964 | Family | Reserved |Class| Number | 2965 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2966 | Reason Phrase (variable) .. 2967 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2969 Family: there are two values defined for this field and specified in 2970 [I-D.ietf-tram-stunbis], Section 14.1: 0x01 for IPv4 addresses and 2971 0x02 for IPv6 addresses. 2973 Reserved: at this point, the 13 bits in the Reserved field MUST be 2974 set to zero by the server and MUST be ignored by the client. 2976 Class: The Class represents the hundreds digit of the error code and 2977 is defined in section 14.8 of [I-D.ietf-tram-stunbis]. 2979 Number: this 8-bit field contains the reason server cannot allocate 2980 one of the requested address types. The error code values could 2981 be either 440 (unsupported address family) or 508 (insufficient 2982 capacity). The number representation is defined in section 14.8 2983 of [I-D.ietf-tram-stunbis]. 2985 Reason Phrase: The recommended reason phrases for error codes 440 2986 and 508 are explained in Section 19. The reason phrase MUST be a 2987 UTF-8 [RFC3629] encoded sequence of less than 128 characters 2988 (which can be as long as 509 bytes when encoding them or 763 bytes 2989 when decoding them). 2991 18.13. ICMP 2993 This attribute is used by servers to signal the reason an UDP packet 2994 was dropped. The following is the format of the ICMP attribute. 2996 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 2997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2998 | Reserved | ICMP Type | ICMP Code | 2999 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3000 | Error Data | 3001 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3003 Reserved: This field MUST be set to 0 when sent, and MUST be ignored 3004 when received. 3006 ICMP Type: The field contains the value in the ICMP type. Its 3007 interpretation depends whether the ICMP was received over IPv4 or 3008 IPv6. 3010 ICMP Code: The field contains the value in the ICMP code. Its 3011 interpretation depends whether the ICMP was received over IPv4 or 3012 IPv6. 3014 Error Data: This field size is 4 bytes long. If the ICMPv6 type is 3015 2 (Packet Too Big Message) or ICMPv4 type is 3 ( Destination 3016 Unreachable) and Code is 4 (fragmentation needed and DF set), the 3017 Error Data field will be set to the Maximum Transmission Unit of 3018 the next-hop link (Section 3.2 of [RFC4443]) and Section 4 of 3019 [RFC1191]). For other ICMPv6 types and ICMPv4 types and codes, 3020 Error Data field MUST be set to zero. 3022 19. STUN Error Response Codes 3024 This document defines the following error response codes: 3026 403 (Forbidden): The request was valid but cannot be performed due 3027 to administrative or similar restrictions. 3029 437 (Allocation Mismatch): A request was received by the server that 3030 requires an allocation to be in place, but no allocation exists, 3031 or a request was received that requires no allocation, but an 3032 allocation exists. 3034 440 (Address Family not Supported): The server does not support the 3035 address family requested by the client. 3037 441 (Wrong Credentials): The credentials in the (non-Allocate) 3038 request do not match those used to create the allocation. 3040 442 (Unsupported Transport Protocol): The Allocate request asked the 3041 server to use a transport protocol between the server and the peer 3042 that the server does not support. NOTE: This does NOT refer to 3043 the transport protocol used in the 5-tuple. 3045 443 (Peer Address Family Mismatch). A peer address is part of a 3046 different address family than that of the relayed transport 3047 address of the allocation. 3049 486 (Allocation Quota Reached): No more allocations using this 3050 username can be created at the present time. 3052 508 (Insufficient Capacity): The server is unable to carry out the 3053 request due to some capacity limit being reached. In an Allocate 3054 response, this could be due to the server having no more relayed 3055 transport addresses available at that time, having none with the 3056 requested properties, or the one that corresponds to the specified 3057 reservation token is not available. 3059 20. Detailed Example 3061 This section gives an example of the use of TURN, showing in detail 3062 the contents of the messages exchanged. The example uses the network 3063 diagram shown in the Overview (Figure 1). 3065 For each message, the attributes included in the message and their 3066 values are shown. For convenience, values are shown in a human- 3067 readable format rather than showing the actual octets; for example, 3068 "XOR-RELAYED-ADDRESS=192.0.2.15:9000" shows that the XOR-RELAYED- 3069 ADDRESS attribute is included with an address of 192.0.2.15 and a 3070 port of 9000, here the address and port are shown before the xor-ing 3071 is done. For attributes with string-like values (e.g., 3072 SOFTWARE="Example client, version 1.03" and 3073 NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda"), the value of the attribute 3074 is shown in quotes for readability, but these quotes do not appear in 3075 the actual value. 3077 TURN TURN Peer Peer 3078 client server A B 3079 | | | | 3080 |--- Allocate request -------------->| | | 3081 | Transaction-Id=0xA56250D3F17ABE679422DE85 | | 3082 | SOFTWARE="Example client, version 1.03" | | 3083 | LIFETIME=3600 (1 hour) | | | 3084 | REQUESTED-TRANSPORT=17 (UDP) | | | 3085 | DONT-FRAGMENT | | | 3086 | | | | 3087 |<-- Allocate error response --------| | | 3088 | Transaction-Id=0xA56250D3F17ABE679422DE85 | | 3089 | SOFTWARE="Example server, version 1.17" | | 3090 | ERROR-CODE=401 (Unauthorized) | | | 3091 | REALM="example.com" | | | 3092 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3093 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3094 | | | | 3095 |--- Allocate request -------------->| | | 3096 | Transaction-Id=0xC271E932AD7446A32C234492 | | 3097 | SOFTWARE="Example client 1.03" | | | 3098 | LIFETIME=3600 (1 hour) | | | 3099 | REQUESTED-TRANSPORT=17 (UDP) | | | 3100 | DONT-FRAGMENT | | | 3101 | USERNAME="George" | | | 3102 | REALM="example.com" | | | 3103 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3104 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3105 | PASSWORD-ALGORITHM=SHA256 | | | 3106 | MESSAGE-INTEGRITY=... | | | 3107 | MESSAGE-INTEGRITY-SHA256=... | | | 3108 | | | | 3109 |<-- Allocate success response ------| | | 3110 | Transaction-Id=0xC271E932AD7446A32C234492 | | 3111 | SOFTWARE="Example server, version 1.17" | | 3112 | LIFETIME=1200 (20 minutes) | | | 3113 | XOR-RELAYED-ADDRESS=192.0.2.15:50000 | | 3114 | XOR-MAPPED-ADDRESS=192.0.2.1:7000 | | 3115 | MESSAGE-INTEGRITY-SHA256=... | | | 3117 The client begins by selecting a host transport address to use for 3118 the TURN session; in this example, the client has selected 3119 198.51.100.2:49721 as shown in Figure 1. The client then sends an 3120 Allocate request to the server at the server transport address. The 3121 client randomly selects a 96-bit transaction id of 3122 0xA56250D3F17ABE679422DE85 for this transaction; this is encoded in 3123 the transaction id field in the fixed header. The client includes a 3124 SOFTWARE attribute that gives information about the client's 3125 software; here the value is "Example client, version 1.03" to 3126 indicate that this is version 1.03 of something called the Example 3127 client. The client includes the LIFETIME attribute because it wishes 3128 the allocation to have a longer lifetime than the default of 10 3129 minutes; the value of this attribute is 3600 seconds, which 3130 corresponds to 1 hour. The client must always include a REQUESTED- 3131 TRANSPORT attribute in an Allocate request and the only value allowed 3132 by this specification is 17, which indicates UDP transport between 3133 the server and the peers. The client also includes the DONT-FRAGMENT 3134 attribute because it wishes to use the DONT-FRAGMENT attribute later 3135 in Send indications; this attribute consists of only an attribute 3136 header, there is no value part. We assume the client has not 3137 recently interacted with the server, thus the client does not include 3138 USERNAME, USERHASH, REALM, NONCE, PASSWORD-ALGORITHMS, PASSWORD- 3139 ALGORITHM, MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 attribute. 3140 Finally, note that the order of attributes in a message is arbitrary 3141 (except for the MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and 3142 FINGERPRINT attributes) and the client could have used a different 3143 order. 3145 Servers require any request to be authenticated. Thus, when the 3146 server receives the initial Allocate request, it rejects the request 3147 because the request does not contain the authentication attributes. 3148 Following the procedures of the long-term credential mechanism of 3149 STUN [I-D.ietf-tram-stunbis], the server includes an ERROR-CODE 3150 attribute with a value of 401 (Unauthorized), a REALM attribute that 3151 specifies the authentication realm used by the server (in this case, 3152 the server's domain "example.com"), and a nonce value in a NONCE 3153 attribute. The NONCE attribute starts with the "nonce cookie" with 3154 the STUN Security Feature "Password algorithm" bit set to 1. The 3155 server includes a PASSWORD-ALGORITHMS attribute that specifies the 3156 list of algorithms that the server can use to derive the long-term 3157 password. If the server sets the STUN Security Feature "Username 3158 anonymity" bit to 1 then the client uses the USERHASH attribute 3159 instead of the USERNAME attribute in the Allocate request to 3160 anonymise the username. The server also includes a SOFTWARE 3161 attribute that gives information about the server's software. 3163 The client, upon receipt of the 401 error, re-attempts the Allocate 3164 request, this time including the authentication attributes. The 3165 client selects a new transaction id, and then populates the new 3166 Allocate request with the same attributes as before. The client 3167 includes a USERNAME attribute and uses the realm value received from 3168 the server to help it determine which value to use; here the client 3169 is configured to use the username "George" for the realm 3170 "example.com". The client includes the PASSWORD-ALGORITHM attribute 3171 indicating the algorithm that the server must use to derive the long- 3172 term password. The client also includes the REALM, PASSWORD- 3173 ALGORITHMS and NONCE attributes, which are just copied from the 401 3174 error response. Finally, the client includes MESSAGE-INTEGRITY- 3175 SHA256 attribute as the last attributes in the message, whose value 3176 is Hashed Message Authentication Code - Secure Hash Algorithm 2 3177 (HMAC-SHA2) hash over the contents of the message (shown as just 3178 "..." above); this HMAC-SHA2 computation includes a password value. 3179 Thus, an attacker cannot compute the message integrity value without 3180 somehow knowing the secret password. 3182 The server, upon receipt of the authenticated Allocate request, 3183 checks that everything is OK, then creates an allocation. The server 3184 replies with an Allocate success response. The server includes a 3185 LIFETIME attribute giving the lifetime of the allocation; here, the 3186 server has reduced the client's requested 1-hour lifetime to just 20 3187 minutes, because this particular server doesn't allow lifetimes 3188 longer than 20 minutes. The server includes an XOR-RELAYED-ADDRESS 3189 attribute whose value is the relayed transport address of the 3190 allocation. The server includes an XOR-MAPPED-ADDRESS attribute 3191 whose value is the server-reflexive address of the client; this value 3192 is not used otherwise in TURN but is returned as a convenience to the 3193 client. The server includes a MESSAGE-INTEGRITY-SHA256 attribute to 3194 authenticate the response and to ensure its integrity; note that the 3195 response does not contain the USERNAME, REALM, and NONCE attributes. 3196 The server also includes a SOFTWARE attribute. 3198 TURN TURN Peer Peer 3199 client server A B 3200 |--- CreatePermission request ------>| | | 3201 | Transaction-Id=0xE5913A8F460956CA277D3319 | | 3202 | XOR-PEER-ADDRESS=192.0.2.150:0 | | | 3203 | USERNAME="George" | | | 3204 | REALM="example.com" | | | 3205 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3206 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3207 | PASSWORD-ALGORITHM=SHA256 | | | 3208 | MESSAGE-INTEGRITY-SHA256=... | | | 3209 | | | | 3210 |<-- CreatePermission success resp.--| | | 3211 | Transaction-Id=0xE5913A8F460956CA277D3319 | | 3212 | MESSAGE-INTEGRITY-SHA256=... | | | 3214 The client then creates a permission towards Peer A in preparation 3215 for sending it some application data. This is done through a 3216 CreatePermission request. The XOR-PEER-ADDRESS attribute contains 3217 the IP address for which a permission is established (the IP address 3218 of peer A); note that the port number in the attribute is ignored 3219 when used in a CreatePermission request, and here it has been set to 3220 0; also, note how the client uses Peer A's server-reflexive IP 3221 address and not its (private) host address. The client uses the same 3222 username, realm, and nonce values as in the previous request on the 3223 allocation. Though it is allowed to do so, the client has chosen not 3224 to include a SOFTWARE attribute in this request. 3226 The server receives the CreatePermission request, creates the 3227 corresponding permission, and then replies with a CreatePermission 3228 success response. Like the client, the server chooses not to include 3229 the SOFTWARE attribute in its reply. Again, note how success 3230 responses contains a MESSAGE-INTEGRITY-SHA256 attribute (assuming the 3231 server uses the long-term credential mechanism), but no USERNAME, 3232 REALM, and NONCE attributes. 3234 TURN TURN Peer Peer 3235 client server A B 3236 |--- Send indication --------------->| | | 3237 | Transaction-Id=0x1278E9ACA2711637EF7D3328 | | 3238 | XOR-PEER-ADDRESS=192.0.2.150:32102 | | 3239 | DONT-FRAGMENT | | | 3240 | DATA=... | | | 3241 | |-- UDP dgm ->| | 3242 | | data=... | | 3243 | | | | 3244 | |<- UDP dgm --| | 3245 | | data=... | | 3246 |<-- Data indication ----------------| | | 3247 | Transaction-Id=0x8231AE8F9242DA9FF287FEFF | | 3248 | XOR-PEER-ADDRESS=192.0.2.150:32102 | | 3249 | DATA=... | | | 3251 The client now sends application data to Peer A using a Send 3252 indication. Peer A's server-reflexive transport address is specified 3253 in the XOR-PEER-ADDRESS attribute, and the application data (shown 3254 here as just "...") is specified in the DATA attribute. The client 3255 is doing a form of path MTU discovery at the application layer and 3256 thus specifies (by including the DONT-FRAGMENT attribute) that the 3257 server should set the DF bit in the UDP datagram to send to the peer. 3258 Indications cannot be authenticated using the long-term credential 3259 mechanism of STUN, so no MESSAGE-INTEGRITY or MESSAGE-INTEGRITY- 3260 SHA256 attribute is included in the message. An application wishing 3261 to ensure that its data is not altered or forged must integrity- 3262 protect its data at the application level. 3264 Upon receipt of the Send indication, the server extracts the 3265 application data and sends it in a UDP datagram to Peer A, with the 3266 relayed transport address as the source transport address of the 3267 datagram, and with the DF bit set as requested. Note that, had the 3268 client not previously established a permission for Peer A's server- 3269 reflexive IP address, then the server would have silently discarded 3270 the Send indication instead. 3272 Peer A then replies with its own UDP datagram containing application 3273 data. The datagram is sent to the relayed transport address on the 3274 server. When this arrives, the server creates a Data indication 3275 containing the source of the UDP datagram in the XOR-PEER-ADDRESS 3276 attribute, and the data from the UDP datagram in the DATA attribute. 3277 The resulting Data indication is then sent to the client. 3279 TURN TURN Peer Peer 3280 client server A B 3281 |--- ChannelBind request ----------->| | | 3282 | Transaction-Id=0x6490D3BC175AFF3D84513212 | | 3283 | CHANNEL-NUMBER=0x4000 | | | 3284 | XOR-PEER-ADDRESS=192.0.2.210:49191 | | 3285 | USERNAME="George" | | | 3286 | REALM="example.com" | | | 3287 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3288 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3289 | PASSWORD-ALGORITHM=SHA256 | | | 3290 | MESSAGE-INTEGRITY-SHA256=... | | | 3291 | | | | 3292 |<-- ChannelBind success response ---| | | 3293 | Transaction-Id=0x6490D3BC175AFF3D84513212 | | 3294 | MESSAGE-INTEGRITY-SHA256=... | | | 3296 The client now binds a channel to Peer B, specifying a free channel 3297 number (0x4000) in the CHANNEL-NUMBER attribute, and Peer B's 3298 transport address in the XOR-PEER-ADDRESS attribute. As before, the 3299 client re-uses the username, realm, and nonce from its last request 3300 in the message. 3302 Upon receipt of the request, the server binds the channel number to 3303 the peer, installs a permission for Peer B's IP address, and then 3304 replies with ChannelBind success response. 3306 TURN TURN Peer Peer 3307 client server A B 3308 |--- ChannelData ------------------->| | | 3309 | Channel-number=0x4000 |--- UDP datagram --------->| 3310 | Data=... | Data=... | 3311 | | | | 3312 | |<-- UDP datagram ----------| 3313 | | Data=... | | 3314 |<-- ChannelData --------------------| | | 3315 | Channel-number=0x4000 | | | 3316 | Data=... | | | 3318 The client now sends a ChannelData message to the server with data 3319 destined for Peer B. The ChannelData message is not a STUN message, 3320 and thus has no transaction id. Instead, it has only three fields: a 3321 channel number, data, and data length; here the channel number field 3322 is 0x4000 (the channel the client just bound to Peer B). When the 3323 server receives the ChannelData message, it checks that the channel 3324 is currently bound (which it is) and then sends the data onward to 3325 Peer B in a UDP datagram, using the relayed transport address as the 3326 source transport address and 192.0.2.210:49191 (the value of the XOR- 3327 PEER-ADDRESS attribute in the ChannelBind request) as the destination 3328 transport address. 3330 Later, Peer B sends a UDP datagram back to the relayed transport 3331 address. This causes the server to send a ChannelData message to the 3332 client containing the data from the UDP datagram. The server knows 3333 to which client to send the ChannelData message because of the 3334 relayed transport address at which the UDP datagram arrived, and 3335 knows to use channel 0x4000 because this is the channel bound to 3336 192.0.2.210:49191. Note that if there had not been any channel 3337 number bound to that address, the server would have used a Data 3338 indication instead. 3340 TURN TURN Peer Peer 3341 client server A B 3342 |--- ChannelBind request ----------->| | | 3343 | Transaction-Id=0xE5913A8F46091637EF7D3328 | | 3344 | CHANNEL-NUMBER=0x4000 | | | 3345 | XOR-PEER-ADDRESS=192.0.2.210:49191 | | 3346 | USERNAME="George" | | | 3347 | REALM="example.com" | | | 3348 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3349 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3350 | PASSWORD-ALGORITHM=SHA256 | | | 3351 | MESSAGE-INTEGRITY-SHA256=... | | | 3352 | | | | 3353 |<-- ChannelBind success response ---| | | 3354 | Transaction-Id=0xE5913A8F46091637EF7D3328 | | 3355 | MESSAGE-INTEGRITY-SHA256=... | | | 3357 The channel binding lasts for 10 minutes unless refreshed. The TURN 3358 client refreshes the binding by sending ChannelBind request rebinding 3359 the channel to the same peer (Peer B's IP address). The server 3360 processes the ChannelBind request, rebinds the channel to the same 3361 peer and resets the time-to-expiry timer back to 10 minutes. 3363 TURN TURN Peer Peer 3364 client server A B 3365 |--- Refresh request --------------->| | | 3366 | Transaction-Id=0x0864B3C27ADE9354B4312414 | | 3367 | SOFTWARE="Example client 1.03" | | | 3368 | USERNAME="George" | | | 3369 | REALM="example.com" | | | 3370 | NONCE="oobMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3371 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3372 | PASSWORD-ALGORITHM=SHA256 | | | 3373 | MESSAGE-INTEGRITY-SHA256=... | | | 3374 | | | | 3375 |<-- Refresh error response ---------| | | 3376 | Transaction-Id=0x0864B3C27ADE9354B4312414 | | 3377 | SOFTWARE="Example server, version 1.17" | | 3378 | ERROR-CODE=438 (Stale Nonce) | | | 3379 | REALM="example.com" | | | 3380 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3381 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3382 | | | | 3383 |--- Refresh request --------------->| | | 3384 | Transaction-Id=0x427BD3E625A85FC731DC4191 | | 3385 | SOFTWARE="Example client 1.03" | | | 3386 | USERNAME="George" | | | 3387 | REALM="example.com" | | | 3388 | NONCE="obMatJos2gAAAadl7W7PeDU4hKE72jda" | | 3389 | PASSWORD-ALGORITHMS=MD5 and SHA256 | | 3390 | PASSWORD-ALGORITHM=SHA256 | | | 3391 | MESSAGE-INTEGRITY-SHA256=... | | | 3392 | | | | 3393 |<-- Refresh success response -------| | | 3394 | Transaction-Id=0x427BD3E625A85FC731DC4191 | | 3395 | SOFTWARE="Example server, version 1.17" | | 3396 | LIFETIME=600 (10 minutes) | | | 3398 Sometime before the 20 minute lifetime is up, the client refreshes 3399 the allocation. This is done using a Refresh request. As before, 3400 the client includes the latest username, realm, and nonce values in 3401 the request. The client also includes the SOFTWARE attribute, 3402 following the recommended practice of always including this attribute 3403 in Allocate and Refresh messages. When the server receives the 3404 Refresh request, it notices that the nonce value has expired, and so 3405 replies with 438 (Stale Nonce) error given a new nonce value. The 3406 client then reattempts the request, this time with the new nonce 3407 value. This second attempt is accepted, and the server replies with 3408 a success response. Note that the client did not include a LIFETIME 3409 attribute in the request, so the server refreshes the allocation for 3410 the default lifetime of 10 minutes (as can be seen by the LIFETIME 3411 attribute in the success response). 3413 21. Security Considerations 3415 This section considers attacks that are possible in a TURN 3416 deployment, and discusses how they are mitigated by mechanisms in the 3417 protocol or recommended practices in the implementation. 3419 Most of the attacks on TURN are mitigated by the server requiring 3420 requests be authenticated. Thus, this specification requires the use 3421 of authentication. The mandatory-to-implement mechanism is the long- 3422 term credential mechanism of STUN. Other authentication mechanisms 3423 of equal or stronger security properties may be used. However, it is 3424 important to ensure that they can be invoked in an inter-operable 3425 way. 3427 21.1. Outsider Attacks 3429 Outsider attacks are ones where the attacker has no credentials in 3430 the system, and is attempting to disrupt the service seen by the 3431 client or the server. 3433 21.1.1. Obtaining Unauthorized Allocations 3435 An attacker might wish to obtain allocations on a TURN server for any 3436 number of nefarious purposes. A TURN server provides a mechanism for 3437 sending and receiving packets while cloaking the actual IP address of 3438 the client. This makes TURN servers an attractive target for 3439 attackers who wish to use it to mask their true identity. 3441 An attacker might also wish to simply utilize the services of a TURN 3442 server without paying for them. Since TURN services require 3443 resources from the provider, it is anticipated that their usage will 3444 come with a cost. 3446 These attacks are prevented using the long-term credential mechanism, 3447 which allows the TURN server to determine the identity of the 3448 requestor and whether the requestor is allowed to obtain the 3449 allocation. 3451 21.1.2. Offline Dictionary Attacks 3453 The long-term credential mechanism used by TURN is subject to offline 3454 dictionary attacks. An attacker that is capable of eavesdropping on 3455 a message exchange between a client and server can determine the 3456 password by trying a number of candidate passwords and seeing if one 3457 of them is correct. This attack works when the passwords are low 3458 entropy, such as a word from the dictionary. This attack can be 3459 mitigated by using strong passwords with large entropy. In 3460 situations where even stronger mitigation is required, (D)TLS 3461 transport between the client and the server can be used. 3463 21.1.3. Faked Refreshes and Permissions 3465 An attacker might wish to attack an active allocation by sending it a 3466 Refresh request with an immediate expiration, in order to delete it 3467 and disrupt service to the client. This is prevented by 3468 authentication of refreshes. Similarly, an attacker wishing to send 3469 CreatePermission requests to create permissions to undesirable 3470 destinations is prevented from doing so through authentication. The 3471 motivations for such an attack are described in Section 21.2. 3473 21.1.4. Fake Data 3475 An attacker might wish to send data to the client or the peer, as if 3476 they came from the peer or client, respectively. To do that, the 3477 attacker can send the client a faked Data Indication or ChannelData 3478 message, or send the TURN server a faked Send Indication or 3479 ChannelData message. 3481 Since indications and ChannelData messages are not authenticated, 3482 this attack is not prevented by TURN. However, this attack is 3483 generally present in IP-based communications and is not substantially 3484 worsened by TURN. Consider a normal, non-TURN IP session between 3485 hosts A and B. An attacker can send packets to B as if they came 3486 from A by sending packets towards B with a spoofed IP address of A. 3487 This attack requires the attacker to know the IP addresses of A and 3488 B. With TURN, an attacker wishing to send packets towards a client 3489 using a Data indication needs to know its IP address (and port), the 3490 IP address and port of the TURN server, and the IP address and port 3491 of the peer (for inclusion in the XOR-PEER-ADDRESS attribute). To 3492 send a fake ChannelData message to a client, an attacker needs to 3493 know the IP address and port of the client, the IP address and port 3494 of the TURN server, and the channel number. This particular 3495 combination is mildly more guessable than in the non-TURN case. 3497 These attacks are more properly mitigated by application-layer 3498 authentication techniques. In the case of real-time traffic, usage 3499 of SRTP [RFC3711] prevents these attacks. 3501 In some situations, the TURN server may be situated in the network 3502 such that it is able to send to hosts to which the client cannot 3503 directly send. This can happen, for example, if the server is 3504 located behind a firewall that allows packets from outside the 3505 firewall to be delivered to the server, but not to other hosts behind 3506 the firewall. In these situations, an attacker could send the server 3507 a Send indication with an XOR-PEER-ADDRESS attribute containing the 3508 transport address of one of the other hosts behind the firewall. If 3509 the server was to allow relaying of traffic to arbitrary peers, then 3510 this would provide a way for the attacker to attack arbitrary hosts 3511 behind the firewall. 3513 To mitigate this attack, TURN requires that the client establish a 3514 permission to a host before sending it data. Thus, an attacker can 3515 only attack hosts with which the client is already communicating, 3516 unless the attacker is able to create authenticated requests. 3517 Furthermore, the server administrator may configure the server to 3518 restrict the range of IP addresses and ports to which it will relay 3519 data. To provide even greater security, the server administrator can 3520 require that the client use (D)TLS for all communication between the 3521 client and the server. 3523 21.1.5. Impersonating a Server 3525 When a client learns a relayed address from a TURN server, it uses 3526 that relayed address in application protocols to receive traffic. 3527 Therefore, an attacker wishing to intercept or redirect that traffic 3528 might try to impersonate a TURN server and provide the client with a 3529 faked relayed address. 3531 This attack is prevented through the long-term credential mechanism, 3532 which provides message integrity for responses in addition to 3533 verifying that they came from the server. Furthermore, an attacker 3534 cannot replay old server responses as the transaction id in the STUN 3535 header prevents this. Replay attacks are further thwarted through 3536 frequent changes to the nonce value. 3538 21.1.6. Eavesdropping Traffic 3540 If the TURN client and server use the STUN Extension for Third-Party 3541 Authorization [RFC7635] (for example it is used in WebRTC), the 3542 username does not reveal the real user's identity, the USERNAME 3543 attribute carries an ephemeral and unique key identifier. If the 3544 TURN client and server use the STUN long-term credential mechanism 3545 and the username reveals the real user's identity, the client MUST 3546 either use the USERHASH attribute instead of the USERNAME attribute 3547 to anonynmize the username or use (D)TLS transport between the client 3548 and the server. 3550 If the TURN client and server use the STUN long-term credential 3551 mechanism and realm information is privacy sensitive, TURN can be run 3552 over (D)TLS. As a reminder, STUN Extension for Third-Party 3553 Authorization does not use realm. 3555 The SOFTWARE attribute can reveal the specific software version of 3556 the TURN client and server to eavesdropper and it might possibly 3557 allow attacks against vulnerable software that is known to contain 3558 security vulnerabilities. If the software version is known to 3559 contain security vulnerabilities, TURN SHOULD be run over (D)TLS to 3560 prevent leaking the SOFTWARE attribute in clear text. If zero-day 3561 vulnerabilities are detected in the software version, the endpoint 3562 policy can be modified to mandate the use of (D)TLS till the patch is 3563 in place to fix the flaw. 3565 TURN concerns itself primarily with authentication and message 3566 integrity. Confidentiality is only a secondary concern, as TURN 3567 control messages do not include information that is particularly 3568 sensitive, with the exception of USERNAME, REALM and SOFTWARE. The 3569 primary protocol content of the messages is the IP address of the 3570 peer. If it is important to prevent an eavesdropper on a TURN 3571 connection from learning this, TURN can be run over (D)TLS. 3573 Confidentiality for the application data relayed by TURN is best 3574 provided by the application protocol itself, since running TURN over 3575 (D)TLS does not protect application data between the server and the 3576 peer. If confidentiality of application data is important, then the 3577 application should encrypt or otherwise protect its data. For 3578 example, for real-time media, confidentiality can be provided by 3579 using SRTP. 3581 21.1.7. TURN Loop Attack 3583 An attacker might attempt to cause data packets to loop indefinitely 3584 between two TURN servers. The attack goes as follows. First, the 3585 attacker sends an Allocate request to server A, using the source 3586 address of server B. Server A will send its response to server B, 3587 and for the attack to succeed, the attacker must have the ability to 3588 either view or guess the contents of this response, so that the 3589 attacker can learn the allocated relayed transport address. The 3590 attacker then sends an Allocate request to server B, using the source 3591 address of server A. Again, the attacker must be able to view or 3592 guess the contents of the response, so it can send learn the 3593 allocated relayed transport address. Using the same spoofed source 3594 address technique, the attacker then binds a channel number on server 3595 A to the relayed transport address on server B, and similarly binds 3596 the same channel number on server B to the relayed transport address 3597 on server A. Finally, the attacker sends a ChannelData message to 3598 server A. 3600 The result is a data packet that loops from the relayed transport 3601 address on server A to the relayed transport address on server B, 3602 then from server B's transport address to server A's transport 3603 address, and then around the loop again. 3605 This attack is mitigated as follows. By requiring all requests to be 3606 authenticated and/or by randomizing the port number allocated for the 3607 relayed transport address, the server forces the attacker to either 3608 intercept or view responses sent to a third party (in this case, the 3609 other server) so that the attacker can authenticate the requests and 3610 learn the relayed transport address. Without one of these two 3611 measures, an attacker can guess the contents of the responses without 3612 needing to see them, which makes the attack much easier to perform. 3613 Furthermore, by requiring authenticated requests, the server forces 3614 the attacker to have credentials acceptable to the server, which 3615 turns this from an outsider attack into an insider attack and allows 3616 the attack to be traced back to the client initiating it. 3618 The attack can be further mitigated by imposing a per-username limit 3619 on the bandwidth used to relay data by allocations owned by that 3620 username, to limit the impact of this attack on other allocations. 3621 More mitigation can be achieved by decrementing the TTL when relaying 3622 data packets (if the underlying OS allows this). 3624 21.2. Firewall Considerations 3626 A key security consideration of TURN is that TURN should not weaken 3627 the protections afforded by firewalls deployed between a client and a 3628 TURN server. It is anticipated that TURN servers will often be 3629 present on the public Internet, and clients may often be inside 3630 enterprise networks with corporate firewalls. If TURN servers 3631 provide a 'backdoor' for reaching into the enterprise, TURN will be 3632 blocked by these firewalls. 3634 TURN servers therefore emulate the behavior of NAT devices that 3635 implement address-dependent filtering [RFC4787], a property common in 3636 many firewalls as well. When a NAT or firewall implements this 3637 behavior, packets from an outside IP address are only allowed to be 3638 sent to an internal IP address and port if the internal IP address 3639 and port had recently sent a packet to that outside IP address. TURN 3640 servers introduce the concept of permissions, which provide exactly 3641 this same behavior on the TURN server. An attacker cannot send a 3642 packet to a TURN server and expect it to be relayed towards the 3643 client, unless the client has tried to contact the attacker first. 3645 It is important to note that some firewalls have policies that are 3646 even more restrictive than address-dependent filtering. Firewalls 3647 can also be configured with address- and port-dependent filtering, or 3648 can be configured to disallow inbound traffic entirely. In these 3649 cases, if a client is allowed to connect the TURN server, 3650 communications to the client will be less restrictive than what the 3651 firewall would normally allow. 3653 21.2.1. Faked Permissions 3655 In firewalls and NAT devices, permissions are granted implicitly 3656 through the traversal of a packet from the inside of the network 3657 towards the outside peer. Thus, a permission cannot, by definition, 3658 be created by any entity except one inside the firewall or NAT. With 3659 TURN, this restriction no longer holds. Since the TURN server sits 3660 outside the firewall, at attacker outside the firewall can now send a 3661 message to the TURN server and try to create a permission for itself. 3663 This attack is prevented because all messages that create permissions 3664 (i.e., ChannelBind and CreatePermission) are authenticated. 3666 21.2.2. Blacklisted IP Addresses 3668 Many firewalls can be configured with blacklists that prevent a 3669 client behind the firewall from sending packets to, or receiving 3670 packets from, ranges of blacklisted IP addresses. This is 3671 accomplished by inspecting the source and destination addresses of 3672 packets entering and exiting the firewall, respectively. 3674 This feature is also present in TURN, since TURN servers are allowed 3675 to arbitrarily restrict the range of addresses of peers that they 3676 will relay to. 3678 21.2.3. Running Servers on Well-Known Ports 3680 A malicious client behind a firewall might try to connect to a TURN 3681 server and obtain an allocation which it then uses to run a server. 3682 For example, a client might try to run a DNS server or FTP server. 3684 This is not possible in TURN. A TURN server will never accept 3685 traffic from a peer for which the client has not installed a 3686 permission. Thus, peers cannot just connect to the allocated port in 3687 order to obtain the service. 3689 21.3. Insider Attacks 3691 In insider attacks, a client has legitimate credentials but defies 3692 the trust relationship that goes with those credentials. These 3693 attacks cannot be prevented by cryptographic means but need to be 3694 considered in the design of the protocol. 3696 21.3.1. DoS against TURN Server 3698 A client wishing to disrupt service to other clients might obtain an 3699 allocation and then flood it with traffic, in an attempt to swamp the 3700 server and prevent it from servicing other legitimate clients. This 3701 is mitigated by the recommendation that the server limit the amount 3702 of bandwidth it will relay for a given username. This won't prevent 3703 a client from sending a large amount of traffic, but it allows the 3704 server to immediately discard traffic in excess. 3706 Since each allocation uses a port number on the IP address of the 3707 TURN server, the number of allocations on a server is finite. An 3708 attacker might attempt to consume all of them by requesting a large 3709 number of allocations. This is prevented by the recommendation that 3710 the server impose a limit of the number of allocations active at a 3711 time for a given username. 3713 21.3.2. Anonymous Relaying of Malicious Traffic 3715 TURN servers provide a degree of anonymization. A client can send 3716 data to peers without revealing its own IP address. TURN servers may 3717 therefore become attractive vehicles for attackers to launch attacks 3718 against targets without fear of detection. Indeed, it is possible 3719 for a client to chain together multiple TURN servers, such that any 3720 number of relays can be used before a target receives a packet. 3722 Administrators who are worried about this attack can maintain logs 3723 that capture the actual source IP and port of the client, and perhaps 3724 even every permission that client installs. This will allow for 3725 forensic tracing to determine the original source, should it be 3726 discovered that an attack is being relayed through a TURN server. 3728 21.3.3. Manipulating Other Allocations 3730 An attacker might attempt to disrupt service to other users of the 3731 TURN server by sending Refresh requests or CreatePermission requests 3732 that (through source address spoofing) appear to be coming from 3733 another user of the TURN server. TURN prevents this by requiring 3734 that the credentials used in CreatePermission, Refresh, and 3735 ChannelBind messages match those used to create the initial 3736 allocation. Thus, the fake requests from the attacker will be 3737 rejected. 3739 21.4. Tunnel Amplification Attack 3741 An attacker might attempt to cause data packets to loop numerous 3742 times between a TURN server and a tunnel between IPv4 and IPv6. The 3743 attack goes as follows. 3745 Suppose an attacker knows that a tunnel endpoint will forward 3746 encapsulated packets from a given IPv6 address (this doesn't 3747 necessarily need to be the tunnel endpoint's address). Suppose he 3748 then spoofs two packets from this address: 3750 1. An Allocate request asking for a v4 address, and 3752 2. A ChannelBind request establishing a channel to the IPv4 address 3753 of the tunnel endpoint 3755 Then he has set up an amplification attack: 3757 o The TURN server will re-encapsulate IPv6 UDP data in v4 and send 3758 it to the tunnel endpoint 3760 o The tunnel endpoint will de-encapsulate packets from the v4 3761 interface and send them to v6 3763 So if the attacker sends a packet of the following form... 3765 IPv6: src=2001:DB8:1::1 dst=2001:DB8::2 3766 UDP: 3767 TURN: 3768 IPv6: src=2001:DB8:1::1 dst=2001:DB8::2 3769 UDP: 3770 TURN: 3771 IPv6: src=2001:DB8:1::1 dst=2001:DB8::2 3772 UDP: 3773 TURN: 3774 ... 3776 Then the TURN server and the tunnel endpoint will send it back and 3777 forth until the last TURN header is consumed, at which point the TURN 3778 server will send an empty packet, which the tunnel endpoint will 3779 drop. 3781 The amplification potential here is limited by the MTU, so it's not 3782 huge: IPv6+UDP+TURN takes 334 bytes, so a four-to-one amplification 3783 out of a 1500-byte packet is possible. But the attacker could still 3784 increase traffic volume by sending multiple packets or by 3785 establishing multiple channels spoofed from different addresses 3786 behind the same tunnel endpoint. 3788 The attack is mitigated as follows. It is RECOMMENDED that TURN 3789 servers not accept allocation or channel binding requests from 3790 addresses known to be tunneled, and that they not forward data to 3791 such addresses. In particular, a TURN server MUST NOT accept Teredo 3792 or 6to4 addresses in these requests. 3794 21.5. Other Considerations 3796 Any relay addresses learned through an Allocate request will not 3797 operate properly with IPsec Authentication Header (AH) [RFC4302] in 3798 transport or tunnel mode. However, tunnel-mode IPsec Encapsulating 3799 Security Payload (ESP) [RFC4303] should still operate. 3801 22. IANA Considerations 3803 [Paragraphs in braces should be removed by the RFC Editor upon 3804 publication] 3806 The codepoints for the STUN methods defined in this specification are 3807 listed in Section 17. [IANA is requested to update the reference 3808 from [RFC5766] to RFC-to-be for the STUN methods listed in 3809 Section 17.] 3811 The codepoints for the STUN attributes defined in this specification 3812 are listed in Section 18. [IANA is requested to update the reference 3813 from [RFC5766] to RFC-to-be for the STUN attributes CHANNEL-NUMBER, 3814 LIFETIME, Reserved (was BANDWIDTH), XOR-PEER-ADDRESS, DATA, XOR- 3815 RELAYED-ADDRESS, REQUESTED-ADDRESS-FAMILY, EVEN-PORT, REQUESTED- 3816 TRANSPORT, DONT-FRAGMENT, Reserved (was TIMER-VAL) and RESERVATION- 3817 TOKEN listed in Section 18.] 3819 [The ADDITIONAL-ADDRESS-FAMILY, ADDRESS-ERROR-CODE and ICMP 3820 attributes requires that IANA allocate a value in the "STUN 3821 attributes Registry" from the comprehension-optional range 3822 (0x8000-0xFFFF), to be replaced for TBD-CA throughout this document] 3824 The codepoints for the STUN error codes defined in this specification 3825 are listed in Section 19. [IANA is requested to update the reference 3826 from [RFC5766] and [RFC6156] to RFC-to-be for the STUN error codes 3827 listed in Section 19.] 3829 IANA has allocated the SRV service name of "turn" for TURN over UDP 3830 or TCP, and the service name of "turns" for TURN over (D)TLS. 3832 IANA has created a registry for TURN channel numbers, initially 3833 populated as follows: 3835 o 0x0000 through 0x3FFF: Reserved and not available for use, since 3836 they conflict with the STUN header. 3838 o 0x4000 through 0x4FFF: A TURN implementation is free to use 3839 channel numbers in this range. 3841 o 0x5000 through 0xFFFF: Unassigned. 3843 Any change to this registry must be made through an IETF Standards 3844 Action. 3846 23. IAB Considerations 3848 The IAB has studied the problem of "Unilateral Self Address Fixing" 3849 (UNSAF), which is the general process by which a client attempts to 3850 determine its address in another realm on the other side of a NAT 3851 through a collaborative protocol-reflection mechanism [RFC3424]. The 3852 TURN extension is an example of a protocol that performs this type of 3853 function. The IAB has mandated that any protocols developed for this 3854 purpose document a specific set of considerations. These 3855 considerations and the responses for TURN are documented in this 3856 section. 3858 Consideration 1: Precise definition of a specific, limited-scope 3859 problem that is to be solved with the UNSAF proposal. A short-term 3860 fix should not be generalized to solve other problems. Such 3861 generalizations lead to the prolonged dependence on and usage of the 3862 supposed short-term fix -- meaning that it is no longer accurate to 3863 call it "short-term". 3865 Response: TURN is a protocol for communication between a relay (= 3866 TURN server) and its client. The protocol allows a client that is 3867 behind a NAT to obtain and use a public IP address on the relay. As 3868 a convenience to the client, TURN also allows the client to determine 3869 its server-reflexive transport address. 3871 Consideration 2: Description of an exit strategy/transition plan. 3872 The better short-term fixes are the ones that will naturally see less 3873 and less use as the appropriate technology is deployed. 3875 Response: TURN will no longer be needed once there are no longer any 3876 NATs. Unfortunately, as of the date of publication of this document, 3877 it no longer seems very likely that NATs will go away any time soon. 3878 However, the need for TURN will also decrease as the number of NATs 3879 with the mapping property of Endpoint-Independent Mapping [RFC4787] 3880 increases. 3882 Consideration 3: Discussion of specific issues that may render 3883 systems more "brittle". For example, approaches that involve using 3884 data at multiple network layers create more dependencies, increase 3885 debugging challenges, and make it harder to transition. 3887 Response: TURN is "brittle" in that it requires the NAT bindings 3888 between the client and the server to be maintained unchanged for the 3889 lifetime of the allocation. This is typically done using keep- 3890 alives. If this is not done, then the client will lose its 3891 allocation and can no longer exchange data with its peers. 3893 Consideration 4: Identify requirements for longer-term, sound 3894 technical solutions; contribute to the process of finding the right 3895 longer-term solution. 3897 Response: The need for TURN will be reduced once NATs implement the 3898 recommendations for NAT UDP behavior documented in [RFC4787]. 3899 Applications are also strongly urged to use ICE [RFC8445] to 3900 communicate with peers; though ICE uses TURN, it does so only as a 3901 last resort, and uses it in a controlled manner. 3903 Consideration 5: Discussion of the impact of the noted practical 3904 issues with existing deployed NATs and experience reports. 3906 Response: Some NATs deployed today exhibit a mapping behavior other 3907 than Endpoint-Independent mapping. These NATs are difficult to work 3908 with, as they make it difficult or impossible for protocols like ICE 3909 to use server-reflexive transport addresses on those NATs. A client 3910 behind such a NAT is often forced to use a relay protocol like TURN 3911 because "UDP hole punching" techniques [RFC5128] do not work. 3913 24. Changes since RFC 5766 3915 This section lists the major changes in the TURN protocol from the 3916 original [RFC5766] specification. 3918 o IPv6 support. 3920 o REQUESTED-ADDRESS-FAMILY attribute. 3922 o Description of the tunnel amplification attack. 3924 o DTLS support. 3926 o Add support for receiving ICMP packets. 3928 o Updates PMTUD. 3930 o Discovery of TURN server. 3932 o TURN URI Scheme Semantics. 3934 o Happy Eyeballs for TURN. 3936 o Align with the changes in STUNbis. 3938 25. Updates to RFC 6156 3940 This section lists the major updates to [RFC6156] in this 3941 specification. 3943 o ADDITIONAL-ADDRESS-FAMILY, AND ADDRESS-ERR-CODE attributes. 3945 o 440 (Address Family not Supported) and 443 (Peer Address Family 3946 Mismatch) responses. 3948 o More details on packet translation. 3950 o TCP-to-UDP and UDP-to-TCP relaying. 3952 26. Acknowledgements 3954 Most of the text in this note comes from the original TURN 3955 specification, [RFC5766]. The authors would like to thank Rohan Mahy 3956 co-author of original TURN specification and everyone who had 3957 contributed to that document. The authors would also like to 3958 acknowledge that this document inherits material from [RFC6156]. 3960 Thanks to Justin Uberti, Pal Martinsen, Oleg Moskalenko, Aijun Wang 3961 and Simon Perreault for their help on the ADDITIONAL-ADDRESS-FAMILY 3962 mechanism. Authors would like to thank Gonzalo Salgueiro, Simon 3963 Perreault, Jonathan Lennox, Brandon Williams, Karl Stahl, Noriyuki 3964 Torii, Nils Ohlmeier, Dan Wing, Vijay Gurbani, Joseph Touch, Justin 3965 Uberti, Christopher Wood, Roman Danyliw, Eric Vyncke, Adam Roach, 3966 Mirja Kuehlewind, Benjamin Kaduk and Oleg Moskalenko for comments and 3967 review. The authors would like to thank Marc for his contributions 3968 to the text. 3970 Special thanks to Magnus Westerlund for the detailed AD review. 3972 27. References 3974 27.1. Normative References 3976 [I-D.ietf-tram-stunbis] 3977 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 3978 D., Mahy, R., and P. Matthews, "Session Traversal 3979 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-21 3980 (work in progress), March 2019. 3982 [Protocol-Numbers] 3983 "IANA Protocol Numbers Registry", 2005, 3984 . 3986 [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, 3987 RFC 792, DOI 10.17487/RFC0792, September 1981, 3988 . 3990 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 3991 Communication Layers", STD 3, RFC 1122, 3992 DOI 10.17487/RFC1122, October 1989, 3993 . 3995 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3996 Requirement Levels", BCP 14, RFC 2119, 3997 DOI 10.17487/RFC2119, March 1997, 3998 . 4000 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 4001 "Definition of the Differentiated Services Field (DS 4002 Field) in the IPv4 and IPv6 Headers", RFC 2474, 4003 DOI 10.17487/RFC2474, December 1998, 4004 . 4006 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 4007 of Explicit Congestion Notification (ECN) to IP", 4008 RFC 3168, DOI 10.17487/RFC3168, September 2001, 4009 . 4011 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4012 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 4013 2003, . 4015 [RFC4443] Conta, A., Deering, S., and M. Gupta, Ed., "Internet 4016 Control Message Protocol (ICMPv6) for the Internet 4017 Protocol Version 6 (IPv6) Specification", STD 89, 4018 RFC 4443, DOI 10.17487/RFC4443, March 2006, 4019 . 4021 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4022 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4023 January 2012, . 4025 [RFC6437] Amante, S., Carpenter, B., Jiang, S., and J. Rajahalme, 4026 "IPv6 Flow Label Specification", RFC 6437, 4027 DOI 10.17487/RFC6437, November 2011, 4028 . 4030 [RFC7065] Petit-Huguenin, M., Nandakumar, S., Salgueiro, G., and P. 4031 Jones, "Traversal Using Relays around NAT (TURN) Uniform 4032 Resource Identifiers", RFC 7065, DOI 10.17487/RFC7065, 4033 November 2013, . 4035 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 4036 Layer Security (DTLS) as Transport for Session Traversal 4037 Utilities for NAT (STUN)", RFC 7350, DOI 10.17487/RFC7350, 4038 August 2014, . 4040 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4041 "Recommendations for Secure Use of Transport Layer 4042 Security (TLS) and Datagram Transport Layer Security 4043 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4044 2015, . 4046 [RFC7915] Bao, C., Li, X., Baker, F., Anderson, T., and F. Gont, 4047 "IP/ICMP Translation Algorithm", RFC 7915, 4048 DOI 10.17487/RFC7915, June 2016, 4049 . 4051 [RFC7982] Martinsen, P., Reddy, T., Wing, D., and V. Singh, 4052 "Measurement of Round-Trip Time and Fractional Loss Using 4053 Session Traversal Utilities for NAT (STUN)", RFC 7982, 4054 DOI 10.17487/RFC7982, September 2016, 4055 . 4057 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4058 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4059 May 2017, . 4061 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4062 (IPv6) Specification", STD 86, RFC 8200, 4063 DOI 10.17487/RFC8200, July 2017, 4064 . 4066 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4067 Better Connectivity Using Concurrency", RFC 8305, 4068 DOI 10.17487/RFC8305, December 2017, 4069 . 4071 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4072 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4073 . 4075 27.2. Informative References 4077 [Frag-Harmful] 4078 Kent, C. and J. Mogul, ""Fragmentation Considered 4079 Harmful", In Proc. SIGCOMM '87 Workshop on Frontiers in 4080 Computer Communications Technology, DOI 4081 10.1145/55483.55524", August 1987, 4082 . 4085 [I-D.ietf-intarea-frag-fragile] 4086 Bonica, R., Baker, F., Huston, G., Hinden, R., Troan, O., 4087 and F. Gont, "IP Fragmentation Considered Fragile", draft- 4088 ietf-intarea-frag-fragile-15 (work in progress), July 4089 2019. 4091 [I-D.ietf-mmusic-ice-sip-sdp] 4092 Petit-Huguenin, M., Nandakumar, S., and A. Keranen, 4093 "Session Description Protocol (SDP) Offer/Answer 4094 procedures for Interactive Connectivity Establishment 4095 (ICE)", draft-ietf-mmusic-ice-sip-sdp-36 (work in 4096 progress), June 2019. 4098 [I-D.ietf-mptcp-rfc6824bis] 4099 Ford, A., Raiciu, C., Handley, M., Bonaventure, O., and C. 4100 Paasch, "TCP Extensions for Multipath Operation with 4101 Multiple Addresses", draft-ietf-mptcp-rfc6824bis-18 (work 4102 in progress), June 2019. 4104 [I-D.ietf-rtcweb-security] 4105 Rescorla, E., "Security Considerations for WebRTC", draft- 4106 ietf-rtcweb-security-12 (work in progress), July 2019. 4108 [I-D.ietf-tram-stun-pmtud] 4109 Petit-Huguenin, M. and G. Salgueiro, "Path MTU Discovery 4110 Using Session Traversal Utilities for NAT (STUN)", draft- 4111 ietf-tram-stun-pmtud-10 (work in progress), September 4112 2018. 4114 [I-D.ietf-tsvwg-udp-options] 4115 Touch, J., "Transport Options for UDP", draft-ietf-tsvwg- 4116 udp-options-07 (work in progress), March 2019. 4118 [Port-Numbers] 4119 "IANA Port Numbers Registry", 2005, 4120 . 4122 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4123 DOI 10.17487/RFC0791, September 1981, 4124 . 4126 [RFC1191] Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, 4127 DOI 10.17487/RFC1191, November 1990, 4128 . 4130 [RFC1918] Rekhter, Y., Moskowitz, B., Karrenberg, D., de Groot, G., 4131 and E. Lear, "Address Allocation for Private Internets", 4132 BCP 5, RFC 1918, DOI 10.17487/RFC1918, February 1996, 4133 . 4135 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 4136 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 4137 DOI 10.17487/RFC1928, March 1996, 4138 . 4140 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 4141 A., Peterson, J., Sparks, R., Handley, M., and E. 4142 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 4143 DOI 10.17487/RFC3261, June 2002, 4144 . 4146 [RFC3424] Daigle, L., Ed. and IAB, "IAB Considerations for 4147 UNilateral Self-Address Fixing (UNSAF) Across Network 4148 Address Translation", RFC 3424, DOI 10.17487/RFC3424, 4149 November 2002, . 4151 [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. 4152 Jacobson, "RTP: A Transport Protocol for Real-Time 4153 Applications", STD 64, RFC 3550, DOI 10.17487/RFC3550, 4154 July 2003, . 4156 [RFC3711] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K. 4157 Norrman, "The Secure Real-time Transport Protocol (SRTP)", 4158 RFC 3711, DOI 10.17487/RFC3711, March 2004, 4159 . 4161 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 4162 "Randomness Requirements for Security", BCP 106, RFC 4086, 4163 DOI 10.17487/RFC4086, June 2005, 4164 . 4166 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 4167 DOI 10.17487/RFC4302, December 2005, 4168 . 4170 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 4171 RFC 4303, DOI 10.17487/RFC4303, December 2005, 4172 . 4174 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4175 Translation (NAT) Behavioral Requirements for Unicast 4176 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4177 2007, . 4179 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 4180 Discovery", RFC 4821, DOI 10.17487/RFC4821, March 2007, 4181 . 4183 [RFC5128] Srisuresh, P., Ford, B., and D. Kegel, "State of Peer-to- 4184 Peer (P2P) Communication across Network Address 4185 Translators (NATs)", RFC 5128, DOI 10.17487/RFC5128, March 4186 2008, . 4188 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 4189 RFC 5482, DOI 10.17487/RFC5482, March 2009, 4190 . 4192 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 4193 Relays around NAT (TURN): Relay Extensions to Session 4194 Traversal Utilities for NAT (STUN)", RFC 5766, 4195 DOI 10.17487/RFC5766, April 2010, 4196 . 4198 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4199 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4200 June 2010, . 4202 [RFC5928] Petit-Huguenin, M., "Traversal Using Relays around NAT 4203 (TURN) Resolution Mechanism", RFC 5928, 4204 DOI 10.17487/RFC5928, August 2010, 4205 . 4207 [RFC6056] Larsen, M. and F. Gont, "Recommendations for Transport- 4208 Protocol Port Randomization", BCP 156, RFC 6056, 4209 DOI 10.17487/RFC6056, January 2011, 4210 . 4212 [RFC6062] Perreault, S., Ed. and J. Rosenberg, "Traversal Using 4213 Relays around NAT (TURN) Extensions for TCP Allocations", 4214 RFC 6062, DOI 10.17487/RFC6062, November 2010, 4215 . 4217 [RFC6156] Camarillo, G., Novo, O., and S. Perreault, Ed., "Traversal 4218 Using Relays around NAT (TURN) Extension for IPv6", 4219 RFC 6156, DOI 10.17487/RFC6156, April 2011, 4220 . 4222 [RFC6263] Marjou, X. and A. Sollaud, "Application Mechanism for 4223 Keeping Alive the NAT Mappings Associated with RTP / RTP 4224 Control Protocol (RTCP) Flows", RFC 6263, 4225 DOI 10.17487/RFC6263, June 2011, 4226 . 4228 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4229 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4230 . 4232 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 4233 Time Communication Use Cases and Requirements", RFC 7478, 4234 DOI 10.17487/RFC7478, March 2015, 4235 . 4237 [RFC7635] Reddy, T., Patil, P., Ravindranath, R., and J. Uberti, 4238 "Session Traversal Utilities for NAT (STUN) Extension for 4239 Third-Party Authorization", RFC 7635, 4240 DOI 10.17487/RFC7635, August 2015, 4241 . 4243 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 4244 (Diffserv) and Real-Time Communication", RFC 7657, 4245 DOI 10.17487/RFC7657, November 2015, 4246 . 4248 [RFC7983] Petit-Huguenin, M. and G. Salgueiro, "Multiplexing Scheme 4249 Updates for Secure Real-time Transport Protocol (SRTP) 4250 Extension for Datagram Transport Layer Security (DTLS)", 4251 RFC 7983, DOI 10.17487/RFC7983, September 2016, 4252 . 4254 [RFC8155] Patil, P., Reddy, T., and D. Wing, "Traversal Using Relays 4255 around NAT (TURN) Server Auto Discovery", RFC 8155, 4256 DOI 10.17487/RFC8155, April 2017, 4257 . 4259 [RFC8311] Black, D., "Relaxing Restrictions on Explicit Congestion 4260 Notification (ECN) Experimentation", RFC 8311, 4261 DOI 10.17487/RFC8311, January 2018, 4262 . 4264 [RFC8445] Keranen, A., Holmberg, C., and J. Rosenberg, "Interactive 4265 Connectivity Establishment (ICE): A Protocol for Network 4266 Address Translator (NAT) Traversal", RFC 8445, 4267 DOI 10.17487/RFC8445, July 2018, 4268 . 4270 Authors' Addresses 4272 Tirumaleswar Reddy (editor) 4273 McAfee, Inc. 4274 Embassy Golf Link Business Park 4275 Bangalore, Karnataka 560071 4276 India 4278 Email: kondtir@gmail.com 4280 Alan Johnston (editor) 4281 Villanova University 4282 Villanova, PA 4283 USA 4285 Email: alan.b.johnston@gmail.com 4287 Philip Matthews 4288 Alcatel-Lucent 4289 600 March Road 4290 Ottawa, Ontario 4291 Canada 4293 Email: philip_matthews@magma.ca 4295 Jonathan Rosenberg 4296 jdrosen.net 4297 Edison, NJ 4298 USA 4300 Email: jdrosen@jdrosen.net 4301 URI: http://www.jdrosen.net