What is a SOCKS5 proxy?
Definition
A proxy protocol, defined in RFC 1928, that relays any TCP stream and optionally UDP without reading it. socks5h sends the hostname to the proxy.
SOCKS5 works below HTTP. The client tells the proxy one thing, where to connect, in a handful of bytes, and from then on the proxy copies data in both directions. It has no idea whether that data is HTTPS, SSH or a database protocol. That is also why a SOCKS5 proxy cannot add Via or X-Forwarded-For, cannot cache, and cannot filter by URL: it relays bytes and never parses a header.
The handshake, byte by byte
RFC 1928 defines two steps. First the client sends a greeting listing the authentication methods it supports, and the server picks one: 00 for none, 01 for GSSAPI, 02 for username and password (defined separately in RFC 1929), or FF if nothing on the list is acceptable. Then the client sends the request below.
| Field | Bytes | Meaning | Sent with socks5:// | Sent with socks5h:// |
|---|---|---|---|---|
| VER | 1 | Protocol version, always 05 |
05 |
05 |
| CMD | 1 | 01 CONNECT, 02 BIND, 03 UDP ASSOCIATE |
01 |
01 |
| RSV | 1 | Reserved, 00 |
00 |
00 |
| ATYP | 1 | Address type: 01 IPv4, 03 domain name, 04 IPv6 |
01 |
03 |
| DST.ADDR | 4, 16, or 1 + name length | Where to connect | 68 14 17 9a (104.20.23.154) |
0b then the 11 bytes of example.com |
| DST.PORT | 2 | Port in network byte order | 01 bb (443) |
01 bb (443) |
The two right-hand columns are not illustrations. We captured them with a 40-line Python SOCKS5 server on localhost that prints every byte it receives, and pointed curl 8.7.1 on macOS at it twice:
$ curl -s -o /dev/null -x socks5://127.0.0.1:38517 https://example.com/
greeting: 05 02 00 01
request: 05 01 00 01 68 14 17 9a 01 bb -> 104.20.23.154 443
$ curl -s -o /dev/null -x socks5h://127.0.0.1:38517 https://example.com/
greeting: 05 02 00 01
request: 05 01 00 03 0b 65 78 61 6d 70 6c 65 2e 63 6f 6d 01 bb -> example.com 443
The greeting is a small surprise. Without credentials, curl offered two methods, 00 and 01, so this build advertises GSSAPI by default. With user:pass in the proxy URL the greeting became 05 03 00 01 02, adding the RFC 1929 method.
socks5 versus socks5h
Look at ATYP and DST.ADDR again. With socks5://, curl resolved example.com on the client and sent four bytes of IPv4. With socks5h:// it sent the name and left resolution to the proxy. Nothing else in the exchange differs, and the consequences are bigger than one byte suggests:
- Your local resolver sees every hostname you request, which is a DNS leak on any setup meant to hide them.
- You resolve from your own location. Sites that answer DNS per region can hand you an address that does not match the proxy’s country.
- A gateway that routes by hostname never gets one.
Python’s requests library follows curl’s convention. Its documentation says the socks5 scheme resolves DNS on the client and socks5h on the proxy server. Write the h unless you have a reason not to.
Reading a SOCKS5 failure
The server answers the request with a reply code, and curl prints it in brackets. We made the lab server refuse one hostname with code 02, which RFC 1928 defines as “connection not allowed by ruleset”, and asked for it both ways:
$ curl -sS -o /dev/null -x socks5h://127.0.0.1:38529 https://blocked.invalid/
curl: (97) Can't complete SOCKS5 connection to blocked.invalid. (2)
$ curl -sS -o /dev/null -x socks5://127.0.0.1:38529 https://blocked.invalid/
curl: (97) Could not resolve host: blocked.invalid
Same exit code, different failures. The first reached the proxy and was refused there; the number at the end is the reply code. The second never sent a request at all. The server logged only a greeting, because curl tried to resolve the name locally and gave up. A hostname that only the proxy side can resolve will always fail that way without the h.
SOCKS5 or an HTTP proxy
For HTTPS scraping the difference is smaller than people expect. An HTTP proxy tunnels HTTPS with CONNECT, so in both cases the TLS handshake runs end to end between your client and the site, and the proxy relays ciphertext. SOCKS5 earns its place elsewhere: non-HTTP protocols such as SSH or IMAP, and UDP through UDP ASSOCIATE where the server implements it, which is worth confirming before you build on it.
Neither protocol encrypts anything on its own. RFC 1929 is blunt about its own weakness: the request carries the password in cleartext, so it is not recommended where sniffing is practical. Over the public internet, that means your proxy password crosses the wire readable unless something else wraps the connection.
Setup differs by client. The curl guide covers the schemes and the socks5h trap with working commands, proxies in Python covers the extra dependency requests needs for SOCKS, and proxies in Node.js covers the agents that add SOCKS support there. For where SOCKS sits among proxy types generally, see what is a proxy server?
Frequently asked questions
Is SOCKS5 more anonymous than an HTTP proxy?
Does SOCKS5 encrypt my traffic?
What does SOCKS5 add over SOCKS4?
Does SOCKS5 support UDP?
Sources
Also covered in
- SOCKS4 vs SOCKS5: Differences Tested on the Wire
- HTTP proxies and SOCKS5 proxiesin What is a proxy server and how does it work?