Socks Protocol Version 5
INTERNET-DRAFT
Expires: In Six Months                                                 M. Leech
<draft-ietf-aft-socks-protocol-v5-01.txt>
<draft-ietf-aft-socks-protocol-v5-02.txt>                              M. Ganis
                                                                       Y. Lee
                                                                       R. Kuris
                                                                       D. Koblas
                                                                       L. Jones

                        SOCKS Protocol Version 5

Status of this Memo

     This document is an Internet-Draft. Internet-Drafts are working
     documents of the Internet Engineering Task Force (IETF), its areas,
     and its working groups. Note that other groups may also distribute
     working documents as Internet-Drafts.

     Internet-Drafts are draft document valid for a maximum of six
     months and may be updated, replaced or obsoleted by other documents
     at any time. It is inappropriate to use Internet-Drafts as
     reference material or to cite them other than as "work in
     progress".

     To learn the current status of any Internet-Draft, please check the
     "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
     Directories on ds.internic.net (US East Coast), nic.nordu.net
     (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
     Rim).

Acknowledgments

     This memo describes a protocol that is an evolution of the previous
     version of the protocol, version 4 [1]. This new protocol stems
     from active discussions and prototype implementations.  The key
     contributors are: Marcus Leech: Bell-Northern Research, David
     Koblas: Independent Consultant, Ying-Da Lee: NEC Systems
     Laboratory, LaMont Jones: Hewlett-Packard Company, Ron Kuris: Unify
     Corporation, Matt Ganis: International Business Machines.

1.  Introduction

     The use of network firewalls, systems that effectively isolate an
     organizations internal network structure from an exterior network,
     such as the INTERNET is becoming increasingly popular.  These
     firewall systems typically act as application-layer gateways
     between networks, usually offering controlled TELNET, FTP, and SMTP
     access.  With the emergence of more sophisticated application layer
     protocols designed to facilitate global information discovery,
     there exists a need to provide a general framework for these
     protocols to transparently and securely traverse a firewall.

     There exists, also, a need for strong authentication of such
     traversal in as fine-grained a manner as is practical. This
     requirement stems from the realization that client-server
     relationships emerge between the networks of various organizations,
     and that such relationships need to be controlled and often
     strongly authenticated.

     The protocol described here is designed to provide a framework for
     client-server applications in both the TCP and UDP domains to
     conveniently and securely use the services of a network firewall.
     The protocol is conceptually a "shim-layer" between the application
     layer and the transport layer, and as such does not provide
     network-layer gateway services, such as forwarding of ICMP
     messages.

2.  Existing practice

     There currently exists a protocol, SOCKS Version 4, that provides
     for unsecured firewall traversal for TCP-based client-server
     applications, including TELNET, FTP and the popular information-
     discovery protocols such as HTTP, WAIS and GOPHER.

     This new protocol extends the SOCKS Version 4 model to include UDP,
     and extends the protocol framework to include provisions for generalized
     strong authentication schemes, and extends the addressing scheme to
     encompass domain-name and V6 IP addresses.

     The implementation of the SOCKS protocol typically involves the
     recompilation or relinking of TCP-based client applications to use
     the appropriate encapsulation routines in the SOCKS library.

