Example 1: 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.
Unless otherwise noted, the decimal numbers appearing in packet- format diagrams
represent the length of the corresponding field, in octets. Where a given octet must
take on a specific value, the syntax X'hh' is used to denote the value of the single
octet in that field. When the word 'Variable' is used, it indicates that the
corresponding field has a variable length defined either by an associated (one or
two octet) length field, or by a data type field.
The client connects to the server, and sends a version identifier/method selection
message:
+----+----------+----------+
|VER | NMETHODS | METHODS |
+----+----------+----------+
| 1 | 1 | 1 to 255 |
+----+----------+----------+
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 METHODS, and sends a METHOD
selection message:
+----+--------+
|VER | METHOD |
+----+--------+
| 1 | 1 |
+----+--------+
If the selected METHOD is X'FF', none of the methods listed by the client are
acceptable, and the client MUST close the connection.
The values currently defined for METHOD are:
X'00' NO AUTHENTICATION REQUIRED
X'01' GSSAPI
X'02' USERNAME/PASSWORD
X'03' to X'7F' IANA ASSIGNED
X'80' to X'FE' RESERVED FOR PRIVATE METHODS
X'FF' NO ACCEPTABLE METHODS
The client and server then enter a method-specific sub-negotiation. Descriptions of
the method-dependent sub-negotiations appear in separate memos.
Developers of new METHOD support for this protocol should contact IANA for a
METHOD number. The ASSIGNED NUMBERS document should be referred to for a
current list of METHOD numbers and their corresponding protocols.
Compliant implementations MUST support GSSAPI and SHOULD support
USERNAME/PASSWORD authentication methods. Example 2: Requests
Once the method-dependent 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-
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:
VER protocol version: X'05'
CMD
CONNECT X'01'
BIND X'02'
UDP ASSOCIATE X'03'
RSV RESERVED
ATYP address type of following address
IP V4 address: X'01'
DOMAINNAME: X'03'
IP V6 address: X'04'
DST.ADDR desired destination address
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 messages, as appropriate for the request type. Example 3: 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 |
+----+-----+-------+------+----------+----------+
| 1 | 1 | X'00' | 1 | Variable | 2 |
+----+-----+-------+------+----------+----------+
Where:
VER protocol version: X'05'
REP Reply field:
X'00' succeeded
X'01' general SOCKS server failure
X'02' connection not allowed by ruleset
X'03' Network unreachable
X'04' Host unreachable
X'05' Connection refused
X'06' TTL expired
X'07' Command not supported
X'08' Address type not supported
X'09' to X'FF' unassigned
RSV RESERVED
ATYP address type of following address
IP V4 address: X'01'
DOMAINNAME: X'03'
IP V6 address: X'04'
BND.ADDR server bound address
BND.PORT server bound port in network octet order
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-
dependent encapsulation. Example 4: 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. 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:
+----+------+------+----------+----------+----------+
|RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA |
+----+------+------+----------+----------+----------+
| 2 | 1 | 1 | Variable | 2 | Variable |
+----+------+------+----------+----------+----------+
The fields in the UDP request header are:
RSV Reserved X'0000'
FRAG Current fragment number
ATYP address type of following addresses:
IP V4 address: X'01'
DOMAINNAME: X'03'
IP V6 address: X'04'
DST.ADDR desired destination address
DST.PORT desired destination port
DATA user data
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 header, and
any authentication-method-dependent encapsulation.
Implementation of fragmentation is optional; an implementation that does not support
fragmentation MUST drop any datagram whose FRAG field is other than X'00'. 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 operating
system:
if ATYP is X'01' - 10+method_dependent octets smaller
if ATYP is X'03' - 262+method_dependent octets smaller
if ATYP is X'04' - 20+method_dependent octets smaller |
Top of Page