RFC 5766
Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)
10. Send and Data Methods
TURN supports two mechanisms for sending and receiving data from peers. This section describes the use of the Send and Data mechanisms, while Section 11 describes the use of the Channel mechanism.10.1. Forming a Send Indication
The client can use a Send indication to pass data to the server for relaying to a peer. A client may use a Send indication even if a channel is bound to that peer. However, the client MUST ensure that there is a permission installed for the IP address of the peer to which the Send indication is being sent; this prevents a third party from using a TURN server to send data to arbitrary destinations. When forming a Send indication, the client MUST include an XOR-PEER- ADDRESS attribute and a DATA attribute. The XOR-PEER-ADDRESS attribute contains the transport address of the peer to which the data is to be sent, and the DATA attribute contains the actual application data to be sent to the peer. The client MAY include a DONT-FRAGMENT attribute in the Send indication if it wishes the server to set the DF bit on the UDP datagram sent to the peer.10.2. Receiving a Send Indication
When the server receives a Send indication, it processes as per Section 4 plus the specific rules mentioned here. The message is first checked for validity. The Send indication MUST contain both an XOR-PEER-ADDRESS attribute and a DATA attribute. If one of these attributes is missing or invalid, then the message is discarded. Note that the DATA attribute is allowed to contain zero bytes of data.
The Send indication may also contain the DONT-FRAGMENT attribute. If
the server is unable to set the DF bit on outgoing UDP datagrams when
this attribute is present, then the server acts as if the DONT-
FRAGMENT attribute is an unknown comprehension-required attribute
(and thus the Send indication is discarded).
The server also checks that there is a permission installed for the
IP address contained in the XOR-PEER-ADDRESS attribute. If no such
permission exists, the message is discarded. Note that a Send
indication never causes the server to refresh the permission.
The server MAY impose restrictions on the IP address and port values
allowed in the XOR-PEER-ADDRESS attribute -- if a value is not
allowed, the server silently discards the Send indication.
If everything is OK, then the server forms a UDP datagram as follows:
o the source transport address is the relayed transport address of
the allocation, where the allocation is determined by the 5-tuple
on which the Send indication arrived;
o the destination transport address is taken from the XOR-PEER-
ADDRESS attribute;
o the data following the UDP header is the contents of the value
field of the DATA attribute.
The handling of the DONT-FRAGMENT attribute (if present), is
described in Section 12.
The resulting UDP datagram is then sent to the peer.
10.3. Receiving a UDP Datagram
When the server receives a UDP datagram at a currently allocated
relayed transport address, the server looks up the allocation
associated with the relayed transport address. The server then
checks to see whether the set of permissions for the allocation allow
the relaying of the UDP datagram as described in Section 8.
If relaying is permitted, then the server checks if there is a
channel bound to the peer that sent the UDP datagram (see
Section 11). If a channel is bound, then processing proceeds as
described in Section 11.7.
If relaying is permitted but no channel is bound to the peer, then
the server forms and sends a Data indication. The Data indication
MUST contain both an XOR-PEER-ADDRESS and a DATA attribute. The DATA
attribute is set to the value of the 'data octets' field from the datagram, and the XOR-PEER-ADDRESS attribute is set to the source transport address of the received UDP datagram. The Data indication is then sent on the 5-tuple associated with the allocation.10.4. Receiving a Data Indication
When the client receives a Data indication, it checks that the Data indication contains both an XOR-PEER-ADDRESS and a DATA attribute, and discards the indication if it does not. The client SHOULD also check that the XOR-PEER-ADDRESS attribute value contains an IP address with which the client believes there is an active permission, and discard the Data indication otherwise. Note that the DATA attribute is allowed to contain zero bytes of data. NOTE: The latter check protects the client against an attacker who somehow manages to trick the server into installing permissions not desired by the client. If the Data indication passes the above checks, the client delivers the data octets inside the DATA attribute to the application, along with an indication that they were received from the peer whose transport address is given by the XOR-PEER-ADDRESS attribute.11. Channels
Channels provide a way for the client and server to send application data using ChannelData messages, which have less overhead than Send and Data indications. The ChannelData message (see Section 11.4) starts with a two-byte field that carries the channel number. The values of this field are allocated as follows: 0x0000 through 0x3FFF: These values can never be used for channel numbers. 0x4000 through 0x7FFF: These values are the allowed channel numbers (16,383 possible values). 0x8000 through 0xFFFF: These values are reserved for future use. Because of this division, ChannelData messages can be distinguished from STUN-formatted messages (e.g., Allocate request, Send indication, etc.) by examining the first two bits of the message: 0b00: STUN-formatted message (since the first two bits of a STUN- formatted message are always zero).
0b01: ChannelData message (since the channel number is the first
field in the ChannelData message and channel numbers fall in the
range 0x4000 - 0x7FFF).
0b10: Reserved
0b11: Reserved
The reserved values may be used in the future to extend the range of
channel numbers. Thus, an implementation MUST NOT assume that a TURN
message always starts with a 0 bit.
Channel bindings are always initiated by the client. The client can
bind a channel to a peer at any time during the lifetime of the
allocation. The client may bind a channel to a peer before
exchanging data with it, or after exchanging data with it (using Send
and Data indications) for some time, or may choose never to bind a
channel to it. The client can also bind channels to some peers while
not binding channels to other peers.
Channel bindings are specific to an allocation, so that the use of a
channel number or peer transport address in a channel binding in one
allocation has no impact on their use in a different allocation. If
an allocation expires, all its channel bindings expire with it.
A channel binding consists of:
o a channel number;
o a transport address (of the peer); and
o A time-to-expiry timer.
Within the context of an allocation, a channel binding is uniquely
identified either by the channel number or by the peer's transport
address. Thus, the same channel cannot be bound to two different
transport addresses, nor can the same transport address be bound to
two different channels.
A channel binding lasts for 10 minutes unless refreshed. Refreshing
the binding (by the server receiving a ChannelBind request rebinding
the channel to the same peer) resets the time-to-expiry timer back to
10 minutes.
When the channel binding expires, the channel becomes unbound. Once
unbound, the channel number can be bound to a different transport
address, and the transport address can be bound to a different
channel number. To prevent race conditions, the client MUST wait 5
minutes after the channel binding expires before attempting to bind the channel number to a different transport address or the transport address to a different channel number. When binding a channel to a peer, the client SHOULD be prepared to receive ChannelData messages on the channel from the server as soon as it has sent the ChannelBind request. Over UDP, it is possible for the client to receive ChannelData messages from the server before it receives a ChannelBind success response. In the other direction, the client MAY elect to send ChannelData messages before receiving the ChannelBind success response. Doing so, however, runs the risk of having the ChannelData messages dropped by the server if the ChannelBind request does not succeed for some reason (e.g., packet lost if the request is sent over UDP, or the server being unable to fulfill the request). A client that wishes to be safe should either queue the data or use Send indications until the channel binding is confirmed.11.1. Sending a ChannelBind Request
A channel binding is created or refreshed using a ChannelBind transaction. A ChannelBind transaction also creates or refreshes a permission towards the peer (see Section 8). To initiate the ChannelBind transaction, the client forms a ChannelBind request. The channel to be bound is specified in a CHANNEL-NUMBER attribute, and the peer's transport address is specified in an XOR-PEER-ADDRESS attribute. Section 11.2 describes the restrictions on these attributes. Rebinding a channel to the same transport address that it is already bound to provides a way to refresh a channel binding and the corresponding permission without sending data to the peer. Note however, that permissions need to be refreshed more frequently than channels.11.2. Receiving a ChannelBind Request
When the server receives a ChannelBind request, it processes as per Section 4 plus the specific rules mentioned here. The server checks the following: o The request contains both a CHANNEL-NUMBER and an XOR-PEER-ADDRESS attribute;
o The channel number is in the range 0x4000 through 0x7FFE
(inclusive);
o The channel number is not currently bound to a different transport
address (same transport address is OK);
o The transport address is not currently bound to a different
channel number.
If any of these tests fail, the server replies with a 400 (Bad
Request) error.
The server MAY impose restrictions on the IP address and port values
allowed in the XOR-PEER-ADDRESS attribute -- if a value is not
allowed, the server rejects the request with a 403 (Forbidden) error.
If the request is valid, but the server is unable to fulfill the
request due to some capacity limit or similar, the server replies
with a 508 (Insufficient Capacity) error.
Otherwise, the server replies with a ChannelBind success response.
There are no required attributes in a successful ChannelBind
response.
If the server can satisfy the request, then the server creates or
refreshes the channel binding using the channel number in the
CHANNEL-NUMBER attribute and the transport address in the XOR-PEER-
ADDRESS attribute. The server also installs or refreshes a
permission for the IP address in the XOR-PEER-ADDRESS attribute as
described in Section 8.
NOTE: A server need not do anything special to implement
idempotency of ChannelBind requests over UDP using the "stateless
stack approach". Retransmitted ChannelBind requests will simply
refresh the channel binding and the corresponding permission.
Furthermore, the client must wait 5 minutes before binding a
previously bound channel number or peer address to a different
channel, eliminating the possibility that the transaction would
initially fail but succeed on a retransmission.
11.3. Receiving a ChannelBind Response
When the client receives a ChannelBind success response, it updates
its data structures to record that the channel binding is now active.
It also updates its data structures to record that the corresponding
permission has been installed or refreshed.
If the client receives a ChannelBind failure response that indicates that the channel information is out-of-sync between the client and the server (e.g., an unexpected 400 "Bad Request" response), then it is RECOMMENDED that the client immediately delete the allocation and start afresh with a new allocation.11.4. The ChannelData Message
The ChannelData message is used to carry application data between the client and the server. It has the following format: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Channel Number | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | / Application Data / / / | | | +-------------------------------+ | | +-------------------------------+ The Channel Number field specifies the number of the channel on which the data is traveling, and thus the address of the peer that is sending or is to receive the data. The Length field specifies the length in bytes of the application data field (i.e., it does not include the size of the ChannelData header). Note that 0 is a valid length. The Application Data field carries the data the client is trying to send to the peer, or that the peer is sending to the client.11.5. Sending a ChannelData Message
Once a client has bound a channel to a peer, then when the client has data to send to that peer it may use either a ChannelData message or a Send indication; that is, the client is not obligated to use the channel when it exists and may freely intermix the two message types when sending data to the peer. The server, on the other hand, MUST use the ChannelData message if a channel has been bound to the peer. The fields of the ChannelData message are filled in as described in Section 11.4.
Over TCP and TLS-over-TCP, the ChannelData message MUST be padded to a multiple of four bytes in order to ensure the alignment of subsequent messages. The padding is not reflected in the length field of the ChannelData message, so the actual size of a ChannelData message (including padding) is (4 + Length) rounded up to the nearest multiple of 4. Over UDP, the padding is not required but MAY be included. The ChannelData message is then sent on the 5-tuple associated with the allocation.11.6. Receiving a ChannelData Message
The receiver of the ChannelData message uses the first two bits to distinguish it from STUN-formatted messages, as described above. If the message uses a value in the reserved range (0x8000 through 0xFFFF), then the message is silently discarded. If the ChannelData message is received in a UDP datagram, and if the UDP datagram is too short to contain the claimed length of the ChannelData message (i.e., the UDP header length field value is less than the ChannelData header length field value + 4 + 8), then the message is silently discarded. If the ChannelData message is received over TCP or over TLS-over-TCP, then the actual length of the ChannelData message is as described in Section 11.5. If the ChannelData message is received on a channel that is not bound to any peer, then the message is silently discarded. On the client, it is RECOMMENDED that the client discard the ChannelData message if the client believes there is no active permission towards the peer. On the server, the receipt of a ChannelData message MUST NOT refresh either the channel binding or the permission towards the peer. On the server, if no errors are detected, the server relays the application data to the peer by forming a UDP datagram as follows: o the source transport address is the relayed transport address of the allocation, where the allocation is determined by the 5-tuple on which the ChannelData message arrived; o the destination transport address is the transport address to which the channel is bound;
o the data following the UDP header is the contents of the data
field of the ChannelData message.
The resulting UDP datagram is then sent to the peer. Note that if
the Length field in the ChannelData message is 0, then there will be
no data in the UDP datagram, but the UDP datagram is still formed and
sent.
11.7. Relaying Data from the Peer
When the server receives a UDP datagram on the relayed transport
address associated with an allocation, the server processes it as
described in Section 10.3. If that section indicates that a
ChannelData message should be sent (because there is a channel bound
to the peer that sent to the UDP datagram), then the server forms and
sends a ChannelData message as described in Section 11.5.
12. IP Header Fields
This section describes how the server sets various fields in the IP
header when relaying between the client and the peer or vice versa.
The descriptions in this section apply: (a) when the server sends a
UDP datagram to the peer, or (b) when the server sends a Data
indication or ChannelData message to the client over UDP transport.
The descriptions in this section do not apply to TURN messages sent
over TCP or TLS transport from the server to the client.
The descriptions below have two parts: a preferred behavior and an
alternate behavior. The server SHOULD implement the preferred
behavior, but if that is not possible for a particular field, then it
SHOULD implement the alternative behavior.
Time to Live (TTL) field
Preferred Behavior: If the incoming value is 0, then the drop the
incoming packet. Otherwise, set the outgoing Time to Live/Hop
Count to one less than the incoming value.
Alternate Behavior: Set the outgoing value to the default for
outgoing packets.
Differentiated Services Code Point (DSCP) field [RFC2474]
Preferred Behavior: Set the outgoing value to the incoming value,
unless the server includes a differentiated services classifier
and marker [RFC2474].
Alternate Behavior: Set the outgoing value to a fixed value, which
by default is Best Effort unless configured otherwise.
In both cases, if the server is immediately adjacent to a
differentiated services classifier and marker, then DSCP MAY be
set to any arbitrary value in the direction towards the
classifier.
Explicit Congestion Notification (ECN) field [RFC3168]
Preferred Behavior: Set the outgoing value to the incoming value,
UNLESS the server is doing Active Queue Management, the incoming
ECN field is ECT(1) (=0b01) or ECT(0) (=0b10), and the server
wishes to indicate that congestion has been experienced, in which
case set the outgoing value to CE (=0b11).
Alternate Behavior: Set the outgoing value to Not-ECT (=0b00).
IPv4 Fragmentation fields
Preferred Behavior: When the server sends a packet to a peer in
response to a Send indication containing the DONT-FRAGMENT
attribute, then set the DF bit in the outgoing IP header to 1. In
all other cases when sending an outgoing packet containing
application data (e.g., Data indication, ChannelData message, or
DONT-FRAGMENT attribute not included in the Send indication), copy
the DF bit from the DF bit of the incoming packet that contained
the application data.
Set the other fragmentation fields (Identification, More
Fragments, Fragment Offset) as appropriate for a packet
originating from the server.
Alternate Behavior: As described in the Preferred Behavior, except
always assume the incoming DF bit is 0.
In both the Preferred and Alternate Behaviors, the resulting
packet may be too large for the outgoing link. If this is the
case, then the normal fragmentation rules apply [RFC1122].
IPv4 Options
Preferred Behavior: The outgoing packet is sent without any IPv4
options.
Alternate Behavior: Same as preferred.
13. New STUN Methods
This section lists the codepoints for the new STUN methods defined in this specification. See elsewhere in this document for the semantics of these new methods. 0x003 : Allocate (only request/response semantics defined) 0x004 : Refresh (only request/response semantics defined) 0x006 : Send (only indication semantics defined) 0x007 : Data (only indication semantics defined) 0x008 : CreatePermission (only request/response semantics defined 0x009 : ChannelBind (only request/response semantics defined)14. New STUN Attributes
This STUN extension defines the following new attributes: 0x000C: CHANNEL-NUMBER 0x000D: LIFETIME 0x0010: Reserved (was BANDWIDTH) 0x0012: XOR-PEER-ADDRESS 0x0013: DATA 0x0016: XOR-RELAYED-ADDRESS 0x0018: EVEN-PORT 0x0019: REQUESTED-TRANSPORT 0x001A: DONT-FRAGMENT 0x0021: Reserved (was TIMER-VAL) 0x0022: RESERVATION-TOKEN Some of these attributes have lengths that are not multiples of 4. By the rules of STUN, any attribute whose length is not a multiple of 4 bytes MUST be immediately followed by 1 to 3 padding bytes to ensure the next attribute (if any) would start on a 4-byte boundary (see [RFC5389]).14.1. CHANNEL-NUMBER
The CHANNEL-NUMBER attribute contains the number of the channel. The value portion of this attribute is 4 bytes long and consists of a 16- bit unsigned integer, followed by a two-octet RFFU (Reserved For Future Use) field, which MUST be set to 0 on transmission and MUST be ignored on reception. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Channel Number | RFFU = 0 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
14.2. LIFETIME
The LIFETIME attribute represents the duration for which the server will maintain an allocation in the absence of a refresh. The value portion of this attribute is 4-bytes long and consists of a 32-bit unsigned integral value representing the number of seconds remaining until expiration.14.3. XOR-PEER-ADDRESS
The XOR-PEER-ADDRESS specifies the address and port of the peer as seen from the TURN server. (For example, the peer's server-reflexive transport address if the peer is behind a NAT.) It is encoded in the same way as XOR-MAPPED-ADDRESS [RFC5389].14.4. DATA
The DATA attribute is present in all Send and Data indications. The value portion of this attribute is variable length and consists of the application data (that is, the data that would immediately follow the UDP header if the data was been sent directly between the client and the peer). If the length of this attribute is not a multiple of 4, then padding must be added after this attribute.14.5. XOR-RELAYED-ADDRESS
The XOR-RELAYED-ADDRESS is present in Allocate responses. It specifies the address and port that the server allocated to the client. It is encoded in the same way as XOR-MAPPED-ADDRESS [RFC5389].14.6. EVEN-PORT
This attribute allows the client to request that the port in the relayed transport address be even, and (optionally) that the server reserve the next-higher port number. The value portion of this attribute is 1 byte long. Its format is:
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|R| RFFU |
+-+-+-+-+-+-+-+-+
The value contains a single 1-bit flag:
R: If 1, the server is requested to reserve the next-higher port
number (on the same IP address) for a subsequent allocation. If
0, no such reservation is requested.
The other 7 bits of the attribute's value must be set to zero on
transmission and ignored on reception.
Since the length of this attribute is not a multiple of 4, padding
must immediately follow this attribute.
14.7. REQUESTED-TRANSPORT
This attribute is used by the client to request a specific transport
protocol for the allocated transport address. The value of this
attribute is 4 bytes with the following format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Protocol | RFFU |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The Protocol field specifies the desired protocol. The codepoints
used in this field are taken from those allowed in the Protocol field
in the IPv4 header and the NextHeader field in the IPv6 header
[Protocol-Numbers]. This specification only allows the use of
codepoint 17 (User Datagram Protocol).
The RFFU field MUST be set to zero on transmission and MUST be
ignored on reception. It is reserved for future uses.
14.8. DONT-FRAGMENT
This attribute is used by the client to request that the server set
the DF (Don't Fragment) bit in the IP header when relaying the
application data onward to the peer. This attribute has no value
part and thus the attribute length field is 0.
14.9. RESERVATION-TOKEN
The RESERVATION-TOKEN attribute contains a token that uniquely identifies a relayed transport address being held in reserve by the server. The server includes this attribute in a success response to tell the client about the token, and the client includes this attribute in a subsequent Allocate request to request the server use that relayed transport address for the allocation. The attribute value is 8 bytes and contains the token value.15. New STUN Error Response Codes
This document defines the following new error response codes: 403 (Forbidden): The request was valid but cannot be performed due to administrative or similar restrictions. 437 (Allocation Mismatch): A request was received by the server that requires an allocation to be in place, but no allocation exists, or a request was received that requires no allocation, but an allocation exists. 441 (Wrong Credentials): The credentials in the (non-Allocate) request do not match those used to create the allocation. 442 (Unsupported Transport Protocol): The Allocate request asked the server to use a transport protocol between the server and the peer that the server does not support. NOTE: This does NOT refer to the transport protocol used in the 5-tuple. 486 (Allocation Quota Reached): No more allocations using this username can be created at the present time. 508 (Insufficient Capacity): The server is unable to carry out the request due to some capacity limit being reached. In an Allocate response, this could be due to the server having no more relayed transport addresses available at that time, having none with the requested properties, or the one that corresponds to the specified reservation token is not available.
(page 48 continued on part 4)
