[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 rfc1928                                     
Socks Protocol Version 5
INTERNET-DRAFT
Expires: April 24, 1995                                                M. Leech
<draft-ietf-aft-socks-protocol-v5-00.txt>                              M. Ganis
                                                                       Y. Lee
                                                                       R. Kuris
                                                                       D. Koblas
                        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. 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, 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.



Leech                                                   [Page 1]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


   There exists, also, a need for strong authentication of such
   traversal in as fine-grained a mannner 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.

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 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 a request to the server with its desired
   destination address, destination port, and authentication
   information. The SOCKS server evaluates the information, and either
   establishes the appropriate connection or denies it.

   The SOCKS request is formed as follows:


   +-----+------+-----+----------+----------+-----+-----+------/
   |  8  |  8   |  8  |    16    |   var    |  4  |  4  |  8   /
   | VER | ATYP | CMD | DST.PORT | DST.ADDR | ULN | ILN | ALEN /
   |     |      |     |          |          |     |     |      /
   +-----+------+-----+----------+----------+-----+-----+------/





Leech                                                   [Page 2]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


   /---------+-----------+----------+
   /   var   |   var     |   var    |
   / SRC.USR | SRC.IDENT | SRC.AUTH |
   /         |           |          |
   /---------+-----------+----------+


   Where:

     o VER       protocol version: X'05'

     o ATYP      address type of following address

                   IP V4 address: X'01'
                   IP V5 address: X'02'
                   DOMAINNAME: X'03'
                   IPNG address: X'04'

     o DST.ADDR      desired destination address

     o DST.PORT      desired destination port in network byte 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 authentication system

     o SRC.AUTH  authenticator as known to the authentication system


4.  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', the
   address is version-4 IP address, if  it  is  X'02',  then  the  field
   specifies  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 the
   address  field  contains a DNS-style domain name, if it is X'04' then
   the field specifies an IPNG address.

   If the ATYP field is X'01', the length of BND.ADDR  is  4  bytes,  if



Leech                                                   [Page 3]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


   X'02'  the  length  is  8 bytes. If the ATYP field is X'03', then the
   first byte of the BND.ADDR specifies the length,  in  bytes,  of  the
   rest of the field.

5.  Replies

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

   +-----+------+-----+----------+----------+
   |  8  |  8   |  8  |   16     |  var     |
   | VER | ATYP | REP | BND.PORT | BND.ADDR |
   |     |      |     |          |          |
   +-----+------+-----+----------+----------+
                   ||
                   \/
                +---------------+
                | 3  | 1 |  4   |
                | ET | R | CODE |
                |    |   |      |
                +----+---+------+

     o VER         protocol version: X'05'

     o ATYP        address type of following address

                     IP V4 address: X'01'
                     IP V5 address: X'02'
                     DOMAINNAME: X'03'
                     IPNG address: X'04'

     o BND.ADDR    server bound address

     o BND.PORT    server bound port in network byte 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



Leech                                                   [Page 4]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


                   R reply bit: always set for replies

                   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

   In a reply, the BND.ADDR and BND.PORT fields  are  the  SOCKS  server
   address  and  port  number  of  the outbound connection 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 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 connections after a
   primary connection  is  established  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 a similar fashion to CONNECT, the SOCKS server  may  use  DST.PORT
   and DST.ADDR 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 assigned in
   the  bind()  call.  The  BND.ADDR  field  contains  the associated IP
   address. The client will typicallly 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 field is meaningful.

   When a reply (CODE value other than X'0') indicates  a  failure,  the



Leech                                                   [Page 5]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


   SOCKS  server will terminate the TCP connection shortly after sending
   the reply.

   6.  Procedure for UDP-based clients

   With UDP-based clients, there is no notion of a connection,  so  each
   datagram  that  is  to  be  carried  by a SOCKS-UDP server must carry
   destination and  authentication  information  with  it.  A  UDP-based
   client  must  send  its datagrams to the SOCKS-UDP server at UDP port
   1080. Each UDP datagram carries a SOCKS request header with it:

   +-----+------+-----+----------+----------+-----+-----+------/
   |  8  |  8   |  8  |    16    |   var    |  4  |  4  |  8   /
   | VER | ATYP | CMD | DST.PORT | DST.ADDR | ULN | ILN | ALEN /
   |     |      |     |          |          |     |     |      /
   +-----+------+-----+----------+----------+-----+-----+------/

   /---------+-----------+----------+
   /   var   |   var     |   var    |
   / SRC.USR | SRC.IDENT | SRC.AUTH |
   /         |           |          |
   /---------+-----------+----------+


     Where:

     o VER       protocol version: X'05'

     o ATYP      address type of following address

                   IP V4 address: X'01'
                   IP V5 address: X'02'
                   DOMAINNAME: X'03'
                   IPNG 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



Leech                                                   [Page 6]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


     o SRC.IDENT identifier as known to the authentication system

     o SRC.AUTH  authenticator as known to the authentication system

   When a SOCKS-UDP 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
   SOCKS-UDP  server  receives  a  reply datagram from a remote host, it
   will encapsulate that  datagram  using  the  standard  SOCKS  request
   header,  and  use  the  DST.ADDR  and  DST.PORT  fields  to  give the
   originating host address and port number.  When  a  SOCKS-UDP  server
   receives  a  RELAY  request from a client, it establishes a temporary
   association between the client address/port and a port on the  SOCKS-
   UDP  server.  This  temporary  association is used to allow UDP reply
   datagrams to be correctly relayed back to the requesting UDP  client.
   The  timer  related  to this association is implementation dependant,
   but must be at least five minutes.

7.  Authentication and identification information

   The standard SOCKS request header includes  information  intended  to
   identify  the  originating  entity  of  the  corresponding connection
   request or datagram relay request. The SRC.USR 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 a person) and SRC.AUTH carries some type
   of strong proof of that identity. In this way, the SOCKS relay  agent
   may  make decisions about access controls based on a strong notion of
   the identity of the entity requesting access.

   In  one  implementation,  the  SRC.IDENT  field  carries   a   unique
   identifier  that  has  associated with it a secret key that is shared
   between the relay agent and the requesting entity. The  corresponding
   SRC.AUTH  field  contains  time-varying  information that is computed
   based on the shared secret key and  a  strong  one-way  hash  of  the
   time-varying data. In this implementation the shared secret key has a
   specific and relatively short lifetime; `out-of-band' techniques  are
   used  from  time to time to assign a new secret key. In this way, the
   secret key acts much like a session key in Kerberos.

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




Leech                                                   [Page 7]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


   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 is no weaker  than
   that provided by the FTP protocol.

8.  Encrypted connections

   The TCP SOCKS server may return a connection-success reply  with  the
   encryption-type  (ET)  field  set non-zero. If this is the case, then
   the SOCKS server expects that all data transferred on the  connection
   after  the  initial  SOCKS  connect  request  will  be encrypted in a
   mutually agreed upon key using the algorithm specified by  the  SOCKS
   server.  In  order  to  make  this  work, the server expects the data
   stream to be encapsulated into a  series  of  encrypted  payloads  as
   follows:


   +------+-------+-----+---------------------------------------------------+
   |  8   |  128  | 16  |        var                                  |     |
   | PLEN | AUTHN | SSN |       DATA                                  | PAD |
   |      |       |     |                                             |     |
   +------+-------+-----+---------------------------------------------------+

   The AUTHN field is 16-bytes long, and  is  expected  to  contain  the
   cryptographic  checksum  (message  digest) of the AUTHN, SSN and DATA
   fields prepended with the key associated with this  connection.  When
   computing this checksum, the AUTHN field is set to all X'00'. The SSN
   field is a unique sequence number for each encrypted payload, this 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 of the encryption algorithm
   in use, to determine the number  of  bytes  of  encrypted  data  that
   follow.  This  is  necessary,  since  the transport in use (TCP) is a
   stream protocol, and  does  not  preserve  I/O  boundaries  across  a
   connection.

   The receiver of an encrypted payload for  which  the  received  AUTHN
   field  fails  to  match  the computed value of AUTHN must immediately
   terminate the connection,  and  log  an  error  to  the  system  log.
   Similarly,  if  a received SSN doesn't increment the current received
   SSN, the payload is a replay, and must terminate the connection.

   Since the encryption is bidirectional, the SOCKS server uses the same
   encapsulation  technique  when  sending  encrypted  data  towards the
   client.

9.  References



Leech                                                   [Page 8]


INTERNET-DRAFT       SOCKS Protocol Version 5               October 1994


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

   [2] Leech, M., et al, "Socks Protocol Version 4" RFCXXXX

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





































Leech                                                   [Page 9]