Skip to content
Glossary

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.

Read the full guideHow to use curl with a proxy: flags, socks5h and errorscurl -x syntax for HTTP and SOCKS5 proxies, plus 15 proxy failures with the exact error curl 8.7.1 and 8.23.0 printed for…

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?
It is quieter by construction, because it never sees HTTP headers and so cannot add ones that identify you or the proxy. It is not anonymous in itself: the site still sees whatever your client sends, and the proxy operator still sees where you connect.
Does SOCKS5 encrypt my traffic?
No. The protocol has no encryption, and with RFC 1929 authentication the password itself crosses the network in cleartext. Encryption comes from TLS inside the tunnel, for example HTTPS to the site.
What does SOCKS5 add over SOCKS4?
RFC 1928 lists three things: UDP support, a framework for stronger authentication methods, and addressing by domain name and IPv6 as well as IPv4. The domain-name address type is what makes socks5h possible.
Does SOCKS5 support UDP?
The protocol does, through the UDP ASSOCIATE command, CMD 03 in RFC 1928. Whether a particular server implements it is a separate question, so confirm with the provider before you build on it, for example for QUIC or DNS over UDP.

Sources

  1. RFC 1928: SOCKS Protocol Version 5
  2. RFC 1929: Username/Password Authentication for SOCKS V5
  3. Requests documentation: SOCKS proxies, socks5 versus socks5h
  4. curl manual: the socks5 and socks5h proxy schemes

Also covered in

All terms, A to Z