rfc3489.txt

this is simple sip stack.

      receives a packet can send a UDP packet back to the internal host.






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


   Determining the type of NAT is important in many cases.  Depending on
   what the application wants to do, it may need to take the particular
   behavior into account.

6.  Overview of Operation

   This section is descriptive only.  Normative behavior is described in
   Sections 8 and 9.

                            /-----\
                          // STUN  \\
                         |   Server  |
                          \\       //
                            \-----/


                       +--------------+             Public Internet
       ................|     NAT 2    |.......................
                       +--------------+


                       +--------------+             Private NET 2
       ................|     NAT 1    |.......................
                       +--------------+

                            /-----\
                          // STUN  \\
                         |   Client  |
                          \\       //               Private NET 1
                            \-----/

                     Figure 1: STUN Configuration

   The typical STUN configuration is shown in Figure 1.  A STUN client
   is connected to private network 1.  This network connects to private
   network 2 through NAT 1.  Private network 2 connects to the public
   Internet through NAT 2.  The STUN server resides on the public
   Internet.

   STUN is a simple client-server protocol.  A client sends a request to
   a server, and the server returns a response.  There are two types of
   requests - Binding Requests, sent over UDP, and Shared Secret
   Requests, sent over TLS [2] over TCP.  Shared Secret Requests ask the
   server to return a temporary username and password.  This username
   and password are used in a subsequent Binding Request and Binding
   Response, for the purposes of authentication and message integrity.





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


   Binding requests are used to determine the bindings allocated by
   NATs.  The client sends a Binding Request to the server, over UDP.
   The server examines the source IP address and port of the request,
   and copies them into a response that is sent back to the client.
   There are some parameters in the request that allow the client to ask
   that the response be sent elsewhere, or that the server send the
   response from a different address and port.  There are attributes for
   providing message integrity and authentication.

   The trick is using STUN to discover the presence of NAT, and to learn
   and use the bindings they allocate.

   The STUN client is typically embedded in an application which needs
   to obtain a public IP address and port that can be used to receive
   data.  For example, it might need to obtain an IP address and port to
   receive Real Time Transport Protocol (RTP) [12] traffic.  When the
   application starts, the STUN client within the application sends a
   STUN Shared Secret Request to its server, obtains a username and
   password, and then sends it a Binding Request.  STUN servers can be
   discovered through DNS SRV records [3], and it is generally assumed
   that the client is configured with the domain to use to find the STUN
   server.  Generally, this will be the domain of the provider of the
   service the application is using (such a provider is incented to
   deploy STUN servers in order to allow its customers to use its
   application through NAT).  Of course, a client can determine the
   address or domain name of a STUN server through other means.  A STUN
   server can even be embedded within an end system.

   The STUN Binding Request is used to discover the presence of a NAT,
   and to discover the public IP address and port mappings generated by
   the NAT.  Binding Requests are sent to the STUN server using UDP.
   When a Binding Request arrives at the STUN server, it may have passed
   through one or more NATs between the STUN client and the STUN server.
   As a result, the source address of the request received by the server
   will be the mapped address created by the NAT closest to the server.
   The STUN server copies that source IP address and port into a STUN
   Binding Response, and sends it back to the source IP address and port
   of the STUN request.  For all of the NAT types above, this response
   will arrive at the STUN client.

   When the STUN client receives the STUN Binding Response, it compares
   the IP address and port in the packet with the local IP address and
   port it bound to when the request was sent.  If these do not match,
   the STUN client is behind one or more NATs.  In the case of a full-
   cone NAT, the IP address and port in the body of the STUN response
   are public, and can be used by any host on the public Internet to
   send packets to the application that sent the STUN request.  An
   application need only listen on the IP address and port from which



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


   the STUN request was sent. Any packets sent by a host on the public
   Internet to the public address and port learned by STUN will be
   received by the application.

   Of course, the host may not be behind a full-cone NAT.  Indeed, it
   doesn't yet know what type of NAT it is behind.  To determine that,
   the client uses additional STUN Binding Requests.  The exact
   procedure is flexible, but would generally work as follows.  The
   client would send a second STUN Binding Request, this time to a
   different IP address, but from the same source IP address and port.
   If the IP address and port in the response are different from those
   in the first response, the client knows it is behind a symmetric NAT.
   To determine if it's behind a full-cone NAT, the client can send a
   STUN Binding Request with flags that tell the STUN server to send a
   response from a different IP address and port than the request was
   received on.  In other words, if the client sent a Binding Request to
   IP address/port A/B using a source IP address/port of X/Y, the STUN
   server would send the Binding Response to X/Y using source IP
   address/port C/D.  If the client receives this response, it knows it
   is behind a full cone NAT.

   STUN also allows the client to ask the server to send the Binding
   Response from the same IP address the request was received on, but
   with a different port.  This can be used to detect whether the client
   is behind a port restricted cone NAT or just a restricted cone NAT.

   It should be noted that the configuration in Figure 1 is not the only
   permissible configuration.  The STUN server can be located anywhere,
   including within another client.  The only requirement is that the
   STUN server is reachable by the client, and if the client is trying
   to obtain a publicly routable address, that the server reside on the
   public Internet.

