Socks Protocol Version 5
Expires: April 24, 1995 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. 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 LaMont
   Jones: Hewlett-Packard, 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 mannner 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 header to include provisions for generalized strong
   authentication schemes, and extends the addressing scheme to
   encompass domain-name and extended 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 sends enters a request to negotiation for the server with its desired
   destination address, destination port, and authentication
   method to be used, authenticates with the chosen method, then sends a
   relay request. The SOCKS server evaluates the information, request, and either
   establishes the appropriate connection or denies it.

   The SOCKS request is formed as follows:

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

              |VER |  8 NMETHODS |  8 METHODS  |  8 MACS |    16
              |   var 1  |  4    1     |  4 1 to 255 |  8   /  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 | ATYP | CMD | DST.PORT | DST.ADDR | ULN METHOD | ILN MACSEL | ALEN /
                    | 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
   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 |      /
   /   var DST.ADDR |   var DST.PORT |   var
   / SRC.USR 1  | SRC.IDENT  1  | SRC.AUTH 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'
                   IP V5 address: X'02'
           o  DOMAINNAME: X'03'
           o  IP V6 address: X'04'
        o  DST.ADDR       desired destination address
        o  DST.PORT       desired destination port in network byte octet order

     o CMD       command: CONNECT X'01' BIND X'02'

     o ULN       length of SRC.USR field in bytes: 4 bits

     o ILN       length of SRC.IDENT field in bytes: 4 bits

     o ALEN      length of SRC.AUTH field in bytes: 8 bits

     o SRC.USR   username as known to the client-side operating system

     o SRC.IDENT identifier as known to

   The SOCKS server will evaluate the authentication system

     o SRC.AUTH  authenticator request based on
   source and destination addresses, and return one or more
   reply packets, as known to appropriate for the authentication system

4. request type.

