SOCKS5 Proxy Implementation Guide

Reviewed September 2026 against the SOCKS5 protocol specification.

What SOCKS5 provides

SOCKS5 is a general proxy protocol defined by RFC 1928. It can relay TCP connections and supports UDP through the UDP ASSOCIATE command. A client can send an IPv4 address, IPv6 address, or domain name in a request.

The protocol negotiates an authentication method, but SOCKS5 does not itself encrypt application data. Use TLS or another end-to-end secure protocol where confidentiality or server authentication is required.

Know the request address types

In a SOCKS5 request, the client names an IPv4 address, an IPv6 address, or a domain name, followed by a port. Sending a domain name lets the proxy resolve the name. Sending an address means the client resolved it first. This is a configuration and policy decision, not a cosmetic URL difference. It affects which resolver sees the lookup, whether split DNS works, and whether a local DNS leak is possible.

Library names vary. For example, a command-line client may distinguish a SOCKS option that resolves hostnames remotely from one that does not. Read the library's documentation and verify with a hostname under your control rather than relying on an option name.

Authentication does not encrypt the route

SOCKS5 negotiates an authentication method before a request. Username/password authentication is defined separately in RFC 1929 and is sent within the SOCKS connection. Do not treat it as transport encryption. Use TLS to the destination, restrict who can reach the proxy, and use a protected secret-delivery mechanism for the credential.

A server should reject unsupported methods, invalid credentials, disallowed destinations, private ranges, and methods it does not offer. A client should distinguish these policy outcomes from a timeout so it does not repeat an invalid login. Test credential rotation by revoking a test credential and confirming that existing and new connections behave as the documented service says.

Connection flow

1. The client connects to the proxy and offers supported authentication methods.
2. The server selects a method or rejects the connection.
3. After authentication, the client sends CONNECT, BIND, or UDP ASSOCIATE with an address and port.
4. The server returns a reply code and bound address.
5. The client exchanges application traffic and closes resources explicitly.

DNS behavior

If the client sends a domain name, the proxy resolves it. If the client resolves first and sends an IP address, DNS occurs locally. This choice affects split DNS, policy, and which network observes the lookup. Test the library rather than inferring behavior from a URL scheme.

Configure a client safely

Use a proxy endpoint only from a secrets store or protected runtime configuration. Keep connect, authentication, read, and whole-operation deadlines separate where the client supports them. Enforce destination allowlists in the application as well as on a proxy you operate. A SOCKS proxy is capable of relaying arbitrary TCP, so an unrestricted server can become an internal-network pivot.

curl --socks5-hostname "$SOCKS_PROXY" \
  --connect-timeout 5 --max-time 20 \
  https://proxy-test.example/exit

Run this pattern only against a test endpoint you control. Check that the returned request ID is correct, TLS certificate validation remains enabled, the expected exit is observed, and proxy credentials never appear in process listings or logs. Prefer configuration mechanisms that do not put passwords in command history.

Test DNS and traffic leaks

Use a test domain whose authoritative logs you can inspect and a web endpoint that records the connecting address. First make a request using the client's remote-hostname mode. Confirm that the test endpoint sees the proxy exit and that the resolver behavior matches the configured proxy path. Then repeat with a pre-resolved address to show the difference. Include IPv6 where the application can use it, because an IPv4-only test does not prove IPv6 traffic follows the proxy.

Also test a direct connection control, proxy-unavailable behavior, redirects, and certificate failures. The client should fail closed for a workflow that requires the proxy rather than falling back to a direct route without an explicit policy. Keep this test traffic on systems you control.

UDP, BIND, and protocol limits

RFC 1928 defines CONNECT, BIND, and UDP ASSOCIATE. Client and provider support varies, so do not assume that a SOCKS5 endpoint supports UDP or inbound BIND merely because it accepts TCP CONNECT. UDP association has its own encapsulation and lifetime behavior, and application protocols may still need encryption and authentication. Test the actual method, address family, and timeout under controlled conditions before relying on it.

Authentication and secrets

RFC 1928 defines method negotiation; username/password is specified separately and does not provide transport encryption. Store credentials as secrets, use one credential per workload, restrict source networks, and never include passwords in logs, screenshots, or committed URLs.

Client checklist

• Validate host, port, address type, and reply codes.
• Set finite connect, authentication, read, and overall deadlines.
• Close sockets on every error path.
• Retry only transient failures with a bounded attempt count.
• Verify whether the library supports IPv6 and UDP if required.
• Keep authenticated multi-step work on a controlled session.

Server checklist

• Bind only to intended interfaces and default deny clients.
• Restrict destinations, ports, methods, and internal network access.
• Prevent access to metadata services and control-plane endpoints.
• Log authentication outcome, policy result, coarse destination, bytes, and latency without payloads or secrets.
• Patch the proxy and operating system and review configuration drift.

Verification

Test supported and rejected authentication, IPv4, IPv6, domain requests, denied destinations, timeout handling, DNS location, TLS to the destination, credential revocation, and log redaction. Use a service you control for the test.

For a managed offering, see datacenter proxy plans. An implementation is secure only when its network exposure, credentials, destinations, and application encryption are all explicit.

Verification procedure

1. Start with a proxy and HTTPS test service you control on an isolated network.
2. Test no acceptable authentication method, valid authentication, invalid authentication, and credential revocation.
3. Test domain, IPv4, and IPv6 request forms; record where DNS resolution occurs.
4. Test allowed and denied destinations, ports, and private-address ranges.
5. Force connection and read timeouts, then confirm sockets close and retries remain bounded.
6. Inspect logs for redaction and confirm TLS validation to the destination has not been disabled.