7.  Message Overview

   STUN messages are TLV (type-length-value) encoded using big endian
   (network ordered) binary.  All STUN messages start with a STUN
   header, followed by a STUN payload.  The payload is a series of STUN
   attributes, the set of which depends on the message type.  The STUN
   header contains a STUN message type, transaction ID, and length.  The
   message type can be Binding Request, Binding Response, Binding Error
   Response, Shared Secret Request, Shared Secret Response, or Shared
   Secret Error Response.  The transaction ID is used to correlate
   requests and responses.  The length indicates the total length of the
   STUN payload, not including the header.  This allows STUN to run over
   TCP.  Shared Secret Requests are always sent over TCP (indeed, using
   TLS over TCP).




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


   Several STUN attributes are defined.  The first is a MAPPED-ADDRESS
   attribute, which is an IP address and port.  It is always placed in
   the Binding Response, and it indicates the source IP address and port
   the server saw in the Binding Request.  There is also a RESPONSE-
   ADDRESS attribute, which contains an IP address and port.  The
   RESPONSE-ADDRESS attribute can be present in the Binding Request, and
   indicates where the Binding Response is to be sent.  It's optional,
   and when not present, the Binding Response is sent to the source IP
   address and port of the Binding Request.

   The third attribute is the CHANGE-REQUEST attribute, and it contains
   two flags to control the IP address and port used to send the
   response.  These flags are called "change IP" and "change port"
   flags.  The CHANGE-REQUEST attribute is allowed only in the Binding
   Request.  The "change IP" and "change port" flags are useful for
   determining whether the client is behind a restricted cone NAT or
   restricted port cone NAT.  They instruct the server to send the
   Binding Responses from a different source IP address and port.  The
   CHANGE-REQUEST attribute is optional in the Binding Request.

   The fourth attribute is the CHANGED-ADDRESS attribute.  It is present
   in Binding Responses.  It informs the client of the source IP address
   and port that would be used if the client requested the "change IP"
   and "change port" behavior.

   The fifth attribute is the SOURCE-ADDRESS attribute.  It is only
   present in Binding Responses.  It indicates the source IP address and
   port where the response was sent from.  It is useful for detecting
   twice NAT configurations.

   The sixth attribute is the USERNAME attribute.  It is present in a
   Shared Secret Response, which provides the client with a temporary
   username and password (encoded in the PASSWORD attribute).  The
   USERNAME is also present in Binding Requests, serving as an index to
   the shared secret used for the integrity protection of the Binding
   Request.  The seventh attribute, PASSWORD, is only found in Shared
   Secret Response messages.  The eight attribute is the MESSAGE-
   INTEGRITY attribute, which contains a message integrity check over
   the Binding Request or Binding Response.

   The ninth attribute is the ERROR-CODE attribute.  This is present in
   the Binding Error Response and Shared Secret Error Response.  It
   indicates the error that has occurred.  The tenth attribute is the
   UNKNOWN-ATTRIBUTES attribute, which is present in either the Binding
   Error Response or Shared Secret Error Response.  It indicates the
   mandatory attributes from the request which were unknown.  The
   eleventh attribute is the REFLECTED-FROM attribute, which is present
   in Binding Responses.  It indicates the IP address and port of the



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


   sender of a Binding Request, used for traceability purposes to
   prevent certain denial-of-service attacks.

8.  Server Behavior

   The server behavior depends on whether the request is a Binding
   Request or a Shared Secret Request.

8.1  Binding Requests

   A STUN server MUST be prepared to receive Binding Requests on four
   address/port combinations - (A1, P1), (A2, P1), (A1, P2), and (A2,
   P2).  (A1, P1) represent the primary address and port, and these are
   the ones obtained through the client discovery procedures below.
   Typically, P1 will be port 3478, the default STUN port.  A2 and P2
   are arbitrary.  A2 and P2 are advertised by the server through the
   CHANGED-ADDRESS attribute, as described below.

   It is RECOMMENDED that the server check the Binding Request for a
   MESSAGE-INTEGRITY attribute.  If not present, and the server requires
   integrity checks on the request, it generates a Binding Error
   Response with an ERROR-CODE attribute with response code 401.  If the
   MESSAGE-INTEGRITY attribute was present, the server computes the HMAC
   over the request 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 request.  If the USERNAME attribute
   was not present, the server MUST generate a Binding Error Response.
   The Binding Error Response MUST include an ERROR-CODE attribute with
   response code 432.  If the USERNAME is present, but the server
   doesn't remember the shared secret for that USERNAME (because it
   timed out, for example), the server MUST generate a Binding Error
   Response.  The Binding Error Response MUST include an ERROR-CODE
   attribute with response code 430.  If the server does know the shared
   secret, but the computed HMAC differs from the one in the request,
   the server MUST generate a Binding Error Response with an ERROR-CODE
   attribute with response code 431.  The Binding Error Response is sent
   to the IP address and port the Binding Request came from, and sent