Socks Protocol Version 5
Expires: In Six Months                                                 M. Leech
<draft-ietf-aft-socks-protocol-v5-01.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 (US East Coast),
   (Europe), (US West Coast), or (Pacific


   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

Leech et al.                                            [Page 1]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

   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

   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.

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 protocol extends the SOCKS Version 4 model to include UDP, and
   extends the protocol 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:

Leech et al.                                            [Page 2]

INTERNET-DRAFT         SOCKS Protocol Version 5               March 1995

              |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

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

                    |VER | METHOD | MACSEL |
                    | 1  |   1    |   1    |

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

   The values currently defined for METHOD are:

        o  X'01' BNR-1
        o  X'02' GSSAPI
        o  X'03' IKMP
        o  X'04' KERBEROS4
        o  X'05' KERBEROS5
        o  X'06' USERNAME/PASSWORD
        o  X'09' S/KEY
        o  X'0A' to X'FE' RESERVED

   The client and server then enter a method-specific subne-

   Descriptions of the method-dependant subnegotiations
   appear in separate drafts.

   The MACS field contains a bit-vector indicating the MAC

Leech et al.                                            [Page 3]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

   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 of 160 bits)

   The MACSEL field indicates which MAC algorithm that the
   server wishes the client to use during computation of the
   MAC field for UDP relay requests. A compliant implementa-
   tion MUST support both compressed and uncompressed MD5.

4.  Requests

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

   The SOCKS request is formed as follows:

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


        o  VER    protocol version: X'05'
        o  CMD
           o  CONNECT X'01'
           o  BIND X'02'
           o  UDP ASSOCIATE X'03'
        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 evaluate the request based on
   source and destination addresses, and return one or more
   reply packets, as appropriate for the request type.

Leech et al.                                            [Page 4]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

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

        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:

   | 1  |  1  | X'00' |  1   | Variable |    2     |   8    |


        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

Leech et al.                                            [Page 5]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

           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
   of authentication, integrity and or confidentiality, the
   replies are encapsulated in the method-dependant encapsu-

   In a reply, the BND.ADDR and BND.PORT fields are the
   SOCKS server address and port number of the outbound con-
   nection for a CONNECT request, and contain the SOCKS
   server bind() address for a BIND request.

   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 connections after a primary connection is estab-
   lished using CONNECT.  In is expected that a SOCKS server
   will use DST.ADDR and DST.PORT in evaluating the BIND

   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 use these pieces of information to notify (via the
   primary or control connection) the application server of
   the `rendezvous point'. 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

Leech et al.                                            [Page 6]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

   connecting host.

   In the reply to a CONNECT, BND.PORT contains the port
   number that the server assigned to connect to the target
   host, while BND.ADDR 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.

   The UDP ASSOCIATE request is used to establish an associ-
   ation within the UDP relay process to handle UDP data-
   grams.  In the reply to a UDP ASSOCIATE request, the
   BND.PORT and BND.ADDR fields indicate the port num-
   ber/address where the client may send UDP request packets
   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, the SOCKS server MUST termi-
   nate the connection. The COOKIE field is used in the com-
   putation of a Message Authentication Code by the UDP
   relay server. The SOCKS server MUST set this field to a
   random value. The association created by the UDP ASSOCI-
   ATE request has a specific and site or implementation
   dependant lifetime.

   When a reply (REP value other than X'00') indicates a
   failure, the SOCKS server MUST terminate the TCP connec-
   tion 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 of integrity, authentication and or confidential-
   ity, the data are encapsulated using the 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 method in use.

7.  Procedure for UDP-based clients

   A UDP-based client 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. Each UDP datagram
   carries a UDP request header with it:

Leech et al.                                            [Page 7]

INTERNET-DRAFT          SOCKS Protocol Version 5              March 1995

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

   The fields in the UDP request header are:

        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

   When a UDP relay server decides to relay a UDP datagram,
   it does so silently, without any notification to the
   requesting client. Similarly, it will drop datagrams 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

   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. 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

Leech et al.                                            [Page 8]

INTERNET-DRAFT     SOCKS Protocol Version 5                   March 1995

   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 end-of-fragment sequence, while a value of X'00'
   indicates that this datagram is standalone. Values
   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.  The reassembly queue must be reinitialized and
   the associated fragments abandoned whenever the REASSEM-
   BLY 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 timer MUST be no less than 5 seconds. It is strongly
   recommended that fragmentation be avoided by applications
   wherever possible.

Leech et al.                                            [Page 9]

INTERNET-DRAFT     SOCKS Protocol Version 5                   March 1995

   Implementation of fragmentation is optional; an implemen-
   tation 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 system:

        o  if ATYP is X'01' - 16 octets smaller
        o  if ATYP is X'03' - 272 octets smaller
        o  if ATYP is X'04' - 28 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 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 on the particular
   authentication and encapsulation methods used in a par-
   ticular implementation.

   The protection for relayed UDP data when an authentica-
   tion method doesn't supply suitable keying material is
   quite weak.  Careful consideration should be given to
   selection of authentication methods when a firewall is
   expected to relay UDP data using this protocol.

9.  References

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

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

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

Leech et al.                                           [Page 10]

INTERNET-DRAFT     SOCKS Protocol Version 5                   March 1995

Authors Address

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

   Phone: (613) 763-9145

Leech et al.                                           [Page 11]