rfc3489.txt

this is simple sip stack.

   of the domain name.  The result will be a list of IP addresses, each
   of which can be contacted at the default port.

   This would allow a firewall admin to open the STUN port, so hosts
   within the enterprise could access new applications. Whether they
   will or won't do this is a good question.

9.2 Obtaining a Shared Secret

   As discussed in Section 12, there are several attacks possible on
   STUN systems.  Many of these are prevented through integrity of
   requests and responses.  To provide that integrity, STUN makes use of
   a shared secret between client and server, used as the keying
   material for an HMAC used in both the Binding Request and Binding
   Response.  STUN allows for the shared secret to be obtained in any
   way (for example, Kerberos [14]).  However, it MUST have at least 128



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


   bits of randomness.  In order to ensure interoperability, this
   specification describes a TLS-based mechanism.  This mechanism,
   described in this section, MUST be implemented by clients and
   servers.

   First, the client determines the IP address and port that it will
   open a TCP connection to.  This is done using the discovery
   procedures in Section 9.1.  The client opens up the connection to
   that address and port, and immediately begins TLS negotiation [2].
   The client MUST verify the identity of the server.  To do that, it
   follows the identification procedures defined in Section 3.1 of RFC
   2818 [5]. Those procedures assume the client is dereferencing a URI.
   For purposes of usage with this specification, the client treats the
   domain name or IP address used in Section 9.1 as the host portion of
   the URI that has been dereferenced.

   Once the connection is opened, the client sends a Shared Secret
   request.  This request has no attributes, just the header.  The
   transaction ID in the header MUST meet the requirements outlined for
   the transaction ID in a binding request, described in Section 9.3
   below.  The server generates a response, which can either be a Shared
   Secret Response or a Shared Secret Error Response.

   If the response was a Shared Secret Error Response, the client checks
   the response code in the ERROR-CODE attribute.  Interpretation of
   those response codes is identical to the processing of Section 9.4
   for the Binding Error Response.

   If a client receives a Shared Secret Response with an attribute whose
   type is greater than 0x7fff, the attribute MUST be ignored.  If the
   client receives a Shared Secret Response with an attribute whose type
   is less than or equal to 0x7fff, the response is ignored.

   If the response was a Shared Secret Response, it will contain a short
   lived username and password, encoded in the USERNAME and PASSWORD
   attributes, respectively.

   The client MAY generate multiple Shared Secret Requests on the
   connection, and it MAY do so before receiving Shared Secret Responses
   to previous Shared Secret Requests.  The client SHOULD close the
   connection as soon as it has finished obtaining usernames and
   passwords.

   Section 9.3 describes how these passwords are used to provide
   integrity protection over Binding Requests, and Section 8.1 describes
   how it is used in Binding Responses.





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


9.3  Formulating the Binding Request

   A Binding Request formulated by the client follows the syntax rules
   defined in Section 11.  Any two requests that are not bit-wise
   identical, and not sent to the same server from the same IP address
   and port, MUST carry different transaction IDs. The transaction ID
   MUST be uniformly and randomly distributed between 0 and 2**128 - 1.
   The large range is needed because the transaction ID serves as a form
   of randomization, helping to prevent replays of previously signed
   responses from the server.  The message type of the request MUST be
   "Binding Request".

   The RESPONSE-ADDRESS attribute is optional in the Binding Request.
   It is used if the client wishes the response to be sent to a
   different IP address and port than the one the request was sent from.
   This is useful for determining whether the client is behind a
   firewall, and for applications that have separated control and data
   components.  See Section 10.3 for more details.  The CHANGE-REQUEST
   attribute is also optional.  Whether it is present depends on what
   the application is trying to accomplish.  See Section 10 for some
   example uses.

   The client SHOULD add a MESSAGE-INTEGRITY and USERNAME attribute to
   the Binding Request.  This MESSAGE-INTEGRITY attribute contains an
   HMAC [13].  The value of the username, and the key to use in the
   MESSAGE-INTEGRITY attribute depend on the shared secret mechanism.
   If the STUN Shared Secret Request was used, the USERNAME must be a
   valid username obtained from a Shared Secret Response within the last
   nine minutes.  The shared secret for the HMAC is the value of the
   PASSWORD attribute obtained from the same Shared Secret Response.

   Once formulated, the client sends the Binding Request.  Reliability
   is accomplished through client retransmissions.  Clients SHOULD
   retransmit the request starting with an interval of 100ms, doubling
   every retransmit until the interval reaches 1.6s.  Retransmissions
   continue with intervals of 1.6s until a response is received, or a
   total of 9 requests have been sent. If no response is received by 1.6
   seconds after the last request has been sent, the client SHOULD
   consider the transaction to have failed. In other words, requests
   would be sent at times 0ms, 100ms, 300ms, 700ms, 1500ms, 3100ms,
   4700ms, 6300ms, and 7900ms. At 9500ms, the client considers the
   transaction to have failed if no response has been received.

