docs/socks4.protocol

   1         SOCKS: A protocol for TCP proxy across firewalls
   2
   3                         Ying-Da Lee
   4                 Principal Member Technical Staff
   5                   NEC Systems Laboratory, CSTC
   6                         ylee@syl.dl.nec.com
   7
   8 SOCKS was originally developed by David Koblas and subsequently modified
   9 and extended by me to its current running version -- version 4. It is a
  10 protocol that relays TCP sessions at a firewall host to allow application
  11 users transparent access across the firewall. Because the protocol is
  12 independent of application protocols, it can be (and has been) used for
  13 many different services, such as telnet, ftp, finger, whois, gopher, WWW,
  14 etc. Access control can be applied at the beginning of each TCP session;
  15 thereafter the server simply relays the data between the client and the
  16 application server, incurring minimum processing overhead. Since SOCKS
  17 never has to know anything about the application protocol, it should also
  18 be easy for it to accommodate applications which use encryption to protect
  19 their traffic from nosey snoopers.
  20
  21 Two operations are defined: CONNECT and BIND.
  22
  23 1) CONNECT
  24
  25 The client connects to the SOCKS server and sends a CONNECT request when
  26 it wants to establish a connection to an application server. The client
  27 includes in the request packet the IP address and the port number of the
  28 destination host, and userid, in the following format.
  29
  30                 +----+----+----+----+----+----+----+----+----+----+....+----+
  31                 | VN | CD | DSTPORT |      DSTIP        | USERID       |NULL|
  32                 +----+----+----+----+----+----+----+----+----+----+....+----+
  33  # of bytes:       1    1      2              4           variable       1
  34
  35 VN is the SOCKS protocol version number and should be 4. CD is the
  36 SOCKS command code and should be 1 for CONNECT request. NULL is a byte
  37 of all zero bits.
  38
  39 The SOCKS server checks to see whether such a request should be granted
  40 based on any combination of source IP address, destination IP address,
  41 destination port number, the userid, and information it may obtain by
  42 consulting IDENT, cf. RFC 1413.  If the request is granted, the SOCKS
  43 server makes a connection to the specified port of the destination host.
  44 A reply packet is sent to the client when this connection is established,
  45 or when the request is rejected or the operation fails.
  46
  47                 +----+----+----+----+----+----+----+----+
  48                 | VN | CD | DSTPORT |      DSTIP        |
  49                 +----+----+----+----+----+----+----+----+
  50  # of bytes:       1    1      2              4
  51
  52 VN is the version of the reply code and should be 0. CD is the result
  53 code with one of the following values:
  54
  55         90: request granted
  56         91: request rejected or failed
  57         92: request rejected becasue SOCKS server cannot connect to
  58             identd on the client
  59         93: request rejected because the client program and identd
  60             report different user-ids
  61
  62 The remaining fields are ignored.
  63
  64 The SOCKS server closes its connection immediately after notifying
  65 the client of a failed or rejected request. For a successful request,
  66 the SOCKS server gets ready to relay traffic on both directions. This
  67 enables the client to do I/O on its connection as if it were directly
  68 connected to the application server.
  69
  70
  71 2) BIND
  72
  73 The client connects to the SOCKS server and sends a BIND request when
  74 it wants to prepare for an inbound connection from an application server.
  75 This should only happen after a primary connection to the application
  76 server has been established with a CONNECT.  Typically, this is part of
  77 the sequence of actions:
  78
  79 -bind(): obtain a socket
  80 -getsockname(): get the IP address and port number of the socket
  81 -listen(): ready to accept call from the application server
  82 -use the primary connection to inform the application server of
  83  the IP address and the port number that it should connect to.
  84 -accept(): accept a connection from the application server
  85
  86 The purpose of SOCKS BIND operation is to support such a sequence
  87 but using a socket on the SOCKS server rather than on the client.
  88
  89 The client includes in the request packet the IP address of the
  90 application server, the destination port used in the primary connection,
  91 and the userid.
  92
  93                 +----+----+----+----+----+----+----+----+----+----+....+----+
  94                 | VN | CD | DSTPORT |      DSTIP        | USERID       |NULL|
  95                 +----+----+----+----+----+----+----+----+----+----+....+----+
  96  # of bytes:       1    1      2              4           variable       1
  97
  98 VN is again 4 for the SOCKS protocol version number. CD must be 2 to
  99 indicate BIND request.
 100
 101 The SOCKS server uses the client information to decide whether the
 102 request is to be granted. The reply it sends back to the client has
 103 the same format as the reply for CONNECT request, i.e.,
 104
 105                 +----+----+----+----+----+----+----+----+
 106                 | VN | CD | DSTPORT |      DSTIP        |
 107                 +----+----+----+----+----+----+----+----+
 108  # of bytes:       1    1      2              4
 109
 110 VN is the version of the reply code and should be 0. CD is the result
 111 code with one of the following values:
 112
 113         90: request granted
 114         91: request rejected or failed
 115         92: request rejected becasue SOCKS server cannot connect to
 116             identd on the client
 117         93: request rejected because the client program and identd
 118             report different user-ids.
 119
 120 However, for a granted request (CD is 90), the DSTPORT and DSTIP fields
 121 are meaningful.  In that case, the SOCKS server obtains a socket to wait
 122 for an incoming connection and sends the port number and the IP address
 123 of that socket to the client in DSTPORT and DSTIP, respectively. If the
 124 DSTIP in the reply is 0 (the value of constant INADDR_ANY), then the
 125 client should replace it by the IP address of the SOCKS server to which
 126 the cleint is connected. (This happens if the SOCKS server is not a
 127 multi-homed host.)  In the typical scenario, these two numbers are
 128 made available to the application client prgram via the result of the
 129 subsequent getsockname() call.  The application protocol must provide a
 130 way for these two pieces of information to be sent from the client to
 131 the application server so that it can initiate the connection, which
 132 connects it to the SOCKS server rather than directly to the application
 133 client as it normally would.
 134
 135 The SOCKS server sends a second reply packet to the client when the
 136 anticipated connection from the application server is established.
 137 The SOCKS server checks the IP address of the originating host against
 138 the value of DSTIP specified in the client's BIND request.  If a mismatch
 139 is found, the CD field in the second reply is set to 91 and the SOCKS
 140 server closes both connections.  If the two match, CD in the second
 141 reply is set to 90 and the SOCKS server gets ready to relay the traffic
 142 on its two connections. From then on the client does I/O on its connection
 143 to the SOCKS server as if it were directly connected to the application
 144 server.
 145
 146
 147
 148 For both CONNECT and BIND operations, the server sets a time limit
 149 (2 minutes in current CSTC implementation) for the establishment of its
 150 connection with the application server. If the connection is still not
 151 establiched when the time limit expires, the server closes its connection
 152 to the client and gives up.