Socks Protocol Version 5
INTERNET-DRAFT
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 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 [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
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 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
field.
The server selects from one of the methods given in METH-
ODS, and a MAC algorithm, then sends a selection indica-
tor:
+----+--------+--------+
|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'00' NO AUTHENTICATION REQUIRED
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'07' SECURE TOKEN TYPE 1 (NO CHALLENGE/RESPONSE)
o X'08' SECURE TOKEN TYPE 2 (CHALLENGE/RESPONSE)
o X'09' S/KEY
o X'0A' to X'FE' RESERVED
o X'FF' NO ACCEPTABLE METHODS
The client and server then enter a method-specific subne-
gotiation.
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 |
+----+-----+-------+------+----------+----------+
Where:
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
octets
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:
+----+-----+-------+------+----------+----------+--------+
|VER | REP | RSV | ATYP | BND.ADDR | BND.PORT | COOKIE |
+----+-----+-------+------+----------+----------+--------+
| 1 | 1 | X'00' | 1 | Variable | 2 | 8 |
+----+-----+-------+------+----------+----------+--------+
Where:
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-
lation.
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
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 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
header.
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-
rithm"
[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
CANADA K1Y 4H7
Email: mleech@bnr.ca
Phone: (613) 763-9145
Leech et al. [Page 11]