9.4  Processing Binding Responses

   The response can either be a Binding Response or Binding Error
   Response.  Binding Error Responses are always received on the source
   address and port the request was sent from.  A Binding Response will



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


   be received on the address and port placed in the RESPONSE-ADDRESS
   attribute of the request.  If none was present, the Binding Responses
   will be received on the source address and port the request was sent
   from.

   If the response is a Binding Error Response, the client checks the
   response code from the ERROR-CODE attribute of the response.  For a
   400 response code, the client SHOULD display the reason phrase to the
   user.  For a 420 response code, the client SHOULD retry the request,
   this time omitting any attributes listed in the UNKNOWN-ATTRIBUTES
   attribute of the response.  For a 430 response code, the client
   SHOULD obtain a new shared secret, and retry the Binding Request with
   a new transaction.  For 401 and 432 response codes, if the client had
   omitted the USERNAME or MESSAGE-INTEGRITY attribute as indicated by
   the error, it SHOULD try again with those attributes.  For a 431
   response code, the client SHOULD alert the user, and MAY try the
   request again after obtaining a new username and password.  For a 500
   response code, the client MAY wait several seconds and then retry the
   request.  For a 600 response code, the client MUST NOT retry the
   request, and SHOULD display the reason phrase to the user.  Unknown
   attributes between 400 and 499 are treated like a 400, unknown
   attributes between 500 and 599 are treated like a 500, and unknown
   attributes between 600 and 699 are treated like a 600.  Any response
   between 100 and 399 MUST result in the cessation of request
   retransmissions, but otherwise is discarded.

   If a client receives a response with an attribute whose type is
   greater than 0x7fff, the attribute MUST be ignored.  If the client
   receives a response with an attribute whose type is less than or
   equal to 0x7fff, request retransmissions MUST cease, but the entire
   response is otherwise ignored.

   If the response is a Binding Response, the client SHOULD check the
   response for a MESSAGE-INTEGRITY attribute.  If not present, and the
   client placed a MESSAGE-INTEGRITY attribute into the request, it MUST
   discard the response.  If present, the client computes the HMAC 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 same as used to compute the MESSAGE-
   INTEGRITY attribute in the request.  If the computed HMAC differs
   from the one in the response, the client MUST discard the response,
   and SHOULD alert the user about a possible attack.  If the computed
   HMAC matches the one from the response, processing continues.

   Reception of a response (either Binding Error Response or Binding
   Response) to a Binding Request will terminate retransmissions of that
   request.  However, clients MUST continue to listen for responses to a
   Binding Request for 10 seconds after the first response.  If it



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


   receives any responses in this interval with different message types
   (Binding Responses and Binding Error Responses, for example) or
   different MAPPED-ADDRESSes, it is an indication of a possible attack.
   The client MUST NOT use the MAPPED-ADDRESS from any of the responses
   it received (either the first or the additional ones), and SHOULD
   alert the user.

   Furthermore, if a client receives more than twice as many Binding
   Responses as the number of Binding Requests it sent, it MUST NOT use
   the MAPPED-ADDRESS from any of those responses, and SHOULD alert the
   user about a potential attack.

   If the Binding Response is authenticated, and the MAPPED-ADDRESS was
   not discarded because of a potential attack, the CLIENT MAY use the
   MAPPED-ADDRESS and SOURCE-ADDRESS attributes.

10.  Use Cases

   The rules of Sections 8 and 9 describe exactly how a client and
   server interact to send requests and get responses.  However, they do
   not dictate how the STUN protocol is used to accomplish useful tasks.
   That is at the discretion of the client.  Here, we provide some
   useful scenarios for applying STUN.

10.1  Discovery Process

   In this scenario, a user is running a multimedia application which
   needs to determine which of the following scenarios applies to it:

   o  On the open Internet

   o  Firewall that blocks UDP

   o  Firewall that allows UDP out, and responses have to come back to
      the source of the request (like a symmetric NAT, but no
      translation.  We call this a symmetric UDP Firewall)

   o  Full-cone NAT

   o  Symmetric NAT

   o  Restricted cone or restricted port cone NAT

   Which of the six scenarios applies can be determined through the flow
   chart described in Figure 2.  The chart refers only to the sequence
   of Binding Requests; Shared Secret Requests will, of course, be
   needed to authenticate each Binding Request used in the sequence.




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


   The flow makes use of three tests.  In test I, the client sends a
   STUN Binding Request to a server, without any flags set in the
   CHANGE-REQUEST attribute, and without the RESPONSE-ADDRESS attribute.
   This causes the server to send the response back to the address and
   port that the request came from.  In test II, the client sends a
   Binding Request with both the "change IP" and "change port" flags
   from the CHANGE-REQUEST attribute set.  In test III, the client sends
   a Binding Request with only the "change port" flag set.

   The client begins by initiating test I.  If this test yields no
   response, the client knows right away that it is not capable of UDP
   connectivity.  If the test produces a response, the client examines
   the MAPPED-ADDRESS attribute.  If this address and port are the same
   as the local IP address and port of the socket used to send the
   request, the client knows that it is not natted.  It executes test
   II.

   If a response is received, the client knows that it has open access
   to the Internet (or, at least, its behind a firewall that behaves
   like a full-cone NAT, but without the translation).  If no response
   is received, the client knows its behind a symmetric UDP firewall.

   In the event that the IP address and port of the socket did not match
   the MAPPED-ADDRESS attribute in the response to test I, the client
   knows that it is behind a NAT.  It performs test II.  If a response
   is received, the client knows that it is behind a full-cone NAT.  If