5.  Addressing

   In an address field (DST.ADDR, BND.ADDR), the ATYP field
   specifies the type of address contained within the field. If ATYP is X'01', field:

        o  X'01'

   the address is a version-4 IP address, if  it  is  X'02',  then  the  field
   specifies with a  version-5 IP address (that is, IP protocol version 4/5,
   not SOCKS protocol version 4/5). If the ATYP field is X'03', then length of 4

        o  X'03'

   the address field contains a DNS-style domain name, if it is X'04' then
   the field specifies an IPNG address.

   If name. The
   first octet of the ATYP address field is X'01', contains the length of BND.ADDR  is  4  bytes,  if
   the  length  is  8 bytes. If domain name.

        o  X'04'

   the ATYP field address is X'03', then the
   first byte of the BND.ADDR specifies the length,  in  bytes,  of  the
   rest a version-6 IP address, with a length of the field.

   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.
   server, and completed the authentication negotiations.
   The server evaluates the request, and returns a reply
   formed as follows:

   |  8  |  8   |  8  |   16     |  var

   |VER | REP | VER  RSV  | ATYP | REP | BND.PORT | BND.ADDR | BND.PORT | COOKIE |      |     |          |          |
                | 3
   | 1  |  4   |
                | ET | R  1  | CODE 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
           o  X'07' to X'FF' unassigned
        o  RSV    RESERVED
        o  ATYP   address type of following address
           o  IP V4 address: X'01'
                     IP V5 address: X'02'
           o  DOMAINNAME: X'03'
           o  IP V6 address: X'04'
        o  BND.ADDR       server bound address
        o  BND.PORT       server bound port in network byte octet order
        o REP         Reply field:

     The reply field is broken up into a 3 subfields:

                   ET encryption type: 3 bits

                     X'0' unencrypted
                     X'1' DES
                     X'2' IDEA
                     X'3' PRIVATE_1
                     X'4' PRIVATE_2
                     X'5' PRIVATE_3
                   R reply bit: always  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

                   CODE reason code 4 bits:

                     X'0' succeeded
                     X'1' general failure
                     X'2' bad/unknown identifier
                     X'3' connection not allowed by ruleset
                     X'4' authentication failure
                     X'5' identifier explicitly blocked 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 connection con-
   nection for a CONNECT request, and contain the SOCKS
   server bind() address for a BIND request.  If  a  reply  contains  a  non-zero ET subfield, the server
   expects that there will be a bi-directional encryption  of  user-data
   on  this  connection  using  the  encryption type specified in the ET
   subfield. It is expected that the  server  and  client  have  already
   negotiated  the  appropriate  key  in an `out-of-band' process. It is
   typically the case that the same key that is used for  authentication
   is used for encryption.

   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 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 secondary sec-
   ondary connections after a primary connection is  established estab-
   lished using CONNECT.  Usually,  then,
   DST.PORT  and  DST.ADDR in a BIND request header would be the same as
   those used in the primary connection, though this is not required.  In is expected that a similar fashion to CONNECT, the SOCKS server  may
   will use  DST.PORT
   and 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 assigned in that the  bind()  call. SOCKS server assigned
   to listen for an incoming connection. The BND.ADDR field
   contains the associated IP address. The client will typicallly 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, only the REP BND.PORT and BND.ADDR
   fields contain the address and port number of the
   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 meaningful. 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 (CODE (REP value other than X'0') X'00') indicates a
   failure, the SOCKS server will MUST terminate the TCP connection connec-
   tion shortly after sending the reply.

   6.  Procedure for UDP-based clients

   With UDP-based clients, there is  This must be no notion of a connection,  so  each
   more than 10 seconds after detecting the condition that  is  to  be  carried  by
   caused a SOCKS-UDP server must carry
   destination 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  information  with  it. 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 SOCKS-UDP UDP
   relay server at the UDP port
   1080. indicated by BND.PORT in the
   reply to the UDP ASSOCIATE request. Each UDP datagram
   carries a SOCKS UDP request header with it:

   |  8  |  8   |  8  |    16    |   var    |  4  |  4  |  8   /
   | VER

   |     |      |     |          |          |     | DST.PORT |      /

   /   var   MAC   |   var   DATA   |   var
   / SRC.USR 1   | SRC.IDENT  1   | SRC.AUTH Variable |
   /    2     | 8 to 20 | Variable |


   The fields in the UDP request header are:

        o VER       protocol version: X'05'  FRAG     Current fragment number
        o  ATYP     address type of following address addresses:
           o  IP V4 address: X'01'
                   IP V5 address: X'02'
           o  DOMAINNAME: X'03'
           o  IP V6 address: X'04'
        o  DST.ADDR desired destination address
        o  DST.PORT desired destination port in network byte order

     o CMD       command: RELAY X'03'

     o ULN       length of SRC.USR field in bytes: 4 bits

     o ILN       length of SRC.IDENT field in bytes: 4 bits

     o ALEN      length of SRC.AUTH field in bytes: 8 bits

     o SRC.USR   username as known to the client-side operating system
     o SRC.IDENT identifier as known to the authentication system
        o SRC.AUTH  authenticator as known to the authentication system  MAC      Message Authentication Code

   When a SOCKS-UDP UDP relay server decides to RELAY 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. relay. When a
   SOCKS-UDP UDP relay server
   receives a reply datagram from a remote host, it
   will MUST
   encapsulate that datagram using the  standard  SOCKS above UDP request
   header,  and  use

   The UDP relay server MUST acquire from the  DST.ADDR  and  DST.PORT  fields  to  give SOCKS server
   originating host expected IP address and port number.  When  a  SOCKS-UDP  server
   receives  a  RELAY  request from a client, it establishes a temporary
   association between of the client address/port and a port on the  SOCKS-
   UDP  server.  This  temporary  association is used to allow UDP reply that will send
   datagrams to be correctly relayed back to the requesting BND.PORT given in the reply to UDP  client.
   The  timer  related ASSO-
   CIATE. It MUST drop any datagrams arriving from any
   source IP address other than the one recorded for the
   particular association.

   Related to this each UDP association is implementation dependant,
   but must be at least five minutes.

7.  Authentication and identification information

   The standard SOCKS request header includes  information  intended a pair of unsigned
   32-bit counters.  These counters are used to
   identify assist in
   computing the  originating  entity current value of the  corresponding connection
   request or datagram relay request. MAC field.  The SRC.USR MAC
   (Message Authentication Code) field is intended as a
   low-to-medium confidence mechanism for a SOCKS relay agent to provide
   usage  auditing  information  only,  and  not  as  an  authentication
   mechanism.  The  SRC.IDENT  and  SRC.AUTH  fields  are  used to carry
   information that a SOCKS relay agent (server) may use to control  and
   authenticate  access  to  its  relay  services.The fundamental notion
   being that SRC.IDENT carries a  unique  identity  associated  with  a
   requesting entity (typically contains a person) and SRC.AUTH carries some type
   of strong proof of that identity. In this way, message-
   digest computation of:

        o  the SOCKS relay  agent
   may  make decisions about access controls based on a strong notion of XCOOKIE digest
        o  the identity of counter
        o  the entity requesting access.

   In  one  implementation, ATYP
        o  the  SRC.IDENT  field  carries   a   unique
   identifier  that  has  associated with it a secret key that is shared
   between DST.ADDR (in network octet order)
        o  the relay agent and DST.PORT (in network octet order)
        o  the requesting entity. The  corresponding
   SRC.AUTH  field  contains  time-varying  information that is computed
   based on DATA
        o  the shared secret key and XCOOKIE digest

   Each algorithm uses a  strong  one-way  hash different length of residue after
   computing the
   time-varying data. In this implementation digest function. For MD5 with 8-octet
   compression, the shared secret key has a
   specific residue is formed by taking octets
   0,2,4,6,8,10,12,14 of the digest, and relatively short lifetime; `out-of-band' techniques concatenating them
   into an 8-octet string.  Similarly for SHA, octets
   0,2,4,6,8,10,12,14,16,18 are
   used  from  time to time concatenated to assign form a new secret key. In this way, the
   secret key acts much like
   10-octet string.  For algorithms that don't specify a session key in Kerberos.

   Another implementation may choose to use
   compression, the SRC.IDENT  and  SRC.AUTH
   fields   to  carry  information  produced  by  so-called  smart  card
   technology to authenticate access.

   Another implementation may  choose  to  carry  the  operating  system
   username  in  SRC.IDENT  and  the  corresponding  access  password in
   SRC.AUTH. In this way, the authentication provided complete digest is no weaker  than
   that provided by the FTP protocol.

