idnits 2.17.1 draft-ietf-behave-turn-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 : ---------------------------------------------------------------------------- == There are 4 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. -- 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? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 3, 2009) is 5403 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) == Missing Reference: '0x4001' is mentioned on line 666, but not defined ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) == Outdated reference: A later version (-07) exists of draft-ietf-behave-turn-tcp-03 == Outdated reference: A later version (-11) exists of draft-ietf-behave-turn-ipv6-06 == Outdated reference: A later version (-09) exists of draft-ietf-tsvwg-port-randomization-04 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 BEHAVE WG J. Rosenberg 3 Internet-Draft Cisco 4 Intended status: Standards Track R. Mahy 5 Expires: January 4, 2010 (Unaffiliated) 6 P. Matthews 7 Alcatel-Lucent 8 July 3, 2009 10 Traversal Using Relays around NAT (TURN): Relay Extensions to Session 11 Traversal Utilities for NAT (STUN) 12 draft-ietf-behave-turn-16 14 Status of this Memo 16 This Internet-Draft is submitted to IETF in full conformance with the 17 provisions of BCP 78 and BCP 79. This document may contain material 18 from IETF Documents or IETF Contributions published or made publicly 19 available before November 10, 2008. The person(s) controlling the 20 copyright in some of this material may not have granted the IETF 21 Trust the right to allow modifications of such material outside the 22 IETF Standards Process. Without obtaining an adequate license from 23 the person(s) controlling the copyright in such materials, this 24 document may not be modified outside the IETF Standards Process, and 25 derivative works of it may not be created outside the IETF Standards 26 Process, except to format it for publication as an RFC or to 27 translate it into languages other than English. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on January 4, 2010. 47 Copyright Notice 48 Copyright (c) 2009 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents in effect on the date of 53 publication of this document (http://trustee.ietf.org/license-info). 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. 57 Abstract 59 If a host is located behind a NAT, then in certain situations it can 60 be impossible for that host to communicate directly with other hosts 61 (peers). In these situations, it is necessary for the host to use 62 the services of an intermediate node that acts as a communication 63 relay. This specification defines a protocol, called TURN (Traversal 64 Using Relays around NAT), that allows the host to control the 65 operation of the relay and to exchange packets with its peers using 66 the relay. TURN differs from some other relay control protocols in 67 that it allows a client to communicate with multiple peers using a 68 single relay address. 70 The TURN protocol was designed to be used as part of the ICE 71 (Interactive Connectivity Establishment) approach to NAT traversal, 72 though it can be also used without ICE. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 6 78 2.1. Transports . . . . . . . . . . . . . . . . . . . . . . . 8 79 2.2. Allocations . . . . . . . . . . . . . . . . . . . . . . . 10 80 2.3. Permissions . . . . . . . . . . . . . . . . . . . . . . . 12 81 2.4. Send Mechanism . . . . . . . . . . . . . . . . . . . . . 12 82 2.5. Channels . . . . . . . . . . . . . . . . . . . . . . . . 14 83 2.6. Unprivileged TURN Servers . . . . . . . . . . . . . . . . 16 84 2.7. Avoiding IP Fragmentation . . . . . . . . . . . . . . . . 17 85 2.8. RTP Support . . . . . . . . . . . . . . . . . . . . . . . 18 86 2.9. Anycast Discovery of Servers . . . . . . . . . . . . . . 18 87 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 4. General Behavior . . . . . . . . . . . . . . . . . . . . . . . 20 89 5. Allocations . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 6. Creating an Allocation . . . . . . . . . . . . . . . . . . . . 24 91 6.1. Sending an Allocate Request . . . . . . . . . . . . . . . 24 92 6.2. Receiving an Allocate Request . . . . . . . . . . . . . . 25 93 6.3. Receiving an Allocate Success Response . . . . . . . . . 29 94 6.4. Receiving an Allocate Error Response . . . . . . . . . . 30 95 7. Refreshing an Allocation . . . . . . . . . . . . . . . . . . . 32 96 7.1. Sending a Refresh Request . . . . . . . . . . . . . . . . 32 97 7.2. Receiving a Refresh Request . . . . . . . . . . . . . . . 32 98 7.3. Receiving a Refresh Response . . . . . . . . . . . . . . 33 99 8. Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 33 100 9. CreatePermission . . . . . . . . . . . . . . . . . . . . . . . 35 101 9.1. Forming a CreatePermission request . . . . . . . . . . . 35 102 9.2. Receiving a CreatePermission request . . . . . . . . . . 35 103 9.3. Receiving a CreatePermission response . . . . . . . . . . 36 104 10. Send and Data Methods . . . . . . . . . . . . . . . . . . . . 36 105 10.1. Forming a Send Indication . . . . . . . . . . . . . . . . 36 106 10.2. Receiving a Send Indication . . . . . . . . . . . . . . . 36 107 10.3. Receiving a UDP Datagram . . . . . . . . . . . . . . . . 37 108 10.4. Receiving a Data Indication . . . . . . . . . . . . . . . 38 109 11. Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 110 11.1. Sending a ChannelBind Request . . . . . . . . . . . . . . 40 111 11.2. Receiving a ChannelBind Request . . . . . . . . . . . . . 40 112 11.3. Receiving a ChannelBind Response . . . . . . . . . . . . 41 113 11.4. The ChannelData Message . . . . . . . . . . . . . . . . . 42 114 11.5. Sending a ChannelData Message . . . . . . . . . . . . . . 42 115 11.6. Receiving a ChannelData Message . . . . . . . . . . . . . 43 116 11.7. Relaying Data from the Peer . . . . . . . . . . . . . . . 44 117 12. IP Header Fields . . . . . . . . . . . . . . . . . . . . . . . 44 118 13. New STUN Methods . . . . . . . . . . . . . . . . . . . . . . . 46 119 14. New STUN Attributes . . . . . . . . . . . . . . . . . . . . . 46 120 14.1. CHANNEL-NUMBER . . . . . . . . . . . . . . . . . . . . . 46 121 14.2. LIFETIME . . . . . . . . . . . . . . . . . . . . . . . . 47 122 14.3. XOR-PEER-ADDRESS . . . . . . . . . . . . . . . . . . . . 47 123 14.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 47 124 14.5. XOR-RELAYED-ADDRESS . . . . . . . . . . . . . . . . . . . 47 125 14.6. EVEN-PORT . . . . . . . . . . . . . . . . . . . . . . . . 47 126 14.7. REQUESTED-TRANSPORT . . . . . . . . . . . . . . . . . . . 48 127 14.8. DONT-FRAGMENT . . . . . . . . . . . . . . . . . . . . . . 48 128 14.9. RESERVATION-TOKEN . . . . . . . . . . . . . . . . . . . . 49 129 15. New STUN Error Response Codes . . . . . . . . . . . . . . . . 49 130 16. Detailed Example . . . . . . . . . . . . . . . . . . . . . . . 49 131 17. Security Considerations . . . . . . . . . . . . . . . . . . . 57 132 17.1. Outsider Attacks . . . . . . . . . . . . . . . . . . . . 57 133 17.1.1. Obtaining Unauthorized Allocations . . . . . . . . . 57 134 17.1.2. Offline Dictionary Attacks . . . . . . . . . . . . . 58 135 17.1.3. Faked Refreshes and Permissions . . . . . . . . . . . 58 136 17.1.4. Fake Data . . . . . . . . . . . . . . . . . . . . . . 58 137 17.1.5. Impersonating a Server . . . . . . . . . . . . . . . 59 138 17.1.6. Eavesdropping Traffic . . . . . . . . . . . . . . . . 59 139 17.1.7. TURN loop attack . . . . . . . . . . . . . . . . . . 60 140 17.2. Firewall Considerations . . . . . . . . . . . . . . . . . 61 141 17.2.1. Faked Permissions . . . . . . . . . . . . . . . . . . 61 142 17.2.2. Blacklisted IP Addresses . . . . . . . . . . . . . . 62 143 17.2.3. Running Servers on Well-Known Ports . . . . . . . . . 62 144 17.3. Insider Attacks . . . . . . . . . . . . . . . . . . . . . 62 145 17.3.1. DoS Against TURN Server . . . . . . . . . . . . . . . 62 146 17.3.2. Anonymous Relaying of Malicious Traffic . . . . . . . 63 147 17.3.3. Manipulating other Allocations . . . . . . . . . . . 63 148 17.4. Other Considerations . . . . . . . . . . . . . . . . . . 63 149 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 63 150 19. IAB Considerations . . . . . . . . . . . . . . . . . . . . . . 64 151 20. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 66 152 21. Changes from Previous Versions . . . . . . . . . . . . . . . . 66 153 21.1. Changes from -15 to -16 . . . . . . . . . . . . . . . . . 66 154 21.2. Changes from -14 to -15 . . . . . . . . . . . . . . . . . 66 155 21.3. Changes from -13 to -14 . . . . . . . . . . . . . . . . . 67 156 21.4. Changes from -12 to -13 . . . . . . . . . . . . . . . . . 67 157 21.5. Changes from -11 to -12 . . . . . . . . . . . . . . . . . 68 158 21.6. Changes from -10 to -11 . . . . . . . . . . . . . . . . . 69 159 21.7. Changes from -09 to -10 . . . . . . . . . . . . . . . . . 70 160 21.8. Changes from -08 to -09 . . . . . . . . . . . . . . . . . 72 161 21.9. Changes from -07 to -08 . . . . . . . . . . . . . . . . . 73 162 21.10. Changes from -06 to -07 . . . . . . . . . . . . . . . . . 74 163 21.11. Changes from -05 to -06 . . . . . . . . . . . . . . . . . 76 164 21.12. Changes from -04 to -05 . . . . . . . . . . . . . . . . . 77 165 22. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 78 166 23. References . . . . . . . . . . . . . . . . . . . . . . . . . . 78 167 23.1. Normative References . . . . . . . . . . . . . . . . . . 78 168 23.2. Informative References . . . . . . . . . . . . . . . . . 79 169 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 81 171 1. Introduction 173 A host behind a NAT may wish to exchange packets with other hosts, 174 some of which may also be behind NATs. To do this, the hosts 175 involved can use 'Hole Punching' techniques (see [RFC5128]) in an 176 attempt discover a direct communication path; that is, a 177 communication path that goes from host to another through intervening 178 NATs and routers, but does not traverse any relays. 180 As described in [RFC5128] and [RFC4787], hole punching techniques 181 will fail if both hosts are behind NATs that are not well-behaved. 182 For example, if both hosts are behind NATs that have a mapping 183 behavior of "address dependent mapping" or "address and port 184 dependent mapping", then hole punching techniques generally fail. 186 When a direct communication path cannot be found, it is necessary to 187 use the services of an intermediate host that acts as a relay for the 188 packets. This relay typically sits in the public Internet and relays 189 packets between two hosts that both sit behind NATs. 191 This specification defines a protocol, called TURN, that allows a 192 host behind a NAT (called the TURN client) to request that another 193 host (called the TURN server) act as a relay. The client can arrange 194 for the server to relay packets to and from certain other hosts 195 (called peers) and can control aspects of how the relaying is done. 196 The client does this by obtaining an IP address and port on the 197 server, called the relayed-transport-address. When a peer sends a 198 packet to the relayed-transport-address, the server relays the packet 199 to the client. When the client sends a data packet to the server, 200 the server relays it to the appropriate peer using the relayed- 201 transport-address as the source. 203 A client using TURN must have some way to communicate the relayed- 204 transport-address to its peers, and to learn each peer's IP address 205 and port (more precisely, each peer's server-reflexive transport 206 address, see Section 2). How this is done is out of the scope of the 207 TURN protocol. One way this might be done is for the client and 208 peers to exchange e-mail messages. Another way is for the client and 209 its peers to use a special-purpose 'introduction' or 'rendezvous' 210 protocol (see [RFC5128] for more details). 212 If TURN is used with ICE [I-D.ietf-mmusic-ice], then the relayed- 213 transport-address and the IP addresses and ports of the peers are 214 included in the ICE candidate information which the rendezvous 215 protocol must carry. For example, if TURN and ICE are used as part 216 of a multimedia solution using SIP [RFC3261], then SIP serves the 217 role of the rendezvous protocol, carrying the ICE candidate 218 information inside the body of SIP messages. If TURN and ICE are 219 used with some other rendezvous protocol, then 220 [I-D.rosenberg-mmusic-ice-nonsip] provides guidance on the services 221 the rendezvous protocol must perform. 223 Though the use of a TURN server to enable communication between two 224 hosts behind NATs is very likely to work, it comes at a high cost to 225 the provider of the TURN server, since the server typically needs a 226 high bandwidth connection to the Internet . As a consequence, it is 227 best to use a TURN server only when a direct communication path 228 cannot be found. When the client and a peer use ICE to determine the 229 communication path, ICE will use hole punching techniques to search 230 for a direct path first and only use a TURN server when a direct path 231 cannot be found. 233 TURN was originally invented to support multimedia sessions signaled 234 using SIP. Since SIP supports forking, TURN supports multiple peers 235 per relayed-transport-address; a feature not supported by other 236 approaches (e.g., SOCKS [RFC1928]). However, care has been taken to 237 make sure that TURN is suitable for other types of applications. 239 TURN was designed as one piece in the larger ICE approach to NAT 240 traversal. Implementors of TURN are urged to investigate ICE and 241 seriously consider using it for their application. However, it is 242 possible to use TURN without ICE. 244 TURN is an extension to the STUN (Session Traversal Utilities for NAT 245 [RFC5389]) protocol. Most, though not all, TURN messages are STUN- 246 formatted messages. A reader of this document should be familiar 247 with STUN. 249 2. Overview of Operation 251 This section gives an overview of the operation of TURN. It is non- 252 normative. 254 In a typical configuration, a TURN client is connected to a private 255 network [RFC1918] and through one or more NATs to the public 256 Internet. On the public Internet is a TURN server. Elsewhere in the 257 Internet are one or more peers that the TURN client wishes to 258 communicate with. These peers may or may not be behind one or more 259 NATs. The client uses the server as a relay to send packets to these 260 peers and to receive packets from these peers. 262 Peer A 263 Server-Reflexive +---------+ 264 Transport Address | | 265 192.0.2.150:32102 | | 266 | /| | 267 TURN | / ^| Peer A | 268 Client's Server | / || | 269 Host Transport Transport | // || | 270 Address Address | // |+---------+ 271 10.1.1.2:49721 192.0.2.15:3478 |+-+ // Peer A 272 | | ||N| / Host Transport 273 | +-+ | ||A|/ Address 274 | | | | v|T| 192.168.100.2:49582 275 | | | | /+-+ 276 +---------+| | | |+---------+ / +---------+ 277 | || |N| || | // | | 278 | TURN |v | | v| TURN |/ | | 279 | Client |----|A|----------| Server |------------------| Peer B | 280 | | | |^ | |^ ^| | 281 | | |T|| | || || | 282 +---------+ | || +---------+| |+---------+ 283 | || | | 284 | || | | 285 +-+| | | 286 | | | 287 | | | 288 Client's | Peer B 289 Server-Reflexive Relayed Transport 290 Transport Address Transport Address Address 291 192.0.2.1:7000 192.0.2.15:50000 192.0.2.210:49191 293 Figure 1 295 Figure 1 shows a typical deployment. In this figure, the TURN client 296 and the TURN server are separated by a NAT, with the client on the 297 private side and the server on the public side of the NAT. This NAT 298 is assumed to be a "bad" NAT; for example, it might have a mapping 299 property of address-and-port-dependent mapping (see [RFC4787] for a 300 description of what this means). 302 The client talks to the server from a (IP address, port) combination 303 called the client's HOST TRANSPORT ADDRESS. (The combination of an 304 IP address and port is called a TRANSPORT ADDRESS). 306 The client sends TURN messages from its host transport address to a 307 transport address on the TURN server which is known as the TURN 308 SERVER TRANSPORT ADDRESS. The client learns the server's transport 309 address through some unspecified means (e.g., configuration), and 310 this address is typically used by many clients simultaneously. 312 Since the client is behind a NAT, the server sees packets from the 313 client as coming from a transport address on the NAT itself. This 314 address is known as the client's SERVER-REFLEXIVE transport address; 315 packets sent by the server to the client's server-reflexive transport 316 address will be forwarded by the NAT to the client's host transport 317 address. 319 The client uses TURN commands to create and manipulate an ALLOCATION 320 on the server. An allocation is a data structure on the server, an 321 important component of which is a RELAYED TRANSPORT ADDRESS. The 322 relayed transport address for the allocation is a transport address 323 on the server which is used to send and receive packets to the peers. 325 Once an allocation is created, the client can send application data 326 to the server along with an indication of which peer the data is to 327 be sent to, and the server will relay this data to the appropriate 328 peer. The client sends the application data to the server inside a 329 TURN message; at the server, the data is extracted from the TURN 330 message and sent to the peer in a UDP datagram. In the reverse 331 direction, a peer can send application data in a UDP datagram to the 332 relayed transport address for the allocation; the server will then 333 encapsulate this data inside a TURN message and send it to the client 334 along with an indication of which peer sent the data. Since the TURN 335 message always contains an indication of which peer the client is 336 communicating with, the client can use a single allocation to 337 communicate with multiple peers. 339 When the peer is behind a NAT, then the client must identify the peer 340 using its server-reflexive transport address rather than its host 341 transport address. For example, to send application data to peer A 342 in the example above, the client must specify 192.0.2.150:32102 (peer 343 A's server-reflexive transport address) rather than 192.168.100.2: 344 49582 (peer A's host transport address). 346 Each allocation on the server belongs to a single client and has 347 exactly one relayed transport address which is used only by that 348 allocation. Thus when a packet arrives at a relayed transport 349 address on the server, the server knows which client the data is 350 intended for. However, the client may have multiple allocations on a 351 server at the same time. 353 2.1. Transports 355 TURN as defined in this specification always uses UDP between the 356 server and the peer. However, this specification allows the use of 357 any one of UDP, TCP, or TLS over TCP to carry the TURN messages 358 between the client and the server. 360 +----------------------------+---------------------+ 361 | TURN client to TURN server | TURN server to peer | 362 +----------------------------+---------------------+ 363 | UDP | UDP | 364 | TCP | UDP | 365 | TLS over TCP | UDP | 366 +----------------------------+---------------------+ 368 If TCP or TLS over TCP is used between the client and the server, 369 then the server will convert between these transports and UDP 370 transport when relaying data to/from the peer. 372 Since this version of TURN only supports UDP between the server and 373 the peer, it is expected that most clients will prefer to also use 374 UDP between the client and the server. That being the case, some 375 readers may wonder: Why also support TCP and TLS over TCP? 377 TURN supports TCP transport between the client and the server because 378 some firewalls are configured to block UDP entirely. These firewalls 379 block UDP but not TCP in part because TCP has properties that make 380 the intention of the nodes being protected by the firewall more 381 obvious to the firewall. For example, TCP has a three-way handshake 382 that makes in clearer that the protected node really wishes to have 383 that particular connection established, while for UDP the best the 384 firewall can do is guess which flows are desired by using filtering 385 rules. Also, TCP has explicit connection teardown, while for UDP the 386 firewall has to use timers to guess when the flow is finished. 388 TURN supports TLS over TCP transport between the client and the 389 server because TLS provides additional security properties not 390 provided by TURN's default digest authentication; properties which 391 some clients may wish to take advantage of. In particular, TLS 392 provides a way for the client to ascertain that it is talking to the 393 server that it intended to, and also provides for confidentiality of 394 TURN control messages. TURN does not require TLS because the 395 overhead of using TLS is higher than that of digest authentication; 396 for example, using TLS likely means that most application data will 397 be doubly encrypted (once by TLS and once to ensure it is still 398 encrypted in the UDP datagram). 400 There is a planned extension to TURN to add support for TCP between 401 the server and the peers [I-D.ietf-behave-turn-tcp]. For this 402 reason, allocations that use UDP between the server and the peers are 403 known as UDP allocations, while allocations that use TCP between the 404 server and the peers are known as TCP allocations. This 405 specification describes only UDP allocations. 407 TURN as defined in this specification only supports IPv4. All IP 408 addresses in this specification must be IPv4 addresses. However, 409 there is a planned extension to TURN to add support for IPv6 and for 410 relaying between IPv4 and IPv6 [I-D.ietf-behave-turn-ipv6]. 412 In some applications for TURN, the client may send and receive 413 packets other than TURN packets on the host transport address it uses 414 to communicate with the server. This can happen, for example, when 415 using TURN with ICE. In these cases, the client can distinguish TURN 416 packets from other packets by examining the source address of the 417 arriving packet: those arriving from the TURN server will be TURN 418 packets. 420 2.2. Allocations 422 To create an allocation on the server, the client uses an Allocate 423 transaction. The client sends a Allocate request to the server, and 424 the server replies with an Allocate success response containing the 425 allocated relayed transport address. The client can include 426 attributes in the Allocate request that describe the type of 427 allocation it desires (e.g., the lifetime of the allocation). Since 428 relaying data may require lots of bandwidth, the server typically 429 requires that the client authenticate itself using STUN's long-term 430 credential mechanism, to show that it is authorized to use the 431 server. 433 Once a relayed transport address is allocated, a client must keep the 434 allocation alive. To do this, the client periodically sends a 435 Refresh request to the server. TURN deliberately uses a different 436 method (Refresh rather than Allocate) for refreshes to ensure that 437 the client is informed if the allocation vanishes for some reason. 439 The frequency of the Refresh transaction is determined by the 440 lifetime of the allocation. The default lifetime of an allocation is 441 10 minutes -- this value was chosen to be long enough so that 442 refreshing is not typically a burden on the client, while expiring 443 allocations where the client has unexpectedly quit in a timely 444 manner. However, the client can request a longer lifetime in the 445 Allocate request and may modify its request in a Refresh request, and 446 the server always indicates the actual lifetime in the response. The 447 client must issue a new Refresh transaction within 'lifetime' seconds 448 of the previous Allocate or Refresh transaction. Once a client no 449 longer wishes to use an Allocation, it should delete the allocation 450 using a Refresh request with a requested lifetime of 0. 452 Both the server and client keep track of a value known as the 453 5-TUPLE. At the client, the 5-tuple consists of the client's host 454 transport address, the server transport address, and the transport 455 protocol used by the client to communicate with the server. At the 456 server, the 5-tuple value is the same except that the client's host 457 transport address is replaced by the client's server-reflexive 458 address, since that is the client's address as seen by the server. 460 Both the client and the server remember the 5-tuple used in the 461 Allocate request. Subsequent messages between the client and the 462 server uses the same 5-tuple. In this way, the client and server 463 know which allocation is being referred to. If the client wishes to 464 allocate a second relayed transport address, it must create a second 465 allocation using a different 5-tuple (e.g., by using a different 466 client host address or port). 468 NOTE: While the terminology used in this document refers to 469 5-tuples, the TURN server can store whatever identifier it likes 470 that yields identical results. Specifically, an implementation 471 may use a file-descriptor in place of a 5-tuple to represent a TCP 472 connection 474 TURN TURN Peer Peer 475 client server A B 476 |-- Allocate request --------------->| | | 477 | | | | 478 |<--------------- Allocate failure --| | | 479 | (401 Unauthorized) | | | 480 | | | | 481 |-- Allocate request --------------->| | | 482 | | | | 483 |<---------- Allocate success resp --| | | 484 | (192.0.2.15:50000) | | | 485 // // // // 486 | | | | 487 |-- Refresh request ---------------->| | | 488 | | | | 489 |<----------- Refresh success resp --| | | 490 | | | | 492 Figure 2 494 In Figure 2, the client sends an Allocate request to the server 495 without credentials. Since the server requires that all requests be 496 authenticated using STUN's long-term credential mechanism, the server 497 rejects the request with a 401 (Unauthorized) error code. The client 498 then tries again, this time including credentials (not shown). This 499 time, the server accepts the Allocate request and returns an Allocate 500 success response containing (amongst other things) the relayed 501 transport address assigned to the allocation. Sometime later the 502 client decides to refresh the allocation and thus sends a Refresh 503 request to the server. The refresh is accepted and the server 504 replies with a Refresh success response. 506 2.3. Permissions 508 To ease concerns amongst enterprise IT administrators that TURN could 509 be used to bypass corporate firewall security, TURN includes the 510 notion of permissions. TURN permissions mimic the address-restricted 511 filtering mechanism of NATs that comply with [RFC4787]. 513 An allocation can have zero or more permissions. Each permission 514 consists of an IP address and a lifetime. When the server receives a 515 UDP datagram on the allocation's relayed transport address, it first 516 checks the list of permissions. If the source IP address of the 517 datagram matches a permission, the application data is relayed to the 518 client, otherwise the UDP datagram is silently discarded. 520 A permission expires after 5 minutes if it is not refreshed, and 521 there is no way to explicitly delete a permission. This behavior was 522 selected to match the behavior of a NAT that complies with [RFC4787]. 524 The client can install or refresh a permission using either a 525 CreatePermission request or a ChannelBind request. Using the 526 CreatePermission request, multiple permissions can be installed or 527 refreshed with a single request -- this is important for applications 528 that use ICE. For security reasons, permissions can only be 529 installed or refreshed by transactions that can be authenticated; 530 thus Send indications and ChannelData messages (which are used to 531 send data to peers) do not install or refresh any permissions. 533 Note that permissions are within the context of an allocation, so 534 adding or expiring a permission in one allocation does not affect 535 other allocations. 537 2.4. Send Mechanism 539 There are two mechanisms for the client and peers to exchange 540 application data using the TURN server. The first mechanism uses the 541 Send and Data methods, the second way uses channels. Common to both 542 ways is the ability of the client to communicate with multiple peers 543 using a single allocated relayed transport address; thus both ways 544 include a means for the client to indicate to the server which peer 545 to forward the data to, and for the server to indicate which peer 546 sent the data. 548 The Send mechanism uses Send and Data indications. Send indications 549 are used to send application data from the client to the server, 550 while Data indications are used to send application data from the 551 server to the client. 553 When using the Send mechanism, the client sends a Send indication to 554 the TURN server containing (a) an XOR-PEER-ADDRESS attribute 555 specifying the (server-reflexive) transport address of the peer and 556 (b) a DATA attribute holding the application data. When the TURN 557 server receives the Send indication, it extracts the application data 558 from the DATA attribute and sends it in a UDP datagram to the peer, 559 using the allocated relay address as the source address. Note that 560 there is no need to specify the relayed transport address, since it 561 is implied by the 5-tuple used for the Send indication. 563 In the reverse direction, UDP datagrams arriving at the relayed 564 transport address on the TURN server are converted into Data 565 indications and sent to the client, with the server-reflexive 566 transport address of the peer included in an XOR-PEER-ADDRESS 567 attribute and the data itself in a DATA attribute. Since the relayed 568 transport address uniquely identified the allocation, the server 569 knows which client to relay the data to. 571 Send and Data indications cannot be authenticated, since the Long- 572 Term Credential Mechanism of STUN does not support authenticating 573 indications. This is not as big an issue as it might first appear, 574 since the client-to-server leg is only half of the total path to the 575 peer; applications that want proper security need to use encryption 576 or similar to protect their data in the UDP datagrams between the 577 server and the peer. However, to prevent attackers from injecting 578 rogue Send indications to arbitrary destinations, TURN requires that 579 a client install a permission to a peer before sending data to it 580 using a Send indication. 582 TURN TURN Peer Peer 583 client server A B 584 | | | | 585 |-- CreatePermission req (Peer A) -->| | | 586 |<-- CreatePermission success resp --| | | 587 | | | | 588 |--- Send ind (Peer A)-------------->| | | 589 | |=== data ===>| | 590 | | | | 591 | |<== data ====| | 592 |<-------------- Data ind (Peer A) --| | | 593 | | | | 594 | | | | 595 |--- Send ind (Peer B)-------------->| | | 596 | | dropped | | 597 | | | | 598 | |<== data ==================| 599 | dropped | | | 600 | | | | 602 Figure 3 604 In Figure 3, the client has already created an allocation and now 605 wishes to send data to its peers. The client first creates a 606 permission by sending the server a CreatePermission request 607 specifying peer A's (server reflexive) IP address in the XOR-PEER- 608 ADDRESS attribute; if this was not done, the server would not relay 609 data between the client and the server. The client then sends data 610 to Peer A using a Send indication; at the server, the application 611 data is extracted and forwarded in a UDP datagram to Peer A, using 612 the relayed transport address as the source transport address. When 613 a UDP datagram from Peer A is received at the relayed transport 614 address, the contents are placed into a Data indication and forwarded 615 to the client. Later, the client attempts to exchange data with Peer 616 B, however no permission has been installed for Peer B, so the Send 617 indication from the client and the UDP datagram from the peer are 618 both dropped by the server. 620 2.5. Channels 622 For some applications (e.g. Voice over IP), the 36 bytes of overhead 623 that a Send indication or Data indication adds to the application 624 data can substantially increase the bandwidth required between the 625 client and the server. To remedy this, TURN offers a second way for 626 the client and server to associate data with a specific peer. 628 This second way uses an alternate packet format known as the 629 ChannelData message. The ChannelData message does not use the STUN 630 header used by other TURN messages, but instead has a 4-byte header 631 that includes a number known as a channel number. Each channel 632 number in use is bound to a specific peer and thus serves as a 633 shorthand for the peer's host transport address. 635 To bind a channel to a peer, the client sends a ChannelBind request 636 to the server, and includes an unbound channel number and the 637 transport address of the peer. Once the channel is bound, the client 638 can use a ChannelData message to send the server data destined for 639 the peer. Similarly, the server can relay data from that peer 640 towards the client using a ChannelData message. 642 Channel bindings last for 10 minutes unless refreshed -- this 643 lifetime was chosen to be longer than the permission lifetime. 644 Channel bindings are refreshed by sending another ChannelBind request 645 rebinding the channel to the peer. Like permissions (but unlike 646 allocations), there is no way to explicitly delete a channel binding; 647 the client must simply wait for it to time out. 648 TURN TURN Peer Peer 649 client server A B 650 | | | | 651 |-- ChannelBind req ---------------->| | | 652 | (Peer A to 0x4001) | | | 653 | | | | 654 |<---------- ChannelBind succ resp --| | | 655 | | | | 656 |-- [0x4001] data ------------------>| | | 657 | |=== data ===>| | 658 | | | | 659 | |<== data ====| | 660 |<------------------ [0x4001] data --| | | 661 | | | | 662 |--- Send ind (Peer A)-------------->| | | 663 | |=== data ===>| | 664 | | | | 665 | |<== data ====| | 666 |<------------------ [0x4001] data --| | | 667 | | | | 669 Figure 4 671 Figure 4 shows the channel mechanism in use. The client has already 672 created an allocation and now wishes to bind a channel to peer A. To 673 do this, the client sends a ChannelBind request to the server, 674 specifying the transport address of Peer A and a channel number 675 (0x4001). After that, the client can send application data 676 encapsulated inside ChannelData messages to Peer A: this is shown as 677 "[0x4001] data" where 0x4001 is the channel number. When the 678 ChannelData message arrives at the server, the server transfers the 679 data to a UDP datagram and sends it to the peer A, as indicated by 680 the channel number. When peer A sends a UDP datagram to the relayed 681 transport address, the data is placed inside a ChannelData message 682 and sent to the client. 684 Once a channel has been bound, the client is free to intermix 685 ChannelData messages and Send indications. In the figure, the client 686 later decides to use a Send indication rather than a ChannelData 687 message to send additional data to peer A. The client might decide to 688 do this, for example, so it can use the DONT-FRAGMENT attribute (see 689 the next section). However, once a channel is bound, the server will 690 always use a ChannelData message, as shown in the call flow. 692 Note that ChannelData messages can only be used for peers to which 693 the client has bound a channel. In the example above, Peer A has 694 been bound to a channel, but Peer B has not, so application data to 695 and from Peer B would use the Send mechanism. 697 2.6. Unprivileged TURN Servers 699 This version of TURN is designed so that the server can be 700 implemented as an application that runs in user space under commonly 701 available operating systems without requiring special privileges. 702 This design decision was taken to make it easy to deploy a TURN 703 server: for example, to allow a TURN server to be integrated into a 704 peer-to-peer application so that one peer can offer NAT traversal 705 services to another peer. 707 This design decision has the following implications for data relayed 708 by a TURN server: 710 o The value of the Diff-Serv field may not be preserved across the 711 server; 713 o The TTL field may be reset, rather than decremented, across the 714 server; 716 o The ECN field may be reset by the server; 718 o ICMP messages are not relayed by the server; 720 o There is no end-to-end fragmentation, since the packet is re- 721 assembled at the server. 723 Future work may specify alternate TURN semantics that address these 724 limitations. 726 2.7. Avoiding IP Fragmentation 728 For reasons described in [Frag-Harmful], applications, especially 729 those sending large volumes of data, should try hard to avoid having 730 their packets fragmented. Applications using TCP can more-or-less 731 ignore this issue because fragmentation avoidance is now a standard 732 part of TCP, but applications using UDP (and thus any application 733 using this version of TURN) must handle fragmentation avoidance 734 themselves. 736 The application running on the client and the peer can take one of 737 two approaches to avoid IP fragmentation. 739 The first approach is to avoid sending large amounts of application 740 data in the TURN messages/UDP datagrams exchanged between the client 741 and the peer. This is the approach taken by most VoIP 742 (Voice-over-IP) applications. In this approach, the application 743 exploits the fact that the IP specification [RFC0791] specifies that 744 IP packets up to 576 bytes should never need to be fragmented. 746 The exact amount of application data that can be included while 747 avoiding fragmentation depends the details of the TURN session 748 between the client and the server: whether UDP, TCP, or TLS transport 749 is used, whether ChannelData messages or Send/Data indications are 750 used, and whether any additional attributes (such as the DONT- 751 FRAGMENT attribute) are included. Another factor, which is hard to 752 determine, is whether the MTU is somewhere along the path is reduced 753 for other reasons, such as the use of IP-in-IP tunneling. 755 As a guideline, sending a maximum of 500 bytes of application data in 756 a single TURN message (by the client on the client-to-server leg) or 757 a UDP datagram (by the peer on the peer-to-server leg) will generally 758 avoid IP fragmentation. To further reduce the chance of 759 fragmentation, it is recommended that the client use ChannelData 760 messages when transferring significant volumes of data, since the 761 overhead of the ChannelData message is less than Send and Data 762 indications. 764 The second approach the client and peer can take to avoid 765 fragmentation is to use a path MTU discovery algorithm to determine 766 the maximum amount of application data than can be sent without 767 fragmentation. 769 Unfortunately, because servers implementing this version of TURN do 770 not relay ICMP messages, the classic Path MTU Discovery algorithm 771 defined in [RFC1191] is not able to discover the MTU of the 772 transmission path between the client and the peer. (Even if they did 773 relay ICMP messages, the algorithm would not always work since ICMP 774 messages are often filtered out by combined NAT/firewall devices). 776 So the client and server need to use a path MTU discovery algorithm 777 that does not require ICMP messages. The Packetized Path MTU 778 Discovery algorithm defined in [RFC4821] is one such algorithm. 780 The details of how to use the algorithm of [RFC4821] with TURN are 781 still under investigation. However, as a step towards this goal, 782 this version of TURN supports a DONT-FRAGMENT attribute. When the 783 client includes this attribute in a Send indication, this tells the 784 server to set the DF bit in the resulting UDP datagram that it sends 785 to the peer. Since some servers may be unable to set the DF bit, the 786 client should also include this attribute in the Allocate request -- 787 any server that does not support the DONT-FRAGMENT attribute will 788 indicate this by rejecting the Allocate request. 790 2.8. RTP Support 792 One of the envisioned uses of TURN is as a relay for clients and 793 peers wishing to exchange real-time data (e.g. voice or video) using 794 RTP. To facilitate the use of TURN for this purpose, TURN includes 795 some special support for older versions of RTP. 797 Old versions of RTP [RFC3550] required that the RTP stream be on an 798 even port number and the associated RTCP stream, if present, be on 799 the next highest port. To allow clients to work with peers that 800 still require this, TURN allows the client to request that the server 801 allocate a relayed-transport-address with an even port number, and to 802 optionally request the server reserve the next-highest port number 803 for a subsequent allocation. 805 2.9. Anycast Discovery of Servers 807 This version of TURN has been designed to permit the future 808 specification of a method of doing anycast discovery of a TURN server 809 over UDP. 811 Specifically, a TURN server can reject an Allocate request with the 812 suggestion that the server try an alternate server. To avoid certain 813 types of attacks, the client must use the same credentials with the 814 alternate server as it would have with the initial server. 816 3. Terminology 818 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 819 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 820 document are to be interpreted as described in RFC 2119 [RFC2119]. 822 Readers are expected to be familiar with [RFC5389] and the terms 823 defined there. 825 The following terms are used in this document: 827 TURN: The protocol spoken between a TURN client and a TURN server. 828 It is an extension to the STUN protocol [RFC5389]. The protocol 829 allows a client to allocate and use a relayed transport address. 831 TURN client: A STUN client that implements this specification. 833 TURN server: A STUN server that implements this specification. It 834 relays data between a TURN client and its peer(s). 836 Peer: A host with which the TURN client wishes to communicate. The 837 TURN server relays traffic between the TURN client and its 838 peer(s). The peer does not interact with the TURN server using 839 the protocol defined in this document; rather, the peer receives 840 data sent by the TURN server and the peer sends data towards the 841 TURN server. 843 Transport Address: The combination of an IP address and a port. 845 Host Transport Address: A transport address on a client or a peer. 847 Server-Reflexive Transport Address: A transport address on the 848 "public side" of a NAT. This address is allocated by the NAT to 849 correspond to a specific host transport address. 851 Relayed Transport Address: A transport address on the TURN server 852 that is used for relaying packets between the client and a peer. 853 A peer sends to this address on the TURN server, and the packet is 854 then relayed to the client. 856 TURN Server Transport Address: A transport address on the TURN 857 server that is used for sending TURN messages to the server. This 858 is the transport address that the client uses to communicate with 859 the server. 861 Peer Transport Address: The transport address of the peer as seen by 862 the server. When the peer is behind a NAT, this is the peer's 863 server-reflexive transport address. 865 Allocation: The relayed transport address granted to a client 866 through an Allocate request, along with related state, such as 867 permissions and expiration timers. 869 5-tuple: The combination (client IP address and port, server IP 870 address and port, and transport protocol (currently one of UDP, 871 TCP, or TLS)) used to communicate between the client and the 872 server. The 5-tuple uniquely identifies this communication 873 stream. The 5-tuple also uniquely identifies the Allocation on 874 the server. 876 Channel: A channel number and associated peer transport address. 877 Once a channel number is bound to a peer's transport address, the 878 client and server can use the more bandwidth-efficient ChannelData 879 message to exchange data. 881 Permission: The IP address and transport protocol (but not the port) 882 of a peer that is permitted to send traffic to the TURN server and 883 have that traffic relayed to the TURN client. The TURN server 884 will only forward traffic to its client from peers that match an 885 existing permission. 887 Realm A string used to describe the server or a context within the 888 server. The realm tells the client which username and password 889 combination to use to authenticate requests. 891 Nonce A string chosen at random by the server and included in the 892 message-digest. To prevent reply attacks, the server should 893 change the nonce regularly. 895 4. General Behavior 897 This section contains general TURN processing rules that apply to all 898 TURN messages. 900 TURN is an extension to STUN. All TURN messages, with the exception 901 of the ChannelData message, are STUN-formatted messages. All the 902 base processing rules described in [RFC5389] apply to STUN-formatted 903 messages. This means that all the message-forming and -processing 904 descriptions in this document are implicitly prefixed with the rules 905 of [RFC5389]. 907 [RFC5389] specifies a Long-Term Credential mechanism for STUN. TURN 908 servers and clients MUST implement this mechanism. The server SHOULD 909 demand that all requests from the client be authenticated using this 910 mechanism, and the client MUST be prepared to authenticate requests 911 if required. 913 In general, it is strongly recommended that servers require 914 requests to be authenticated, as the security of TURN can 915 otherwise be quite weak. One reason that a server might not 916 require requests to be authenticated is that TURN is being used in 917 a carefully controlled environment in which the risks of 918 unauthenticated requests by hostile third-parties have been 919 mitigated. See Section 17 for more discussion on this point. 921 Note that Long-Term Credential mechanism applies only to requests and 922 cannot be used to authenticate indications, thus indications in TURN 923 are never authenticated. If the server requires requests to be 924 authenticated, then the server's administrator MUST choose a realm 925 value that will uniquely identify the username and password 926 combination that the client must use, even if the client uses 927 multiple servers under different administrations. The server's 928 administrator MAY choose to allocate a unique username to each 929 client, or MAY choose to allocate the same username to more than one 930 client (for example, to all clients from the same department or 931 company). For each allocation, the server SHOULD generate a new 932 random nonce when the allocation is first attempted following the 933 randomness recommendations in [RFC4086] and SHOULD expire the nonce 934 at least once every hour during the lifetime of the allocation. 936 All requests after the initial Allocate must use the same username as 937 that used to create the allocation, to prevent attackers from 938 hijacking the client's allocation. Specifically, if the server 939 requires the use of the Long-Term Credential mechanism, and if a non- 940 Allocate request passes authentication under this mechanism, and if 941 the 5-tuple identifies an existing allocation, but the request does 942 not use the same username as used to create the allocation, then the 943 request MUST be rejected with a 441 (Wrong Credentials) error. 945 When a TURN message arrives at the server from the client, the server 946 uses the 5-tuple in the message to identify the associated 947 allocation. For all TURN messages (including ChannelData) EXCEPT an 948 Allocate request, if the 5-tuple does not identify an existing 949 allocation, then the message MUST either be rejected with a 437 950 Allocation Mismatch error (if it is a request), or silently ignored 951 (if it is an indication or a ChannelData message). A client 952 receiving a 437 error response to a request other than Allocate MUST 953 assume the allocation no longer exists. 955 The client SHOULD include the SOFTWARE attribute in all Allocate and 956 Refresh requests and MAY include it in any other requests or 957 indications. The server SHOULD include the SOFTWARE attribute in all 958 Allocate and Refresh responses (either success or failure) and MAY 959 include it in other responses or indications. The client and the 960 server MAY include the FINGERPRINT attribute in any STUN-formatted 961 messages defined in this document. 963 TURN does not use the backwards-compatibility mechanism described in 965 [RFC5389]. 967 TURN as defined in this specification only supports IPv4. The 968 client's IP address, the server's IP address and all IP addresses 969 appearing in a relayed-transport-address MUST be IPv4 addresses. 971 By default, TURN runs on the same ports as STUN: 3478 for TURN over 972 UDP and TCP, and 5349 for TURN over TLS. However, TURN has its own 973 set of SRV service names: "turn" for UDP and TCP, and "turns" for 974 TLS. Either the SRV procedures or the ALTERNATE-SERVER procedures, 975 both described in Section 6, can be used to run TURN on a different 976 port. 978 To ensure interoperability, a TURN server MUST support the use of UDP 979 transport between the client and the server, and SHOULD support the 980 use of TCP and TLS transport. 982 When UDP transport is used between the client and the server, the 983 client will retransmit a request if it does not receive a response 984 within a certain timeout period. Because of this, the server may 985 receive two (or more) requests with the same 5-tuple and same 986 transaction id. STUN requires that the server recognize this case 987 and treat the request as idempotent (see [RFC5389]). Some 988 implementations may choose to meet this requirement by remembering 989 all received requests and the corresponding responses for 40 seconds. 990 Other implementations may choose to reprocess the request and arrange 991 that such reprocessing returns essentially the same response. To aid 992 implementors who choose the latter approach (the so-called "stateless 993 stack approach"), this specification includes some implementation 994 notes on how this might be done. Implementations are free to choose 995 either approach or choose some other approach that gives the same 996 results. 998 When TCP transport is used between the client and the server, it is 999 possible that a bit error will cause a length field in a TURN packet 1000 to become corrupted, causing the receiver to lose synchronization 1001 with the incoming stream of TURN messages. A client or server which 1002 detects a long sequence of invalid TURN messages over TCP transport 1003 SHOULD close the corresponding TCP connection to help the other end 1004 detect this situation more rapidly. 1006 To mitigate either intentional or unintentional denial-of-service 1007 attacks against the server by clients with valid usernames and 1008 passwords, it is RECOMMENDED that the server impose limits on both 1009 the number of allocations active at one time for a given username and 1010 on the amount of bandwidth those allocations can use. The server 1011 should reject new allocations that would exceed the limit on the 1012 allowed number of allocations active at one time with a 486 1013 (Allocation Quota Exceeded) (see Section 6.2), and should discard 1014 application data traffic that exceeds the bandwidth quota. 1016 5. Allocations 1018 All TURN operations revolve around allocations, and all TURN messages 1019 are associated with an allocation. An allocation conceptually 1020 consists of the following state data: 1022 o the relayed transport address 1024 o The 5-tuple: (client's IP address, client's port, server IP 1025 address, server port, transport protocol) 1027 o the authentication information 1029 o the time-to-expiry 1031 o A list of permissions 1033 o A list of channel to peer bindings 1035 The relayed transport address is the transport address allocated by 1036 the server for communicating with peers, while the 5-tuple describes 1037 the communication path between the client and the server. On the 1038 client, the 5-tuple uses the client's host transport address, while 1039 on the server the 5-tuple uses the client's server-reflexive 1040 transport address. 1042 Both the relayed-transport-address and the 5-tuple MUST be unique 1043 across all allocations, so either one can be used to uniquely 1044 identify the allocation. 1046 The authentication information (e.g., username, password, realm, and 1047 nonce) are used to both verify subsequent requests and to compute the 1048 message integrity of responses. The username, realm, and nonce 1049 values are initially those used in the authenticated Allocate request 1050 that creates the allocation, though the server can change the nonce 1051 value during the lifetime of the allocation using a 438 (Stale Nonce) 1052 reply. Note that rather than storing the password explicitly, it may 1053 be desirable for security reasons for the server to store the key 1054 value which is an MD5 hash over the username, realm and password (see 1055 [RFC5389]). 1057 The time-to-expiry is the time in seconds left until the allocation 1058 expires. Each Allocate or Refresh transaction sets this timer, which 1059 then ticks down towards 0. By default, each Allocate or Refresh 1060 transaction resets this timer to the default lifetime value of 600 1061 seconds (10 minutes), but the client can request a different value in 1062 the Allocate and Refresh request. Allocations can only be refreshed 1063 using the Refresh request; sending data to a peer does not refresh an 1064 allocation. When an allocation expires, the state data associated 1065 with the allocation can be freed. 1067 The list of permissions is described in Section 8 and the list of 1068 channels is described in Section 11. 1070 6. Creating an Allocation 1072 An allocation on the server is created using an Allocate transaction. 1074 6.1. Sending an Allocate Request 1076 The client forms an Allocate request as follows. 1078 The client first picks a host transport address. It is RECOMMENDED 1079 that the client pick a currently-unused transport address, typically 1080 by allowing the underlying OS to pick a currently-unused port for a 1081 new socket. 1083 The client then picks a transport protocol to use between the client 1084 and the server. The transport protocol MUST be one of UDP, TCP, or 1085 TLS over TCP. Since this specification only allows UDP between the 1086 server and the peers, it is RECOMMENDED that the client pick UDP 1087 unless it has a reason to use a different transport. One reason to 1088 pick a different transport would be that the client believes, either 1089 through configuration or by experiment, that it is unable to contact 1090 any TURN server using UDP. See Section 2.1 for more discussion. 1092 The client also picks a server transport address, which SHOULD be 1093 done as follows. The client receives (perhaps through configuration) 1094 a domain name for a TURN server. The client then uses the DNS 1095 procedures described in [RFC5389], but using an SRV service name of 1096 "turn" (or "turns" for TURN over TLS) instead of "stun" (or "stuns"). 1097 For example, to find servers in the example.com domain, the client 1098 performs a lookup for '_turn._udp.example.com', 1099 '_turn._tcp.example.com', and '_turns._tcp.example.com' if the client 1100 wants to communicate with the server using UDP, TCP, or TLS over TCP, 1101 respectively. 1103 The client MUST include a REQUESTED-TRANSPORT attribute in the 1104 request. This attribute specifies the transport protocol between the 1105 server and the peers (note that this is NOT the transport protocol 1106 that appears in the 5-tuple). In this specification, the REQUESTED- 1107 TRANSPORT type is always UDP. This attribute is included to allow 1108 future extensions specify other protocols. 1110 If the client wishes the server to initialize the time-to-expiry 1111 field of the allocation to some value other the default lifetime, 1112 then it MAY include a LIFETIME attribute specifying its desired 1113 value. This is just a request, and the server may elect to use a 1114 different value. Note that the server will ignore requests to 1115 initialize the field to less than the default value. 1117 If the client wishes to later use the DONT-FRAGMENT attribute in one 1118 or more Send indications on this allocation, then the client SHOULD 1119 include the DONT-FRAGMENT attribute in the Allocate request. This 1120 allows the client to test whether this attribute is supported by the 1121 server. 1123 If the client requires the port number of the relayed-transport 1124 address be even, the client includes the EVEN-PORT attribute. If 1125 this attribute is not included, then the port can be even or odd. By 1126 setting the R bit in the EVEN-PORT attribute to 1, the client can 1127 request that the server reserve the next highest port number (on the 1128 same IP address) for a subsequent allocation. If the R bit is 0, no 1129 such request is made. 1131 The client MAY also include a RESERVATION-TOKEN attribute in the 1132 request to ask the server to use a previously reserved port for the 1133 allocation. If the RESERVATION-TOKEN attribute is included, then the 1134 client MUST omit the EVEN-PORT attribute. 1136 Once constructed, the client sends the Allocate request on the 1137 5-tuple. 1139 6.2. Receiving an Allocate Request 1141 When the server receives an Allocate request, it performs the 1142 following checks: 1144 1. The server SHOULD require that the request be authenticated using 1145 the Long-Term Credential mechanism of [RFC5389]. 1147 2. The server checks if the 5-tuple is currently in use by an 1148 existing allocation. If yes, the server rejects the request with 1149 a 437 (Allocation Mismatch) error. 1151 3. The server checks if the request contain a REQUESTED-TRANSPORT 1152 attribute. If the REQUESTED-TRANSPORT attribute is not included 1153 or is malformed, the server rejects the request with a 400 (Bad 1154 Request) error. Otherwise, if the attribute is included but 1155 specifies a protocol other that UDP, the server rejects the 1156 request with a 442 (Unsupported Transport Protocol) error. 1158 4. The request may contain a DONT-FRAGMENT attribute. If it does, 1159 but the server does not support sending UDP datagrams with the DF 1160 bit set to 1 (see Section 12), then the server treats the DONT- 1161 FRAGMENT attribute in the Allocate request as an unknown 1162 comprehension-required attribute. 1164 5. The server checks if the request contains a RESERVATION-TOKEN 1165 attribute. If yes, and the request also contains a EVEN-PORT 1166 attribute, then the server rejects the request with a 400 (Bad 1167 Request) error. Otherwise it checks to see if the token is valid 1168 (i.e., the token is in range and has not expired, and the 1169 corresponding relayed transport address is still available). If 1170 the token is not valid for some reason, the server rejects the 1171 request with a 508 (Insufficient Port Capacity) error. 1173 6. The server checks if the request contains an EVEN-PORT attribute. 1174 If yes, then the server checks that it can satisfy the request 1175 (i.e., can allocate a relayed-transport-address as described 1176 below). If the server cannot satisfy the request, then the 1177 server rejects the request with a 508 (Insufficient Port 1178 Capacity) error. 1180 7. At any point, the server MAY choose to reject the request with a 1181 486 (Allocation Quota Reached) error if it feels the client is 1182 trying to exceed some locally-defined allocation quota. The 1183 server is free to define this allocation quota any way it wishes, 1184 but SHOULD define it based on the username used to authenticate 1185 the request, and not on the client's transport address. 1187 8. Also at any point, the server MAY choose to reject the request 1188 with a 300 (Try Alternate) error if it wishes to redirect the 1189 client to a different server. The use of this error code and 1190 attribute follow the specification in [RFC5389]. 1192 If all the checks pass, the server creates the allocation. The 1193 5-tuple is set to the 5-tuple from the Allocate request, while the 1194 list of permissions and the list of channels are initially empty. 1196 The server chooses a relayed-transport-address for the allocation as 1197 follows: 1199 o If the request contains a RESERVATION-TOKEN, the server uses the 1200 previously-reserved transport address corresponding to the 1201 included token (if it is still available). Note that the 1202 reservation is a server-wide reservation and is not specific to a 1203 particular allocation, since the Allocate request containing the 1204 RESERVATION-TOKEN uses a different 5-tuple than the Allocate 1205 request that made the reservation. The 5-tuple for the Allocate 1206 request containing the RESERVATION-TOKEN attribute can be any 1207 allowed 5-tuple; it can use a different client IP address and 1208 port, a different transport protocol, and even different server IP 1209 address and port (provided, of course, that the server IP address 1210 and port is one that the server is listening for TURN requests 1211 on). 1213 o If the request contains an EVEN-PORT attribute with the R bit set 1214 to 0, then the server allocates a relayed-transport-address with 1215 an even port number. 1217 o If the request contains an EVEN-PORT attribute with the R bit set 1218 to 1, then the server looks for a pair of port numbers N and N+1 1219 on the same IP address, where N is even. Port N is used in the 1220 current allocation, while the relayed transport address with port 1221 N+1 is assigned a token and reserved for a future allocation. The 1222 server MUST hold this reservation for at least 30 seconds, and MAY 1223 choose to hold longer (e.g. until the allocation with port N 1224 expires). The server then includes the token in a RESERVATION- 1225 TOKEN attribute in the success response. 1227 o Otherwise, the server allocates any available relayed-transport- 1228 address. 1230 In all cases, the server SHOULD only allocate ports from the range 1231 49152 - 65535 (the Dynamic and/or Private Port range [Port-Numbers]), 1232 unless the TURN server application knows, through some means not 1233 specified here, that other applications running on the same host as 1234 the TURN server application will not be impacted by allocating ports 1235 outside this range. This condition can often be satisfied by running 1236 the TURN server application on a dedicated machine and/or by 1237 arranging that any other applications on the machine allocate ports 1238 before the TURN server application starts. In any case, the TURN 1239 server SHOULD NOT allocate ports in the range 0 - 1023 (the Well- 1240 Known Port range) to discourage clients from using TURN to run 1241 standard services. 1243 NOTE: The IETF is currently investigating the topic of randomized 1244 port assignments to avoid certain types of attacks (see 1245 [I-D.ietf-tsvwg-port-randomization]). It is strongly recommended 1246 that a TURN implementor keep abreast of this topic and, if 1247 appropriate, implement a randomized port assignment algorithm. 1248 This is especially applicable to servers that choose to pre- 1249 allocate a number of ports from the underlying OS and then later 1250 assign them to allocations; for example, a server may choose this 1251 technique to implement the EVEN-PORT attribute. 1253 The server determines the initial value of the time-to-expiry field 1254 as follows. If the request contains a LIFETIME attribute, then the 1255 server computes MIN(client's proposed lifetime, server's maximum 1256 allowed lifetime). If this computed lifetime is greater than the 1257 default lifetime, then the server uses that value. Otherwise, the 1258 server uses the default lifetime. It is RECOMMENDED that the server 1259 use a maximum allowed lifetime value of no more than 3600 seconds (1 1260 hour). Servers that implement allocation quotas or charge users for 1261 allocations in some way may wish to use a smaller maximum allowed 1262 lifetime (perhaps as small as the default lifetime) to more quickly 1263 remove orphaned allocations (that is, allocations where the 1264 corresponding client has crashed or terminated or the client 1265 connection has been lost for some reason). Also note that the time- 1266 to-expiry is recomputed with each successful Refresh request, and 1267 thus the value computed here applies only until the first refresh. 1269 Once the allocation is created, the server replies with a success 1270 response. The success response contains: 1272 o A XOR-RELAYED-ADDRESS attribute containing the relayed transport 1273 address; 1275 o A LIFETIME attribute containing the current value of the time-to- 1276 expiry timer; 1278 o A RESERVATION-TOKEN attribute (if a second relayed transport 1279 address was reserved). 1281 o An XOR-MAPPED-ADDRESS attribute containing the client's IP address 1282 and port (from the 5-tuple). 1284 NOTE: The XOR-MAPPED-ADDRESS attribute is included in the response 1285 as a convenience to the client. TURN itself does not make use of 1286 this value, but clients running ICE can often need this value and 1287 can thus avoid having to do an extra Binding transaction with some 1288 STUN server to learn it. 1290 The response (either success or error) is sent back to the client on 1291 the 5-tuple. 1293 NOTE: Implementations may implement the idempotency of the 1294 Allocate request over UDP using the so-called "stateless stack 1295 approach" as follows. To detect retransmissions when the original 1296 request was successful in creating an allocation, the server can 1297 store the transaction id that created the request with the 1298 allocation data and compare it with incoming Allocate requests on 1299 the same 5-tuple. Once such a request is detected, the server can 1300 stop parsing the request and immediately generate a success 1301 response. When building this response, the value of the LIFETIME 1302 attribute can be taken from the time-to-expiry field in the 1303 allocate state data, even though this value may differ slightly 1304 from the LIFETIME value originally returned. In addition, the 1305 server may need to store an indication of any reservation token 1306 returned in the original response, so that this may be returned in 1307 any retransmitted responses. 1309 For the case where the original request was unsuccessful in 1310 creating an allocation, the server may choose to do nothing 1311 special. Note, however, that there is a rare case where the 1312 server rejects the original request but accepts the retransmitted 1313 request (because conditions have changed in the brief intervening 1314 time period). If the client receives the first failure response, 1315 it will ignore the second (success) response and believe that an 1316 allocation was not created. An allocation created in this matter 1317 will eventually timeout, since the client will not refresh it. 1318 Furthermore, if the client later retries with the same 5-tuple but 1319 different transaction id, it will receive a 437 (Allocation 1320 Mismatch), which will cause it to retry with a different 5-tuple. 1321 The server may use a smaller maximum lifetime value to minimize 1322 the lifetime of allocations "orphaned" in this manner. 1324 6.3. Receiving an Allocate Success Response 1326 If the client receives an Allocate success response, then it MUST 1327 check that the mapped address and the relayed transport address are 1328 in an address family that the client understands and is prepared to 1329 deal with. This specification only covers the case where these two 1330 addresses are IPv4 addresses. If these two addresses are not in an 1331 address family that the client is prepared to deal with, then the 1332 client MUST delete the allocation (Section 7) and MUST NOT attempt to 1333 create another allocation on that server until it believes the 1334 mismatch has been fixed. 1336 The IETF is currently considering mechanisms for transitioning 1337 between IPv4 and IPv6 that could result in a client originating an 1338 Allocate request over IPv6, but the request would arrive at the 1339 server over IPv4, or vica-versa. Hence the importance of this 1340 check. 1342 Otherwise, the client creates its own copy of the allocation data 1343 structure to track what is happening on the server. In particular, 1344 the client needs to remember the actual lifetime received back from 1345 the server, rather than the value sent to the server in the request. 1346 The client must also remember the 5-tuple used for the request and 1347 the username and password it used to authenticate the request to 1348 ensure that it reuses them for subsequent messages. The client also 1349 needs to track the channels and permissions it establishes on the 1350 server. 1352 The client will probably wish to send the relayed transport address 1353 to peers (using some method not specified here) so the peers can 1354 communicate with it. The client may also wish to use the server- 1355 reflexive address it receives in the XOR-MAPPED-ADDRESS attribute in 1356 its ICE processing. 1358 6.4. Receiving an Allocate Error Response 1360 If the client receives an Allocate error response, then the 1361 processing depends on the actual error code returned: 1363 o (Request timed out): There is either a problem with the server, or 1364 a problem reaching the server with the chosen transport. The 1365 client considers the current transaction as having failed but MAY 1366 choose to retry the Allocate request using a different transport 1367 (e.g., TCP instead of UDP). 1369 o 300 (Try Alternate): The server would like the client to use the 1370 server specified in the ALTERNATE-SERVER attribute instead. The 1371 client considers the current transaction as having failed, but 1372 SHOULD try the Allocate request with the alternate server before 1373 trying any other servers (e.g., other servers discovered using the 1374 SRV procedures). When trying the Allocate request with the 1375 alternate server, the client follows the ALTERNATE-SERVER 1376 procedures specified in [RFC5389]. 1378 o 400 (Bad Request): The server believes the client's request is 1379 malformed for some reason. The client considers the current 1380 transaction as having failed. The client MAY notify the user or 1381 operator and SHOULD NOT retry the request with this server until 1382 it believes the problem has been fixed. 1384 o 401 (Unauthorized): If the client has followed the procedures of 1385 the Long-Term Credential mechanism and still gets this error, then 1386 the server is not accepting the client's credentials. In this 1387 case, the client considers the current transaction as having 1388 failed and SHOULD notify the user or operator. The client SHOULD 1389 NOT send any further requests to this server until it believes the 1390 problem has been fixed. 1392 o 403 (Forbidden): The request is valid, but the server is refusing 1393 to perform it, likely due to administrative restrictions. The 1394 client considers the current transaction as having failed. The 1395 client MAY notify the user or operator and SHOULD NOT retry the 1396 same request with this server until it believes the problem has 1397 been fixed. 1399 o 420 (Unknown Attribute): If the client included a DONT-FRAGMENT 1400 attribute in the request and the server rejected the request with 1401 a 420 error code and listed the DONT-FRAGMENT attribute in the 1402 UNKNOWN-ATTRIBUTES attribute in the error response, then the 1403 client now knows that the server does not support the DONT- 1404 FRAGMENT attribute. The client considers the current transaction 1405 as having failed but MAY choose to retry the Allocate request 1406 without the DONT-FRAGMENT attribute. 1408 o 437 (Allocation Mismatch): This indicates that the client has 1409 picked a 5-tuple which the server sees as already in use. One way 1410 this could happen is if an intervening NAT assigned a mapped 1411 transport address that was used by another client which recently 1412 crashed. The client considers the current transaction as having 1413 failed. The client SHOULD pick another client transport address 1414 and retry the Allocate request (using a different transaction id). 1415 The client SHOULD try three different client transport addresses 1416 before giving up on this server. Once the client gives up on the 1417 server, it SHOULD NOT try to create another allocation on the 1418 server for 2 minutes. 1420 o 438 (Stale Nonce): See the procedures for the Long-Term Credential 1421 mechanism [RFC5389]. 1423 o 441 (Wrong Credentials): The client should not receive this error 1424 in response to a Allocate request. The client MAY notify the user 1425 or operator and SHOULD NOT retry the same request with this server 1426 until it believes the problem has been fixed. 1428 o 442 (Unsupported Transport Address): The client should not receive 1429 this error in response to a request for a UDP allocation. The 1430 client MAY notify the user or operator and SHOULD NOT reattempt 1431 the request with this server until it believes the problem has 1432 been fixed. 1434 o 486 (Allocation Quota Reached): The server is currently unable to 1435 create any more allocations with this username. The client 1436 considers the current transaction as having failed. The client 1437 SHOULD wait at least 1 minute before trying to create any more 1438 allocations on the server. 1440 o 508 (Insufficient Port Capacity): The server has no more relayed 1441 transport addresses available, or has none with the requested 1442 properties, or the one that was reserved is no longer available. 1444 The client considers the current operation as having failed. If 1445 the client is using either the EVEN-PORT or the RESERVATION-TOKEN 1446 attribute, then the client MAY choose to remove or modify this 1447 attribute and try again immediately. Otherwise, the client SHOULD 1448 wait at least 1 minute before trying to create any more 1449 allocations on this server. 1451 An unknown error response MUST be handled as described in [RFC5389]. 1453 7. Refreshing an Allocation 1455 A Refresh transaction can be used to either (a) refresh an existing 1456 allocation and update its time-to-expiry, or (b) delete an existing 1457 allocation. 1459 If a client wishes to continue using an allocation, then the client 1460 MUST refresh it before it expires. It is suggested that the client 1461 refresh the allocation roughly 1 minute before it expires. If a 1462 client no longer wishes to use an allocation, then it SHOULD 1463 explicitly delete the allocation. A client MAY also refresh an 1464 allocation at any time for other reasons. 1466 7.1. Sending a Refresh Request 1468 If the client wishes to immediately delete an existing allocation, it 1469 includes a LIFETIME attribute with a value of 0. All other forms of 1470 the request refresh the allocation. 1472 The Refresh transaction updates the time-to-expiry timer of an 1473 allocation. If the client wishes the server to set the time-to- 1474 expiry timer to something other than the default lifetime, it 1475 includes a LIFETIME attribute with the requested value. The server 1476 then computes a new time-to-expiry value in the same way as it does 1477 for an Allocate transaction, with the exception that a requested 1478 lifetime of 0 causes the server to immediately delete the allocation. 1480 7.2. Receiving a Refresh Request 1482 When the server receives a Refresh request, it processes as per 1483 Section 4 plus the specific rules mentioned here. 1485 The server computes a value called the "desired lifetime" as follows: 1486 If the request contains a LIFETIME attribute and the attribute value 1487 is 0, then the "desired lifetime" is 0. Otherwise, if the request 1488 contains a LIFETIME attribute, then the server computes MIN(client's 1489 requested lifetime, server's maximum allowed lifetime). If this 1490 computed value is greater than the default lifetime, then the 1491 "desired lifetime" is the computed value. Otherwise the "desired 1492 lifetime" is the default lifetime. 1494 Subsequent processing depends on the desired lifetime value: 1496 o If desired lifetime is 0, then the request succeeds and the 1497 allocation is deleted. 1499 o If the desired lifetime is non-zero, then the request succeeds and 1500 the allocation's time-to-expiry is set to the desired lifetime 1502 If the request succeeds, then server sends a success response 1503 containing: 1505 o A LIFETIME attribute containing the current value of the time-to- 1506 expiry timer. 1508 NOTE: A server need not do anything special to implement 1509 idempotency of Refresh requests over UDP using the "stateless 1510 stack approach". Retransmitted Refresh requests with a non-zero 1511 desired lifetime will simply refresh the allocation. A 1512 retransmitted Refresh request with a zero desired lifetime will 1513 cause a 437 (Allocation Mismatch) response if the allocation has 1514 already been deleted, but the client will treat this as equivalent 1515 to a success response (see below). 1517 7.3. Receiving a Refresh Response 1519 If the client receives a success response to its Refresh request with 1520 a non-zero lifetime, it updates its copy of the allocation data 1521 structure with the time-to-expiry value contained in the response. 1523 If the client receives a 437 (Allocation Mismatch) error response to 1524 a request to delete the allocation, then the allocation no longer 1525 exists and it should consider its request as having effectively 1526 succeeded. 1528 8. Permissions 1530 For each allocation, the server keeps a list of zero or more 1531 permissions. Each permission consists of an IP address which 1532 uniquely identifies the permission, and an associated time-to-expiry. 1533 The IP address describes a set of peers that are allowed to send data 1534 to the client, and the time-to-expiry is the number of seconds until 1535 the permission expires. 1537 By sending either CreatePermission requests or ChannelBind requests, 1538 the client can cause the server to install or refresh a permission 1539 for a given IP address. This causes one of two things to happen: 1541 o If no permission for that IP address exists, then a permission is 1542 created with the given IP address and a time-to-expiry equal to 1543 Permission Lifetime. 1545 o If a permission for that IP address already exists, then the time- 1546 to-expiry for that permission is reset to Permission Lifetime. 1548 The Permission Lifetime MUST be 300 seconds (= 5 minutes). 1550 Each permission's time-to-expiry decreases down once per second until 1551 it reaches 0, at which point the permission expires and is deleted. 1553 CreatePermission and ChannelBind requests may be freely intermixed on 1554 a permission. A given permission may be installed or refreshed at 1555 one point in time with a CreatePermission request, and then refreshed 1556 with a ChannelBind request at a different point in time, or vice- 1557 versa. 1559 When a UDP datagram arrives at the relayed transport address for the 1560 allocation, the server extracts the source IP address from the IP 1561 header. The server then compares this address with the IP address 1562 associated with each permission in the list of permissions for the 1563 allocation. If no match is found, relaying is not permitted, and the 1564 server silently discards the UDP datagram. If an exact match is 1565 found, then the permission check is considered to have succeeded and 1566 the server continues to process the UDP datagram as specified 1567 elsewhere (Section 10.3). Note that only addresses are compared and 1568 port numbers are not considered. 1570 The permissions for one allocation are totally unrelated to the 1571 permissions for a different allocation. If an allocation expires, 1572 all its permissions expire with it. 1574 NOTE: Though TURN permissions expire after 5 minutes, many NATs 1575 deployed at the time of publication expire their UDP bindings 1576 considerably faster. Thus an application using TURN will probably 1577 wish to send some sort of keep-alive traffic at a much faster 1578 rate. Applications using ICE should follow the keep-alive 1579 guidelines of ICE [I-D.ietf-mmusic-ice], and applications not 1580 using ICE are advised to do something similar. 1582 9. CreatePermission 1584 TURN supports two ways for the client to install or refresh 1585 permissions on the server. This section describes one way: the 1586 CreatePermission request. 1588 A CreatePermission request may be used in conjunction with either the 1589 Send mechanism in Section 10 or the Channel mechanism in Section 11. 1591 9.1. Forming a CreatePermission request 1593 The client who wishes to install or refresh one or more permissions 1594 can send a CreatePermission request to the server. 1596 When forming a CreatePermission request, the client MUST include at 1597 least one XOR-PEER-ADDRESS attribute, and MAY include more than one 1598 such attribute. The IP address portion of each XOR-PEER-ADDRESS 1599 attribute contains the IP address for which a permission should be 1600 installed or refreshed. The port portion of each XOR-PEER-ADDRESS 1601 attribute will be ignored and can be any arbitrary value. The 1602 various XOR-PEER-ADDRESS attributes can appear in any order. 1604 9.2. Receiving a CreatePermission request 1606 When the server receives the CreatePermission request, it processes 1607 as per Section 4 plus the specific rules mentioned here. 1609 The message is checked for validity. The CreatePermission request 1610 MUST contain at least XOR-PEER-ADDRESS attribute and MAY contain 1611 multiple such attributes. If no such attribute exists, or if any of 1612 these attributes are invalid, then a 400 (Bad Request) error is 1613 returned. If the request is valid, but the server is unable to 1614 satisfy the request due to some capacity limit or similar, then a 508 1615 (Insufficient Capacity) error is returned. 1617 The server MAY impose restrictions on the IP address and port values 1618 allowed in the XOR-PEER-ADDRESS attribute -- if a value is not 1619 allowed, the server rejects the request with a 403 (Forbidden) error. 1621 If the message is valid and the server is capable of carrying out the 1622 request, then the server installs or refreshes a permission for the 1623 IP address contained in each XOR-PEER-ADDRESS attribute as described 1624 in Section 8. The port portion of each attribute is ignored and may 1625 be any arbitrary value. 1627 The server then responds with a CreatePermission success response. 1628 There are no mandatory attributes in the success response. 1630 NOTE: A server need not do anything special to implement 1631 idempotency of CreatePermission requests over UDP using the 1632 "stateless stack approach". Retransmitted CreatePermission 1633 requests will simply refresh the permissions. 1635 9.3. Receiving a CreatePermission response 1637 If the client receives a valid CreatePermission success response, 1638 then the client updates its data structures to indicate that the 1639 permissions have been installed or refreshed. 1641 10. Send and Data Methods 1643 TURN supports two mechanisms for sending and receiving data from 1644 peers. This section describes the use of the Send and Data 1645 mechanism, while Section 11 describes the use of the Channel 1646 mechanism. 1648 10.1. Forming a Send Indication 1650 The client can use a Send indication to pass data to the server for 1651 relaying to a peer. A client may use a Send indication even if a 1652 channel is bound to that peer. However the client MUST ensure that 1653 there is a permission installed for the IP address of the peer to 1654 which the Send indication is being sent; this prevents a third party 1655 from using a TURN server to send data to arbitrary destinations. 1657 When forming a Send indication, the client MUST include a XOR-PEER- 1658 ADDRESS attribute and a DATA attribute. The XOR-PEER-ADDRESS 1659 attribute contains the transport address of the peer to which the 1660 data is to be sent, and the DATA attribute contains the actual 1661 application data to be sent to the peer. 1663 The client MAY include a DONT-FRAGMENT attribute in the Send 1664 indication if it wishes the server to set the DF bit on the UDP 1665 datagram sent to the peer. 1667 10.2. Receiving a Send Indication 1669 When the server receives a Send indication, it processes as per 1670 Section 4 plus the specific rules mentioned here. 1672 The message is first checked for validity. The Send indication MUST 1673 contain both a XOR-PEER-ADDRESS attribute and a DATA attribute. If 1674 one of these attributes is missing or invalid, then the message is 1675 discarded. Note that the DATA attribute is allowed to contain zero 1676 bytes of data. 1678 The Send indication may also contain the DONT-FRAGMENT attribute. If 1679 the server is unable to set the DF bit on outgoing UDP datagrams when 1680 this attribute is present, then the server acts as if the DONT- 1681 FRAGMENT attribute is an unknown comprehension-required attribute 1682 (and thus the Send indication is discarded). 1684 The server also checks that there is a permission installed for the 1685 IP address contained in the XOR-PEER-ADDRESS attribute. If no such 1686 permission exists, the message is discarded. Note that a Send 1687 indication never causes the server to refresh the permission. 1689 The server MAY impose restrictions on the IP address and port values 1690 allowed in the XOR-PEER-ADDRESS attribute -- if a value is not 1691 allowed, the server silently discards the Send indication. 1693 If everything is OK, then the server forms a UDP datagram as follows: 1695 o the source transport address is the relayed transport address of 1696 the allocation, where the allocation is determined by the 5-tuple 1697 on which the Send indication arrived; 1699 o the destination transport address is taken from the XOR-PEER- 1700 ADDRESS attribute; 1702 o the data following the UDP header is the contents of the value 1703 field of the DATA attribute. 1705 The handling of the DONT-FRAGMENT attribute (if present), is 1706 described in Section 12. 1708 The resulting UDP datagram is then sent to the peer. 1710 10.3. Receiving a UDP Datagram 1712 When the server receives a UDP datagram at a currently allocated 1713 relayed transport address, the server looks up the allocation 1714 associated with the relayed transport address. The server then 1715 checks to see whether the set of permissions for the allocation allow 1716 the relaying of the UDP datagram as described in Section 8. 1718 If relaying is permitted, then the server checks if there is a 1719 channel bound to the peer that sent the UDP datagram (see 1720 Section 11). If a channel is bound, then processing proceeds as 1721 described in Section 11.7. 1723 If relaying is permitted but no channel is bound to the peer, then 1724 the server forms and sends a Data indication. The Data indication 1725 MUST contain both a XOR-PEER-ADDRESS and a DATA attribute. The DATA 1726 attribute is set to the value of the 'data octets' field from the 1727 datagram, and the XOR-PEER-ADDRESS attribute is set to the source 1728 transport address of the received UDP datagram. The Data indication 1729 is then sent on the 5-tuple associated with the allocation. 1731 10.4. Receiving a Data Indication 1733 When the client receives a Data indication, it checks that the Data 1734 indication contains both a XOR-PEER-ADDRESS and a DATA attribute, and 1735 discards the indication if it does not. The client SHOULD also check 1736 that the XOR-PEER-ADDRESS attribute value contains an IP address with 1737 which the client believes there is an active permission, and discard 1738 the Data indication otherwise. Note that the DATA attribute is 1739 allowed to contain zero bytes of data. 1741 NOTE: The latter check protects the client against an attacker who 1742 somehow manages to trick the server into installing permissions 1743 not desired by the client. 1745 If the Data indication passes the above checks, the client delivers 1746 the data octets inside the DATA attribute to the application, along 1747 with an indication that they were received from the peer whose 1748 transport address is given by the XOR-PEER-ADDRESS attribute. 1750 11. Channels 1752 Channels provide a way for the client and server to send application 1753 data using ChannelData messages, which have less overhead than Send 1754 and Data indications. 1756 The ChannelData message (see Section 11.4) starts with a two-byte 1757 field that carries the channel number. The values of this field are 1758 allocated as follows: 1760 0x0000 through 0x3FFF: These values can never be used for channel 1761 numbers. 1763 0x4000 through 0x7FFF: These values are the allowed channel 1764 numbers (16,383 possible values) 1766 0x8000 through 0xFFFF: These values are reserved for future use. 1768 Because of this division, ChannelData messages can be distinguished 1769 from STUN-formatted messages (e.g., Allocate request, Send 1770 indication, etc) by examining the first two bits of the message: 1772 0b00: STUN-formatted message (since the first two bits of a STUN- 1773 formatted message are always zero) 1775 0b01: ChannelData message (since the channel number is the first 1776 field in the ChannelData message and channel numbers fall in the 1777 range 0x4000 - 0x7FFF) 1779 0b10: Reserved 1781 0b11: Reserved 1783 The reserved values may be used in the future to extend the range of 1784 channel numbers. Thus an implementation MUST NOT assume that a TURN 1785 message always starts with a 0 bit. 1787 Channel bindings are always initiated by the client. The client can 1788 bind a channel to a peer at any time during the lifetime of the 1789 allocation. The client may bind a channel to a peer before 1790 exchanging data with it, or after exchanging data with it (using Send 1791 and Data indications) for some time, or may choose never to bind a 1792 channel to it. The client can also bind channels to some peers while 1793 not binding channels to other peers. 1795 Channel bindings are specific to an allocation, so that the use of a 1796 channel number or peer transport address in a channel binding in one 1797 allocation has no impact on their use in a different allocation. If 1798 an allocation expires, all its channel bindings expire with it. 1800 A channel binding consists of: 1802 o A channel number; 1804 o A transport address (of the peer); 1806 o A time-to-expiry timer. 1808 Within the context of an allocation, a channel binding is uniquely 1809 identified either by the channel number or by the peer's transport 1810 address. Thus the same channel cannot be bound to two different 1811 transport addresses, nor can the same transport address be bound to 1812 two different channels. 1814 A channel binding lasts for 10 minutes unless refreshed. Refreshing 1815 the binding (by the server receiving a ChannelBind request rebinding 1816 the channel to the same peer) resets the time-to-expiry timer back to 1817 10 minutes. 1819 When the channel binding expires, the channel becomes unbound. Once 1820 unbound, the channel number can be bound to a different transport 1821 address, and the transport address can be bound to a different 1822 channel number. To prevent race conditions, the client MUST wait 5 1823 minutes after the channel binding expires before attempting to bind 1824 the channel number to a different transport address or the transport 1825 address to a different channel number. 1827 When binding a channel to a peer, the client SHOULD be prepared to 1828 receive ChannelData messages on the channel from the server as soon 1829 as it has sent the ChannelBind request. Over UDP, it is possible for 1830 the client to receive ChannelData messages from the server before it 1831 receives a ChannelBind success response. 1833 In the other direction, the client MAY elect to send ChannelData 1834 messages before receiving the ChannelBind success response. Doing 1835 so, however, runs the risk of having the ChannelData messages dropped 1836 by the server if the ChannelBind request does not succeed for some 1837 reason (e.g., packet lost if the request is sent over UDP, or the 1838 server being unable to fulfill the request). A client that wishes to 1839 be safe should either queue the data, or use Send indications until 1840 the channel binding is confirmed. 1842 11.1. Sending a ChannelBind Request 1844 A channel binding is created or refreshed using a ChannelBind 1845 transaction. A ChannelBind transaction also creates or refreshes a 1846 permission towards the peer (see Section 8). 1848 To initiate the ChannelBind transaction, the client forms a 1849 ChannelBind request. The channel to be bound is specified in a 1850 CHANNEL-NUMBER attribute, and the peer's transport address is 1851 specified in a XOR-PEER-ADDRESS attribute. Section 11.2 describes 1852 the restrictions on these attributes. 1854 Rebinding a channel to the same transport address that it is already 1855 bound to provides a way to refresh a channel binding and the 1856 corresponding permission without sending data to the peer. Note 1857 however, that permissions need to be refreshed more frequently than 1858 channels. 1860 11.2. Receiving a ChannelBind Request 1862 When the server receives a ChannelBind request, it processes as per 1863 Section 4 plus the specific rules mentioned here. 1865 The server checks the following: 1867 o The request contains both a CHANNEL-NUMBER and a XOR-PEER-ADDRESS 1868 attribute; 1870 o The channel number is in the range 0x4000 through 0x7FFE 1871 (inclusive); 1873 o The channel number is not currently bound to a different transport 1874 address (same transport address is OK); 1876 o The transport address is not currently bound to a different 1877 channel number. 1879 If any of these tests fail, the server replies with a 400 (Bad 1880 Request) error. 1882 The server MAY impose restrictions on the IP address and port values 1883 allowed in the XOR-PEER-ADDRESS attribute -- if a value is not 1884 allowed, the server rejects the request with a 403 (Forbidden) error. 1886 If the request is valid, but the server is unable to fulfill the 1887 request due to some capacity limit or similar, the server replies 1888 with a 508 (Insufficient Capacity) error. 1890 Otherwise, the server replies with a ChannelBind success response. 1891 There are no required attributes in a successful ChannelBind 1892 response. 1894 If the server can satisfy the request, then the server creates or 1895 refreshes the channel binding using the channel number in the 1896 CHANNEL-NUMBER attribute and the transport address in the XOR-PEER- 1897 ADDRESS attribute. The server also installs or refreshes a 1898 permission for the IP address in the XOR-PEER-ADDRESS attribute as 1899 described in Section 8. 1901 NOTE: A server need not do anything special to implement 1902 idempotency of ChannelBind requests over UDP using the "stateless 1903 stack approach". Retransmitted ChannelBind requests will simply 1904 refresh the channel binding and the corresponding permission. 1905 Furthermore, the client must wait 5 minutes before binding a 1906 previously bound channel number or peer address to a different 1907 channel, eliminating the possibility that the transaction would 1908 initially fail but succeed on a retransmission. 1910 11.3. Receiving a ChannelBind Response 1912 When the client receives a ChannelBind success response, it updates 1913 its data structures to record that the channel binding is now active. 1914 It also updates its data structures to record that the corresponding 1915 permission has been installed or refreshed. 1917 If the client receives a ChannelBind failure response that indicates 1918 that the channel information is out-of-sync between the client and 1919 the server (e.g., an unexpected 400 "Bad Request" response), then it 1920 is RECOMMENDED that the client immediately delete the allocation and 1921 start afresh with a new allocation. 1923 11.4. The ChannelData Message 1925 The ChannelData message is used to carry application data between the 1926 client and the server. It has the following format: 1928 0 1 2 3 1929 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 1930 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1931 | Channel Number | Length | 1932 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1933 | | 1934 / Application Data / 1935 / / 1936 | | 1937 | +-------------------------------+ 1938 | | 1939 +-------------------------------+ 1941 The Channel Number field specifies the number of the channel on which 1942 the data is traveling, and thus the address of the peer that is 1943 sending or is to receive the data. 1945 The Length field specifies the length in bytes of the application 1946 data field (i.e., it does not include the size of the ChannelData 1947 header). Note that 0 is a valid length. 1949 The Application Data field carries the data the client is trying to 1950 send to the peer, or that the peer is sending to the client. 1952 11.5. Sending a ChannelData Message 1954 Once a client has bound a channel to a peer, then when the client has 1955 data to send to that peer it may use either a ChannelData message or 1956 a Send indication; that is, the client is not obligated to use the 1957 channel when it exists and may freely intermix the two message types 1958 when sending data to the peer. The server, on the other hand, MUST 1959 use the ChannelData message if a channel has been bound to the peer. 1961 The fields of the ChannelData message are filled in as described in 1962 Section 11.4. 1964 Over stream transports, the ChannelData message MUST be padded to a 1965 multiple of four bytes in order to ensure the alignment of subsequent 1966 messages. The padding is not reflected in the length field of the 1967 ChannelData message, so the actual size of a ChannelData message 1968 (including padding) is (4 + Length) rounded up to the nearest 1969 multiple of 4. Over UDP, the padding is not required but MAY be 1970 included. 1972 The ChannelData message is then sent on the 5-tuple associated with 1973 the allocation. 1975 11.6. Receiving a ChannelData Message 1977 The receiver of the ChannelData message uses the first two bits to 1978 distinguish it from STUN-formatted messages, as described above. If 1979 the message uses a value in the reserved range (0x8000 through 1980 0xFFFF), then the message is silently discarded. 1982 If the ChannelData message is received in a UDP datagram, and if the 1983 UDP datagram is too short to contain the claimed length of the 1984 ChannelData message (i.e., the UDP header length field value is less 1985 than the ChannelData header length field value + 4 + 8), then the 1986 message is silently discarded. 1988 If the ChannelData message is received over TCP or over TLS over TCP, 1989 then the actual length of the ChannelData message is as described in 1990 Section 11.5. 1992 If the ChannelData message is received on a channel which is not 1993 bound to any peer, then the message is silently discarded. 1995 On the client, it is RECOMMENDED that the client discard the 1996 ChannelData message if the client believes there is no active 1997 permission towards the peer. On the server, the receipt of a 1998 ChannelData message MUST NOT refresh either the channel binding or 1999 the permission towards the peer. 2001 On the server, if no errors are detected, the server relays the 2002 application data to the peer by forming a UDP datagram as follows: 2004 o the source transport address is the relayed transport address of 2005 the allocation, where the allocation is determined by the 5-tuple 2006 on which the ChannelData message arrived; 2008 o the destination transport address is the transport address to 2009 which the channel is bound; 2011 o the data following the UDP header is the contents of the data 2012 field of the ChannelData message. 2014 The resulting UDP datagram is then sent to the peer. Note that if 2015 the Length field in the ChannelData message is 0, then there will be 2016 no data in the UDP datagram, but the UDP datagram is still formed and 2017 sent. 2019 11.7. Relaying Data from the Peer 2021 When the server receives a UDP datagram on the relayed transport 2022 address associated with an allocation, the server processes it as 2023 described in Section 10.3. If that section indicates that a 2024 ChannelData message should be sent (because there is a channel bound 2025 to the peer that sent to UDP datagram), then the server forms and 2026 sends a ChannelData message as described in Section 11.5. 2028 12. IP Header Fields 2030 This section describes how the server sets various fields in the IP 2031 header when relaying between the client and the peer or vica-versa. 2032 The descriptions in this section apply: (a) when the server sends a 2033 UDP datagram to the peer, or (b) when the server sends a Data 2034 indication or ChannelData message to the client over UDP transport. 2035 The descriptions in this section do not apply to TURN messages sent 2036 over TCP or TLS transport from the server to the client. 2038 The descriptions below have two parts: a preferred behavior and an 2039 alternate behavior. The server SHOULD implement the preferred 2040 behavior, but if that is not possible for a particular field, then it 2041 SHOULD implement the alternative behavior. 2043 Time to Live (TTL) field 2045 Preferred Behavior: If the incoming value is 0, then the drop the 2046 incoming packet. Otherwise set the outgoing Time to Live/Hop 2047 Count to one less than the incoming value. 2049 Alternate Behavior: Set the outgoing value to the default for 2050 outgoing packets. 2052 Diff-Serv Code Point (DSCP) field [RFC2474] 2054 Preferred Behavior: Set the outgoing value to the incoming value, 2055 unless the server includes a differentiated services classifier 2056 and marker [RFC2474]. 2058 Alternate Behavior: Set the outgoing value to a fixed value, which 2059 by default is Best Effort unless configured otherwise. 2061 In both cases, if the server is immediately adjacent to a 2062 differentiated services classifier and marker, then DSCP MAY be 2063 set to any arbitrary value in the direction towards the 2064 classifier. 2066 Explicit Congestion Notification (ECN) field [RFC3168] 2068 Preferred Behavior: Set the outgoing value to the incoming value, 2069 UNLESS the server is doing Active Queue Management, the incoming 2070 ECN field is ECT(1) (=0b01) or ECT(0) (=0b10), and the server 2071 wishes to indicate that congestion has been experienced, in which 2072 case set the outgoing value to CE (=0b11). 2074 Alternate Behavior: Set the outgoing value to Not-ECT (=0b00). 2076 IPv4 Fragmentation fields 2078 Preferred Behavior: 2080 When the server sends a packet to a peer in response to a Send 2081 indication containing the DONT-FRAGMENT attribute, then set the 2082 DF bit in the outgoing IP header to 1. In all other cases when 2083 sending an outgoing packet containing application data (e.g., 2084 Data indication, ChannelData message, or DONT-FRAGMENT 2085 attribute not included in the Send indication), copy the DF bit 2086 from the DF bit of the incoming packet that contained the 2087 application data. 2089 Set the other fragmentation fields (Identification, MF, 2090 Fragment Offset) as appropriate for a packet originating from 2091 the server. 2093 Alternate Behavior: As described in the Preferred Behavior, except 2094 always assume the incoming DF bit is 0. 2096 In both the Preferred and Alternate Behaviors, the resulting 2097 packet may be too large for the outgoing link. If this is the 2098 case, then the normal fragmentation rules apply [RFC1122]. 2100 IPv4 Options 2101 Preferred Behavior: The outgoing packet is sent without any IPv4 2102 options. 2104 Alternate Behavior: Same as preferred. 2106 13. New STUN Methods 2108 This section lists the codepoints for the new STUN methods defined in 2109 this specification. See elsewhere in this document for the semantics 2110 of these new methods. 2112 0x003 : Allocate (only request/response semantics defined) 2113 0x004 : Refresh (only request/response semantics defined) 2114 0x006 : Send (only indication semantics defined) 2115 0x007 : Data (only indication semantics defined) 2116 0x008 : CreatePermission (only request/response semantics defined 2117 0x009 : ChannelBind (only request/response semantics defined) 2119 14. New STUN Attributes 2121 This STUN extension defines the following new attributes: 2123 0x000C: CHANNEL-NUMBER 2124 0x000D: LIFETIME 2125 0x0010: Reserved (was BANDWIDTH) 2126 0x0012: XOR-PEER-ADDRESS 2127 0x0013: DATA 2128 0x0016: XOR-RELAYED-ADDRESS 2129 0x0018: EVEN-PORT 2130 0x0019: REQUESTED-TRANSPORT 2131 0x001A: DONT-FRAGMENT 2132 0x0021: Reserved (was TIMER-VAL) 2133 0x0022: RESERVATION-TOKEN 2135 Some of these attributes have lengths that are not multiples of 4. 2136 By the rules of STUN, any attribute whose length is not a multiple of 2137 4 bytes MUST be immediately followed by 1 to 3 padding bytes to 2138 ensure the next attribute (if any) would start on a 4-byte boundary 2139 (see [RFC5389]). 2141 14.1. CHANNEL-NUMBER 2143 The CHANNEL-NUMBER attribute contains the number of the channel. The 2144 value portion of this attribute is 4 bytes long and consists of a 16- 2145 bit unsigned integer, followed by a two-octet RFFU (Reserved For 2146 Future Use) field which MUST be set to 0 on transmission and MUST be 2147 ignored on reception. 2149 0 1 2 3 2150 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 2151 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2152 | Channel Number | RFFU = 0 | 2153 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2155 14.2. LIFETIME 2157 The LIFETIME attribute represents the duration for which the server 2158 will maintain an allocation in the absence of a refresh. The value 2159 portion of this attribute is 4-bytes long and consists of a 32-bit 2160 unsigned integral value representing the number of seconds remaining 2161 until expiration. 2163 14.3. XOR-PEER-ADDRESS 2165 The XOR-PEER-ADDRESS specifies the address and port of the peer as 2166 seen from the TURN server. (In other words, the peer's server- 2167 reflexive transport address if the peer is behind a NAT). It is 2168 encoded in the same way as XOR-MAPPED-ADDRESS [RFC5389]. 2170 14.4. DATA 2172 The DATA attribute is present in all Send and Data indications. The 2173 value portion of this attribute is variable-length and consists of 2174 the application data (that is, the data that would immediately follow 2175 the UDP header if the data was been sent directly between the client 2176 and the peer). If the length of this attribute is not a multiple of 2177 4, then padding must be added after this attribute. 2179 14.5. XOR-RELAYED-ADDRESS 2181 The XOR-RELAYED-ADDRESS is present in Allocate responses. It 2182 specifies the address and port that the server allocated to the 2183 client. It is encoded in the same way as XOR-MAPPED-ADDRESS 2184 [RFC5389]. 2186 14.6. EVEN-PORT 2188 This attribute allows the client to request that the port in the 2189 relayed-transport-address be even, and (optionally) that the server 2190 reserve the next-higher port number. The value portion of this 2191 attribute is 1 byte long. Its format is: 2193 0 2194 0 1 2 3 4 5 6 7 2195 +-+-+-+-+-+-+-+-+ 2196 |R| RFFU | 2197 +-+-+-+-+-+-+-+-+ 2199 The value contains a single 1-bit flag: 2201 R: If 1, the server is requested to reserve the next higher port 2202 number (on the same IP address) for a subsequent allocation. If 2203 0, no such reservation is requested. 2205 The other 7 bits of the attribute's value must be set to zero on 2206 transmission and ignored on reception. 2208 Since the length of this attribute is not a multiple of 4, padding 2209 must immediately follow this attribute. 2211 14.7. REQUESTED-TRANSPORT 2213 This attribute is used by the client to request a specific transport 2214 protocol for the allocated transport address. The value of this 2215 attribute is 4 bytes with the following format: 2216 0 1 2 3 2217 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 2218 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2219 | Protocol | RFFU | 2220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2222 The Protocol field specifies the desired protocol. The codepoints 2223 used in this field are taken from those allowed in the Protocol field 2224 in the IPv4 header and the NextHeader field in the IPv6 header 2225 [Protocol-Numbers]. This specification only allows the use of 2226 codepoint 17 (User Datagram Protocol). 2228 The RFFU field MUST be set to zero on transmission and MUST be 2229 ignored on reception. It is reserved for future uses. 2231 14.8. DONT-FRAGMENT 2233 This attribute is used by the client to request that the server set 2234 the DF (Don't Fragment) bit in the IP header when relaying the 2235 application data onward to the peer. This attribute has no value 2236 part and thus the attribute length field is 0. 2238 14.9. RESERVATION-TOKEN 2240 The RESERVATION-TOKEN attribute contains a token that uniquely 2241 identifies a relayed transport address being held in reserve by the 2242 server. The server includes this attribute in a success response to 2243 tell the client about the token, and the client includes this 2244 attribute in a subsequent Allocate request to request the server use 2245 that relayed transport address for the allocation. 2247 The attribute value is 8 bytes and contains the token value. 2249 15. New STUN Error Response Codes 2251 This document defines the following new error response codes: 2253 403 (Forbidden): The request was valid, but cannot be performed due 2254 to administrative or similar restrictions. 2256 437 (Allocation Mismatch): A request was received by the server that 2257 requires an allocation to be in place, but there is none, or a 2258 request was received which requires no allocation, but there is 2259 one. 2261 441 (Wrong Credentials): The credentials in the (non-Allocate) 2262 request, though otherwise acceptable to the server, do not match 2263 those used to create the allocation. 2265 442 (Unsupported Transport Protocol): The Allocate request asked the 2266 server to use a transport protocol between the server and the peer 2267 that the server does not support. NOTE: This does NOT refer to 2268 the transport protocol used in the 5-tuple. 2270 486 (Allocation Quota Reached): No more allocations using this 2271 username can be created at the present time. 2273 508 (Insufficient Capacity): The server is unable to carry out the 2274 request due to some capacity limit being reached. In an Allocate 2275 response, this could be due to the server having no more relayed 2276 transport addresses available right now, or having none with the 2277 requested properties, or the one that corresponds to the specified 2278 reservation token is not available. 2280 16. Detailed Example 2282 This section gives a example of the use of TURN, showing in detail 2283 the contents of the messages exchanged. The example uses the network 2284 diagram shown in the Overview (Figure 1). 2286 For each message, the attributes included in the message and their 2287 values are shown. For convenience, values are shown in a human- 2288 readable format rather than showing the actual octets; for example 2289 "XOR-RELAYED-ADDRESS=192.0.2.15:9000" shows that the XOR-RELAYED- 2290 ADDRESS attribute is included with an address of 192.0.2.15 and a 2291 port of 9000, here the address and port are shown before the xor-ing 2292 is done. For attributes with string-like values (e.g. 2293 SOFTWARE="Example client, version 1.03" and 2294 NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm"), the value of the attribute 2295 is shown in quotes for readability, but these quotes do not appear in 2296 the actual value. 2298 TURN TURN Peer Peer 2299 client server A B 2300 | | | | 2301 |--- Allocate request -------------->| | | 2302 | Transaction-Id=0xA56250D3F17ABE679422DE85 | | 2303 | SOFTWARE="Example client, version 1.03" | | 2304 | LIFETIME=3600 (1 hour) | | | 2305 | REQUESTED-TRANSPORT=17 (UDP) | | | 2306 | DONT-FRAGMENT | | | 2307 | | | | 2308 |<-- Allocate error response --------| | | 2309 | Transaction-Id=0xA56250D3F17ABE679422DE85 | | 2310 | SOFTWARE="Example server, version 1.17" | | 2311 | ERROR-CODE=401 (Unauthorized) | | | 2312 | REALM="example.com" | | | 2313 | NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm" | | 2314 | | | | 2315 |--- Allocate request -------------->| | | 2316 | Transaction-Id=0xC271E932AD7446A32C234492 | | 2317 | SOFTWARE="Example client 1.03" | | | 2318 | LIFETIME=3600 (1 hour) | | | 2319 | REQUESTED-TRANSPORT=17 (UDP) | | | 2320 | DONT-FRAGMENT | | | 2321 | USERNAME="George" | | | 2322 | REALM="example.com" | | | 2323 | NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm" | | 2324 | MESSAGE-INTEGRITY=... | | | 2325 | | | | 2326 |<-- Allocate success response ------| | | 2327 | Transaction-Id=0xC271E932AD7446A32C234492 | | 2328 | SOFTWARE="Example server, version 1.17" | | 2329 | LIFETIME=1200 (20 minutes) | | | 2330 | XOR-RELAYED-ADDRESS=192.0.2.15:50000 | | 2331 | XOR-MAPPED-ADDRESS=192.0.2.1:7000 | | 2332 | MESSAGE-INTEGRITY=... | | | 2334 The client begins by selecting a host transport address to use for 2335 the TURN session; in this example the client has selected 10.1.1.2: 2336 49721 as shown in Figure 1. The client then sends an Allocate 2337 request to the server at the server transport address. The client 2338 randomly selects a 96-bit transaction id of 2339 0xA56250D3F17ABE679422DE85 for this transaction; this is encoded in 2340 the transaction id field in the fixed header. The client includes a 2341 SOFTWARE attribute that gives information about the client's 2342 software; here the value is "Example client, version 1.03" to 2343 indicate that this is version 1.03 of something called the Example 2344 client. The client includes the LIFETIME attribute because it wishes 2345 the allocation to have a longer lifetime than the default of 10 2346 minutes; the value of this attribute is 3600 seconds, which 2347 corresponds to 1 hour. The client must always include a REQUESTED- 2348 TRANSPORT attribute in an Allocate request and the only value allowed 2349 by this specification is 17, which indicates UDP transport between 2350 the server and the peers. The client also includes the DONT-FRAGMENT 2351 attribute because it wishes to use the DONT-FRAGMENT attribute later 2352 in Send indications; this attribute consists of only an attribute 2353 header, there is no value part. We assume the client has not 2354 recently interacted with the server, thus the client does not include 2355 USERNAME, REALM, NONCE, or MESSAGE-INTEGRITY attribute. Finally, 2356 note that the order of attributes in a message is arbitrary (except 2357 for the MESSAGE-INTEGRITY and FINGERPRINT attributes) and the client 2358 could have used a different order. 2360 The server follows the recommended practice in this specification of 2361 requiring all requests to be authenticated. Thus when the server 2362 receives the initial Allocate request, it rejects the request because 2363 the request does not contain the authentication attributes. 2364 Following the procedures of the Long-Term Credential Mechanism of 2365 STUN [RFC5389], the server includes an ERROR-CODE attribute with a 2366 value of 401 (Unauthorized), a REALM attribute that specifies the 2367 authentication realm used by the server (in this case, the server's 2368 domain "example.com"), and a nonce value in a NONCE attribute. The 2369 server also includes a SOFTWARE attribute that gives information 2370 about the server's software. 2372 The client, upon receipt of the 401 error, re-attempts the Allocate 2373 request, this time including the authentication attributes. The 2374 client selects a new transaction id, and then populates the new 2375 Allocate request with the same attributes as before. The client 2376 includes a USERNAME attribute and uses the realm value received from 2377 the server to help it determine which value to use; here the client 2378 is configured to use the username "George" for the realm 2379 "example.com". The client also includes the REALM and NONCE 2380 attributes, which are just copied from the 401 error response. 2381 Finally, the client includes a MESSAGE-INTEGRITY attribute as the 2382 last attribute in the message, whose value is an HMAC-SHA1 hash over 2383 the contents of the message (shown as just "..." above); this HMAC- 2384 SHA1 computation includes a password value, thus an attacker cannot 2385 compute the message integrity value without somehow knowing the 2386 secret password. 2388 The server, upon receipt of the authenticated Allocate request, 2389 checks that everything is OK, then creates an allocation. The server 2390 replies with an Allocate success response. The server includes a 2391 LIFETIME attribute giving the lifetime of the allocation; here, the 2392 server has reduced the client's requested 1 hour lifetime to just 20 2393 minutes, because this particular server doesn't allow lifetimes 2394 longer than 20 minutes. The server includes an XOR-RELAYED-ADDRESS 2395 attribute whose value is the relayed transport address of the 2396 allocation. The server includes an XOR-MAPPED-ADDRESS attribute 2397 whose value is the server-reflexive address of the client; this value 2398 is not used otherwise in TURN but is returned as a convenience to the 2399 client. The server includes a MESSAGE-INTEGRITY attribute to 2400 authenticate the response and to insure its integrity; note that the 2401 response does not contain the USERNAME, REALM, and NONCE attributes. 2402 The server also includes a SOFTWARE attribute. 2404 TURN TURN Peer Peer 2405 client server A B 2406 |--- CreatePermission request ------>| | | 2407 | Transaction-Id=0xE5913A8F460956CA277D3319 | | 2408 | XOR-PEER-ADDRESS=192.0.2.150:0 | | | 2409 | USERNAME="George" | | | 2410 | REALM="example.com" | | | 2411 | NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm" | | 2412 | MESSAGE-INTEGRITY=... | | | 2413 | | | | 2414 |<-- CreatePermission success resp.--| | | 2415 | Transaction-Id=0xE5913A8F460956CA277D3319 | | 2416 | MESSAGE-INTEGRITY=... | | | 2418 The client then creates a permission towards peer A in preparation 2419 for sending it some application data. This is done through a 2420 CreatePermission request. The XOR-PEER-ADDRESS attribute contains 2421 the IP address for which a permission is established (the IP address 2422 of peer A); note that the port number in the attribute is ignored 2423 when used in a CreatePermission request, and here it has been set to 2424 0; also note how the client uses Peer A's server-reflexive IP address 2425 and not its (private) host address. The client uses the same 2426 username, realm, and nonce values as in the previous request on the 2427 allocation. Though it is allowed to do so, the client has chosen not 2428 to include a SOFTWARE attribute in this request. 2430 The server receives the CreatePermission request, creates the 2431 corresponding permission, and then replies with a CreatePermission 2432 success response. Like the client, the server chooses not to include 2433 the SOFTWARE attribute in its reply. Again, note how success 2434 responses contain a MESSAGE-INTEGRITY attribute (assuming the server 2435 uses the Long-Term Credential Mechanism), but no USERNAME, REALM, and 2436 NONCE attributes. 2438 TURN TURN Peer Peer 2439 client server A B 2440 |--- Send indication --------------->| | | 2441 | Transaction-Id=0x1278E9ACA2711637EF7D3328 | | 2442 | XOR-PEER-ADDRESS=192.0.2.150:32102 | | 2443 | DONT-FRAGMENT | | | 2444 | DATA=... | | | 2445 | |-- UDP dgm ->| | 2446 | | data=... | | 2447 | | | | 2448 | |<- UDP dgm --| | 2449 | | data=... | | 2450 |<-- Data indication ----------------| | | 2451 | Transaction-Id=0x8231AE8F9242DA9FF287FEFF | | 2452 | XOR-PEER-ADDRSSS=192.0.2.150:32102 | | 2453 | DATA=... | | | 2455 The client now sends application data to Peer A using a Send 2456 indication. Peer A's server-reflexive transport address is specified 2457 in the XOR-PEER-ADDRESS attribute, and the application data (shown 2458 here as just "...") is specified in the DATA attribute. The client 2459 is doing a form of path MTU discovery at the application layer and 2460 thus specifies (by including the DONT-FRAGMENT attribute) that the 2461 server should set the DF bit in the UDP datagram send to the peer. 2462 Indications cannot be authenticated using the Long-Term Credential 2463 Mechanism of STUN, so no MESSAGE-INTEGRITY attribute is included in 2464 the message. An application wishing to ensure that its data is not 2465 altered or forged must integrity-protect its data at the application 2466 level. 2468 Upon receipt of the Send indication, the server extracts the 2469 application data and sends it in a UDP datagram to Peer A, with the 2470 relayed-transport-address as the source transport address of the 2471 datagram, and with the DF bit set as requested. Note that, had the 2472 client not previously established a permission for Peer A's server- 2473 reflexive IP address, then the server would have silently discarded 2474 the Send indication instead. 2476 Peer A then replies with its own UDP datagram containing application 2477 data. The datagram is sent to the relayed-transport-address on the 2478 server. When this arrives, the server creates a Data indication 2479 containing the source of the UDP datagram in the XOR-PEER-ADDRESS 2480 attribute, and the data from the UDP datagram in the DATA attribute. 2481 The resulting Data indication is then sent to the client. 2483 TURN TURN Peer Peer 2484 client server A B 2485 |--- ChannelBind request ----------->| | | 2486 | Transaction-Id=0x6490D3BC175AFF3D84513212 | | 2487 | CHANNEL-NUMBER=0x4000 | | | 2488 | XOR-PEER-ADDRESS=192.0.2.210:49191 | | 2489 | USERNAME="George" | | | 2490 | REALM="example.com" | | | 2491 | NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm" | | 2492 | MESSAGE-INTEGRITY=... | | | 2493 | | | | 2494 |<-- ChannelBind success response ---| | | 2495 | Transaction-Id=0x6490D3BC175AFF3D84513212 | | 2496 | MESSAGE-INTEGRITY=... | | | 2498 The client now binds a channel to Peer B, specifying a free channel 2499 number (0x4000) in the CHANNEL-NUMBER attribute, and Peer B's 2500 transport address in the XOR-PEER-ADDRESS attribute. As before, the 2501 client re-uses the username, realm, and nonce from its last request 2502 in the message. 2504 Upon receipt of the request, the server binds the channel number to 2505 the peer, installs a permission for Peer B's IP address, and then 2506 replies with ChannelBind success response. 2508 TURN TURN Peer Peer 2509 client server A B 2510 |--- ChannelData ------------------->| | | 2511 | Channel-number=0x4000 |--- UDP datagram --------->| 2512 | Data=... | Data=... | 2513 | | | | 2514 | |<-- UDP datagram ----------| 2515 | | Data=... | | 2516 |<-- ChannelData --------------------| | | 2517 | Channel-number=0x4000 | | | 2518 | Data=... | | | 2520 The client now sends a ChannelData message to the server with data 2521 destined for Peer B. The ChannelData message is not a STUN message, 2522 and thus has no transaction id. Instead, it has only three fields: a 2523 channel number, data, and data length; here the channel number field 2524 is 0x4000 (the channel the client just bound to Peer B). When the 2525 server receives the ChannelData message, it checks that the channel 2526 is currently bound (which it is) and then sends the data onward to 2527 Peer B in a UDP datagram, using the relayed-transport-address as the 2528 source transport address and 192.0.2.210:49191 (the value of the XOR- 2529 PEER-ADDRESS attribute in the ChannelBind request) as the destination 2530 transport address. 2532 Later, Peer B sends a UDP datagram back to the relayed-transport- 2533 address. This causes the server to send a ChannelData message to the 2534 client containing the data from the UDP datagram. The server knows 2535 which client to send the ChannelData message to because of the 2536 relayed-transport-address the UDP datagram arrived at, and knows to 2537 use channel 0x4000 because this is the channel bound to 192.0.2.210: 2538 49191. Note that if there had not been any channel number bound to 2539 that address, the server would have used a Data indication instead. 2541 TURN TURN Peer Peer 2542 client server A B 2543 |--- Refresh request --------------->| | | 2544 | Transaction-Id=0x0864B3C27ADE9354B4312414 | | 2545 | SOFTWARE="Example client 1.03" | | | 2546 | USERNAME="George" | | | 2547 | REALM="example.com" | | | 2548 | NONCE="adl7W7PeDU4hKE72jdaQvbAMcr6h39sm" | | 2549 | MESSAGE-INTEGRITY=... | | | 2550 | | | | 2551 |<-- Refresh error response ---------| | | 2552 | Transaction-Id=0x0864B3C27ADE9354B4312414 | | 2553 | SOFTWARE="Example server, version 1.17" | | 2554 | ERROR-CODE=438 (Stale Nonce) | | | 2555 | REALM="example.com" | | | 2556 | NONCE="npSw1Xw239bBwGYhjNWgz2yH47sxB2j" | | 2557 | | | | 2558 |--- Refresh request --------------->| | | 2559 | Transaction-Id=0x427BD3E625A85FC731DC4191 | | 2560 | SOFTWARE="Example client 1.03" | | | 2561 | USERNAME="George" | | | 2562 | REALM="example.com" | | | 2563 | NONCE="npSw1Xw239bBwGYhjNWgz2yH47sxB2j" | | 2564 | MESSAGE-INTEGRITY=... | | | 2565 | | | | 2566 |<-- Refresh success response -------| | | 2567 | Transaction-Id=0x427BD3E625A85FC731DC4191 | | 2568 | SOFTWARE="Example server, version 1.17" | | 2569 | LIFETIME=600 (10 minutes) | | | 2571 Sometime before the 20 minute lifetime is up, the client refreshes 2572 the allocation. This is done using a Refresh request. As before, 2573 the client includes the latest username, realm, and nonce values in 2574 the request. The client also includes the SOFTWARE attribute, 2575 following the recommended practice of always including this attribute 2576 in Allocate and Refresh messages. When the server receives the 2577 Refresh request, it notices that the nonce value has expired, and so 2578 replies with 438 (Stale Nonce) error given a new nonce value. The 2579 client then reattempts the request, this time with the new nonce 2580 value. This second attempt is accepted, and the server replies with 2581 a success response. Note that the client did not include a LIFETIME 2582 attribute in the request, so the server refreshes the allocation for 2583 the default lifetime of 10 minutes (as can be seen by the LIFETIME 2584 attribute in the success response). 2586 17. Security Considerations 2588 This section considers attacks that are possible in a TURN 2589 deployment, and discusses how they are mitigated by mechanisms in the 2590 protocol or recommended practices in the implementation. 2592 Note: Most of the attacks on TURN are mitigated by the server 2593 requiring requests be authenticated using the Long-Term Credential 2594 mechanism of STUN. Thus it is strongly recommended that servers 2595 demand that requests be authenticated. However, in certain 2596 deployments, the use of this mechanism may be unnecessary. An 2597 example might be a deployment where access to the TURN server is 2598 available only through a network where their are fairly tight 2599 controls over what devices can connect to the network (and by whom) 2600 and what software these devices can use. Tightly-run corporate 2601 networks can arguably fall into this category. 2603 17.1. Outsider Attacks 2605 Outsider attacks are ones where the attacker has no credentials in 2606 the system, and is attempting to disrupt the service seen by the 2607 client or the server. 2609 17.1.1. Obtaining Unauthorized Allocations 2611 An attacker might wish to obtain allocations on a TURN server for any 2612 number of nefarious purposes. A TURN server provides a mechanism for 2613 sending and receiving packets while cloaking the actual IP address of 2614 the client. This makes TURN servers an attractive target for 2615 attackers who wish to use it to mask their true identity. 2617 An attacker might also wish to simply utilize the services of a TURN 2618 server without paying for them. Since TURN services require 2619 resources from the provider, it is anticipated that their usage will 2620 come with a cost. 2622 These attacks are prevented using the digest authentication mechanism 2623 which allows the TURN server to determine the identity of the 2624 requestor and whether the requestor is allowed to obtain the 2625 allocation. 2627 17.1.2. Offline Dictionary Attacks 2629 The digest authentication mechanism used by TURN is subject to 2630 offline dictionary attacks. An attacker that is capable of 2631 eavesdropping on a message exchange between a client and server can 2632 determine the password by trying a number of candidate passwords and 2633 seeing if one of them is correct. This attack works when the 2634 passwords are low entropy, such as a word from the dictionary. This 2635 attack can be mitigated by using strong passwords with large entropy. 2636 In situations where even stronger mitigation is required, TLS 2637 transport between the client and the server can be used. 2639 17.1.3. Faked Refreshes and Permissions 2641 An attacker might wish to attack an active allocation by sending it a 2642 Refresh request with an immediate expiration, in order to delete it 2643 and disrupt service to the client. This is prevented by 2644 authentication of refreshes. Similarly, an attacker wishing to send 2645 CreatePermission requests to create permissions to undesirable 2646 destinations is prevented from doing so through authentication. The 2647 motivations for such an attack are described in Section 17.2. 2649 17.1.4. Fake Data 2651 An attacker might wish to send data to the client or the peer, as if 2652 they came from the peer or client respectively. To do that, the 2653 attacker can send the client a faked Data Indication or ChannelData 2654 message, or send the TURN server a faked Send Indication or 2655 ChannelData message. 2657 Indeed, since indications and ChannelData messages are not 2658 authenticated, this attack is not prevented by TURN. However, this 2659 attack is generally present in IP-based communications and is not 2660 substantially worsened by TURN. Consider an normal, non-TURN IP 2661 session between hosts A and B. An attacker can send packets to B as 2662 if they came from A by sending packets towards A with a spoofed IP 2663 address of B. This attack requires the attacker to know the IP 2664 addresses of A and B. With TURN, an attacker wishing to send packets 2665 towards a client using a Data indication needs to know its IP address 2666 (and port), the IP address and port of the TURN server, and the IP 2667 address and port of the peer (for inclusion in the XOR-PEER-ADDRESS 2668 attribute). To send a fake ChannelData message to a client, an 2669 attacker needs to know the IP address and port of the client, the IP 2670 address and port of the TURN server, and the channel number. This 2671 particular combination is mildly more guessable than in the non-TURN 2672 case. 2674 These attacks are more properly mitigated by application layer 2675 authentication techniques. In the case of real time traffic, usage 2676 of SRTP [RFC3711] prevents these attacks. 2678 In some situations, the TURN server may be situated in the network 2679 such that it is able to send to hosts that the client cannot directly 2680 send to. This can happen, for example, if the server is located 2681 behind a firewall that allows packets from outside the firewall to be 2682 delivered to the server, but not to other hosts behind the firewall. 2683 In these situations, an attacker could send the server a Send 2684 indication with an XOR-PEER-ADDRESS attribute containing the 2685 transport address of one of the other hosts behind the firewall. If 2686 the server was to allow relaying of traffic to arbitrary peers, then 2687 this would provide a way for the attacker to attack arbitrary hosts 2688 behind the firewall. 2690 To mitigate this attack, TURN requires that the client establish a 2691 permission to a host before sending it data. Thus an attacker can 2692 only attack hosts that the client is already communicating with, 2693 unless the attacker is able to create authenticated requests. 2694 Furthermore, the server administrator may configure the server to 2695 restrict the range of IP addresses and ports that it will relay data 2696 to. To provide even greater security, the server administrator can 2697 require that the client use TLS for all communication between the 2698 client and the server. 2700 17.1.5. Impersonating a Server 2702 When a client learns a relayed address from a TURN server, it uses 2703 that relayed address in application protocols to receive traffic. 2704 Therefore, an attacker wishing to intercept or redirect that traffic 2705 might try to impersonate a TURN server and provide the client with a 2706 faked relayed address. 2708 This attack is prevented through the digest authentication mechanism, 2709 which provides message integrity for responses in addition to 2710 verifying that they came from the server. Furthermore, an attacker 2711 cannot replay old server responses as the transaction ID in the STUN 2712 header prevents this. Replay attacks are further thwarted through 2713 frequent changes to the nonce value. 2715 17.1.6. Eavesdropping Traffic 2717 TURN concerns itself primarily with authentication and message 2718 integrity. Confidentiality is only a secondary concern, as TURN 2719 control messages do not include information that is particularly 2720 sensitive. The primary protocol content of the messages is the IP 2721 address of the peer. If it is important to prevent an eavesdropper 2722 on a TURN connection from learning this, TURN can be run over TLS. 2724 Confidentiality for the application data relayed by TURN is best 2725 provided by the application protocol itself, since running TURN over 2726 TLS does not protect application data between the server and the 2727 peer. If confidentiality of application data is important, then the 2728 application should encrypt or otherwise protect its data. For 2729 example, for real time media, confidentiality can be provided by 2730 using SRTP. 2732 17.1.7. TURN loop attack 2734 An attacker might attempt to cause data packets to loop indefinitely 2735 between two TURN servers. The attack goes as follows. First, the 2736 attacker sends an Allocate request to server A, using the source 2737 address of server B. Server A will send its response to server B, and 2738 for the attack to succeed, the attacker must have the ability to 2739 either view or guess the contents of this response, so that the 2740 attacker can learn the allocated relayed-transport-address. The 2741 attacker then sends an Allocate request to server B, using the source 2742 address of server A. Again, the attacker must be able to view or 2743 guess the contents of the response, so it can send learn the 2744 allocated relayed-transport-address. Using the same spoofed source 2745 address technique, the attacker then binds a channel number on server 2746 A to the relayed-transport-address on server B, and similarly binds 2747 the same channel number on server B to the relayed-transport-address 2748 on server A. Finally, the attacker sends a ChannelData message to 2749 server A. 2751 The result is a data packet that loops from the relayed-transport- 2752 address on server A to the relayed-transport-address on server B, 2753 then from server B's transport address to server A's transport 2754 address, and then around the loop again. 2756 This attack is mitigated as follows. By requiring all requests to be 2757 authenticated and/or by randomizing the port number allocated for the 2758 relayed-transport-address, the server forces the attacker to either 2759 intercept or view responses sent to a third party (in this case, the 2760 other server) so that the attacker can authenticate the requests and 2761 learn the relayed-transport-address. Without one of these two 2762 measures, an attacker can guess the contents of the responses without 2763 needing to see them, which makes the attack much easier to perform. 2764 Furthermore, by requiring authenticated requests, the server forces 2765 the attacker to have credentials acceptable to the server, which 2766 turns this from an outsider attack into an insider attack and allows 2767 the attack to be traced back to the client initiating it. 2769 The attack can be further mitigated by imposing a per-username limit 2770 on the bandwidth used to relay data by allocations owned by that 2771 username, to limit the impact of this attack on other allocations. 2773 More mitigation can be achieved by decrementing the TTL when relaying 2774 data packets (if the underlying OS allows this). 2776 17.2. Firewall Considerations 2778 A key aspect of TURN's security considerations is that it should not 2779 weaken the protections afforded by firewalls deployed between a 2780 client and a TURN server. It is anticipated that TURN servers will 2781 often be present on the public Internet, and clients may often be 2782 inside enterprise networks with corporate firewalls. If TURN servers 2783 provide a 'backdoor' for reaching into the enterprise, TURN will be 2784 blocked by these firewalls. 2786 TURN servers therefore emulate the behavior of NAT devices which 2787 implement address-dependent filtering [RFC4787], a property common in 2788 many firewalls as well. When a NAT or firewall implements this 2789 behavior, packets from an outside IP address are only allowed to be 2790 sent to an internal IP address and port if the internal IP address 2791 and port had recently sent a packet to that outside IP address. TURN 2792 servers introduce the concept of permissions, which provide exactly 2793 this same behavior on the TURN server. An attacker cannot send a 2794 packet to a TURN server and expect it to be relayed towards the 2795 client, unless the client has tried to contact the attacker first. 2797 It is important to note that some firewalls have policies which are 2798 even more restrictive than address-dependent filtering. Firewalls 2799 can also be configured with address and port dependent filtering, or 2800 can be configured to disallow inbound traffic entirely. In these 2801 cases, if a client is allowed to connect the TURN server, 2802 communications to the client will be less restrictive than what the 2803 firewall would normally allow. 2805 17.2.1. Faked Permissions 2807 In firewalls and NAT devices, permissions are granted implicitly 2808 through the traversal of a packet from the inside of the network 2809 towards the outside peer. Thus, a permission cannot, by definition, 2810 be created by any entity except one inside the firewall or NAT. With 2811 TURN, this restriction no longer holds. Since the TURN server sits 2812 outside the firewall, at attacker outside the firewall can now send a 2813 message to the TURN server and try to create a permission for itself. 2815 This attack is prevented because all messages which create 2816 permissions (i.e., ChannelBind and CreatePermission) are 2817 authenticated. 2819 17.2.2. Blacklisted IP Addresses 2821 Many firewalls can be configured with blacklists which prevent a 2822 client behind the firewall from sending packets to, or receiving 2823 packets from, ranges of blacklisted IP addresses. This is 2824 accomplished by inspecting the source and destination addresses of 2825 packets entering and exiting the firewall, respectively. 2827 If a client connects to a TURN server, it will be able to bypass such 2828 blacklisting policies and communicate with IP addresses which the 2829 firewall would otherwise restrict. This is a problem for other 2830 protocols that provide tunneling functions, such as VPNs. It is 2831 possible to build TURN-aware firewalls which inspect TURN messages, 2832 and check the IP address of the correspondent. TURN messages to 2833 offending destinations can then be rejected. TURN is designed so 2834 that this inspection can be done statelessly. 2836 17.2.3. Running Servers on Well-Known Ports 2838 A malicious client behind a firewall might try to connect to a TURN 2839 server and obtain an allocation which it then uses to run a server. 2840 For example, a client might try to run a DNS server or FTP server. 2842 This is not possible in TURN. A TURN server will never accept 2843 traffic from a peer for which the client has not installed a 2844 permission. Thus, peers cannot just connect to the allocated port in 2845 order to obtain the service. 2847 17.3. Insider Attacks 2849 In insider attacks, a client has legitimate credentials but defies 2850 the trust relationship that goes with those credentials. These 2851 attacks cannot be prevented by cryptographic means but need to be 2852 considered in the design of the protocol. 2854 17.3.1. DoS Against TURN Server 2856 A client wishing to disrupt service to other clients might obtain an 2857 allocation and then flood it with traffic, in an attempt to swamp the 2858 server and prevent it from servicing other legitimate clients. This 2859 is mitigated by the recommendation that the server limit the amount 2860 of bandwidth it will relay for a given username. This won't prevent 2861 a client from sending a large amount of traffic, but it allows the 2862 server to immediately discard traffic in excess. 2864 Since each allocation uses a port number on the IP address of the 2865 TURN server, the number of allocations on a server is finite. An 2866 attacker might attempt to consume all of them by requesting a large 2867 number of allocations. This is prevented by the recommendation that 2868 the server impose a limit of the number of allocations active at a 2869 time for a given username. 2871 17.3.2. Anonymous Relaying of Malicious Traffic 2873 TURN servers provide a degree of anonymization. A client can send 2874 data to correspondent peers without revealing their own IP addresses. 2875 TURN servers may therefore become attractive vehicles for attackers 2876 to launch attacks against targets without fear of detection. Indeed, 2877 it is possible for a client to chain together multiple TURN servers, 2878 such that any number of relays can be used before a target receives a 2879 packet. 2881 Administrators who are worried about this attack can maintain logs 2882 which capture the actual source IP and port of the client, and 2883 perhaps even every permission that client installs. This will allow 2884 for forensic tracing to determine the original source, should it be 2885 discovered that an attack is being relayed through a TURN server. 2887 17.3.3. Manipulating other Allocations 2889 An attacker might attempt to disrupt service to other users of the 2890 TURN server by sending Refresh requests or CreatePermission requests 2891 which (through source address spoofing) appear to be coming from 2892 another user of the TURN server. TURN prevents this by requiring 2893 that the credentials used in CreatePermission, Refresh, and 2894 ChannelBind messages match those used to create the initial 2895 allocation. Thus, the fake requests from the attacker will be 2896 rejected. 2898 17.4. Other Considerations 2900 Any relay addresses learned through an Allocate request will not 2901 operate properly with IPSec Authentication Header (AH) [RFC4302] in 2902 transport or tunnel mode. However, tunnel-mode IPSec ESP [RFC4303] 2903 should still operate. 2905 18. IANA Considerations 2907 Since TURN is an extension to STUN [RFC5389], the methods, attributes 2908 and error codes defined in this specification are new methods, 2909 attributes, and error codes for STUN. This section requests IANA to 2910 add these new protocol elements to the IANA registry of STUN protocol 2911 elements. 2913 The codepoints for the new STUN methods defined in this specification 2914 are listed in Section 13. 2916 The codepoints for the new STUN attributes defined in this 2917 specification are listed in Section 14. 2919 The codepoints for the new STUN error codes defined in this 2920 specification are listed in Section 15. 2922 IANA is requested to allocate the SRV service name of "turn" for TURN 2923 over UDP or TCP, and the service name of "turns" for TURN over TLS. 2925 IANA is requested to create a registry for TURN channel numbers, 2926 initially populated as follows: 2928 0x0000 through 0x3FFF: Not available for use, since they conflict 2929 with the STUN header. 2931 0x4000 through 0x7FFF: A TURN implementation is free to use 2932 channel numbers in this range. 2934 0x8000 through 0xFFFF: Reserved. 2936 Any change to this registry must be made through an IETF Standards 2937 Action. 2939 19. IAB Considerations 2941 The IAB has studied the problem of "Unilateral Self Address Fixing", 2942 which is the general process by which a client attempts to determine 2943 its address in another realm on the other side of a NAT through a 2944 collaborative protocol reflection mechanism [RFC3424]. The TURN 2945 extension is an example of a protocol that performs this type of 2946 function. The IAB has mandated that any protocols developed for this 2947 purpose document a specific set of considerations. These 2948 considerations and the responses for TURN are documented in this 2949 section. 2951 Consideration 1: Precise definition of a specific, limited-scope 2952 problem that is to be solved with the UNSAF proposal. A short term 2953 fix should not be generalized to solve other problems. Such 2954 generalizations lead to the prolonged dependence on and usage of the 2955 supposed short term fix -- meaning that it is no longer accurate to 2956 call it "short term". 2958 Response: TURN is a protocol for communication between a relay (= 2959 TURN server) and its client. The protocol allows a client that is 2960 behind a NAT to obtain and use a public IP address on the relay. As 2961 a convenience to the client, TURN also allows the client to determine 2962 its server-reflexive transport address. 2964 Consideration 2: Description of an exit strategy/transition plan. 2965 The better short term fixes are the ones that will naturally see less 2966 and less use as the appropriate technology is deployed. 2968 Response: TURN will no longer be needed once there are no longer any 2969 NATs. Unfortunately, as of the date of publication of this document, 2970 it no longer seems very likely that NATs will go away any time soon. 2971 However, the need for TURN will also decrease as the number of NATs 2972 with the mapping property of Endpoint-Independent Mapping [RFC4787] 2973 increases. 2975 Consideration 3: Discussion of specific issues that may render 2976 systems more "brittle". For example, approaches that involve using 2977 data at multiple network layers create more dependencies, increase 2978 debugging challenges, and make it harder to transition. 2980 Response: TURN is "brittle" in that it requires the NAT bindings 2981 between the client and the server to be maintained unchanged for the 2982 lifetime of the allocation. This is typically done using keep- 2983 alives. If this is not done, then the client will lose its 2984 allocation and can no longer exchange data with its peers. 2986 Consideration 4: Identify requirements for longer term, sound 2987 technical solutions; contribute to the process of finding the right 2988 longer term solution. 2990 Response: The need for TURN will be reduced once NATs implement the 2991 recommendations for NAT UDP behavior documented in [RFC4787]. 2992 Applications are also strongly urged to use ICE [I-D.ietf-mmusic-ice] 2993 to communicate with peers; though ICE uses TURN, it does so only as a 2994 last resort, and uses it in a controlled manner. 2996 Consideration 5: Discussion of the impact of the noted practical 2997 issues with existing deployed NATs and experience reports. 2999 Response: Some NATs deployed today exhibit a mapping behavior other 3000 than Endpoint-Independent mapping. These NATs are difficult to work 3001 with, as they make it difficult or impossible for protocols like ICE 3002 to use server-reflexive transport addresses on those NATs. A client 3003 behind such a NAT is often forced to use a relay protocol like TURN 3004 because "UDP hole punching" techniques [RFC5128] do not work. 3006 20. Open Issues 3008 Note to RFC Editor: Please remove this section prior to publication 3009 of this document as an RFC. 3011 This section lists the known issues in this version of the 3012 specification. 3014 (No known issues at this time). 3016 21. Changes from Previous Versions 3018 Note to RFC Editor: Please remove this section prior to publication 3019 of this document as an RFC. 3021 This section lists the technical and major editorial changes between 3022 the various versions of this specification. Minor editorial changes 3023 are not described. 3025 21.1. Changes from -15 to -16 3027 o Removed much of the text around the usage of ALTERNATE-SERVER. 3028 Previously, this document modified the specification of ALTERNATE- 3029 SERVER in the draft version of RFC 5389, but those modifications 3030 made it into the final version of RFC 5389 and so the extra text 3031 is no longer needed in this document. 3033 o Clarified the text in Section 8 and Section 10.3 around the 3034 checking of permissions when relaying a UDP datagram. 3036 o Added text specifying the requirements for support the various 3037 transport methods. 3039 21.2. Changes from -14 to -15 3041 o Added text saying that TURN servers and client MUST implement the 3042 Long-Term Credential Mechanism. Added text strongly recommending 3043 that servers require that all requests be authenticated. Noted a 3044 few cases where not using the Long-Term Credential Mechanism might 3045 be acceptable. 3047 o Added text to section Section 6.4 saying that unknown error 3048 responses must be handled as per [RFC5389]. 3050 o Added text clarifying the exact length of each attribute and 3051 reminding the reader that certain attributes must be immediately 3052 followed by 1 to 3 padding bytes. 3054 o Added a sentence to the acknowledgment section thanking Marc 3055 Petit-Huginen for his efforts in implementing many previous 3056 versions of the specification. 3058 o Fixed a number of minor document errors. 3060 21.3. Changes from -13 to -14 3062 o Reworded the text in Section 6.2 and Section 7.2 to more clearly 3063 describe how the allocation lifetime is computed in the case where 3064 a client requests a lifetime that is greater than both the default 3065 lifetime and the server's maximum allowed lifetime. 3067 o In Section 8, changed the term "default permission lifetime" to 3068 "Permission Lifetime" to make it clearer that the lifetime of a 3069 permission is not configurable. 3071 o In Section 6.2, swapped the steps that check the RESERVATION-TOKEN 3072 and EVEN-PORT attributes to correctly handle the case where an 3073 Allocate request contains both attributes. The new text correctly 3074 returns 400 Bad Request in this case. 3076 o Added text in the Overview section to describe why various timer 3077 values were chosen. 3079 o Added a sentence to the IAB consideration section saying that the 3080 disappearance of NATs in the near-term seems unlikely. 3082 o The former "Other Features" section of the Overview has been 3083 replaced with a series of sections describing various secondary 3084 features of TURN, and the text describing and motivating these 3085 secondary features has been expanded. As a part of this rewrite, 3086 there is now a section that describes how to avoid IP 3087 fragmentation when using TURN. 3089 o Added some additional text in the Overview to explain how a client 3090 would select between UDP, TCP, and TLS transport. 3092 o Fixed various minor typos. 3094 21.4. Changes from -12 to -13 3096 o Added a new error code: 403 (Forbidden). 3098 o When processing a CreatePermission or ChannelBind request 3099 containing a XOR-PEER-ADDRESS attribute, the server is allow to 3100 reject certain IP address and port combinations for administrative 3101 or other reasons by returning a 403 (Forbidden) error. 3103 o Added a request to IANA to establish a registery for channel 3104 numbers. 3106 o Clarified the usage of the nonce value: a new random nonce SHOULD 3107 be selected for each Allocate attempt, and the nonce SHOULD be 3108 expired at least once an hour. Referenced [RFC4086] for 3109 guidelines on selecting the nonce value. 3111 o Made a number of minor editoral changes. 3113 21.5. Changes from -11 to -12 3115 o Changed the port numbers used in the examples for the client, the 3116 peers, and the relayed-transport-address to put them in the 3117 Dynamic port range. They were previously in the Registered port 3118 range, which was arguably unrealistic. 3120 o Noted that the XOR-MAPPED-ADDRESS attribute is defined in RFC 3121 5389. 3123 o Used the codepoint names (Not-ECT, ECT(0), ECT(1), and CE) when 3124 talking about the ECN field. 3126 o Updated the Introduction to note that the client must not only 3127 communicate its relayed-transport-address to the peers, but also 3128 learn the peers' server-reflexive transport addresses. As a 3129 result, removed the suggestion that the client could use a webpage 3130 to communicate with its peers. 3132 o Added a description of the "TURN Loop attack" and its mitigation 3133 to the Security Considerations section. 3135 o Fixed some errors in the examples in the Overview section. They 3136 had not been updated to be consistent with the change introduced 3137 in version -11 that a permission must be created before a client 3138 can send data to a peer. 3140 o In the Additional Features subsection of the Overview, reworded 3141 the discussion of what end-to-end features are preserved by TURN. 3142 The previous text said that a number of features did not work, but 3143 as of version -11, these features _may_ work. At the same time, 3144 added a sentence noting that any Path MTU Discovery mechanism 3145 using the DONT-FRAGMENT attribute will not receive ICMP messages 3146 and will thus have to use techniques like those described in 3147 [RFC4821]. 3149 o Added the recommendation that, when TCP transport is used between 3150 the client and the server, both ends should close the connection 3151 if they notice a long sequence of invalid TURN messages. A likely 3152 cause of this is an undetected bit error corrupting a length field 3153 somewhere. 3155 o Reworded the paragraph explaining that channel bindings are per- 3156 allocation to further stress this point. 3158 o In the discussion on setting the fragmentation fields, added a 3159 sentence saying that the client or server should follow the normal 3160 rules for fragmentation as described in [RFC1122]. 3162 21.6. Changes from -10 to -11 3164 o Clarified that, when the client is redirected to an alternate 3165 server, the client uses the same transport protocol to the 3166 alternate server as it did to the original server. 3168 o Clarified the information that the server needs to store to 3169 authenticate requests and to compute the message-integrity on 3170 responses. Noted that the server need not store the password 3171 explicitly, but can instead store the key value, which may be 3172 desirable for security reasons. 3174 o Clarified that TURN runs on the same ports as TURN by default, but 3175 noted that a server can use a different port because TURN has its 3176 own SRV service names. Strengthened the language for using the 3177 SRV procedures from "typically" to "SHOULD". Also added a 3178 sentence in the IANA considerations section requesting that IANA 3179 reserve the service names for TURN; previously they were described 3180 in the text but not mentioned in the IANA considerations section. 3182 o Added a detailed example, complete with attributes and their 3183 values, of the use of TURN. 3185 o Reduced the range of channel numbers. Channel numbers now range 3186 from 0x4000 through 0x7FFF. Values in the range 0x8000 through 3187 0xFFFF are now reserved. 3189 o Rewrote the IAB Considerations section to directly address the 3190 considerations listed in [RFC3424]. 3192 o Generalized the 508 error code so it can be used for any sort of 3193 capacity-related problem. This error code was previously allowed 3194 only in Allocate responses, but is now also allowed in 3195 CreatePermission and ChannelBind responses to indicate that the 3196 server is unable to carry out the request due to some capacity 3197 problem. 3199 o Changed the syntax of the CreatePermission request to allow 3200 multiple XOR-PEER-ADDRESS attributes to appear in the message, so 3201 that multiple permissions can be created or refreshed at the same 3202 time. 3204 o Added the restriction that the server must already have a 3205 permission installed for the IP address in the XOR-PEER-ADDRESS 3206 attribute of a Send indication, otherwise the Send indication is 3207 ignored by the server. 3209 o Put back the preferred behaviors into Section 12, reversing the 3210 change made in version -10. 3212 o Explicitly allow the server to restrict the range of IP addresses 3213 and ports it is willing to relay data too. 3215 21.7. Changes from -09 to -10 3217 o Changed the recommendation for using the SOFTWARE attribute. 3218 Previously its use was recommended in all requests and responses; 3219 now it is only recommended in Allocate and Refresh requests and 3220 responses, though it may appear elsewhere. Also, version -09 3221 incorrectly referred to this attribute as "SOFTWARE-TYPE". 3223 o Changed the name of the PEER-ADDRESS and RELAYED-ADDRESS 3224 attributes to XOR-PEER-ADDRESS and XOR-RELAYED-ADDRESS 3225 respectively for consistency with other specifications. 3227 o Removed the concept of a "preserving" allocation. All allocations 3228 are now non-preserving. This simplifies the base specification 3229 and allows it to advance more rapidly; see the discussion in the 3230 BEHAVE meeting of 29 July 2008. The concept of a preserving 3231 allocation will be advanced as an extension to TURN. As part of 3232 this change, the P bit in the REQUESTED-PROPS attribute, the ICMP 3233 attribute, and ICMP message relaying was removed. Further, in 3234 Section 12, the preferred behaviors were removed, leaving the 3235 alternate behaviors as the specified behaviors. 3237 o Replaced the REQUESTED-PROPS attribute with the EVEN-PORT 3238 attribute. The new attribute lacks the feature of the old 3239 attribute of being an alternate way to specify new allocation 3240 properties. As a consequence, the only way to specify a new 3241 allocation property is to define a new attribute. 3243 o Added text recommending that the client check that the IP address 3244 in XOR-PEER-ADDRESS attribute in a received Data indication is one 3245 with which the client believes there is an active permission. 3246 Similarly, it is recommended that the client check that a 3247 permission exist when receiving a ChannelData message. 3249 o Added text recommending that the client delete the allocation if 3250 it receives a ChannelBind failure response on an unbound channel. 3252 o Added the CreatePermission request/response transaction which adds 3253 or updates permissions, and removed the ability for Send 3254 indications and ChannelBind messages to install or update 3255 permissions. The net effect is that only authenticate-able 3256 messages (i.e., CreatePermission requests and ChannelBind 3257 requests) can install or refresh permissions; unauthenticate-able 3258 Send indications and ChannelData messages do not. 3260 o Removed all support for IPv6. All IPv6 support, including ways of 3261 relaying between IPv4 and IPv6, will now be covered in 3262 [I-D.ietf-behave-turn-ipv6]. 3264 o Reserved attribute code point 0x0021. This was previously used 3265 for the TIMER-VAL attribute, which was removed when the 3266 SetActiveDestination feature was removed. 3268 o Added the DONT-FRAGMENT attribute which allows the client to 3269 request that the server set the DF bit when sending the UDP 3270 datagram to the peer. This attribute may appear in both Allocate 3271 requests and Send indications. 3273 o Changed how the ALTERNATE-SERVER attribute is used. The attribute 3274 can no longer be used with any error code, but must be used with 3275 300 (Try Alternative). It can now appear in unauthenticated 3276 responses, however there are restrictions around how the 3277 subsequent Allocate request is authenticated. 3279 o Reworked the details of how idempotency of requests is handled, 3280 making it clear that the stack can either remember all 3281 transactions for 40 seconds, or can handle this using the so- 3282 called "stateless stack approach". Made some changes to the 3283 semantics of the Allocate, Refresh, and ChannelBind requests as a 3284 consequence. 3286 o Added the requirement that a client cannot re-use previously bound 3287 channel number or transport address until 5 minutes after the 3288 channel binding expires. This avoids various race conditions. 3290 o Removed the requirement that an allocation cannot be re-used 3291 within 2 minutes of having been deleted. This requirement was put 3292 in place to prevent mis-delivered packets but is no longer seen as 3293 having any real value. 3295 o Added a recommendation that the server impose quotas on both the 3296 number of allocations and the amount of bandwidth a given username 3297 can use at one time. These quotas help protect against denial-of- 3298 service attacks. 3300 o Completely rewrote the security considerations section. 3302 o Made quite a few changes to the descriptive text in both the 3303 Overview and the normative text to try to further clarify 3304 concepts. 3306 21.8. Changes from -08 to -09 3308 o Added text to properly define the ICMP attribute. This attribute 3309 was introduced in TURN-08, but not fully defined due to an 3310 oversight. Clarified that the attribute can appear in a Data 3311 indication, but not a Send indication. Added text to the section 3312 on receiving a Data indication that points out that this attribute 3313 may be present. 3315 o Changed the wording around the handling of the DSCP field to allow 3316 the server to set the DSCP to an arbitrary value if the next hop 3317 is a Diff-Serv classifier and marker. 3319 o When the server generates a 508 response due to an unsupported 3320 flag in the REQUESTED-PROPS attribute, the server now includes the 3321 REQUESTED-PROPS attribute in the response with all the flags it 3322 supports set to 1. This allows the client to see if the server 3323 does not understand one of its flags. Similarly, the client is 3324 now allowed to immediately retry the request if it modifies the 3325 included REQUESTED-PROPS attribute. 3327 o Clarified that the REQUESTED-PROPS attribute can be used in 3328 conjunction with the RESERVATION-TOKEN attribute as long as both 3329 the E and R bits are 0. The spec previously contradicted itself 3330 on this point. 3332 o Clarified that when the server receives a ChannelData message with 3333 a length field of 0, it sends a UDP Datagram to the peer that 3334 contains no application data. 3336 o Rewrote some text around relaying incoming UDP Datagrams to avoid 3337 duplication of text in the Data indication and Channel sections. 3339 o Added a note that points out that the on-going work on randomizing 3340 port allocations [I-D.ietf-tsvwg-port-randomization] may be 3341 applicable to TURN. 3343 o Clarified that the Allocate request containing a RESERVATION-TOKEN 3344 attribute can use any 5-tuple, and that 5-tuple need not have any 3345 specific relationship to the 5-tuple of the Allocate request that 3346 created the reservation. 3348 o Added a note that discusses retransmitted Allocate requests over 3349 UDP where the first request receives a failure response, but the 3350 second receives a success response. The server may elect to 3351 remember transmitted failure responses to avoid this situation. 3353 o Added text about the usage of the SOFTWARE-TYPE attribute 3354 (formerly known as the SERVER attribute) in TURN messages. 3356 o Rewrote the text in the Overview that motivates why TURN supports 3357 TCP and TLS between the client and the server. The previous text 3358 had been identified by various readers as inadequate and 3359 misleading. 3361 o Rewrote the section how a server handles a Refresh request to 3362 clarify processing in various error conditions. The new text 3363 makes it clear that it is OK to delete a non-existent allocation. 3364 It also clarifies how to handle retransmissions of Refresh 3365 requests over UDP. 3367 o Renamed the "RELAY-ADDRESS" attribute to "RELAYED-ADDRESS", since 3368 the text consistently uses the term "relayed transport address" 3369 for the concept and ICE uses the term "relayed candidate". 3371 o Changed the codepoint assigned to the error code "Wrong 3372 Credentials" from 438 to 441 to avoid a conflict with the "Stale 3373 Nonce" error code of STUN. 3375 o Changed the text to consistently use non-capitalized "request", 3376 "response" and "indication", except in headings, error code names, 3377 etc. 3379 o Added a note mentioning that TURN packets can be demuxed from 3380 other packets arriving on the same socket by looking at the 3381 5-tuple of the arriving packet. 3383 o Clarified that there are no required attributes is a ChannelBind 3384 success response. 3386 21.9. Changes from -07 to -08 3388 o Removed the BANDWIDTH attribute and all associated text (including 3389 error code 507 "Insufficient Bandwidth Capacity"), as the 3390 requirements for this feature were not clear and it was felt the 3391 feature could be easily added later. 3393 o Changed the format of the REQUESTED-PROPS attribute from a one- 3394 byte field to a set of bit flags. Changed the semantics of the 3395 unused portion of the value from RFFU to "MUST be 0" to give a 3396 more desirable behavior when new flags are defined. 3398 o Introduced the concept of Preserving vs. Non-Preserving 3399 allocations. As a result, completely revamped the rules for how 3400 to set the fields in the IP header, and added rules for relaying 3401 ICMP messages when the allocation is Preserving. 3403 21.10. Changes from -06 to -07 3405 o Rewrote the General Behavior section, making various changes in 3406 the process. 3408 o Changed the usage of authentication from MUST to SHOULD. 3410 o Changed the requirement that subsequent requests use the same 3411 username and password from MUST to SHOULD to allow for the 3412 possibility of changing the credentials using some unspecified 3413 mechanism. 3415 o Introduced a 438 (Wrong Credentials) error which is used when a 3416 non-Allocate request authenticates but does not use the same 3417 username and password as the Allocate request. Having a separate 3418 error code for this case avoids the client being confused over 3419 what the error actually is. 3421 o The server must now prevent the relayed transport address and the 3422 5-tuple from being reused in different allocations for 2 minutes 3423 after the allocation expires. 3425 o Changed the usage of FINGERPRINT from MUST NOT to MAY, to allow 3426 for the possible multiplexing of TURN with some other protocol. 3428 o Rewrote much of the section on Allocations, splitting it into 3429 three new sections (one on allocations in general, one on creating 3430 an allocation, and one on refreshing an allocation). 3432 o Replaced the mechanism for requesting relayed transport addresses 3433 with specific properties. The new mechanism is less powerful: a 3434 client can request an even port, or a pair of ports, but cannot 3435 request a single odd port or a specific port as was possible under 3436 the old mechanism. Nor can the client request a specific IP 3437 address. 3439 o Changed the rules for handling ALTERNATE-SERVER, removing the 3440 requirement that the referring server have "positive knowledge" 3441 about the state of the alternate server. The new rules instead 3442 rely on text in STUN to prevent referral loops. 3444 o Changed the rules for allocation lifetimes. Allocations lifetimes 3445 are now a minimum of 10 minutes; the client can ask for longer 3446 values, but requests for shorter values are ignored. The text now 3447 recommends that the client refresh an allocation one minute before 3448 it expires. 3450 o Put in temporary procedures for handling the BANDWIDTH attribute, 3451 modelled on the LIFETIME attribute. These procedures are mostly 3452 placeholders and likely to change in the next revision. 3454 o Added a detailed description of how a client reacts to the various 3455 errors it can receive in reply to an Allocate request. This 3456 replaces the various descriptions that were previously scattered 3457 throughout the document, which were inconsistent and sometimes 3458 contradictory. 3460 o Added a new section that gives the normative rules for 3461 permissions. 3463 o Changed the rules around permission lifetimes. The text used to 3464 recommend a value of one minute; it MUST now be 5 minutes. 3466 o Removed the errors "Channel Missing or Invalid", "Peer Address 3467 Missing or Invalid" and "Lifetime Malformed or Invalid" and used 3468 400 "Bad Request" instead. 3470 o Rewrote portions of the section on Send and Data indications and 3471 the section on Channels to try to make the client vs. server 3472 behavior clearer. 3474 o Channel bindings now expire after 10 minutes, and must be 3475 refreshed to keep them alive. 3477 o Binding a channel now installs or refreshes a permission for the 3478 IP address of corresponding peer. 3480 o Changed the wording describing the situation when the client sends 3481 a ChannelData message before receiving the ChannelBind success 3482 response. -06 said that client SHOULD NOT do this; -07 now says 3483 that a client MAY, but describes the consequences of doing it. 3485 o Added a section discussing the setting of fields in the IP header. 3487 o Replaced the REQUESTED-PORT-PROPS attribute with the REQUESTED- 3488 PROPS attribute that has a different format and semantics, but 3489 reuses the same code point. 3491 o Replaced the REQUESTED-IP attribute with the RESERVATION-TOKEN 3492 attribute, which has a different format and semantics, but reuses 3493 the same code point. 3495 o Removed error codes 443 and 444, and replaced them with 508 3496 (Insufficient Port Capacity). Also changed the error text for 3497 code 507 from "Insufficient Capacity" to "Insufficient Bandwidth 3498 Capacity". 3500 21.11. Changes from -05 to -06 3502 o Changed the mechanism for allocating channels to the one proposed 3503 by Eric Rescorla at the Dec 2007 IETF meeting. 3505 o Removed the framing mechanism (which was used to frame all 3506 messages) and replaced it with the ChannelData message. As part 3507 of this change, noted that the demux of ChannelData messages from 3508 TURN messages can be done using the first two bits of the message. 3510 o Rewrote the sections on transmitted and receiving data as a result 3511 of the above to changes, splitting it into a section on Send and 3512 Data indications and a separate section on channels. 3514 o Clarified the handling of Allocate request messages. In 3515 particular, subsequent Allocate request messages over UDP with the 3516 same transaction id are not an error but a retransmission. 3518 o Restricted the range of ports available for allocation to the 3519 Dynamic and/or Private Port range, and noted when ports outside 3520 this range can be used. 3522 o Changed the format of the REQUESTED-TRANSPORT attribute. The 3523 previous version used 00 for UDP and 01 for TCP; the new version 3524 uses protocol numbers from the IANA protocol number registry. The 3525 format of the attribute also changed. 3527 o Made a large number of changes to the non-normative portion of the 3528 document to reflect technical changes and improve the 3529 presentation. 3531 o Added the Issues section. 3533 21.12. Changes from -04 to -05 3535 o Removed the ability to allocate addresses for TCP relaying. This 3536 is now covered in a separate document. However, communication 3537 between the client and the server can still run over TCP or TLS/ 3538 TCP. This resulted in the removal of the Connect method and the 3539 TIMER-VAL and CONNECT-STAT attributes. 3541 o Added the concept of channels. All communication between the 3542 client and the server flows on a channel. Channels are numbered 3543 0..65535. Channel 0 is used for TURN messages, while the 3544 remaining channels are used for sending unencapsulated data to/ 3545 from a remote peer. This concept adds a new Channel Confirmation 3546 method and a new CHANNEL-NUMBER attribute. The new attribute is 3547 also used in the Send and Data methods. 3549 o The framing mechanism formally used just for stream-oriented 3550 transports is now also used for UDP, and the former Type and 3551 Reserved fields in the header have been replaced by a Channel 3552 Number field. The length field is zero when running over UDP. 3554 o TURN now runs on its own port, rather than using the STUN port. 3555 The use of channels requires this. 3557 o Removed the SetActiveDestination concept. This has been replaced 3558 by the concept of channels. 3560 o Changed the allocation refresh mechanism. The new mechanism uses 3561 a new Refresh method, rather than repeating the Allocation 3562 transaction. 3564 o Changed the syntax of SRV requests for secure transport. The new 3565 syntax is "_turns._tcp" rather than the old "_turn._tls". This 3566 change mirrors the corresponding change in STUN SRV syntax. 3568 o Renamed the old REMOTE-ADDRESS attribute to PEER-ADDRESS, and 3569 changed it to use the XOR-MAPPED-ADDRESS format. 3571 o Changed the RELAY-ADDRESS attribute to use the XOR-MAPPED-ADDRESS 3572 format (instead of the MAPPED-ADDRESS format)). 3574 o Renamed the 437 error code from "No Binding" to "Allocation 3575 Mismatch". 3577 o Added a discussion of what happens if a client's public binding on 3578 its outermost NAT changes. 3580 o The document now consistently uses the term "peer" as the name of 3581 a remote endpoint with which the client wishes to communicate. 3583 o Rewrote much of the document to describe the new concepts. At the 3584 same time, tried to make the presentation clearer and less 3585 repetitive. 3587 22. Acknowledgements 3589 The authors would like to thank the various participants in the 3590 BEHAVE working group for their many comments on this draft. Marc 3591 Petit-Huguenin, Remi Denis-Courmont, Jason Fischl, Derek MacDonald, 3592 Scott Godin, Cullen Jennings, Lars Eggert, Magnus Westerlund, Benny 3593 Prijono, and Eric Rescorla have been particularly helpful, with Eric 3594 suggesting the channel allocation mechanism, Cullen suggesting the 3595 REQUESTED-PORT-PROPS mechanism, and Marc spending many hours 3596 implementing the preliminary versions to look for problems. 3597 Christian Huitema was an early contributor to this document and was a 3598 co-author on the first few drafts. Finally, the authors would like 3599 to thank Dan Wing for both his contributions to the text and his huge 3600 help in restarting progress on this draft after work had stalled. 3602 23. References 3604 23.1. Normative References 3606 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3607 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3608 October 2008. 3610 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3611 Requirement Levels", BCP 14, RFC 2119, March 1997. 3613 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3614 "Definition of the Differentiated Services Field (DS 3615 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3616 December 1998. 3618 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 3619 of Explicit Congestion Notification (ECN) to IP", 3620 RFC 3168, September 2001. 3622 [RFC1122] Braden, R., "Requirements for Internet Hosts - 3623 Communication Layers", STD 3, RFC 1122, October 1989. 3625 23.2. Informative References 3627 [RFC1191] Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, 3628 November 1990. 3630 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 3631 September 1981. 3633 [RFC1918] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and 3634 E. Lear, "Address Allocation for Private Internets", 3635 BCP 5, RFC 1918, February 1996. 3637 [RFC3424] Daigle, L. and IAB, "IAB Considerations for UNilateral 3638 Self-Address Fixing (UNSAF) Across Network Address 3639 Translation", RFC 3424, November 2002. 3641 [RFC4787] Audet, F. and C. Jennings, "Network Address Translation 3642 (NAT) Behavioral Requirements for Unicast UDP", BCP 127, 3643 RFC 4787, January 2007. 3645 [I-D.ietf-mmusic-ice] 3646 Rosenberg, J., "Interactive Connectivity Establishment 3647 (ICE): A Protocol for Network Address Translator (NAT) 3648 Traversal for Offer/Answer Protocols", 3649 draft-ietf-mmusic-ice-19 (work in progress), October 2007. 3651 [I-D.ietf-behave-turn-tcp] 3652 Perreault, S. and J. Rosenberg, "Traversal Using Relays 3653 around NAT (TURN) Extensions for TCP Allocations", 3654 draft-ietf-behave-turn-tcp-03 (work in progress), 3655 May 2009. 3657 [I-D.ietf-behave-turn-ipv6] 3658 Camarillo, G. and O. Novo, "Traversal Using Relays around 3659 NAT (TURN) Extension for IPv6", 3660 draft-ietf-behave-turn-ipv6-06 (work in progress), 3661 March 2009. 3663 [I-D.ietf-tsvwg-port-randomization] 3664 Larsen, M. and F. Gont, "Port Randomization", 3665 draft-ietf-tsvwg-port-randomization-04 (work in progress), 3666 July 2009. 3668 [RFC5128] Srisuresh, P., Ford, B., and D. Kegel, "State of Peer-to- 3669 Peer (P2P) Communication across Network Address 3670 Translators (NATs)", RFC 5128, March 2008. 3672 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 3673 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 3674 March 1996. 3676 [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. 3677 Jacobson, "RTP: A Transport Protocol for Real-Time 3678 Applications", STD 64, RFC 3550, July 2003. 3680 [RFC3711] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K. 3681 Norrman, "The Secure Real-time Transport Protocol (SRTP)", 3682 RFC 3711, March 2004. 3684 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 3685 December 2005. 3687 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 3688 RFC 4303, December 2005. 3690 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 3691 Discovery", RFC 4821, March 2007. 3693 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 3694 A., Peterson, J., Sparks, R., Handley, M., and E. 3695 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 3696 June 2002. 3698 [I-D.rosenberg-mmusic-ice-nonsip] 3699 Rosenberg, J., "Guidelines for Usage of Interactive 3700 Connectivity Establishment (ICE) by non Session 3701 Initiation Protocol (SIP) Protocols", 3702 draft-rosenberg-mmusic-ice-nonsip-01 (work in progress), 3703 July 2008. 3705 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 3706 Requirements for Security", BCP 106, RFC 4086, June 2005. 3708 [Frag-Harmful] 3709 Kent and Mogul, "Fragmentation Considered Harmful". 3711 Proc. SIGCOMM '87, vol. 17, No. 5, October 1987 3713 [Port-Numbers] 3714 "IANA Port Numbers Registry", 3715 . 3717 [Protocol-Numbers] 3718 "IANA Protocol Numbers Registry", 2005, 3719 . 3721 Authors' Addresses 3723 Jonathan Rosenberg 3724 Cisco Systems, Inc. 3725 Edison, NJ 3726 USA 3728 Email: jdrosen@cisco.com 3729 URI: http://www.jdrosen.net 3731 Rohan Mahy 3732 (Unaffiliated) 3734 Email: rohan@ekabal.com 3736 Philip Matthews 3737 Alcatel-Lucent 3738 600 March Road 3739 Ottawa, Ontario 3740 Canada 3742 Phone: 3743 Fax: 3744 Email: philip_matthews@magma.ca 3745 URI: