RFC 1928

SOCKS Protocol Version 5

📅 published March 1996, from ietf

RFC 1928: SOCKS Protocol Version 5 🧦

okay bestie, this is RFC 1928, and it's called SOCKS Protocol Version 5 🎀 It's from the Network Working Group, dated March 1996, and it's on the Standards Track 🔥

the author squad is M. Leech (Bell-Northern Research Ltd), M. Ganis (International Business Machines), Y. Lee (NEC Systems Laboratory), R. Kuris (Unify Corporation), D. Koblas (Independent Consultant), and L. Jones (Hewlett-Packard Company) 👑

fyi, the header doesn't list anything it obsoletes or updates, so this one stands on its own 💅

Status of this Memo 📜

so this doc is an Internet standards track protocol for the whole Internet community 🌐 and it's literally asking for discussion and suggestions for improvements 🫶 if you want the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚 and distribution of this memo is unlimited 🦋

Acknowledgments 🙌

this memo describes a protocol that is an evolution of the previous version, version 4 [1] ✨ it came out of 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 ✨

okay so firewalls are the walls that isolate an organization's internal network structure from an exterior network, like the INTERNET 🧱 and they're getting more and more popular 📈 these firewall systems usually act as application-layer gateways between networks, typically offering controlled TELNET, FTP, and SMTP access 🔒 with fancier application layer protocols showing up to help with global information discovery, we need a general framework so those protocols can transparently and securely traverse a firewall 🧚

we also need strong authentication for that traversal, and as fine-grained as is practical 💅 why? because client-server relationships form between the networks of different organizations, and those relationships need to be controlled and often strongly authenticated 👑

this protocol gives client-server applications in both the TCP and UDP domains a framework to conveniently and securely use the services of a network firewall 🦋 it's conceptually a "shim-layer" between the application layer and the transport layer, so it does not provide network-layer gateway services, such as forwarding of ICMP messages 🙈

2. Existing practice 🍓

there's already SOCKS Version 4, which gives unsecured firewall traversal for TCP-based client-server applications, like TELNET, FTP, and the popular information-discovery protocols HTTP, WAIS and GOPHER 🌸

this new protocol extends the SOCKS Version 4 model to include UDP 🎀 it also adds provisions for generalized strong authentication schemes, and it extends the addressing scheme to cover domain-name and V6 IP addresses ✨

implementing SOCKS usually means recompiling or relinking TCP-based client applications so they use the right encapsulation routines in the SOCKS library 🧩

Note:

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. 🙈

3. Procedure for TCP-based clients 🛤️

when a TCP-based client wants to connect to an object that's only reachable through a firewall (whether that's the case 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, and 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 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 🤝 the descriptions of the method-dependent sub-negotiations live 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 🔥

4. 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 like this:

        +----+-----+-------+------+----------+----------+
        |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 then return one or more reply messages, as appropriate for the request type 🎯

5. Addressing 🏠

in an address field (DST.ADDR, BND.ADDR), the ATYP field specifies the type of address inside the field:

  • X'01': the address is a version-4 IP address, with a length of 4 octets
  • X'03': the address field contains a fully-qualified domain name. The first octet of the address field contains the number of octets of name that follow, there is no terminating NUL octet.
  • 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 like this:

        +----+-----+-------+------+----------+----------+
        |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 🛡️

CONNECT 🔌

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 🏢 it's expected that the SOCKS server will use DST.ADDR and DST.PORT, and the client-side source address and port, when evaluating the CONNECT request 👀

BIND ✨

okay so the BIND request is for protocols where the client has to accept connections that come from the server 🫶. FTP is the classic example. Its main client-to-server connection handles commands and status reports, but a server-to-client connection can be used to move data on demand (LS, GET, PUT) 📂

it's expected that the client side of an application protocol will only use BIND to set up secondary connections, and only after a primary connection has been made with CONNECT 🔗 also, a SOCKS server is expected to use DST.ADDR and DST.PORT when evaluating the BIND request 👀

