Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 5766

Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)

Pages: 67
Obsoleted by:  8656
Updated by:  81558553
Part 3 of 4 – Pages 35 to 48
First   Prev   Next

Top   ToC   RFC5766 - Page 35   prevText

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.
Top   ToC   RFC5766 - Page 36
   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
Top   ToC   RFC5766 - Page 37
   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).
Top   ToC   RFC5766 - Page 38
      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
Top   ToC   RFC5766 - Page 39
   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;
Top   ToC   RFC5766 - Page 40
   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.
Top   ToC   RFC5766 - Page 41
   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.
Top   ToC   RFC5766 - Page 42
   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;
Top   ToC   RFC5766 - Page 43
   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].
Top   ToC   RFC5766 - Page 44
      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.
Top   ToC   RFC5766 - Page 45

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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Top   ToC   RFC5766 - Page 46

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:
Top   ToC   RFC5766 - Page 47
      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.
Top   ToC   RFC5766 - Page 48

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)

Next Section