SOCKS5 — API

Service entry points

start.php defines the SOCKS constants, loads configuration and HandshakeBuffer, and creates the Server worker. config.php reads environment variables; running it alone is not the service startup procedure.

HandshakeBuffer

Method	Behavior
append(string $data): void	Append bytes; throw UnexpectedValueException if accumulated data exceeds 65,536 bytes.
take(int $stage): ?string	Consume one complete stage packet; return null while incomplete or for an unsupported stage.
drain(): string	Return and clear all remaining bytes.

Stages 0, 1 and 2 parse the greeting, username/password authentication and destination request respectively. Following packets remain buffered. An IPv6 packet may be structurally parsed, but the service rejects IPv6 destinations.

Configuration

Bind defaults to 127.0.0.1, port to 1080. SOCKS5_USERNAME and SOCKS5_PASSWORD must both be nonempty and at most 255 bytes. SOCKS5_ALLOW_NO_AUTH=1 selects anonymous access only when the bind address begins with 127..

SOCKS5_PID_FILE and SOCKS5_LOG_FILE select per-instance paths, defaulting to files under sys_get_temp_dir(). Use the same PID path for startup and shutdown. There is no environment option enabling UDP.

Protocol

Greeting uses version 5 and at least one offered method. Authentication uses subnegotiation version 1 with nonempty credentials. CONNECT requires reserved byte zero and a valid IPv4 address or hostname. Ports are unsigned 16-bit values in network byte order.

Success is returned after upstream connection establishment and contains its local address and port. An unsupported method returns 05 ff; an incorrect password returns a failed auth status. Unsupported UDP returns command-not-supported. Invalid packet structure, oversized buffers and handshake timeouts may simply close the connection.

Boundaries

The handshake deadline is 10 seconds from acceptance and is removed after entering relay mode. It is not an idle timeout for established streams. Credentials are not encrypted by SOCKS5; protect the client-to-proxy network separately.

There is no built-in destination ACL, user database or rate limit. An authenticated client uses the proxy host’s network access. Restrict egress if access to private networks must be blocked.

Local integration test

The source repository’s python3 tests/integration.py starts a temporary loopback echo server and a proxy on an ephemeral port with temporary PID/log files. It exercises fragmented and coalesced handshakes, early application data, authentication failures, disabled UDP and malformed greetings. It does not validate IPv6 or encrypted client-to-proxy transport.