3.  Procedure for TCP-based clients

     When a TCP-based client wishes to establish a connection to an
     object that is reachable only via a firewall (such determination is
     left up to the implementation), it must open a TCP connection to
     the appropriate SOCKS port on the SOCKS server system.  The SOCKS
     service is conventionally located on TCP port 1080.  If the
     connection request succeeds, the client enters a negotiation for
     the authentication method to be used, authenticates with the chosen
     method, then sends a relay request.  The SOCKS server evaluates the
     request, and either establishes the appropriate connection or
     denies it.

     The client connects to the server, and sends a version
     identifier/method selection packet:

              +----+----------+----------+------+ message:

                   +----+----------+----------+
                   |VER | NMETHODS | METHODS  | MACS |
              +----+----------+----------+------+
                   +----+----------+----------+
                   | 1  |    1     | 1 to 255 |  1   |
              +----+----------+----------+------+
                   +----+----------+----------+

     The VER field is set to X'05' for this version of the
     protocol.  The NMETHODS field contains the number of
     method identifier octets that appear in the METHODS
     field.

     The server selects from one of the methods given in METH-
   ODS,
     METHODS, and a MAC algorithm, then sends a METHOD selection indica-
   tor:

                    +----+--------+--------+ message:

                         +----+--------+
                         |VER | METHOD | MACSEL |
                    +----+--------+--------+
                    | 1
                         +----+--------+
                         | 1  |   1    |
                    +----+--------+--------+
                         +----+--------+

     If the selection indicator selected METHOD is X'FF', none of the METHODS methods
     listed by the client are acceptable, and the server client
     MUST close the connection.

     The values currently defined for METHOD are:

          o  X'00' NO AUTHENTICATION REQUIRED
          o  X'01' BNR-1
        o  X'02' GSSAPI
          o  X'03' IKMP
        o  X'04' KERBEROS4
        o  X'05' KERBEROS5
        o  X'06'  X'02' USERNAME/PASSWORD

          o  X'07' SECURE TOKEN TYPE 1 (NO CHALLENGE/RESPONSE)
        o  X'08' SECURE TOKEN TYPE 2 (CHALLENGE/RESPONSE)
        o  X'09' S/KEY  X'03' to X'7F' IANA ASSIGNED

          o  X'0A'  X'80' to X'FE' RESERVED FOR PRIVATE METHODS

          o  X'FF' NO ACCEPTABLE METHODS

     The client and server then enter a method-specific subne-
   gotiation. sub-
     negotiation.  Descriptions of the method-dependant subnegotiations method-dependent sub-
     negotiations appear in separate drafts.

   The MACS field contains a bit-vector indicating the MAC
   algorithms available to the client.  Bits are labelled
   from most-significant (0) to least significant (7):

        o  0 - MD5 with 64-bit compression [2]
        o  1 - MD5 with no compression (complete digest of 128 bits)
        o  2 - SHA with 80-bit compression [3]
        o  3 - SHA with no compression (complete digest

     Developers of 160 bits) new METHOD support for this protocol
     should contact IANA for a METHOD number.  The MACSEL field indicates which MAC algorithm that the
   server wishes the client ASSIGNED
     NUMBERS document should be referred to use during computation of the
   MAC field for UDP relay requests. A compliant implementa-
   tion a current
     list of METHOD numbers and their corresponding proto-
     cols.

     Compliant implementations MUST support both compressed GSSAPI and uncompressed MD5.
     USERNAME/PASSWORD authentication methods.

4.  Requests

     Once the method-dependant method-dependent subnegotiation has completed,
     the client sends the request details.  If the negotiated negoti-
     ated method includes encapsulation for purposes of
     integrity
   checking/and or checking and/or confidentiality, these
     requests MUST be encapsulated in the method-dependant method-dependent
     encapsulation.

     The SOCKS request is formed as follows:

        +----+-----+-------+------+----------+----------+
        |VER | CMD |  RSV  | ATYP | DST.ADDR | DST.PORT |
        +----+-----+-------+------+----------+----------+
        | 1  |  1  | X'00' |  1   | Variable |    2     |
        +----+-----+-------+------+----------+----------+

     Where:

          o  VER    protocol version: X'05'
          o  CMD
             o  CONNECT X'01'
             o  BIND X'02'
             o  UDP ASSOCIATE X'03'
             o  UDP DESTROY X'04'
          o  RSV    RESERVED
          o  ATYP   address type of following address
             o  IP V4 address: X'01'
             o  DOMAINNAME: X'03'
             o  IP V6 address: X'04'
          o  DST.ADDR       desired destination address
          o  DST.PORT       desired destination port in network octet order

     The SOCKS server will typically evaluate the request
     based on source and destination addresses, and return
     one or more reply packets, messages, as appropriate for the
     request type.

5.  Addressing
     In an address field (DST.ADDR, BND.ADDR), the ATYP
     field specifies the type of address contained within
     the field:

          o  X'01'

     the address is a version-4 IP address, with a length of
     4 octets

          o  X'03'

     the address field contains a DNS-style domain name.
     The first octet of the address field contains the
     length of the domain name.

          o  X'04'

     the address is a version-6 IP address, with a length of
     16 octets.