8.  Encrypted connections used.

   The TCP SOCKS server may return a connection-success reply  with value for the
   encryption-type  (ET)  field  set non-zero. If this XCOOKIE digest is determined by a mes-
   sage-digest consisting of:

        o  the case, then
   the SOCKS server expects that all data transferred on method-dependant authentication key material
             (if any, else 8 octets of X'AA')
        o  the  connection
   after COOKIE from the  initial  SOCKS  connect UDP ASSOCIATE request  will
        o  the method-dependant authentication key material
             (if any, else 8 octets of X'AA')

   The method-dependant authentication key material MUST be encrypted
   at least 8 octets in a
   mutually agreed upon key using the algorithm specified by  the  SOCKS
   server.  In  order  to  make  this  work, length.

   The sender increments its counter after sending the server expects data-
   gram, while the data
   stream to be encapsulated into a  series  of  encrypted  payloads  as

   |  8   |  128  | 16  |        var                                  |     |
   | PLEN | AUTHN | SSN |       DATA                                  | PAD |
   |      |       |     |                                             |     |
   +------+-------+-----+---------------------------------------------------+ receiver increments its counter after
   receipt. The AUTHN field is 16-bytes long, and receiver MUST be prepared to accept data-
   grams whose counter value is several units ahead of the
   expected value, due to  contain  the
   cryptographic  checksum  (message  digest) of datagram loss. This is typically
   implemented by the AUTHN, SSN receiver looking for a MAC match by
   repeatedly incrementing its counter value, and DATA
   fields prepended with the key associated with this  connection.  When
   computing looking
   for a match. The receiver does this checksum, the AUTHN field until either there is set to all X'00'.
   a MAC match, or the tolerance has been exceeded The SSN rec-
   ommended counter mismatch tolerance is 7 units.The coun-
   ters start at zero.

   The FRAG field is a unique sequence number for each encrypted payload, indicates whether or not this datagram is
   an unsigned 16-bit value transmitted in network byte order.

   The receiver of an  encrypted  payload  shall  use  the  PLEN  field,
   appropriately  rounded  for the blocksize
   one of the encryption algorithm
   in use, to determine the a number of  bytes fragments. The high-order bit indi-
   cates end-of-fragment sequence, while a value of  encrypted  data X'00'
   indicates that
   follow.  This this datagram is  necessary,  since standalone. Values
   between 1 and 127 indicate the transport in use (TCP) is fragment position within a
   stream protocol,
   fragment sequence. The implicit counter value increments
   on every fragment. Each receiver will have a REASSEMBLY
   QUEUE and  does  not  preserve  I/O  boundaries  across a
   connection. REASSEMBLY TIMER associated with these frag-
   ments.  The receiver 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.

   Implementation of fragmentation is optional; an encrypted payload 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  received  AUTHN
   field  fails  to  match  the computed MAC value is outside of AUTHN must immediately
   terminate the connection,  and  log  an  error acceptable range.
   Repeated occurrences of invalid MAC values should cause
   the UDP relay server to destroy the  system  log.
   Similarly,  if association.

   The programming interface for a received SSN doesn't increment SOCKS-aware UDP MUST
   report an available buffer space for UDP datagrams that
   is smaller than the current received
   SSN, actual space provided by the payload 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 replay, and must terminate UDP ASSOCIATE request
   has a specific lifetime. It is strongly recommended that
   this lifetime be extended by the connection.

   Since lifetime value every
   time a valid datagram arrives from the encryption is bidirectional, client at the SOCKS server uses UDP
   relay server.

8.  Security Considerations

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

   The protection for relayed UDP data when  sending  encrypted 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  towards the
   client. using this protocol.

9.  References

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

   [2] Leech, M., et al, "Socks Protocol Version 4" RFCXXXX Rivest, Ron. RFC1321, "The MD5 Message-Digest Algo-

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

Authors Address

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

   Phone: (613) 763-9145