during a BIND operation, the SOCKS server sends the client two replies 💌 the first one comes after the server creates and binds a new socket. BND.PORT holds the port number the SOCKS server picked to listen for an incoming connection, and BND.ADDR holds the matching IP address. the client usually passes this rendezvous address along (over the primary or control connection) to the application server, so they know where to connect 🧚 the second reply only shows up after the expected incoming connection succeeds or fails.

in that second reply, BND.PORT and BND.ADDR contain the address and port number of the connecting host 💜

UDP ASSOCIATE 🦋

the UDP ASSOCIATE request sets up an association inside the UDP relay process so it can handle UDP datagrams 📦 DST.ADDR and DST.PORT hold the address and port the client expects to send its UDP datagrams from for this association. the server MAY use this info to limit access to the association 🔐 if the client doesn't have this info at the time of the UDP ASSOCIATE, the client MUST use a port number and address of all zeros 🌸

a UDP association ends when the TCP connection that the UDP ASSOCIATE request came in on ends 💀

in the reply to a UDP ASSOCIATE request, BND.PORT and BND.ADDR show the port number and address where the client MUST send its UDP request messages to be relayed 🎀

Reply Processing 💅

when a reply (REP value other than X'00') signals a failure, the SOCKS server MUST terminate the TCP connection shortly after sending the reply. this has to happen no more than 10 seconds after the server detects the condition that caused the failure ⏱️

if the reply code (REP value of X'00') says success, and the request was either a BIND or a CONNECT, the client is good to go and can start passing data 🔥 if the selected authentication method supports encapsulation for integrity, authentication, and/or confidentiality, the data get encapsulated using that method's encapsulation. same deal in reverse: 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 given by BND.PORT in the reply to the UDP ASSOCIATE request 💖 if the selected authentication method provides encapsulation for authenticity, integrity, and/or confidentiality, the datagram MUST be encapsulated using the appropriate encapsulation. each UDP datagram comes with a UDP request header attached, and it looks like this:

+----+------+------+----------+----------+----------+
|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 the 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, with no notification to the requesting client 🤫 same vibe for datagrams it can't or won't relay: it just drops them 🗑️ when a UDP relay server gets a reply datagram from a remote host, it MUST encapsulate that datagram using the UDP request header above, plus any authentication-method-dependent encapsulation 🧁

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 ASSOCIATE. it MUST drop any datagrams arriving from any source IP address other than the one recorded for that particular association 🚫

the FRAG field tells you whether this datagram is one of several fragments. if fragmentation is implemented, the high-order bit marks the end-of-fragment sequence, and a value of X'00' means the datagram is standalone 📮 values between 1 and 127 give the fragment's position within a fragment sequence. each receiver has a REASSEMBLY QUEUE and a REASSEMBLY TIMER tied to these fragments 🧩 the reassembly queue gets reinitialized and the associated fragments get abandoned whenever the REASSEMBLY TIMER expires, or whenever a new datagram shows up with a FRAG value lower than the highest FRAG value already processed for that fragment sequence ⏳ the reassembly timer MUST be no less than 5 seconds. it is recommended that applications avoid fragmentation wherever possible, no cap 🙈

implementing fragmentation is optional, but 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 the operating system provides:

  • 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

8. Security Considerations 🔐

⚠️ this part is seriously important, bestie. this document describes a protocol for the application-layer traversal of IP network firewalls. the security of that traversal is highly dependent on the particular authentication and encapsulation methods a given implementation provides, and that get selected during negotiation between the SOCKS client and the SOCKS server. the stakes are high here!!

careful consideration should be given by the administrator to the selection of authentication methods 💀🫶

9. References 📚

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

Author's Address 💌

Marcus Leech
Bell-Northern Research Ltd
P.O. Box 3511, Stn. C,
Ottawa, ON
CANADA K1Y 4H7

Phone: (613) 763-9145
EMail: mleech@bnr.ca
📦 where this page comes from