6.  Replies

     The SOCKS request information is sent by the client as
     soon as it has established a connection to the SOCKS
     server, and completed the authentication negotiations.
     The server evaluates the request, and returns a reply
     formed as follows:

   +----+-----+-------+------+----------+----------+--------+

        +----+-----+-------+------+----------+----------+
        |VER | REP |  RSV  | ATYP | BND.ADDR | BND.PORT | COOKIE |
   +----+-----+-------+------+----------+----------+--------+
        +----+-----+-------+------+----------+----------+
        | 1  |  1  | X'00' |  1   | Variable |    2     |   8    |
   +----+-----+-------+------+----------+----------+--------+
        +----+-----+-------+------+----------+----------+

     Where:

          o  VER    protocol version: X'05'
          o  REP    Reply field:
             o  X'00' succeeded
             o  X'01' general SOCKS server failure
             o  X'02' connection not allowed by ruleset
             o  X'03' Network unreachable
             o  X'04' Host unreachable
             o  X'05' Connection refused
             o  X'06' TTL expired
             o  X'07' to X'FF' unassigned
          o  RSV    RESERVED
          o  ATYP   address type of following address
             o  IP V4 address: X'01'
             o  DOMAINNAME: X'03'
             o  IP V6 address: X'04'
          o  BND.ADDR       server bound address
          o  BND.PORT       server bound port in network octet order
        o  COOKIE extra data used by UDP ASSOCIATE

     Fields marked RESERVED (RSV) must be set to X'00'.

     If the chosen method includes encapsulation for purposes pur-
     poses of authentication, integrity and or confidentiality, and/or confidential-
     ity, the replies are encapsulated in the method-dependant encapsu-
   lation. method-
     dependent encapsulation.

   CONNECT

     In the reply to a reply, CONNECT, BND.PORT contains the port
     number that the server assigned to connect to the tar-
     get host, while BND.ADDR and BND.PORT fields contains the associated IP
     address.  The supplied BND.ADDR is often different from
     the IP address that the client uses to reach the SOCKS
     server, since such servers are often multi-homed.  It
     is expected that the SOCKS server will use DST.ADDR and
     DST.PORT, and the client-side source address and port number of
     in evaluating the outbound con-
   nection for a CONNECT request, and contain the SOCKS
   server bind() address for a BIND request.

   BIND

     The BIND request is used in protocols which require the
     client to accept connections from the server.  FTP is a
     well-known example, which uses the primary client-to-
     server connection for commands and status reports, but
     may use a server-to-client connection for transferring
     data on demand (e.g. LS, GET, PUT).

     It is expected that the client side of an application
     protocol will use the BIND request only to establish sec-
   ondary
     secondary connections after a primary connection is estab-
   lished
     established using CONNECT.  In is expected that a SOCKS
     server will use DST.ADDR and DST.PORT in evaluating the
     BIND request.

     Two replies are sent from the SOCKS server to the
     client during a BIND operation.  The first is sent
     after the server creates and binds a new socket.  The
     BND.PORT field contains the port number that the SOCKS
     server assigned to listen for an incoming connection.

     The BND.ADDR field contains the associated IP address.
     The client will typi-
   cally typically use these pieces of information informa-
     tion to notify (via the primary or control connection)
     the application server of the `rendezvous point'. rendezvous address.  The
     second reply occurs only after the anticipated incoming
     connection succeeds or fails.

     In the second reply, the BND.PORT and BND.ADDR fields
     contain the address and port number of the connecting
     host.

   In

   UDP ASSOCIATE

     The UDP ASSOCIATE request is used to establish an asso-
     ciation within the reply UDP relay process to handle UDP
     datagrams.  The DST.ADDR field is ignored in a CONNECT, BND.PORT contains the port
   number that the server assigned to connect to the target
   host, UDP
     ASSOCIATE request, while BND.ADDR contains the associated IP address.
   The supplied BND.ADDR is often different from DST.PORT field contains
     the IP
   address idle-timeout time, in minutes, that the client uses an association
     is allowed to reach exist without explicit client-side activ-
     ity.  If DST.PORT is zero, the SOCKS server,
   since such servers are often multi-homed.

   The UDP ASSOCIATE request is used to establish server SHOULD use
     an associ-
   ation within the UDP relay process to handle UDP data-
   grams. administrator-defined default.

     In the reply to a UDP ASSOCIATE request, the BND.PORT
     and BND.ADDR fields indicate the port num-
   ber/address number/address
     where the client may send UDP request packets messages to be
     relayed. The DST.ADDR and DST.PORT fields are
   ignored in a UDP ASSOCIATE request.  Once a UDP ASSOCIATE request has been processed, pro-
     cessed, the SOCKS server client MUST termi-
   nate terminate the connection.

   UDP DESTROY

     The COOKIE field UDP DESTROY request is used in to destroy an existing
     association within the UDP relay process.  The DST.ADDR
     and DST.PORT fields contain the com-
   putation address and port number
     of a Message Authentication Code by the UDP relay server. The SOCKS server MUST set this field process corresponding to a
   random value. The association created by the associa-
     tion to destroy.  Once a UDP ASSOCI-
   ATE ASSOCIATE request has a specific and site or implementation
   dependant lifetime. been
     processed, the SOCKS client MUST terminate the connec-
     tion.

     When a reply (REP value other than X'00') indicates a
     failure, the SOCKS server MUST terminate the TCP connec-
   tion con-
     nection shortly after sending the reply.  This must be
     no more than 10 seconds after detecting the condition
     that caused a failure.

     If the reply code (REP value of X'00') indicates a suc-
     cess, and the request was either a BIND or a CONNECT,
     the client may now start passing data.  If the selected
     authentication method supports encapsulation for the pur-
   poses
     purposes of integrity, authentication and or confidential-
   ity, and/or confiden-
     tiality, the data are encapsulated using the method-dependent method-
     dependent encapsulation.  Similarly, when data arrives
     at the SOCKS server for the client, the server MUST
     encapsulate the data as appropriate for the authentication authentica-
     tion method in use.

7.  Procedure for UDP-based clients

     A UDP-based client must MUST send its datagrams to the UDP
     relay server at the UDP port indicated by BND.PORT in
     the reply to the UDP ASSOCIATE request.  If the
     selected authentication method provides encapsulation
     for the purposes of authenticity, integrity, and/or
     confidentiality, the datagram MUST be encapsulated
     using the appropriate encapsulation.  Each UDP datagram
     carries a UDP request header with it:

   +-----+------+----------+----------+---------+----------+
   |FRAG

      +----+------+------+----------+----------+----------+
      |RSV | FRAG | ATYP | DST.ADDR | DST.PORT |   MAC   |   DATA   |
   +-----+------+----------+----------+---------+----------+
      +----+------+------+----------+----------+----------+
      | 1  |  2   |  1   | Variable |    2     | 8 to 20 | Variable |
   +-----+------+----------+----------+---------+----------+
      +----+------+------+----------+----------+----------+

     The fields in the UDP request header are:

          o  RSV  Reserved X'0000'
          o  FRAG    Current fragment number
          o  ATYP    address type of following addresses:
             o  IP V4 address: X'01'
             o  DOMAINNAME: X'03'
             o  IP V6 address: X'04'
          o  DST.ADDR       desired destination address
          o  DST.PORT       desired destination port
          o  MAC      Message Authentication Code  DATA     user data

     When a UDP relay server decides to relay a UDP datagram, data-
     gram, it does so silently, without any notification to
     the requesting client.  Similarly, it will drop datagrams data-
     grams it cannot or will not relay.  When a UDP relay
     server receives a reply datagram from a remote host, it
     MUST encapsulate that datagram using the above UDP
     request
   header. header, and any authentication-method-dependent
     encapsulation.

     The UDP relay server MUST acquire from the SOCKS server
     the expected IP address of the client that will send
     datagrams to the BND.PORT given in the reply to UDP ASSO-
   CIATE.
     ASSOCIATE.  It MUST drop any datagrams arriving from
     any source IP address other than the one recorded for
     the particular association.

   Related to each UDP association is a pair of unsigned
   32-bit counters.  These counters are used to assist in
   computing the current value of the MAC field.  The MAC
   (Message Authentication Code) field contains a message-
   digest computation of:

        o  the XCOOKIE digest
        o  the counter
        o  the ATYP
        o  the DST.ADDR (in network octet order)
        o  the DST.PORT (in network octet order)
        o  the DATA
        o  the XCOOKIE digest

   Each algorithm uses a different length of residue after
   computing the digest function. For MD5 with 8-octet
   compression, the residue is formed by taking octets
   0,2,4,6,8,10,12,14 of the digest, and concatenating them
   into an 8-octet string.  Similarly for SHA, octets
   0,2,4,6,8,10,12,14,16,18 are concatenated to form a
   10-octet string.  For algorithms that don't specify a
   compression, the complete digest is used.

   The value for the XCOOKIE digest is determined by a mes-
   sage-digest consisting of:

        o  the method-dependant authentication key material
             (if any, else 8 octets of X'AA')
        o  the COOKIE from the UDP ASSOCIATE request
        o  the method-dependant authentication key material
             (if any, else 8 octets of X'AA')

   The method-dependant authentication key material MUST be
   at least 8 octets in length.

   The sender increments its counter after sending the data-
   gram, while the receiver increments its counter after
   receipt. The receiver MUST be prepared to accept data-
   grams whose counter value is several units ahead of the
   expected value, due to datagram loss. This is typically
   implemented by the receiver looking for a MAC match by
   repeatedly incrementing its counter value, and looking
   for a match. The receiver does this until either there is
   a MAC match, or the tolerance has been exceeded The rec-
   ommended counter mismatch tolerance is 7 units.The coun-
   ters start at zero.

     The FRAG field indicates whether or not this datagram
     is one of a number of fragments.  The high-order bit indi-
   cates
     indicates end-of-fragment sequence, while a value of
     X'00' indicates that this datagram is standalone. Values  Val-
     ues between 1 and 127 indicate the fragment position
     within a fragment sequence. The implicit counter value increments
   on every fragment.  Each receiver will have a
     REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with
     these frag-
   ments. fragments.  The reassembly queue must be reinitialized reini-
     tialized and the associated fragments abandoned whenever when-
     ever the REASSEM-
   BLY REASSEMBLY TIMER expires, or a new datagram
     arrives carrying a FRAG field whose value is less than
     the highest FRAG value processed for this fragment
     sequence.  The reassem-
   bly reassembly timer MUST be no less than 5
     seconds.  It is strongly recommended that fragmentation be
     avoided by applications wherever possible.

     Implementation of fragmentation is optional; an implemen-
   tation imple-
     mentation that does not support fragmentation MUST drop
     any datagram whose FRAG field is other than X'00'.

     The UDP relay server MUST drop any datagrams for which
   the MAC value is outside of the acceptable range.
   Repeated occurrences of invalid MAC values should cause
   the UDP relay server to destroy the association.

   The programming interface for a SOCKS-aware UDP MUST
     report an available buffer space for UDP datagrams that
     is smaller than the actual space provided by the operat-
   ing oper-
     ating system:

          o  if ATYP is X'01' - 16 10+method_dependent octets smaller
          o  if ATYP is X'03' - 272 262+method_dependent octets smaller
          o  if ATYP is X'04' - 28 20+method_dependent octets smaller

     The ASSOCIATION established with a UDP ASSOCIATE
     request has a specific lifetime. It is strongly recommended that
   this lifetime be extended by  The UDP server SHOULD
     refresh the lifetime value every time a valid datagram
     arrives from the client at the UDP relay server.

8.  Security Considerations

     This document describes a protocol for the application-
     layer traversal of IP network firewalls.  The security
     of such traversal is highly dependant dependent on the particular
     authentication and encapsulation methods used provided in a par-
   ticular implementation.

   The protection for relayed UDP data when an authentica-
     particular implementation, and selected during negotia-
     tion method doesn't supply suitable keying material is
   quite weak. between SOCKS client and SOCKS server.

     Careful consideration should be given by the adminis-
     trator to the selection of authentication methods when a firewall is
   expected to relay UDP data using this protocol. methods.

9.  References

     [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Secu-
     rity Symposium

   [2] Rivest, Ron. RFC1321, "The MD5 Message-Digest Algo-
   rithm"

   [3] FIPS180-1, "Secure Hash Standard", NIST Publication

Authors Address

     Marcus Leech
     Bell-Northern Research
     P.O. Box 3511, Stn. C,
     Ottawa, ON
     CANADA K1Y 4H7

     Email: mleech@bnr.ca
     Phone: (613) 763-9145