idnits 2.17.1 draft-ietf-behave-turn-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 19. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2216. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2227. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2234. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2240. 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 1 instance 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 25, 2008) is 5904 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 434, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-behave-rfc3489bis-15 == Outdated reference: A later version (-07) exists of draft-ietf-behave-turn-tcp-00 == Outdated reference: A later version (-11) exists of draft-ietf-behave-turn-ipv6-04 == Outdated reference: A later version (-11) exists of draft-ietf-tsvwg-udp-guidelines-05 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 8 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: August 28, 2008 Plantronics 6 P. Matthews 7 Avaya 8 February 25, 2008 10 Traversal Using Relays around NAT (TURN): Relay Extensions to Session 11 Traversal Utilities for NAT (STUN) 12 draft-ietf-behave-turn-07 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 28, 2008. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2008). 43 Abstract 45 If a host is located behind a NAT, then in certain situations it can 46 be impossible for that host to communicate directly with other hosts 47 (peers) located behind other NATs. In these situations, it is 48 necessary for the host to use the services of an intermediate node 49 that acts as a communication relay. This specification defines a 50 protocol, called TURN (Traversal Using Relays around NAT), that 51 allows the host to control the operation of the relay and to exchange 52 packets with its peers using the relay. 54 The TURN protocol can be used in isolation, but is more properly used 55 as part of the ICE (Interactive Connectivity Establishment) approach 56 to NAT traversal. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 4 62 2.1. Transports . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.2. Allocations . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.3. Exchanging Data with Peers . . . . . . . . . . . . . . . . 8 65 2.4. Channels . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 2.5. Permissions . . . . . . . . . . . . . . . . . . . . . . . 11 67 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 4. General Behavior . . . . . . . . . . . . . . . . . . . . . . . 12 69 5. Allocations . . . . . . . . . . . . . . . . . . . . . . . . . 13 70 6. Creating an Allocation . . . . . . . . . . . . . . . . . . . . 15 71 6.1. Sending an Allocate Request . . . . . . . . . . . . . . . 15 72 6.2. Receiving an Allocate Request . . . . . . . . . . . . . . 16 73 6.3. Receiving an Allocate Response . . . . . . . . . . . . . . 20 74 7. Refreshing an Allocation . . . . . . . . . . . . . . . . . . . 22 75 7.1. Sending a Refresh Request . . . . . . . . . . . . . . . . 22 76 7.2. Receiving a Refresh Request . . . . . . . . . . . . . . . 23 77 7.3. Receiving a Refresh Response . . . . . . . . . . . . . . . 24 78 8. Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 24 79 9. Send and Data Indications . . . . . . . . . . . . . . . . . . 25 80 9.1. Sending a Send Indication . . . . . . . . . . . . . . . . 25 81 9.2. Receiving a Send Indication . . . . . . . . . . . . . . . 26 82 9.3. Receiving a UDP Datagram . . . . . . . . . . . . . . . . . 26 83 9.4. Receiving a Data Indication . . . . . . . . . . . . . . . 26 84 10. Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 85 10.1. Sending a ChannelBind Request . . . . . . . . . . . . . . 28 86 10.2. Receiving a ChannelBind Request . . . . . . . . . . . . . 28 87 10.3. Receiving a ChannelBind Response . . . . . . . . . . . . . 29 88 10.4. The ChannelData Message . . . . . . . . . . . . . . . . . 29 89 10.5. Sending a ChannelData Message . . . . . . . . . . . . . . 30 90 10.6. Receiving a ChannelData Message . . . . . . . . . . . . . 30 91 10.7. Relaying . . . . . . . . . . . . . . . . . . . . . . . . . 31 92 11. IP Header Fields and Path MTU . . . . . . . . . . . . . . . . 31 93 11.1. DiffServ Code Point (DSCP) . . . . . . . . . . . . . . . . 32 94 11.2. Don't Fragment (DF) bit . . . . . . . . . . . . . . . . . 33 95 11.3. Other IP Header Fields . . . . . . . . . . . . . . . . . . 33 96 11.4. Path MTU . . . . . . . . . . . . . . . . . . . . . . . . . 33 97 12. New STUN Methods . . . . . . . . . . . . . . . . . . . . . . . 34 98 13. New STUN Attributes . . . . . . . . . . . . . . . . . . . . . 35 99 13.1. CHANNEL-NUMBER . . . . . . . . . . . . . . . . . . . . . . 35 100 13.2. LIFETIME . . . . . . . . . . . . . . . . . . . . . . . . . 35 101 13.3. BANDWIDTH . . . . . . . . . . . . . . . . . . . . . . . . 35 102 13.4. PEER-ADDRESS . . . . . . . . . . . . . . . . . . . . . . . 35 103 13.5. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 104 13.6. RELAY-ADDRESS . . . . . . . . . . . . . . . . . . . . . . 36 105 13.7. REQUESTED-PROPS . . . . . . . . . . . . . . . . . . . . . 36 106 13.8. REQUESTED-TRANSPORT . . . . . . . . . . . . . . . . . . . 37 107 13.9. RESERVATION-TOKEN . . . . . . . . . . . . . . . . . . . . 37 108 14. New STUN Error Response Codes . . . . . . . . . . . . . . . . 37 109 15. Security Considerations . . . . . . . . . . . . . . . . . . . 38 110 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 111 17. IAB Considerations . . . . . . . . . . . . . . . . . . . . . . 40 112 18. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 113 19. Changes from Previous Versions . . . . . . . . . . . . . . . . 40 114 19.1. Changes from -06 to -07 . . . . . . . . . . . . . . . . . 41 115 19.2. Changes from -05 to -06 . . . . . . . . . . . . . . . . . 43 116 19.3. Changes from -04 to -05 . . . . . . . . . . . . . . . . . 43 117 20. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 45 118 21. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 45 119 22. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 120 22.1. Normative References . . . . . . . . . . . . . . . . . . . 45 121 22.2. Informative References . . . . . . . . . . . . . . . . . . 46 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47 123 Intellectual Property and Copyright Statements . . . . . . . . . . 49 125 1. Introduction 127 Session Traversal Utilities for NAT (STUN) 128 [I-D.ietf-behave-rfc3489bis] provides a suite of tools for 129 facilitating the traversal of NAT. Specifically, it defines the 130 Binding method, which is used by a client to determine its reflexive 131 transport address towards the STUN server. The reflexive transport 132 address can be used by the client for receiving packets from peers, 133 but only when the client is behind "good" NATs. In particular, if a 134 client is behind a NAT whose mapping behavior [RFC4787] is address or 135 address and port dependent (sometimes called "bad" NATs), the 136 reflexive transport address will not be usable for communicating with 137 a peer. 139 The only reliable way to obtain a UDP transport address that can be 140 used for corresponding with a peer through such a NAT is to make use 141 of a relay. The relay sits on the public side of the NAT, and 142 allocates transport addresses to clients reaching it from behind the 143 private side of the NAT. These allocated transport addresses, called 144 relayed transport address, are IP addresses and ports on the relay. 145 When the relay receives a packet on one of these allocated addresses, 146 the relay forwards it toward the client. 148 This specification defines an extension to STUN, called TURN, that 149 allows a client to request a relayed transport address on a TURN 150 server. 152 Though a relayed transport address is highly likely to work when 153 corresponding with a peer, it comes at high cost to the provider of 154 the relay service. As a consequence, relayed transport addresses 155 should only be used as a last resort. Protocols using relayed 156 transport addresses should make use of mechanisms to dynamically 157 determine whether such an address is actually needed. One such 158 mechanism, defined for multimedia session establishment protocols 159 based on the offer/answer protocol in RFC 3264 [RFC3264], is 160 Interactive Connectivity Establishment (ICE) [I-D.ietf-mmusic-ice]. 162 TURN was originally invented to support multimedia sessions signaled 163 using SIP. Since SIP supports forking, TURN supports multiple peers 164 per client; a feature not supported by other approaches (e.g., SOCKS 165 [RFC1928]). However, care has been taken in the later stages of its 166 development to make sure that TURN is suitable for other types of 167 applications. 169 2. Overview of Operation 171 This section gives an overview of the operation of TURN. It is non- 172 normative. 174 In a typical configuration, a TURN client is connected to a private 175 network [RFC1918] and through one or more NATs to the public 176 Internet. On the public Internet is a TURN server. Elsewhere in the 177 Internet are one or more peers that the TURN client wishes to 178 communicate with. These peers may or may not be behind one or more 179 NATs. 181 +---------+ 182 | | 183 | | 184 / | Peer A | 185 Client's TURN // | | 186 Host Transport Server / | | 187 Address Address +-+ // +---------+ 188 10.1.1.2:17240 192.0.2.15:3478 |N|/ 192.168.100.2:16400 189 | | |A| 190 | +-+ | /|T| 191 | | | | / +-+ 192 v | | | / 192.0.2.210:18200 193 +---------+ | | |+---------+ / +---------+ 194 | | |N| || | // | | 195 | TURN | | | v| TURN |/ | | 196 | Client |----|A|----------| Server |------------------| Peer B | 197 | | | |^ | |^ ^| | 198 | | |T|| | || || | 199 +---------+ | || +---------+| |+---------+ 200 | || | | 201 | || | | 202 +-+| | | 203 | | | 204 | | | 205 Client's | Peer B 206 Server-Reflexive Relayed Transport 207 Transport Address Transport Address Address 208 192.0.2.1:7000 192.0.2.15:9000 192.0.2.210:18200 210 Figure 1 212 Figure 1 shows a typical deployment. In this figure, the TURN client 213 and the TURN server are separated by a NAT, with the client on the 214 private side and the server on the public side of the NAT. This NAT 215 is assumed to be a "bad" NAT; for example, it might have a mapping 216 property of address-and-port-dependent mapping (see [RFC4787]) for a 217 description of what this means). 219 The client has allocated a local port on one of its addresses for use 220 in communicating with the server. The combination of an IP address 221 and a port is called a TRANSPORT ADDRESS and since this (IP address, 222 port) combination is located on the client and not on the NAT, it is 223 called the client's HOST transport address. 225 The client sends TURN messages from its host transport address to a 226 transport address on the TURN server which is known as the TURN 227 SERVER ADDRESS. The client learns the server's address through some 228 unspecified means (e.g., configuration), and this address is 229 typically used by many clients simultaneously. The TURN server 230 address is used by the client to send both commands and data to the 231 server; the commands are processed by the TURN server, while the data 232 is relayed on to the peers. 234 Since the client is behind a NAT, the server sees these packets as 235 coming from a transport address on the NAT itself. This address is 236 known as the client's SERVER-REFLEXIVE transport address; packets 237 sent by the server to the client's server-reflexive transport address 238 will be forwarded by the NAT to the client's host transport address. 240 The client uses TURN commands to allocate a RELAYED TRANSPORT 241 ADDRESS, which is an transport address located on the TURN server. 242 The server ensures that there is a one-to-one relationship between 243 the client's server-reflexive transport address and the relayed 244 transport address; thus a packet received at the relayed transport 245 address can be unambiguously relayed by the server to the client. 247 The client will typically communicate this relayed transport address 248 to one or more peers through some mechanism not specified here (e.g., 249 an ICE offer or answer [I-D.ietf-mmusic-ice]). Once this is done, 250 the client can send data to the server to relay towards its peers. 251 In the reverse direction, peers can send data to the the relayed 252 transport address of the client. The server will relay this data to 253 the client as long as the client explicitly created a permission (see 254 Section 2.5) for the IP address of the peer. 256 2.1. Transports 258 TURN as defined in this specification only allows the use of UDP 259 between the server and the peer. However, this specification allows 260 the use of any one of UDP, TCP, or TLS over TCP to carry the TURN 261 messages between the client and the server. 263 +----------------------------+---------------------+ 264 | TURN client to TURN server | TURN server to peer | 265 +----------------------------+---------------------+ 266 | UDP | UDP | 267 | TCP | UDP | 268 | TLS over TCP | UDP | 269 +----------------------------+---------------------+ 271 If TCP or TLS over TCP is used between the client and the server, 272 then the server will convert between stream transport and UDP 273 transport when relaying data. TURN allows both TCP and TLS over TCP 274 as transports in part because many firewalls are configured to not 275 pass any UDP traffic. 277 For TURN clients, using TLS over TCP to communicate with the TURN 278 server provides two benefits. First, the client can be assured that 279 the addresses of its peers are not visible to any attackers between 280 it and the server. Second, the client may be able to communicate 281 with TURN servers using TLS when it would not be able to communicate 282 with the same server using TCP or UDP, due to the policy of a 283 firewall between the TURN client and its server. In this second 284 case, TLS between the client and TURN server facilitates traversal. 286 There is a planned extension to TURN to add support for TCP between 287 the server and the peers [I-D.ietf-behave-turn-tcp]. For this 288 reason, allocations that use UDP between the server and the peers are 289 known as UDP allocations, while allocations that use TCP between the 290 server and the peers are known as TCP allocations. This 291 specification describes only UDP allocations. 293 2.2. Allocations 295 To allocate a relayed transport address, the client uses an Allocate 296 transaction. The client sends a Allocate Request to the server, and 297 the server replies with an Allocate Response containing the allocated 298 relayed transport address. The client can include attributes in the 299 Allocate Request that describe the type of allocation it desires 300 (e.g., the lifetime of the allocation). And since relaying data can 301 require lots of bandwidth, the server typically requires that the 302 client authenticate itself using STUN's long-term credential 303 mechanism, to show that it is authorized to use the server. 305 Once a relayed transport address is allocated, a client must keep the 306 allocation alive. To do this, the client periodically sends a 307 Refresh Request to the server with the allocated related transport 308 address. TURN deliberately uses a different method (Refresh rather 309 than Allocate) for refreshes to ensure that the client is informed if 310 the allocation vanishes for some reason. 312 The frequency of the Refresh transaction is determined by the 313 lifetime of the allocation. The client can request a lifetime in the 314 Allocate Request and may modify its request in a Refresh Request, and 315 the server always indicates the actual lifetime in the response. The 316 client must issue a new Refresh transaction within 'lifetime' seconds 317 of the previous Allocate or Refresh transaction. If a client no 318 longer wishes to use an Allocation, it should do a Refresh 319 transaction with a requested lifetime of 0. 321 Note that sending or receiving data from a peer DOES NOT refresh the 322 allocation. 324 The server keeps track of the client reflexive transport address and 325 port, the server transport address and port, and the protocol used by 326 the client to communicate with the server. (Together known as a 327 5-tuple. The server remembers the 5-tuple used in the Allocate 328 Request. Subsequent transactions between the client and the server 329 use this same 5-tuple. In this way, the server knows which client 330 owns the allocated relayed transport address. If the client wishes 331 to allocate a second relayed transport address, it must use a 332 different 5-tuple for this allocation (e.g., by using a different 333 client host address)., 335 While the terminology used in this document refers to 5-tuples, 336 the TURN server can store whatever identifier it likes that yields 337 identical results. Specifically, many implementations use a file- 338 descriptor in place of a 5-tuple to represent a TCP connection. 340 2.3. Exchanging Data with Peers 342 There are two ways for the client and peers to exchange data using 343 the TURN server. The first way uses Send and Data indications, the 344 second way uses channels. Common to both ways is the ability of the 345 client to communicate with multiple peers using a single allocated 346 relayed transport address; thus both ways include a means for the 347 client to indicate to the server which peer to forward the data to, 348 and for the server to indicate which peer sent the data. 350 When using the first way, the client sends a Send indication to the 351 TURN server containing, in attributes inside the indication, the 352 transport address of the peer and the data to be sent to that peer. 353 When the TURN server receives the Send Indication, it extracts the 354 data from the Send Indication and sends it in a UDP datagram to the 355 peer, using the allocated relay address as the source address. In 356 the reverse direction, UDP datagrams arriving at the relay address on 357 the TURN server are converted into Data Indications and sent to the 358 client, with the transport address of the peer included in an 359 attribute in the Data Indication. 361 TURN TURN Peer Peer 362 client server A B 363 |--- Allocate Req -->| | | 364 |<-- Allocate Resp ---| | | 365 | | | | 366 |--- Send (Peer A)--->| | | 367 | |=== data ===>| | 368 | | | | 369 | |<== data ====| | 370 |<-- Data (Peer A)----| | | 371 | | | | 372 |--- Send (Peer B)--->| | | 373 | |=== data =================>| 374 | | | | 375 | |<== data ==================| 376 |<-- Data (Peer B)----| | | 378 Figure 2 380 In the figure above, the client first allocates a relayed transport 381 address. It then sends data to Peer A using a Send Indication; at 382 the server, the data is extracted and forwarded in a UDP datagram to 383 Peer A, using the relayed transport address as the source transport 384 address. When a UDP datagram from Peer A is received at the relayed 385 transport address, the contents are placed into a Data Indication and 386 forwarded to the client. A similar exchange happens with Peer B. 388 2.4. Channels 390 For some applications (e.g. Voice over IP), the 36 bytes of overhead 391 that a Send or Data indication adds to the application data can 392 substantially increase the bandwidth required between the client and 393 the server. To remedy this, TURN offers a second way for the client 394 and server to associate data with a specific peer. 396 This second way uses an alternate packet format known as the 397 ChannelData message. The ChannelData message does not use the STUN 398 header used by other TURN messages, but instead has a 4-byte header 399 that includes a number known as a channel number. Each channel 400 number in use is bound to a specific peer and thus serves as a 401 shorthand for the peer's address. 403 To bind a channel to a peer, the client sends a ChannelBind request 404 to the server, and includes an unbound channel number and the 405 transport address of the peer. Once the channel is bound, the client 406 can use a ChannelData message to send the server data destined for 407 the peer. Similarly, the server can relay data from that peer 408 towards the client using a ChannelData message. 410 Channel bindings last for 10 minutes unless refreshed. Channel 411 bindings are refreshed by sending ChannelData messages from the 412 client to the server, or by rebinding the channel to the peer. 414 TURN TURN Peer Peer 415 client server A B 416 |--- Allocate Req -->| | | 417 |<-- Allocate Resp ---| | | 418 | | | | 419 |--- Send (Peer A)--->| | | 420 | |=== data ===>| | 421 | | | | 422 | |<== data ====| | 423 |<-- Data (Peer A)----| | | 424 | | | | 425 |- ChannelBind Req -->| | | 426 | (Peer A to 0x4001) | | | 427 | | | | 428 |<- ChannelBind Resp -| | | 429 | | | | 430 |-- [0x4001] data --->| | | 431 | |=== data ===>| | 432 | | | | 433 | |<== data ====| | 434 |<- [0x4001] data --->| | | 435 | | | | 436 |--- Send (Peer B)--->| | | 437 | |=== data =================>| 438 | | | | 439 | |<== data ==================| 440 |<-- Data (Peer B)----| | | 442 Figure 3 444 The figure above shows the channel mechanism in use. The client 445 begins by allocating a relayed transport address, and then uses that 446 address to exchange data with Peer A. After a bit, the client decides 447 to bind a channel to Peer A. To do this, it sends a ChannelBind 448 request to the server, specifying the transport address of Peer A and 449 a channel number (0x4001). After that, the client can send 450 application data encapsulated inside ChannelData messages to Peer A: 451 this is shown as "[0x4001] data" where 0x4001 is the channel number. 453 Note that ChannelData messages can only be used for peers to which 454 the client has bound a channel. In the example above, Peer A has 455 been bound to a channel, but Peer B has not, so application data to 456 and from Peer B uses Send and Data indications. 458 Channel bindings are always initiated by the client. 460 2.5. Permissions 462 To ease concerns amongst enterprise IT administrators that TURN could 463 be used to bypass corporate firewall security, TURN includes the 464 notion of permissions. TURN permissions mimic the address-restricted 465 filtering mechanism of NATs that comply with [RFC4787]. 467 The client can install a permission by sending data to a peer (or by 468 doing certain other things). Once a permission is installed, any 469 peer with the same IP address (the ports numbers can differ) is 470 permitted to send data to the client. After 5 minutes, the 471 permission times out and the server drops any UDP datagrams arriving 472 at the relayed transport from that IP address. Note that permissions 473 are within the context of an allocation, so adding or expiring a 474 permission in one allocation does not affect other allocations. 476 Data received from the peer DOES NOT refresh the permission. 478 3. Terminology 480 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 481 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 482 document are to be interpreted as described in RFC 2119 [RFC2119]. 484 Readers are expected to be familar with [I-D.ietf-behave-rfc3489bis] 485 and the terms defined there. 487 The following terms are used in this document: 489 TURN: A protocol spoken between a TURN client and a TURN server. It 490 is an extension to the STUN protocol [I-D.ietf-behave-rfc3489bis]. 491 The protocol allows a client to allocate and use a relayed 492 transport address. 494 TURN client: A STUN client that implements this specification. 496 TURN server: A STUN server that implements this specification. It 497 relays data between a TURN client and its peer(s). 499 Peer: A host with which the TURN client wishes to communicate. The 500 TURN server relays traffic between the TURN client and its 501 peer(s). The peer does not interact with the TURN server using 502 the protocol defined in this document; rather, the peer receives 503 data sent by the TURN server and the peer sends data towards the 504 TURN server. 506 Host Transport Address: A transport address allocated on a host. 508 Server-Reflexive Transport Address: A transport address on the 509 "public side" of a NAT. This address is allocated by the NAT to 510 correspond to a specific host transport address. 512 Relayed Transport Address: A transport address that exists on a TURN 513 server. If a permission exists, packets that arrive at this 514 address are relayed towards the TURN client. 516 Allocation: The relayed transport address granted to a client 517 through an Allocate request, along with related state, such as 518 permissions and expiration timers. 520 5-tuple: The combination (client IP address and port, server IP 521 address and port, and transport protocol (UDP or TCP)) used to 522 communicate between the client and the server . The 5-tuple 523 uniquely identifies this communication stream. The 5-tuple also 524 uniquely identifies the Allocation on the server. 526 Permission: The IP address and transport protocol (but not the port) 527 of a peer that is permitted to send traffic to the TURN server and 528 have that traffic relayed to the TURN client. The TURN server 529 will only forward traffic to its client from peers that match an 530 existing permission. 532 4. General Behavior 534 This section contains general TURN processing rules that apply to all 535 TURN messages. 537 TURN is an extension to STUN. All TURN messages, with the exception 538 of the ChannelData message, are STUN-formatted messages. All the 539 base processing rules described in [I-D.ietf-behave-rfc3489bis] apply 540 to STUN-formatted messages. This means that all the message-forming 541 and -processing descriptions in this document are implicitly prefixed 542 with the rules of [I-D.ietf-behave-rfc3489bis]. 544 In addition, the server SHOULD require that all TURN requests use the 545 Long-Term Credential mechanism described in 546 [I-D.ietf-behave-rfc3489bis], and the client MUST be prepared to 547 authenticate requests if required. The server's administrator MUST 548 choose a realm value that will uniquely identify the username and 549 password combination that the client must use, even if the client 550 uses multiple servers under different administrations. The server's 551 administrator MAY choose to allocate a unique username to each 552 client, or MAY choose to allocate the same username to more than one 553 client (for example, to all clients from the same department or 554 company). 556 The client and/or the server MAY include the FINGERPRINT attribute in 557 any of the methods defined in this document. However, TURN does not 558 use the backwards-compatibility mechanism described in 559 [I-D.ietf-behave-rfc3489bis]. 561 By default, TURN runs on the same port as STUN. However, either the 562 SRV procedures or the ALTERNATE-SERVER procedures described in 563 Section 6 may be used to run TURN on a different port. 565 5. Allocations 567 All TURN operations revolve around allocations, and all TURN messages 568 are associated with an allocation. An allocation conceptually 569 consists of the following state data: 571 o Relayed transport address 573 o The 5-tuple: client IP address, client port, server IP address, 574 server port, transport protocol 576 o Username 578 o Transaction ID of the Allocate request 580 o Bandwidth 582 o Time-to-expiry 584 o List of permissions 586 o List of channel to peer bindings 588 The relayed transport address is the transport address allocated by 589 the server for communicating with peers, while the 5-tuple describes 590 the communication path between the client and the server. Both of 591 these MUST be unique across all allocations, so either one can be 592 used to uniquely identify the allocation. 594 When a TURN message arrives at the server from the client, the server 595 uses the 5-tuple in the message to identify the associated 596 allocation. For all TURN messages (including ChannelData) EXCEPT an 597 Allocate request, if the 5-tuple does not identify an existing 598 allocation, then the message MUST either be rejected with a 437 599 Allocation Mismatch error (if it is a request), or silently ignored 600 (if it is an indication or a ChannelData message). A client 601 receiving a 437 error response to a request other than Allocate MUST 602 assume the allocation no longer exists. 604 The username and password of the allocation is the username and 605 password of the authenticated Allocate request that creates the 606 allocation. Subsequent requests on an allocation use the same 607 username and password as those used to create the allocation, to 608 prevent attackers from hijacking the client's allocation. 609 Specifically, if the server requires the use of the Long-Term 610 Credential mechanism, and if a non-Allocate request passes 611 authentication under this mechanism, and if the 5-tuple identifies an 612 existing allocation, but the request does not use the same username 613 as used to create the allocation, then the request MUST be rejected 614 with a 438 (Wrong Credentials) error. 616 The transaction ID of the allocation is the transaction ID used in 617 the Allocate request. This is used to detect retransmissions of the 618 Allocate request over UDP (see Section 6.2 for details). 620 The bandwidth is the maximum bandwidth between the client and the 621 server that the client expects to need (in either direction). The 622 server MAY choose to police this value and refuse allocations to 623 ensure that the total bandwidth across all allocations does not 624 exceed the server's capacity. Servers that do so SHOULD require that 625 an allocation's bandwidth lie within two values: the minimum per- 626 allocation bandwidth and the maximum per-allocation bandwidth. 628 NOTE: Readers should be aware that the details around bandwidth 629 are still preliminary. The present description is likely to 630 change, perhaps significantly, before the specification is 631 finalized. 633 The time-to-expiry is the time in seconds left until the allocation 634 expires. Each Allocate or Refresh transaction sets this timer, which 635 then ticks down towards 0. By default, each Allocate or Refresh 636 transaction resets this timer to 600 seconds (10 minutes), but the 637 client can request a different value in the Allocate and Refresh 638 request. Allocations can only be refreshed using the Refresh 639 request; sending data to a peer does not refresh an allocation. When 640 an allocation expires, the state data associated with the allocation 641 is freed. However the server MUST ensure that neither the relayed 642 transport address nor the client reflexive transport address from the 643 5-tuple are re-used in other allocations until 2 minutes after the 644 allocation expires; this ensures that any messages that are in 645 transit when the allocation expires are gone before either of these 646 transport addresses are re-used. 648 The list of permissions is described in Section 8 and the list of 649 channels is described in Section 10. 651 6. Creating an Allocation 653 An allocation on the server is created using an Allocate transaction. 655 6.1. Sending an Allocate Request 657 The client forms an Allocate request as follows. 659 The client first needs to pick a host transport address that the 660 server does not think is currently in use, or was recently in use. 661 The client SHOULD pick a currently-unused transport address on the 662 client's host (typically by allowing its OS to pick a currently- 663 unused port for a new socket). 665 The client needs to pick a transport protocol to use between the 666 client and the server. The transport protocol MUST be one of UDP, 667 TCP, or TLS over TCP. Since this specification only allows UDP 668 between the server and the peers, it is RECOMMENDED that the client 669 pick UDP unless it has a reason to use a different transport. One 670 reason to pick a different transport would be that the client 671 believes, either through configuration or by experiment, that it is 672 unable to contact any TURN server using UDP. See Section 2.1 for 673 more discussion. 675 The client must also pick a server transport address. Typically, 676 this is done by the client learning (perhaps through configuration) 677 one or more domain names for TURN servers. In this case, the client 678 uses the DNS procedures described in [I-D.ietf-behave-rfc3489bis], 679 but using an SRV service name of "turn" (or "turns" for TURN over 680 TLS) instead of "stun" (or "stuns"). For example, to find servers in 681 the example.com domain, the client performs a lookup for 682 '_turn._udp.example.com', '_turn._tcp.example.com', and 683 '_turns._tcp.example.com' if the client wants to communicate with the 684 server using UDP, TCP, or TLS over TCP, respectively. 686 The client MUST include a REQUESTED-TRANSPORT attribute in the 687 request. This attribute specifies the transport protocol between the 688 server and the peers (note: NOT the one in the 5-tuple). In this 689 specification, the REQUESTED-TRANSPORT type is always UDP. This 690 attribute is included to allow future extensions specify other 691 protocols (e.g., [I-D.ietf-behave-turn-tcp]). 693 The client MAY include a BANDWIDTH attribute, describing the maximum 694 bandwidth that the client expects to exchange between it and the 695 server over this allocation. This is just a request, and the server 696 may elect to use a different value. If the client omits this 697 attribute, the server will pick a bandwidth for the allocation. 699 If the client wishes the server to initialize the time-to-expire 700 field of the allocation to some value other the default lifetime, 701 then it MAY include a LIFETIME attribute specifying its desired 702 value. This is just a request, and the server may elect to use a 703 different value. Note that the server will ignore requests to 704 initialize the field to less than the default value. 706 If the client wishes to communicate with older peers that make 707 certain assumptions about the port numbers that an endpoint uses, 708 then it MAY include either a REQUESTED-PROPS attribute or a 709 RESERVATION-TOKEN attribute (but not both). Using the REQUESTED- 710 PROPS attribute, the client can request: 712 o That the server allocate a relayed transport address with an even 713 port number, OR 715 o That the server reserve a pair of relayed transport addresses with 716 adjacent port numbers N and N+1, where N is even and N+1 is odd, 717 and then use port N for the current allocation. In this case, the 718 server returns a RESERVATION-TOKEN attribute in the response which 719 the client can then include in a subsequent Allocate request to 720 create an allocation with port number N+1. 722 The client then sends the allocation on the 5-tuple. 724 6.2. Receiving an Allocate Request 726 When the server receives an Allocate request, it performs the 727 following checks: 729 1. The server checks the credentials of the request, as per the 730 Long-Term Credential mechanism of [I-D.ietf-behave-rfc3489bis]. 732 2. The server checks if the 5-tuple is currently in use by an 733 existing allocation, or was it in use by another allocation 734 within the last 2 minutes. If yes, then there are two sub-cases: 736 * If the transport protocol in the 5-tuple is UDP, and if the 737 5-tuple is currently in use by an existing allocation, and if 738 the transaction id of the request matches the transaction id 739 stored with the allocation, then the request is a 740 retransmission of the original request. The server replies 741 either with a stored copy of the original response, or with a 742 response rebuilt from the stored state data. If the server 743 chooses to rebuild the response, then (a) it need not parse 744 the request further, but can immediately start building a 745 success response, (b) the value of the LIFETIME attribute can 746 be set to the current value of the time-to-expire timer, and 747 (c) the server may need to include an extra field in the 748 allocation to store the token returned in a RESERVATION-TOKEN 749 attribute. 751 * Otherwise, the server rejects the request with a 437 752 (Allocation Mismatch) error. 754 NOTE: If the request includes credentials that are acceptable to 755 server, but the 5-tuple is already in use, then it is important 756 that the server reject the request with a 437 (Allocation 757 Mismatch) error rather than a 401 (Unauthorized) error. This 758 ensures that the client knows that the problem is with the 759 5-tuple, rather than (wrongly) believing that the problem lies 760 with its credentials. 762 3. The server checks if the request contain a REQUESTED-TRANPORT 763 attribute. If the REQUESTED-TRANSPORT attribute is not included 764 or is malformed, the server rejects the request with a 400 (Bad 765 Request) error. Otherwise, if the attribute is included but 766 specifies a protocol other that UDP, the server rejects the 767 request with a 422 (Unsupported Transport Protocol) error. 769 4. The server checks if the request contains a BANDWIDTH attribute. 770 If yes, but the attribute is malformed or is out of range, the 771 server rejects the request with a 400 (Bad Request) error. 772 Otherwise, the server checks if it is willing to grant the 773 bandwidth request. The details of this check are described 774 below. If the server is not willing, it rejects the request with 775 a 507 (Insufficient Bandwidth Capacity) error. 777 5. The server checks if the request contains a REQUESTED-PROPS 778 attribute. If yes, then the server checks if it understands the 779 prop-type and can satisfy the request. If the prop-type is not 780 understood, or if the server cannot satisfy the request, then the 781 server rejects the request with a 508 (Insufficient Port 782 Capacity) error. 784 6. The server checks if the request contains a RESERVATION-TOKEN 785 attribute. If yes, and the request also contains a REQUESTED- 786 PROPS attribute, then the server rejectes the request with a 400 787 (Bad Request) error. Otherwise it checks to see if the token is 788 valid (i.e., the token is in range and has not expired, and the 789 corresponding relayed transport address is still available). If 790 the token is not valid for some reason, the server rejects the 791 request with a 508 (Insufficient Port Capacity) error. 793 7. At any point, the server MAY also choose to reject the request 794 with a 486 (Allocation Quota Reached) error if it feels the 795 client is trying to exceed some locally-defined allocation quota. 796 The server is free to define this allocation quota any way it 797 wishes, but SHOULD define it based on the username used to 798 authenticate the request, and not on the client's transport 799 address. 801 If the server rejects the request with one of the error codes 422 802 (Unsupported Transport Protocol), 486 (Allocation Quota Reached), 507 803 (Insufficient Bandwidth Capacity) or 508 (Insufficient Port 804 Capacity), it MAY include an ALTERNATE-SERVER attribute in the error 805 response redirecting the client to another server that it believes 806 will accept the request. If the attribute is included, the address 807 MUST be from the same address family as the server's transport 808 address. Note that, if the attribute is included, the client will 809 try this alternate server before trying the other servers given by 810 the SRV procedures. 812 If all the checks pass, the server creates the allocation. The 813 5-tuple is set to the 5-tuple from the Allocate request, while the 814 list of permissions and the list of channels are initially empty. 816 When allocating a relayed transport address for the allocation, the 817 server MUST allocate an IP address of the same family (e.g, IPv4 vs. 818 IPv6) as the server's transport address. 820 NOTE: An extension to TURN to allow an address from a different 821 address family is currently in progress 822 [I-D.ietf-behave-turn-ipv6]. 824 In addition, the server SHOULD only allocate ports from the range 825 49152 - 65535 (the Dynamic and/or Private Port range [Port-Numbers]), 826 unless the TURN server application knows, through some means not 827 specified here, that other applications running on the same host as 828 the TURN server application will not be impacted by allocating ports 829 outside this range. This condition can often be satisfied by running 830 the TURN server application on a dedicated machine and/or by 831 arranging that any other applications on the machine allocate ports 832 before the TURN server application starts. In any case, the TURN 833 server SHOULD NOT allocate ports in the range 0 - 1023 (the Well- 834 Known Port range) to discourage clients from using TURN to run 835 standard services. 837 If the request contains a REQUESTED-PROPS attribute requesting a pair 838 of ports, then the server looks for a pair of port numbers N and N+1 839 on the same IP address, where N is even. Port N is used in the 840 current allocation, while the relayed transport address with port N+1 841 is assigned a token and reserved for a future allocation. The server 842 MUST hold this reservation for at least 30 seconds, and MAY choose to 843 hold longer (e.g. until the allocation with port N expires). The 844 server then includes the token in a RESERVATION-TOKEN attribute in 845 the success response. 847 If the request contains a RESERVATION-TOKEN, the server uses the 848 previously-reserved transport address corresponding to the included 849 token (if it is still available). 851 The server determines the initial value of the allocation's bandwidth 852 as follows. If the BANDWIDTH attribute was not included, or if the 853 requested bandwidth is less than the minimum per-allocation 854 bandwidth, then the server behaves as if the minimum per-allocation 855 bandwidth was requested. Otherwise, if the request bandwidth is 856 greater than the maximum per-allocation bandwidth, then the server 857 behaves as if the maximum per-allocation bandwidth was requested. 859 The server then check if the (updated) requested bandwidth is 860 available, and if necessary reduces the requested bandwidth to the 861 amount that is willing to grant. If the result less than the minimum 862 per-allocation bandwidth, then the server considers the request to be 863 unsatisfiable, and rejects the request with a 507 (Insufficient 864 Bandwidth Capacity) error. Otherwise, the requested bandwidth 865 becomes the bandwidth of the allocation. 867 The server determines the initial value of the time-to-expire field 868 as follows. If the request contains a LIFETIME attribute, and the 869 proposed lifetime value is greater than the default lifetime, and the 870 proposed lifetime value is otherwise acceptable to the server, then 871 the server uses that value. Otherwise, the server uses the default 872 value. It is RECOMMENDED that the server impose a maximum lifetime 873 of no more than 3600 seconds (1 hour). 875 NOTE: Both the bandwidth and the time-to-expire are recomputed 876 with each successful Refresh request. Thus the values computed 877 here apply only until the first refresh. 879 Once the allocation is created, the server replies with a success 880 response. The success response contains: 882 o A RELAYED-ADDRESS attribute containing the relayed transport 883 address; 885 o A LIFETIME attribute containing the current value of the time-to- 886 expire timer; 888 o A BANDWIDTH attribute containing the actual bandwidth of the 889 allocation; and 891 o A RESERVATION-TOKEN attribute (if a second relayed transport 892 address was reserved). 894 o An XOR-MAPPED-ADDRESS attribute containing the client's IP address 895 and port (from the 5-tuple); 897 NOTE: The XOR-MAPPED-ADDRESS attribute is included in the response 898 as a convenience to the client. TURN itself does not make use of 899 this value, but clients running ICE can often need this value and 900 can thus avoid having to do an extra Binding transaction with some 901 STUN server to learn it. 903 The response (either success or error) is sent back to the client on 904 the 5-tuple. 906 6.3. Receiving an Allocate Response 908 If the client receives a success response, then it MUST check that 909 the relayed transport address is in an address family that the client 910 understands and is prepared to deal with. This specification only 911 covers the case where the relayed transport address is of the same 912 address family as the client's transport address. If the relayed 913 transport address is not in an address family that the client is 914 prepared to deal with, then the client MUST delete the allocation 915 (Section 7) and MUST NOT attempt to create another allocation on that 916 server until it believes the mismatch has been fixed. 918 Otherwise, the client creates its own copy of the allocation data 919 structure to track what is happening on the server. In particular, 920 the client needs to remember the actual lifetime and the actual 921 bandwith received back from the server, rather than the values sent 922 to the server in the request. The client must also remember the 923 5-tuple used for the request and the username and password it used to 924 authenticate the request to ensure that it reuses them for subsequent 925 messages. The client also needs to track the channels and 926 permissions it establishes on the server. 928 The client will probably wish to send the relayed transport address 929 to peers (using some method not specified here) so the peers can 930 communicate with it. The client may also wish to use the server- 931 reflexive address it receives in the XOR-MAPPED-ADDRESS attribute in 932 its ICE processing. 934 If the client receives an error response, then the processing depends 935 on the actual error code returned: 937 o (Request timed out): There is either a problem with the server, or 938 a problem reaching the server with the chosen transport. The 939 client MAY choose to try again using a different transport (e.g., 940 TCP instead of UDP), or the client MAY try a different server. 942 o 400 (Bad Request): The server believes the client's request is 943 malformed for some reason. The client MAY notify the user or 944 operator and SHOULD NOT retry the same request with this server 945 until it believes the problem has been fixed. The client MAY try 946 a different server. 948 o 401 (Unauthorized): If the client has followed the procedures of 949 the Long-Term Credential mechanism and still gets this error, then 950 the server is not accepting the client's credentials. The client 951 SHOULD notify the user or operator and SHOULD NOT send any further 952 requests to this server until it believes the problem has been 953 fixed. The client MAY try a different server. 955 o 437 (Allocation Mismatch): This indicates that the client has 956 picked a 5-tuple which the server sees as already in use or which 957 was recently in use. One way this could happen is if an 958 intervening NAT assigned a mapped transport address that was 959 recently used by another allocation. The client SHOULD pick 960 another client transport address and retry the Allocate request 961 (using a different transaction id). The client SHOULD try three 962 different client transport addresses before giving up on this 963 server. Once the client gives up on the server, it SHOULD NOT try 964 to create another allocation on the server for 2 minutes. 966 o 438 (Wrong Credentials): The client should not receive this error 967 in response to a Allocate request. The client MAY notify the user 968 or operator and SHOULD NOT retry the same request with this server 969 until it believes the problem has been fixed. The client MAY try 970 a different server. 972 o 442 (Unsupported Transport Address): The client should not receive 973 this error in response to a request for a UDP allocation. The 974 client MAY notify the user or operator and SHOULD NOT retry the 975 same request with this server until it believes the problem has 976 been fixed. The client MAY try a different server. 978 o 486 (Allocation Quota Reached): The server is currently unable to 979 create any more allocations with this username. The client SHOULD 980 wait at least 1 minute before trying to create any more 981 allocations on the server. The client MAY try a different server. 983 o 507 (Insufficient Bandwidth Capacity): The server is currently 984 unable to allocate any bandwidth to this allocation. The client 985 SHOULD wait at least 1 minute before trying to create any more 986 allocations on the server. The client MAY try a different server. 988 o 508 (Insufficient Port Capacity): The server has no more relayed 989 transport addresses avaiable, or has none with the requested 990 properties, or the one that was reserved is no longer available. 991 If the client is using either the REQUESTED-PROPS or the 992 RESERVATION-TOKEN attribute, then the client MAY choose to remove 993 this attribute and try again immediately. Otherwise, the client 994 SHOULD wait at least 1 minute before trying to create any more 995 allocations on this server. The client MAY try a different 996 server. 998 If the error response contains an ALTERNATE-SERVER attribute, and the 999 client elects to try a different server, the the client SHOULD try 1000 the alternate server specified in that attribute (while obeying the 1001 rules in [I-D.ietf-behave-rfc3489bis] for avoiding redirection loops) 1002 before trying any other servers found using the SRV procedures of 1003 [I-D.ietf-behave-rfc3489bis]. 1005 7. Refreshing an Allocation 1007 A Refresh transaction can be used to either (a) refresh an existing 1008 allocation and update its time-to-expire and bandwidth, or (b) delete 1009 an existing allocation. 1011 If a client wishes to continue using an allocation, then the client 1012 MUST refresh it before it expires. It is suggested that the client 1013 refresh the allocation roughly 1 minute before it expires. If a 1014 client no longer wishes to use an allocation, then it SHOULD 1015 explicitly delete the allocation. A client MAY also change the 1016 bandwidth and/or the time-to-expire of an allocation at any time for 1017 other reasons. 1019 7.1. Sending a Refresh Request 1021 If the client wishes to immediately delete an existing allocation, it 1022 includes a LIFETIME attribute with a value of 0. All other forms of 1023 the request refresh the allocation. 1025 The Refresh transaction updates the time-to-expire timer of an 1026 allocation. If the client wishes the server to set the time-to- 1027 expire timer to something other than the default lifetime, it 1028 includes a LIFETIME attribute with the requested value. The server 1029 then computes a new time-to-expire value in the same way as it does 1030 for an Allocate transaction, with the exception that a requested 1031 lifetime of 0 causes the server to immediately delete the allocation. 1033 The Refresh transaction also updates the bandwidth of an allocation. 1034 If the client wishes the server to update the bandwidth to something 1035 other than the mimimum per-allocation bandwidth, it includes the 1036 BANDWIDTH attribute with the requested value. 1038 The Refresh transaction is sent on the 5-tuple for the allocation. 1040 7.2. Receiving a Refresh Request 1042 When the server receives a Refresh request, it processes it as 1043 follows. If, during processing, an error in the request is detected 1044 (for example, a syntax error in the request which causes a 400 1045 error), then the request is rejected with an error response but the 1046 allocation is NOT deleted (but note that a 437 error will indicate 1047 that the allocation was not found). 1049 The server determines the new value for the time-to-expire field as 1050 follows. If the request contains a LIFETIME attribute, and the 1051 attribute value is 0, then the server uses a value of 0, which causes 1052 the allocation to expire. Otherwise, if the request contains a 1053 LIFETIME attribute and the attribute value is greater than the 1054 default lifetime, and the attribute value is otherwise acceptable to 1055 the server, then the server uses the attribute value. Otherwise, the 1056 server uses the default value. It is RECOMMENDED that the server 1057 impose a maximum lifetime of no more than 3600 seconds (1 hour). 1059 Assuming the allocation is not now expired, the server then 1060 determines a new value for the bandwidth as follows. If the request 1061 contains a BANDWIDTH attribute, or if the requested bandwidth is less 1062 than the minimum per-allocation bandwidth, then the server behaves as 1063 if the minimum per-allocation bandwidth was requested. Otherwise, if 1064 the request bandwidth is greater than the maximum per-allocation 1065 bandwidth, then the server behaves as if the maximum per-allocation 1066 bandwidth was requested. 1068 The server then compares the requested allocation bandwidth with the 1069 current allocation bandwidth. If the requested bandwidth is smaller, 1070 the current allocation bandwidth is updated. If the requested 1071 bandwidth is larger, then the current allocation bandwidth is 1072 increased to either the requested bandwidth or to the maximum 1073 currently available, whichever is smaller. 1075 The server then constructs a success response containing: 1077 o A LIFETIME attribute containing the current value of the time-to- 1078 expire timer; and 1080 o A BANDWIDTH attribute containing the actual bandwidth of the 1081 allocation. 1083 The response is then sent on the 5-tuple. 1085 7.3. Receiving a Refresh Response 1087 If the client receives a success response to its Refresh request, it 1088 updates its copy of the allocation data structure with the bandwidth 1089 and time-to-expire values contained in the response. 1091 If the client receives an 437 (Allocation Mismatch) error response to 1092 its Refresh request, then it must consider the allocation as having 1093 expired, as described in Section 4. All other errors indicate a 1094 software error on the part of either the client or the server. 1096 8. Permissions 1098 For each allocation, the server keeps a list of zero or more 1099 permissions. Each permission consists an IP address which uniquely 1100 identifies the permission, and an associated time-to-expiry. The IP 1101 address describes a peer that is allowed to send data to the client, 1102 and the time-to-expiry is the number of seconds until the permission 1103 expires. 1105 Various events, as described in subsequent sections, can cause a 1106 permission for a given IP address to be installed or refreshed. This 1107 causes one of two things to happen: 1109 o If no permission for that IP address exists, then a permission is 1110 created with the given IP address and a time-to-expiry equal to 1111 the default permission lifetime. 1113 o If a permission for that IP address already exists, then the 1114 lifetime for that permission is reset to the default permission 1115 lifetime. 1117 The default permission lifetime MUST be 300 seconds (= 5 minutes). 1119 Each permission's time-to-expire decreases down once per second until 1120 it reaches 0, at which point the permission expires and is deleted. 1122 When a UDP datagram arrives at the relayed transport address for the 1123 allocation, the server checks the list of permissions for that 1124 allocation. If there is a permission with an IP address that is 1125 equal to the source IP address of the UDP datagram, then the UDP 1126 datagram can be relayed to the client. Otherwise, the UDP datagram 1127 is silently discarded. Note that only IP addresses are compared; 1128 port numbers are irrelevant. 1130 The permissions for one allocation are totally unrelated to the 1131 permissions for a different allocation. If an allocation expires, 1132 all its permissions expire with it. 1134 NOTE: Though TURN permissions expire after 5 minutes, many NATs 1135 deployed at the time of publication expire their UDP bindings 1136 considerably faster. Thus an application using TURN will probably 1137 wish to send some sort of keep-alive traffic at a much faster 1138 rate. Applications using ICE should follow the keep-alive 1139 guidelines of ICE [I-D.ietf-mmusic-ice], and applications not 1140 using ICE are advised to do something similar. 1142 9. Send and Data Indications 1144 TURN supports two ways to send and receive data from peers. This 1145 section describes the use of Send and Data indications, while 1146 Section 10 describes the use of the Channel Mechanism. 1148 9.1. Sending a Send Indication 1150 A client can use a Send Indication to pass data to the server for 1151 relaying to a peer. A client can also use a Send Indication without 1152 a DATA attribute to install or refresh a permission for the specified 1153 IP address. A client may use a Send indication to send data to a 1154 peer even if a channel is bound to that peer. 1156 When forming a Send Indication, the client MUST include a PEER- 1157 ADDRESS attribute and MAY include a DATA attribute. If the DATA 1158 attribute is included, then the DATA attribute contains the actual 1159 application data to be sent to the peer, and the PEER-ADDRESS 1160 attribute contains the transport address of the peer to which the 1161 data is to be sent. If the DATA attribute is not present, then the 1162 PEER-ADDRESS attribute contains the IP address for which a permission 1163 is to be installed or refreshed; in this case the port specified in 1164 the attribute is ignored. 1166 Note that no authentication attributes are included, since 1167 indications cannot be authenticated using the Long-Term Credential 1168 mechanism. 1170 The Send Indication MUST be sent using the same 5-tuple used for the 1171 original allocation. 1173 9.2. Receiving a Send Indication 1175 When the server receives a Send indication, it processes it as 1176 follows. 1178 If the received Send indication contains a DATA attribute, then it 1179 forms a UDP datagram as follows: 1181 o the source transport address is the relayed transport address of 1182 the allocation, where the allocation is determined by the 5-tuple 1183 on which the Send Indication arrived; 1185 o the destination transport address is taken from the PEER-ADDRESS 1186 attribute; 1188 o the data following the UDP header is the contents of the value 1189 field of the DATA attribute. 1191 The resulting UDP datagram is then sent to the peer. If any errors 1192 are detected during this process (e.g., the Send indication does not 1193 contain a PEER-ADDRESS attribute), the received indication is 1194 silently discarded and no UDP datagram is sent. 1196 When the server receives a valid Send Indication, either with or 1197 without a DATA attribute, it also installs or refreshes a permission 1198 for the IP address contained in the PEER-ADDRESS attribute (see 1199 Section 8). 1201 9.3. Receiving a UDP Datagram 1203 When the server receives a UDP datagram at a currently allocated 1204 relayed transport address, the server looks up the allocation 1205 associated with the relayed transport address. It then checks to see 1206 if relaying is permitted, as described in section Section 8). 1208 If relaying is permitted, and there is no channel bound to the peer 1209 that sent the UDP datagram (see ISection 10), then the server forms 1210 and sends a Data indication. The Data indication MUST contain both a 1211 PEER-ADDRESS and a DATA attribute. The DATA attribute is set to the 1212 value of the 'data octets' field from the datagram, and the PEER- 1213 ADDRESS attribute is set to the source transport address of the 1214 received UDP datagram. The Data indication is then sent on the 1215 5-tuple associated with the allocation. 1217 9.4. Receiving a Data Indication 1219 When the client receives a Data indication, it checks that the Data 1220 indication contains both a PEER-ADDRESS and a DATA attribute. It 1221 then delivers the data octets inside the DATA attribute to the 1222 application, along with an indication that they were received from 1223 the peer whose transport address is given by the PEER-ADDRESS 1224 attribute. 1226 10. Channels 1228 Channels provide a way for the client and server to send application 1229 data using ChannelData messages, which have less overhead than Send 1230 and Data indications. 1232 Channel bindings are always initiated by the client. The client can 1233 bind a channel to a peer at any time during the lifetime of the 1234 allocation. The client may bind a channel to a peer before 1235 exchanging data with it, or after exchanging data with it (using Send 1236 and Data indications) for some time, or may choose never to bind a 1237 channel it. The client can also bind channels to some peers while 1238 not binding channels to other peers. 1240 Channel bindings are specific to an allocation, so that a binding in 1241 one allocation has no relationship to a binding in any other 1242 allocation. If an allocation expires, all its channel bindings 1243 expire with it. 1245 A channel binding consists of: 1247 o A channel number; 1249 o A transport address (of the peer); 1251 o A time-to-expiry timer. 1253 Within the context of an allocation, a channel binding is uniquely 1254 identified either by the channel number or by the transport address. 1255 Thus the same channel cannot be bound to two different transport 1256 addresses, nor can the same transport address be bound to two 1257 different channels. 1259 A channel binding last for 10 minutes unless refreshed. Refreshing 1260 the binding (by the server receiving either a ChannelBind request 1261 rebinding the channel to the same peer, or by the server receiving a 1262 ChannelData message on that channel) resets the time-to-expire timer 1263 back to 10 minutes. When the channel binding expires, the channel 1264 becomes unbound and available for binding to a different transport 1265 address. 1267 When binding a channel to a peer, the client SHOULD be prepared to 1268 receive ChannelData messages on the channel from the server as soon 1269 as it has sent the ChannelBind request. Over UDP, it is possible for 1270 the client to receive ChannelData messages from the server before it 1271 receives a ChannelBind success response. 1273 In the other direction, the client MAY elect to send ChannelData 1274 messages before receiving the ChannelBind success response. Doing 1275 so, however, runs the risk of having the ChannelData messages dropped 1276 by the server if the ChannelBind request does not succeed for some 1277 reason (e.g., packet lost if the request is sent over UDP, or the 1278 server being unable to fulfill the request). A client that wishes to 1279 be safe should either queue the data, or use Send indications until 1280 the channel binding is confirmed. 1282 10.1. Sending a ChannelBind Request 1284 A channel binding is created using a ChannelBind transaction. A 1285 channel binding can also be refreshed using a ChannelBind 1286 transaction. 1288 To initiate the ChannelBind transaction, the client forms a 1289 ChannelBind request. The channel to be bound is specified in a 1290 CHANNEL-NUMBER attribute, and the peer's transport address is 1291 specified in a PEER-ADDRESS attribute. Section 10.2 describes the 1292 restrictions on these attributes. 1294 Note that rebinding a channel to the same transport address that it 1295 is already bound to provides a way to refresh a channel binding 1296 without sending data to the peer. 1298 Once formed, the ChannelBind Request is sent using the 5-tuple for 1299 the allocation. 1301 10.2. Receiving a ChannelBind Request 1303 When the server receives a ChannelBind request, it checks the 1304 following: 1306 o The request contains both a CHANNEL-NUMBER and a PEER-ADDRESS 1307 attribute; 1309 o The channel number is in the range 0x4000 to 0xFFFE (inclusive); 1311 o The channel number is not currently bound to a different transport 1312 address (same transport address is OK); 1314 o The transport address is not currently bound to a different 1315 channel number. 1317 If any of these tests fail, the server replies with an error response 1318 with error code 400 "Bad Request". Otherwise, the ChannelBind 1319 request is valid and the server replies with a ChannelBind success 1320 response. 1322 If ChannelBind request is valid, then the server creates or refreshes 1323 the channel binding using the channel number in the CHANNEL-ADDRESS 1324 attribute and the transport address in the PEER-ADDRESS attribute. 1325 The server also installs or refreshes a permission for the IP address 1326 in the PEER-ADDRESS attribute. 1328 10.3. Receiving a ChannelBind Response 1330 When the client receives a successful ChannelBind response, it 1331 updates its data structures to record that the channel binding is now 1332 active. 1334 10.4. The ChannelData Message 1336 The ChannelData message is used to carry application data between the 1337 client and the server. It has the following format: 1339 0 1 2 3 1340 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 1341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1342 | Channel Number | Length | 1343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1344 | | 1345 / Application Data / 1346 / / 1347 | | 1348 | +-------------------------------+ 1349 | | 1350 +-------------------------------+ 1352 The Channel Number field specifies the number of the channel on which 1353 the data is traveling, and thus the address of the peer that is 1354 sending or is to receive the data. The channel number MUST be in the 1355 range 0x4000 - 0xFFFF, with channel number 0xFFFF being reserved for 1356 possible future extensions. 1358 Channel numbers 0x0000 - 0x3FFF cannot be used because bits 0 and 1 1359 are used to distinguish ChannelData messages from STUN-formatted 1360 messages (i.e., Allocate, Send, Data, ChannelBind, etc). STUN- 1361 formatted messages always have bits 0 and 1 as "00", while 1362 ChannelData messages use combinations "01", "10", and "11". 1364 The Length field specifies the length in bytes of the application 1365 data field (i.e., it does not include the size of the ChannelData 1366 header). Note that 0 is a valid length. 1368 The Application Data field carries the data the client is trying to 1369 send to the peer, or that the peer is sending to the client. 1371 10.5. Sending a ChannelData Message 1373 Once a client has bound a channel to a peer, then when the client has 1374 data to send to that peer it may use either a ChannelData message or 1375 a Send Indication; that is, the client is not obligated to use the 1376 channel when it exists and may freely intermix the two message types 1377 when sending data to the peer. The server, on the other hand, MUST 1378 use the ChannelData message if a channel has been bound to the peer. 1380 The fields of the ChannelData message are filled in as described in 1381 Section 10.4. 1383 Over stream transports, the ChannelData message MUST be padded to a 1384 multiple of four bytes in order to ensure the alignment of subsequent 1385 messages. The padding is not reflected in the length field of the 1386 ChannelData message, so the actual size of a ChannelData message 1387 (including padding) is (4 + Length) rounded up to the nearest 1388 multiple of 4. Over UDP, the padding is not required but MAY be 1389 included. 1391 The ChannelData message is then sent on the 5-tuple associated with 1392 the allocation. 1394 10.6. Receiving a ChannelData Message 1396 The receiver of the ChannelData message uses bits 0 and 1 to 1397 distinguish it from STUN-formatted messages, as described in 1398 Section 10.4. 1400 If the ChannelData message is received in a UDP datagram, and if the 1401 UDP datagram is too short to contain the claimed length of the 1402 ChannelData message (i.e., the UDP header length field value is less 1403 than the ChannelData header length field value + 4 + 8), then the 1404 message is silently discarded. 1406 If the ChannelData message is received over TCP or over TLS over TCP, 1407 then the actual length of the ChannelData message is as described in 1408 Section 10.5. 1410 If the ChannelData message is received on a channel which is not 1411 bound to any peer, then the message is silently discarded. 1413 10.7. Relaying 1415 When a server receives a ChannelData message, it first processes it 1416 as described in the previous section. If no errors are detected, it 1417 relays the application data to the peer by forming a UDP datagram as 1418 follows: 1420 o the source transport address is the relayed transport address of 1421 the allocation, where the allocation is determined by the 5-tuple 1422 on which the ChannelData message arrived; 1424 o the destination transport address is the transport address to 1425 which the channel is bound; 1427 o the data following the UDP header is the contents of the data 1428 field of the ChannelData message. 1430 The resulting UDP datagram is then sent to the peer. 1432 If the ChannelData message is valid, then the server refreshes the 1433 channel binding, and also installs or refreshes a permission for the 1434 IP address part of the transport address to which the UDP datagram is 1435 sent (see Section 8). 1437 In the other direction, when the server receives a UDP datagram on 1438 the relayed transport address associated with an allocation, then it 1439 first checks to see if it is permitted to relay the datagram. This 1440 check is done as described in Section 8. If relaying is permitted, 1441 then the server checks to see if there is a channel bound to the peer 1442 that sent the UDP datagram. If there is, then it SHOULD form and 1443 send a ChannelData message as described in Section 10.5. If no 1444 channel is bound to the peer, then it MUST form and send a Data 1445 indication as described in Section 9.3. 1447 11. IP Header Fields and Path MTU 1449 This section describes how the server should set various fields in 1450 the IP header when relaying application data. The requirements here 1451 document the desired behavior of the server, but it is recognized 1452 that some of these requirements may be impossible to implement in 1453 certain environments. 1455 NOTE: The recommendations in this section are the result of much 1456 discussion, and are a compromise between the perfect relaying 1457 solution and one that can be implemented easily. In particular, 1458 these recommendations takes into account the following: 1460 * TURN allows a TCP, or a TLS over TCP, connection between the 1461 client and the server, while using a UDP connection between the 1462 server and a peer. For this reason, the notion of a single 1463 end-to-end connection does not always exist. 1465 * Many people want to run a TURN server as a process in user- 1466 space under common operating systems, without requiring the 1467 server process to have special privileges (such as those 1468 required to use RAW sockets). One motivation for this is the 1469 desire to implement a TURN server in a peer application in a 1470 peer-to-peer overlay to provide relaying functions to other 1471 peers which reside behind 'bad' NATs; such applications are 1472 often downloaded by users with very little knowledge of 1473 computers and networking. 1475 * A process in user-space under many common operating systems is 1476 rather restricted in which fields in the IP header it can set 1477 and (even worse) read. 1479 * TURN is the relay solution of last resort. It is intended to 1480 be used only when a direct connection between the TURN client 1481 and the peer cannot be established. 1483 11.1. DiffServ Code Point (DSCP) 1485 If the client-server connection uses UDP, then the server SHOULD read 1486 the DSCP from the IP header of the received Data indication or 1487 ChannelData message and use that DSCP for the corresponding outgoing 1488 UDP datagram. In the reverse direction, the server SHOULD read the 1489 DSCP from the arriving UDP datagram and use that DSCP for the 1490 corresponding outgoing Data indication or ChannelData message. 1492 If the client-server connection uses TCP (or TLS over TCP), then to 1493 the extent possible, the server SHOULD read the DSCP from the TCP 1494 connection whenever it reads a Data indication or a ChannelData 1495 message from the TCP socket, and use that DSCP for the corresponding 1496 outgoing UDP datagram. In the reverse direction, the server SHOULD 1497 read the DSCP from the IP header of the received UDP datagram, and 1498 set the DSCP of the TCP connection to the same value. 1500 If, for efficiency or other reasons, the server is unable to read the 1501 DSCP for every message, then it SHOULD read these values at frequent 1502 intervals and use the DSCP learned for all outgoing packets (in the 1503 appropriate direction and on this allocation) until the next time it 1504 reads the DSCP. 1506 NOTE: By copying the DSCP, the server ensures that the application 1507 data gets consistent QoS treatment along the entire path from the 1508 client to the peer. 1510 11.2. Don't Fragment (DF) bit 1512 When the client sends a Data indication or ChannelData message to the 1513 server using UDP IPv4, it SHOULD NOT set the DF (Don't Fragment) bit 1514 unless the application explicitly requests the bit to be set. 1516 When the server sends a UDP datagram to a peer over IPv4, or when 1517 sends a Data indication or a ChannelData message to the client using 1518 UDP over IPv4, the server SHOULD NOT set the DF bit. 1520 When using TCP or TLS over TCP, the client and the server MAY let the 1521 setting of the DF bit be determined by the TCP/IP stack. 1523 NOTE: By not setting the DF bit over UDP, the server maximizes the 1524 chances that the UDP datagram, Data indication, or ChannelData 1525 message will be delivered. This is consistent with the view that 1526 TURN is a relay solution of last resort. 1528 11.3. Other IP Header Fields 1530 The server SHOULD NOT preserve the ECN (Explicit Congestion 1531 Notification) field, and MAY preserve thee TTL (Time-To-Live) fields 1532 when relaying application data. 1534 NOTE: The ECN field is not preserved because the view is that 1535 there are two connections here: one between the client and the 1536 server, and a second between the server and a peer. For example, 1537 if the client-server connection uses TCP, then the ECN field 1538 conveys useful information between the two TCP stacks, but is 1539 meaningless outside that TCP connection. 1541 The TTL field need not be preserved because there seems to be 1542 little chance of a forwarding loop, and because reading the TTL 1543 field is impossible without using RAW sockets in most situations. 1545 11.4. Path MTU 1547 Applications using TURN SHOULD follow the guidelines in 1548 [I-D.ietf-tsvwg-udp-guidelines], but use the algorithm of [RFC4821] 1549 rather than the algorithm of [RFC1191] to determine the Path MTU. 1550 This algorithm should be run at the application level (and not at the 1551 TURN layer or below) and used to discovery the maximum size of a 1552 application PDU that can be successfully delivered to the far end 1553 application. 1555 NOTE: According to [I-D.ietf-tsvwg-udp-guidelines], applications 1556 using UDP should do Path MTU Discovery. If they do not do Path 1557 MTU Discovery, then they must restrict their packet size to 576 1558 (over IPv4) or 1280 (over IPv6). 1560 The original Path MTU Discovery algorithm [RFC1191] will not work 1561 because a TURN server does not relay ICMP packets. 1563 The Path MTU Discover algorithm described in [RFC4821] will work. 1564 However, when run over a path that goes through a TURN server, it 1565 will not discover the Path MTU (because the DF bit is not set by 1566 the server), but intead will discover the maximum size of an 1567 application PDU that can be delivered between the client and the 1568 peer. Applications that limit themselves to this discovered size 1569 WILL be able to communicate effectively, though the application 1570 PDU may end up being fragmented on the section of the path after 1571 the server. 1573 Applications that instead restrict their packet size to 576 or 1574 1280 may suffer from the fact that TURN adds some overhead between 1575 the client and the server. Thus in some situations, these 1576 applications will see their maximum-sized packets dropped. 1577 However, this overhead is only 4 bytes when channels are used, so 1578 the chances of this happening are small. 1580 12. New STUN Methods 1582 This section lists the codepoints for the new STUN methods defined in 1583 this specification. See elsewhere in this document for the semantics 1584 of these new methods. 1586 Request/Response Transactions 1587 0x003 : Allocate 1588 0x004 : Refresh 1589 0x009 : ChannelBind 1591 Indications 1592 0x006 : Send 1593 0x007 : Data 1595 13. New STUN Attributes 1597 This STUN extension defines the following new attributes: 1599 0x000C: CHANNEL-NUMBER 1600 0x000D: LIFETIME 1601 0x0010: BANDWIDTH 1602 0x0012: PEER-ADDRESS 1603 0x0013: DATA 1604 0x0016: RELAY-ADDRESS 1605 0x0018: REQUESTED-PROPS 1606 0x0019: REQUESTED-TRANSPORT 1607 0x0022: RESERVATION-TOKEN 1609 13.1. CHANNEL-NUMBER 1611 The CHANNEL-NUMBER attribute contains the number of the channel. It 1612 is a 16-bit unsigned integer, followed by a two-octet RFFU (Reserved 1613 For Future Use) field which MUST be set to 0 on transmission and 1614 ignored on reception. 1616 0 1 2 3 1617 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 1618 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1619 | Channel Number | Reserved = 0 | 1620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1622 13.2. LIFETIME 1624 The lifetime attribute represents the duration for which the server 1625 will maintain an allocation in the absence of a refresh. It is a 32- 1626 bit unsigned integral value representing the number of seconds 1627 remaining until expiration. 1629 13.3. BANDWIDTH 1631 The bandwidth attribute represents the peak bandwidth that the client 1632 expects to use on the client to server connection. It is a 32-bit 1633 unsigned integral value and is measured in kilobits per second. 1635 13.4. PEER-ADDRESS 1637 The PEER-ADDRESS specifies the address and port of the peer as seen 1638 from the TURN server. It is encoded in the same way as XOR-MAPPED- 1639 ADDRESS. 1641 13.5. DATA 1643 The DATA attribute is present in all Data Indications and most Send 1644 Indications. It contains raw payload data that is to be sent (in the 1645 case of a Send Request) or was received (in the case of a Data 1646 Indication). 1648 13.6. RELAY-ADDRESS 1650 The RELAY-ADDRESS is present in Allocate responses. It specifies the 1651 address and port that the server allocated to the client. It is 1652 encoded in the same way as XOR-MAPPED-ADDRESS. 1654 13.7. REQUESTED-PROPS 1656 This attribute allows the client to request certain properties for 1657 the relayed transport address that is allocated by the server. The 1658 attribute is 32 bits long. Its format is: 1660 0 1 2 3 1661 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 1662 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1663 | Prop-type | Reserved = 0 | 1664 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1666 The field labeled "Prop-type" is an 8-bit field specifying the 1667 desired property. The rest of the attribute is RFFU (Reserved For 1668 Future Use) and MUST be set to 0 on transmission and ignored on 1669 reception. The values of the "Prop-type" field are: 1671 0x00 (Reserved) 1672 0x01 Even port number 1673 0x02 Pair of ports 1675 If the value of the "Prop-type" field is 0x01, then the client is 1676 requesting the server allocate an even-numbered port for the relayed 1677 transport address. 1679 If the value of the "Prop-type" field is 0x02, then client is 1680 requesting the server allocate an even-numbered port for the relayed 1681 transport address, and in addition reserve the next-highest port for 1682 a subsequent allocation. 1684 All other values of the "Prop-type" field are reserved. 1686 13.8. REQUESTED-TRANSPORT 1688 This attribute is used by the client to request a specific transport 1689 protocol for the allocated transport address. It has the following 1690 format: 1691 0 1 2 3 1692 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 1693 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1694 | Protocol | Reserved = 0 | 1695 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1697 The Protocol field specifies the desired protocol. The codepoints 1698 used in this field are taken from those allowed in the Protocol field 1699 in the IPv4 header and the NextHeader field in the IPv6 header 1700 [Protocol-Numbers]. This specification only allows the use of 1701 codepoint 17 (User Datagram Protocol). 1703 The RFFU field is set to zero on transmission and ignored on 1704 receiption. It is reserved for future uses. 1706 13.9. RESERVATION-TOKEN 1708 The RESERVATION-TOKEN attribute contains a token that uniquely 1709 identifies a relayed transport address being held in reserve by the 1710 server. The server includes this attribute in a success response to 1711 tell the client about the token, and the client includes this 1712 attribute in a subsequent Allocate request to request the server use 1713 that relayed transport address for the allocation. 1715 The attribute value is a 64-bit-long field containing the token 1716 value. 1718 14. New STUN Error Response Codes 1720 This document defines the following new error response codes: 1722 437 (Allocation Mismatch): A request was received by the server that 1723 requires an allocation to be in place, but there is none, or a 1724 request was received which requires no allocation, but there is 1725 one. 1727 438 (Wrong Credentials): The credentials in the (non-Allocate) 1728 request, though otherwise acceptable to the server, do not match 1729 those used to create the allocation. 1731 442 (Unsupported Transport Protocol): The Allocate request asked the 1732 server to use a transport protocol between the server and the peer 1733 that the server does not support. NOTE: This does NOT refer to 1734 the transport protocol used in the 5-tuple. 1736 486 (Allocation Quota Reached): No more allocations using this 1737 username can be created at the present time. 1739 507 (Insufficient Bandwidth Capacity): The server cannot create an 1740 allocation with the requested bandwidth right now as it has 1741 exhausted its capacity. 1743 508 (Insufficient Port Capacity): The server has no more relayed 1744 transport addresses available right now, or has none with the 1745 requested properties, or the one that corresponds to the specified 1746 token is not available. 1748 15. Security Considerations 1750 TURN servers allocate bandwidth and port resources to clients, in 1751 contrast to the Binding method defined in 1752 [I-D.ietf-behave-rfc3489bis]. Therefore, a TURN server may require 1753 the authentication and authorization of STUN requests. This 1754 authentication is provided by mechanisms defined in the STUN 1755 specification itself, in particular digest authentication. 1757 Because TURN servers allocate resources, they can be susceptible to 1758 denial-of-service attacks. All Allocate transactions are 1759 authenticated, so that an unknown attacker cannot launch an attack. 1760 An authenticated attacker can generate multiple Allocate Requests, 1761 however. To prevent a single malicious user from allocating all of 1762 the resources on the server, it is RECOMMENDED that a server 1763 implement a modest per user limit on the amount of bandwidth that can 1764 be allocated. Such a mechanism does not prevent a large number of 1765 malicious users from each requesting a small number of allocations. 1766 Attacks such as these are possible using botnets, and are difficult 1767 to detect and prevent. Implementors of TURN should keep up with best 1768 practices around detection of anomalous botnet attacks. 1770 A client will use the transport address learned from the RELAY- 1771 ADDRESS attribute of the Allocate Response to tell other users how to 1772 reach them. Therefore, a client needs to be certain that this 1773 address is valid, and will actually route to them. Such validation 1774 occurs through the message integrity checks provided in the Allocate 1775 response. They can guarantee the authenticity and integrity of the 1776 allocated addresses. Note that TURN is not susceptible to the 1777 attacks described in Section 12.2.3, 12.2.4, 12.2.5 or 12.2.6 of 1779 [I-D.ietf-behave-rfc3489bis] [[TODO: Update section number references 1780 to 3489bis]]. These attacks are based on the fact that a STUN server 1781 mirrors the source IP address, which cannot be authenticated. STUN 1782 does not use the source address of the Allocate Request in providing 1783 the RELAY-ADDRESS, and therefore, those attacks do not apply. 1785 TURN attempts to adhere as closely as possible to common firewall 1786 policies, consistent with allowing data to flow. TURN has fairly 1787 limited applicability, requiring a user to explicitly authorize 1788 permission to receive data from a peer, one IP address at a time. 1789 Thus, it does not provide a general technique for externalizing 1790 sockets. Rather, it has similar security properties to the placement 1791 of an address-restricted NAT in the network, allowing messaging in 1792 from a peer only if the internal client has sent a packet out towards 1793 the IP address of that peer. This limitation means that TURN cannot 1794 be used to run, for example, SIP servers, NTP servers, FTP servers or 1795 other network servers that service a large number of clients. 1796 Rather, it facilitates rendezvous of NATted clients that use some 1797 other protocol, such as SIP, to communicate IP addresses and ports 1798 for communications. 1800 Confidentiality of the transport addresses learned through Allocate 1801 transactions does not appear to be that important. If required, it 1802 can be provided by running TURN over TLS. 1804 TURN does not and cannot guarantee that UDP data is delivered in 1805 sequence or to the correct address. As most TURN clients will only 1806 communicate with a single peer, the use of a single channel number 1807 will be very common. Consider an enterprise where Alice and Bob are 1808 involved in separate calls through the enterprise NAT to their 1809 corporate TURN server. If the corporate NAT reboots, it is possible 1810 that Bob will obtain the exact NAT binding originally used by Alice. 1811 If Alice and Bob were using identical channel numbers, Bob will 1812 receive unencapsulated data intended for Alice and will send data 1813 accidentally to Alice's peer. This is not a problem with TURN. This 1814 is precisely what would happen if there was no TURN server and Bob 1815 and Alice instead provided a (STUN) reflexive transport address to 1816 their peers. If detecting this misdelivery is a problem, the client 1817 and its peer need to use message integrity on their data. 1819 Relay servers are useful even for users not behind a NAT. They can 1820 provide a way for truly anonymous communications. A user can cause a 1821 call to have its media routed through a TURN server, so that the 1822 user's IP addresses are never revealed. 1824 Any relay addresses learned through an Allocate request will not 1825 operate properly with IPSec Authentication Header (AH) [RFC4302] in 1826 transport or tunnel mode. However, tunnel-mode IPSec ESP [RFC4303] 1827 should still operate. 1829 16. IANA Considerations 1831 Since TURN is an extension to STUN [I-D.ietf-behave-rfc3489bis], the 1832 methods, attributes and error codes defined in this specification are 1833 new method, attributes, and error codes for STUN. This section 1834 directs IANA to add these new protocol elements to the IANA registry 1835 of STUN protocol elements. 1837 The codepoints for the new STUN methods defined in this specification 1838 are listed in Section 12. 1840 The codepoints for the new STUN attributes defined in this 1841 specification are listed in Section 13. 1843 The codepoints for the new STUN error codes defined in this 1844 specification are listed in Section 14. 1846 Extensions to TURN can be made through IETF consensus. 1848 17. IAB Considerations 1850 The IAB has studied the problem of "Unilateral Self Address Fixing", 1851 which is the general process by which a client attempts to determine 1852 its address in another realm on the other side of a NAT through a 1853 collaborative protocol reflection mechanism [RFC3424]. The TURN 1854 extension is an example of a protocol that performs this type of 1855 function. The IAB has mandated that any protocols developed for this 1856 purpose document a specific set of considerations. 1858 TURN is an extension of the STUN protocol. As such, the specific 1859 usages of STUN that use the TURN extensions need to specifically 1860 address these considerations. Currently the only STUN usage that 1861 uses TURN is ICE [I-D.ietf-mmusic-ice]. 1863 18. Example 1865 TBD 1867 19. Changes from Previous Versions 1869 Note to RFC Editor: Please remove this section prior to publication 1870 of this document as an RFC. 1872 This section lists the changes between the various versions of this 1873 specification. 1875 19.1. Changes from -06 to -07 1877 o Rewrote the General Behavior section, making various changes in 1878 the process. 1880 o Changed the usage of authentication from MUST to SHOULD. 1882 o Changed the requirement that subsequent requests use the same 1883 username and password from MUST to SHOULD to allow for the 1884 possibility of changing the credentials using some unspecified 1885 mechanism. 1887 o Introduced a 438 (Wrong Credentials) error which is used when a 1888 non-Allocate request authenticates but does not use the same 1889 username and password as the Allocate request. Having a separate 1890 error code for this case avoids the client being confused over 1891 what the error actually is. 1893 o The server must now prevent the relayed transport address and the 1894 5-tuple from being reused in different allocations for 2 minutes 1895 after the allocation expires. 1897 o Changed the usage of FINGERPRINT from MUST NOT to MAY, to allow 1898 for the possible multiplexing of TURN with some other protocol. 1900 o Rewrote much of the section on Allocations, splitting it into 1901 three new sections (one on allocations in general, one on creating 1902 an allocation, and one on refreshing an allocation). 1904 o Replaced the mechanism for requesting relayed transport addresses 1905 with specific properties. The new mechanism is less powerful: a 1906 client can request an even port, or a pair of ports, but cannot 1907 request a single odd port or a specific port as was possible under 1908 the old mechanism. Nor can the client request a specific IP 1909 address. 1911 o Changed the rules for handling ALTERNATE-SERVER, removing the 1912 requirement that the referring server have "positive knowledge" 1913 about the state of the alternate server. The new rules instead 1914 rely on text in STUN to prevent referral loops. 1916 o Changed the rules for allocation lifetimes. Allocations lifetimes 1917 are now a minimum of 10 minutes; the client can ask for longer 1918 values, but requests for shorter values are ignored. The text now 1919 recommends that the client refresh an allocation one minute before 1920 it expires. 1922 o Put in temporary procedures for handling the BANDWIDTH attribute, 1923 modelled on the LIFETIME attribute. These procedures are mostly 1924 placeholders and likely to change in the next revision. 1926 o Added a detailed description of how a client reacts to the various 1927 errors it can receive in reply to an Allocate request. This 1928 replaces the various descriptions that were previously scattered 1929 throughout the document, which were inconsistent and sometimes 1930 contradictory. 1932 o Added a new section that gives the normative rules for 1933 permissions. 1935 o Changed the rules around permission lifetimes. The text used to 1936 recommend a value of one minute; it MUST now be 5 minutes. 1938 o Removed the errors "Channel Missing or Invalid", "Peer Address 1939 Missing or Invalid" and "Lifetime Malformed or Invalid" and used 1940 400 "Bad Request" instead. 1942 o Rewrote portions of the section on Send and Data indications and 1943 the section on Channels to try to make the client vs. server 1944 behavior clearer. 1946 o Channel bindings now expire after 10 minutes, and must be 1947 refreshed to keep them alive. 1949 o Binding a channel now installs or refreshes a permission for the 1950 IP address of corresponding peer. 1952 o Changed the wording describing the situation when the client sends 1953 a ChannelData message before receiving the ChannelBind success 1954 response. -06 said that client SHOULD NOT do this; -07 now says 1955 that a client MAY, but describes the consequences of doing it. 1957 o Added a section discussing the setting of fields in the IP header. 1959 o Replaced the REQUESTED-PORT-PROPS attribute with the REQUESTED- 1960 PROPS attribute that has a different format and semantics, but 1961 reuses the same code point. 1963 o Replaced the REQUESTED-IP attribute with the RESERVATION-TOKEN 1964 attribute, which has a different format and semantics, but reuses 1965 the same code point. 1967 o Removed error codes 443 and 444, and replaced them with 508 1968 (Insufficient Port Capacity). Also changed the error text for 1969 code 507 from "Insufficient Capacity" to "Insufficient Bandwidth 1970 Capacity". 1972 19.2. Changes from -05 to -06 1974 o Changed the mechanism for allocating channels to the one proposed 1975 by Eric Rescorla at the Dec 2007 IETF meeting. 1977 o Removed the framing mechanism (which was used to frame all 1978 messages) and replaced it with the ChannelData message. As part 1979 of this change, noted that the demux of ChannelData messages from 1980 TURN messages can be done using the first two bits of the message. 1982 o Rewrote the sections on transmitted and receiving data as a result 1983 of the above to changes, splitting it into a section on Send and 1984 Data Indications and a separate section on channels. 1986 o Clarified the handling of Allocate Request messages. In 1987 particular, subsequent Allocate Request messages over UDP with the 1988 same transaction id are not an error but a retransmission. 1990 o Restricted the range of ports available for allocation to the 1991 Dynamic and/or Private Port range, and noted when ports outside 1992 this range can be used. 1994 o Changed the format of the REQUESTED-TRANSPORT attribute. The 1995 previous version used 00 for UDP and 01 for TCP; the new version 1996 uses protocol numbers from the IANA protocol number registry. The 1997 format of the attribute also changed. 1999 o Made a large number of changes to the non-normative portion of the 2000 document to reflect technical changes and improve the 2001 presentation. 2003 o Added the Issues section. 2005 19.3. Changes from -04 to -05 2007 o Removed the ability to allocate addresses for TCP relaying. This 2008 is now covered in a separate document. However, communication 2009 between the client and the server can still run over TCP or TLS/ 2010 TCP. This resulted in the removal of the Connect method and the 2011 TIMER-VAL and CONNECT-STAT attributes. 2013 o Added the concept of channels. All communication between the 2014 client and the server flows on a channel. Channels are numbered 2015 0..65535. Channel 0 is used for TURN messages, while the 2016 remaining channels are used for sending unencapsulated data to/ 2017 from a remote peer. This concept adds a new Channel Confirmation 2018 method and a new CHANNEL-NUMBER attribute. The new attribute is 2019 also used in the Send and Data methods. 2021 o The framing mechanism formally used just for stream-oriented 2022 transports is now also used for UDP, and the former Type and 2023 Reserved fields in the header have been replaced by a Channel 2024 Number field. The length field is zero when running over UDP. 2026 o TURN now runs on its own port, rather than using the STUN port. 2027 The use of channels requires this. 2029 o Removed the SetActiveDestination concept. This has been replaced 2030 by the concept of channels. 2032 o Changed the allocation refresh mechanism. The new mechanism uses 2033 a new Refresh method, rather than repeating the Allocation 2034 transaction. 2036 o Changed the syntax of SRV requests for secure transport. The new 2037 syntax is "_turns._tcp" rather than the old "_turn._tls". This 2038 change mirrors the corresponding change in STUN SRV syntax. 2040 o Renamed the old REMOTE-ADDRESS attribute to PEER-ADDRESS, and 2041 changed it to use the XOR-MAPPED-ADDRESS format. 2043 o Changed the RELAY-ADDRESS attribute to use the XOR-MAPPED-ADDRESS 2044 format (instead of the MAPPED-ADDRESS format)). 2046 o Renamed the 437 error code from "No Binding" to "Allocation 2047 Mismatch". 2049 o Added a discussion of what happens if a client's public binding on 2050 its outermost NAT changes. 2052 o The document now consistently uses the term "peer" as the name of 2053 a remote endpoint with which the client wishes to communicate. 2055 o Rewrote much of the document to describe the new concepts. At the 2056 same time, tried to make the presentation clearer and less 2057 repetitive. 2059 20. Open Issues 2061 NOTE to RFC Editor: Please remove this section prior to publication 2062 of this document as an RFC. 2064 Bandwidth: How should bandwidth be specified? What are the right 2065 rules around bandwidth? 2067 Alternate Server: Do we still want this mechanism? Is the current 2068 proposal acceptable? Note that the usage of the ALTERNATE-SERVER 2069 attribute in this document is inconsistent with its usage in STUN. 2070 In STUN, if the ALTERNATE-SERVER attribute is used, then the error 2071 that the server would otherwise generate is replaced by a 300 (Try 2072 Alternate) code. In this document, the 300 error code is not used, 2073 and the server returns an appropriate error code and then includes 2074 the ALTERNATE-SERVER attribute in the response. In this way, the 2075 client can see the actual error code, rather than always seeing error 2076 code 300, and can thus make a more intelligent decision on whether it 2077 wishes to try the alternate server. 2079 Public TURN servers: The text currently says that a server "SHOULD" 2080 use the Long-Term Credential mechanism, with the unstated idea that a 2081 public TURN server would not use it. But this really weakens the 2082 security of TURN. Is there a better way to allow public servers? Or 2083 should we just drop the notion of a public server entirely? 2085 21. Acknowledgements 2087 The authors would like to thank the various participants in the 2088 BEHAVE working group for their many comments on this draft. Marc 2089 Petit-Huguenin, Remi Denis-Courmont, Derek MacDonald, Cullen 2090 Jennings, Lars Eggert, Magnus Westerlund, and Eric Rescorla have been 2091 particularly helpful, with Eric also suggesting the channel 2092 allocation mechanism, and Cullen suggesting the REQUESTED-PROPS 2093 mechanism. Christian Huitema was an early contributor to this 2094 document and was a co-author on the first few drafts. Finally, the 2095 authors would like to thank Dan Wing for both his contributions to 2096 the text and his huge help in restarting progress on this draft after 2097 work had stalled. 2099 22. References 2101 22.1. Normative References 2103 [I-D.ietf-behave-rfc3489bis] 2104 Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2105 "Session Traversal Utilities for (NAT) (STUN)", 2106 draft-ietf-behave-rfc3489bis-15 (work in progress), 2107 February 2008. 2109 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2110 Requirement Levels", BCP 14, RFC 2119, March 1997. 2112 22.2. Informative References 2114 [RFC1918] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and 2115 E. Lear, "Address Allocation for Private Internets", 2116 BCP 5, RFC 1918, February 1996. 2118 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 2119 with Session Description Protocol (SDP)", RFC 3264, 2120 June 2002. 2122 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 2123 December 2005. 2125 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 2126 RFC 4303, December 2005. 2128 [RFC3424] Daigle, L. and IAB, "IAB Considerations for UNilateral 2129 Self-Address Fixing (UNSAF) Across Network Address 2130 Translation", RFC 3424, November 2002. 2132 [I-D.ietf-mmusic-ice] 2133 Rosenberg, J., "Interactive Connectivity Establishment 2134 (ICE): A Protocol for Network Address Translator (NAT) 2135 Traversal for Offer/Answer Protocols", 2136 draft-ietf-mmusic-ice-19 (work in progress), October 2007. 2138 [RFC4787] Audet, F. and C. Jennings, "Network Address Translation 2139 (NAT) Behavioral Requirements for Unicast UDP", BCP 127, 2140 RFC 4787, January 2007. 2142 [I-D.ietf-behave-turn-tcp] 2143 Rosenberg, J. and R. Mahy, "Traversal Using Relays around 2144 NAT (TURN) Extensions for TCP Allocations", 2145 draft-ietf-behave-turn-tcp-00 (work in progress), 2146 November 2007. 2148 [I-D.ietf-behave-turn-ipv6] 2149 Camarillo, G. and O. Novo, "Traversal Using Relays around 2150 NAT (TURN) Extension for IPv4/IPv6 Transition", 2151 draft-ietf-behave-turn-ipv6-04 (work in progress), 2152 January 2008. 2154 [I-D.ietf-tsvwg-udp-guidelines] 2155 Eggert, L. and G. Fairhurst, "UDP Usage Guidelines for 2156 Application Designers", draft-ietf-tsvwg-udp-guidelines-05 2157 (work in progress), February 2008. 2159 [RFC1191] Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, 2160 November 1990. 2162 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 2163 Discovery", RFC 4821, March 2007. 2165 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 2166 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 2167 March 1996. 2169 [Port-Numbers] 2170 "IANA Port Numbers Registry", 2171 . 2173 [Protocol-Numbers] 2174 "IANA Protocol Numbers Registry", 2005, 2175 . 2177 Authors' Addresses 2179 Jonathan Rosenberg 2180 Cisco Systems, Inc. 2181 Edison, NJ 2182 USA 2184 Email: jdrosen@cisco.com 2185 URI: http://www.jdrosen.net 2187 Rohan Mahy 2188 Plantronics, Inc. 2190 Email: rohan@ekabal.com 2191 Philip Matthews 2192 Avaya, Inc. 2193 1135 Innovation Drive 2194 Ottawa, Ontario K2K 3G7 2195 Canada 2197 Phone: +1 613-592-4343 x224 2198 Fax: 2199 Email: philip_matthews@magma.ca 2200 URI: 2202 Full Copyright Statement 2204 Copyright (C) The IETF Trust (2008). 2206 This document is subject to the rights, licenses and restrictions 2207 contained in BCP 78, and except as set forth therein, the authors 2208 retain all their rights. 2210 This document and the information contained herein are provided on an 2211 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2212 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2213 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2214 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2215 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2216 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2218 Intellectual Property 2220 The IETF takes no position regarding the validity or scope of any 2221 Intellectual Property Rights or other rights that might be claimed to 2222 pertain to the implementation or use of the technology described in 2223 this document or the extent to which any license under such rights 2224 might or might not be available; nor does it represent that it has 2225 made any independent effort to identify any such rights. Information 2226 on the procedures with respect to rights in RFC documents can be 2227 found in BCP 78 and BCP 79. 2229 Copies of IPR disclosures made to the IETF Secretariat and any 2230 assurances of licenses to be made available, or the result of an 2231 attempt made to obtain a general license or permission for the use of 2232 such proprietary rights by implementers or users of this 2233 specification can be obtained from the IETF on-line IPR repository at 2234 http://www.ietf.org/ipr. 2236 The IETF invites any interested party to bring to its attention any 2237 copyrights, patents or patent applications, or other proprietary 2238 rights that may cover technology that may be required to implement 2239 this standard. Please address the information to the IETF at 2240 ietf-ipr@ietf.org. 2242 Acknowledgment 2244 Funding for the RFC Editor function is provided by the IETF 2245 Administrative Support Activity (IASA).