Shadowsocks is a secure split proxy loosely based on SOCKS5.

client <---> ss-local <--[encrypted]--> ss-remote <---> target

The Shadowsocks local component (ss-local) acts like a traditional SOCKS5 server and provides proxy service to clients. It encrypts and forwards data streams and packets from the client to the Shadowsocks remote component (ss-remote), which decrypts and forwards to the target. Replies from target are similarly encrypted and relayed by ss-remote back to ss-local, which decrypts and eventually returns to the original client.

Addressing

Addresses used in Shadowsocks follow the SOCKS5 address format:

[1-byte type][variable-length host][2-byte port]

The following address types are defined:

0x01: host is a 4-byte IPv4 address.
0x03: host is a variable length string, starting with a 1-byte length, followed by up to 255-byte domain name.
0x04: host is a 16-byte IPv6 address.

The port number is a 2-byte big-endian unsigned integer.

TCP

ss-local initiates a TCP connection to ss-remote by sending an encrypted data stream starting with the target address followed by payload data. The exact encryption scheme differs depending on the cipher used.

[target address][payload]

ss-remote receives the encrypted data stream, decrypts and parses the leading target address. It then establishes a new TCP connection to the target and forwards payload data to it. ss-remote receives reply from the target, encrypts and forwards it back to the ss-local, until ss-local disconnects.

For better obfuscation purposes, both local and remote SHOULD send the handshake data along with some payload in the first packet.

UDP

ss-local sends an encrypted data packet containing the target address and payload to ss-remote.

[target address][payload]

Upon receiving the encrypted packet, ss-remote decrypts and parses the target address. It then sends a new data packet containing only the payload to the target. ss-remote receives data packets back from target and prepends the target address to the payload in each packet, then sends encrypted copies back to ss-local.

[target address][payload]

Essentially, ss-remote is performing Network Address Translation for ss-local.

Getting Started

First, you need to pick a shadowsocks server and client implementation. Any implementation below is compatible with each other.

CLI implementations

shadowsocks: The original Python implementation.
shadowsocks-libev: Lightweight C implementation for embedded devices and low end boxes. Very small footprint (several megabytes) for thousands of connections.
go-shadowsocks2: Go implementation focusing on core features and code reusability.
shadowsocks-rust: A rust port of shadowsocks.

Feature comparison

	ss	ss-libev	go-ss2	ss-rust
TCP Fast Open	✓	✓	✗	✓
Multiuser	✓	✓	✗	✓
Management API	✓	✓	✗	✓
Redirect mode	✗	✓	✓	✓
Tunnel mode	✓	✓	✓	✓
UDP Relay	✓	✓	✓	✓
MPTCP	✗	✓	✗	✓
AEAD ciphers	✓	✓	✓	✓
Plugin	✗	✓	✗	✓
Plugin UDP (Experimental)	✗	✗	✗	✓

GUI Clients

shadowsocks-android: Android client.
shadowsocks-windows: Windows client.
shadowsocksX-NG: MacOS client.
shadowsocks-qt5: Cross-platform client for Windows/MacOS/Linux.

Feature comparison

	ss-win	ssx-ng	ss-qt5	ss-android
System Proxy	✓	✓	✗	✓
CHNRoutes	✓	✓	✗	✓
PAC Configuration	✓	✓	✗	✗
Profile Switching	✓	✓	✓	✓
QR Code Scan	✓	✓	✓	✓
QR Code Generation	✓	✓	✓	✓