tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 5766

 
 
 

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

Part 3 of 4, p. 35 to 48
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 35 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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 RFC Part