rfc3489.txt

this is simple sip stack.

   from the IP address and port the Binding Request was sent to.

   Assuming the message integrity check passed, processing continues.
   The server MUST check for any attributes in the request with values
   less than or equal to 0x7fff which it does not understand.  If it
   encounters any, the server MUST generate a Binding Error Response,
   and it MUST include an ERROR-CODE attribute with a 420 response code.






Rosenberg, et al.           Standards Track                    [Page 10]

RFC 3489                          STUN                        March 2003


   That response MUST contain an UNKNOWN-ATTRIBUTES attribute listing
   the attributes with values less than or equal to 0x7fff which were
   not understood.  The Binding Error Response is sent to the IP address
   and port the Binding Request came from, and sent from the IP address
   and port the Binding Request was sent to.

   Assuming the request was correctly formed, the server MUST generate a
   single Binding Response.  The Binding Response MUST contain the same
   transaction ID contained in the Binding Request.  The length in the
   message header MUST contain the total length of the message in bytes,
   excluding the header.  The Binding Response MUST have a message type
   of "Binding Response".

   The server MUST add a MAPPED-ADDRESS attribute to the Binding
   Response.  The IP address component of this attribute MUST be set to
   the source IP address observed in the Binding Request.  The port
   component of this attribute MUST be set to the source port observed
   in the Binding Request.

   If the RESPONSE-ADDRESS attribute was absent from the Binding
   Request, the destination address and port of the Binding Response
   MUST be the same as the source address and port of the Binding
   Request.  Otherwise, the destination address and port of the Binding
   Response MUST be the value of the IP address and port in the
   RESPONSE-ADDRESS attribute.

   The source address and port of the Binding Response depend on the
   value of the CHANGE-REQUEST attribute and on the address and port the
   Binding Request was received on, and are summarized in Table 1.

   Let Da represent the destination IP address of the Binding Request
   (which will be either A1 or A2), and Dp represent the destination
   port of the Binding Request (which will be either P1 or P2).  Let Ca
   represent the other address, so that if Da is A1, Ca is A2.  If Da is
   A2, Ca is A1.  Similarly, let Cp represent the other port, so that if
   Dp is P1, Cp is P2.  If Dp is P2, Cp is P1.  If the "change port"
   flag was set in CHANGE-REQUEST attribute of the Binding Request, and
   the "change IP" flag was not set, the source IP address of the
   Binding Response MUST be Da and the source port of the Binding
   Response MUST be Cp.  If the "change IP" flag was set in the Binding
   Request, and the "change port" flag was not set, the source IP
   address of the Binding Response MUST be Ca and the source port of the
   Binding Response MUST be Dp.  When both flags are set, the source IP
   address of the Binding Response MUST be Ca and the source port of the
   Binding Response MUST be Cp.  If neither flag is set, or if the
   CHANGE-REQUEST attribute is absent entirely, the source IP address of
   the Binding Response MUST be Da and the source port of the Binding
   Response MUST be Dp.



Rosenberg, et al.           Standards Track                    [Page 11]

RFC 3489                          STUN                        March 2003


      Flags          Source Address  Source Port   CHANGED-ADDRESS
      none           Da              Dp            Ca:Cp
      Change IP      Ca              Dp            Ca:Cp
      Change port    Da              Cp            Ca:Cp
      Change IP and
        Change port  Ca              Cp            Ca:Cp

   Table 1: Impact of Flags on Packet Source and CHANGED-ADDRESS

   The server MUST add a SOURCE-ADDRESS attribute to the Binding
   Response, containing the source address and port used to send the
   Binding Response.

   The server MUST add a CHANGED-ADDRESS attribute to the Binding
   Response.  This contains the source IP address and port that would be
   used if the client had set the "change IP" and "change port" flags in
   the Binding Request.  As summarized in Table 1, these are Ca and Cp,
   respectively, regardless of the value of the CHANGE-REQUEST flags.

   If the Binding Request contained both the USERNAME and MESSAGE-
   INTEGRITY attributes, the server MUST add a MESSAGE-INTEGRITY
   attribute to the Binding Response.  The attribute contains an HMAC
   [13] over the response, as described in Section 11.2.8.  The key to
   use depends on the shared secret mechanism.  If the STUN Shared
   Secret Request was used, the key MUST be the one associated with the
   USERNAME attribute present in the Binding Request.

   If the Binding Request contained a RESPONSE-ADDRESS attribute, the
   server MUST add a REFLECTED-FROM attribute to the response.  If the
   Binding Request was authenticated using a username obtained from a
   Shared Secret Request, the REFLECTED-FROM attribute MUST contain the
   source IP address and port where that Shared Secret Request came
   from.  If the username present in the request was not allocated using
   a Shared Secret Request, the REFLECTED-FROM attribute MUST contain
   the source address and port of the entity which obtained the
   username, as best can be verified with the mechanism used to allocate
   the username.  If the username was not present in the request, and
   the server was willing to process the request, the REFLECTED-FROM
   attribute SHOULD contain the source IP address and port where the
   request came from.

   The server SHOULD NOT retransmit the response.  Reliability is
   achieved by having the client periodically resend the request, each
   of which triggers a response from the server.







Rosenberg, et al.           Standards Track                    [Page 12]

RFC 3489                          STUN                        March 2003


