HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:47:23 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Tue, 21 Mar 1995 23:00:00 GMT ETag: "2e9cc6-5461-2f6f5a70" Accept-Ranges: bytes Content-Length: 21601 Connection: close Content-Type: text/plain Socks Protocol Version 5 INTERNET-DRAFT Expires: In Six Months M. Leech 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]