8.2 Shared Secret Requests

   Shared Secret Requests are always received on TLS connections.  When
   the server receives a request from the client to establish a TLS
   connection, it MUST proceed with TLS, and SHOULD present a site
   certificate.  The TLS ciphersuite TLS_RSA_WITH_AES_128_CBC_SHA [4]
   SHOULD be used.  Client TLS authentication MUST NOT be done, since
   the server is not allocating any resources to clients, and the
   computational burden can be a source of attacks.

   If the server receives a Shared Secret Request, it MUST verify that
   the request arrived on a TLS connection.  If it did not receive the
   request over TLS, it MUST generate a Shared Secret Error Response,
   and it MUST include an ERROR-CODE attribute with a 433 response code.
   The destination for the error response depends on the transport on
   which the request was received.  If the Shared Secret Request was
   received over TCP, the Shared Secret Error Response is sent over the
   same connection the request was received on.  If the Shared Secret
   Request was receive over UDP, the Shared Secret Error Response is
   sent to the source IP address and port that the request came from.

   The server MUST check for any attributes in the request with values
   less than or equal to 0x7fff which it does not understand.  If it
   encounters any, the server MUST generate a Shared Secret Error
   Response, and it MUST include an ERROR-CODE attribute with a 420
   response code.  That response MUST contain an UNKNOWN-ATTRIBUTES
   attribute listing the attributes with values less than or equal to
   0x7fff which were not understood.  The Shared Secret Error Response
   is sent over the TLS connection.

   All Shared Secret Error Responses MUST contain the same transaction
   ID contained in the Shared Secret Request. The length in the message
   header MUST contain the total length of the message in bytes,
   excluding the header.  The Shared Secret Error Response MUST have a
   message type of "Shared Secret Error Response" (0x0112).

   Assuming the request was properly constructed, the server creates a
   Shared Secret Response.  The Shared Secret Response MUST contain the
   same transaction ID contained in the Shared Secret Request.  The
   length in the message header MUST contain the total length of the
   message in bytes, excluding the header.  The Shared Secret Response
   MUST have a message type of "Shared Secret Response".  The Shared
   Secret Response MUST contain a USERNAME attribute and a PASSWORD
   attribute.  The USERNAME attribute serves as an index to the
   password, which is contained in the PASSWORD attribute.  The server
   can use any mechanism it chooses to generate the username.  However,
   the username MUST be valid for a period of at least 10 minutes.
   Validity means that the server can compute the password for that



Rosenberg, et al.           Standards Track                    [Page 13]

RFC 3489                          STUN                        March 2003


   username.  There MUST be a single password for each username.  In
   other words, the server cannot, 10 minutes later, assign a different
   password to the same username.  The server MUST hand out a different
   username for each distinct Shared Secret Request.  Distinct, in this
   case, implies a different transaction ID.  It is RECOMMENDED that the
   server explicitly invalidate the username after ten minutes.  It MUST
   invalidate the username after 30 minutes.  The PASSWORD contains the
   password bound to that username.  The password MUST have at least 128
   bits.  The likelihood that the server assigns the same password for
   two different usernames MUST be vanishingly small, and the passwords
   MUST be unguessable.  In other words, they MUST be a
   cryptographically random function of the username.

   These requirements can still be met using a stateless server, by
   intelligently computing the USERNAME and PASSWORD.  One approach is
   to construct the USERNAME as:

      USERNAME = <prefix,rounded-time,clientIP,hmac>

   Where prefix is some random text string (different for each shared
   secret request), rounded-time is the current time modulo 20 minutes,
   clientIP is the source IP address where the Shared Secret Request
   came from, and hmac is an HMAC [13] over the prefix, rounded-time,
   and client IP, using a server private key.

   The password is then computed as:

      password = <hmac(USERNAME,anotherprivatekey)>

   With this structure, the username itself, which will be present in
   the Binding Request, contains the source IP address where the Shared
   Secret Request came from.  That allows the server to meet the
   requirements specified in Section 8.1 for constructing the
   REFLECTED-FROM attribute.  The server can verify that the username
   was not tampered with, using the hmac present in the username.

   The Shared Secret Response is sent over the same TLS connection the
   request was received on.  The server SHOULD keep the connection open,
   and let the client close it.

9.  Client Behavior

   The behavior of the client is very straightforward.  Its task is to
   discover the STUN server, obtain a shared secret, formulate the
   Binding Request, handle request reliability, and process the Binding
   Responses.





Rosenberg, et al.           Standards Track                    [Page 14]

RFC 3489                          STUN                        March 2003


9.1  Discovery

   Generally, the client will be configured with a domain name of the
   provider of the STUN servers.  This domain name is resolved to an IP
   address and port using the SRV procedures specified in RFC 2782 [3].

   Specifically, the service name is "stun".  The protocol is "udp" for
   sending Binding Requests, or "tcp" for sending Shared Secret
   Requests.  The procedures of RFC 2782 are followed to determine the
   server to contact.  RFC 2782 spells out the details of how a set of
   SRV records are sorted and then tried.  However, it only states that
   the client should "try to connect to the (protocol, address,
   service)" without giving any details on what happens in the event of
   failure.  Those details are described here for STUN.

   For STUN requests, failure occurs if there is a transport failure of
   some sort (generally, due to fatal ICMP errors in UDP or connection
   failures in TCP).  Failure also occurs if the transaction fails due
   to timeout.  This occurs 9.5 seconds after the first request is sent,
   for both Shared Secret Requests and Binding Requests.  See Section
   9.3 for details on transaction timeouts for Binding Requests.  If a
   failure occurs, the client SHOULD create a new request, which is
   identical to the previous, but has a different transaction ID and
   MESSAGE INTEGRITY attribute (the HMAC will change because the
   transaction ID has changed).  That request is sent to the next
   element in the list as specified by RFC 2782.

   The default port for STUN requests is 3478, for both TCP and UDP.
   Administrators SHOULD use this port in their SRV records, but MAY use
   others.

   If no SRV records were found, the client performs an A record lookup