Shadowsocks documentation
Navigation
Shadowsocks Configuration Format
Config File
Shadowsocks takes JSON format configurations:
{
“server”:”my_server_ip”,
“server_port”:8388,
“local_port”:1080,
“password”:”barfoo!”,
“method”:”chacha20-ietf-poly1305″
}
JSON Format
- server : your hostname or server IP (IPv4/IPv6).
- server_port: server port number.
- local_port: local port number.
- password: a password used to encrypt transfer.
- method: encryption method.
Encryption Method
We configure our servers and recommend that you use the chacha20-ietf-poly1305 AEAD cipher because it is the strongest method of encryption.
If configuring your own shadowsocks server, you can choose from either “chacha20-ietf-poly1305” or “aes-256-gcm”.
URI & QR Code
Shadowsocks for Android / IOS also takes BASE64 encoded URI format configs:
ss://BASE64-ENCODED-STRING-WITHOUT-PADDING#TAG
The plain URI should be: ss://method:password@hostname:port
The above URI doesn’t follow RFC3986. The password in this case should be plain text, not percent-encoded.
Example: We are using a server at 192.168.100.1:8888 using bf-cfb encryption method and password test/!@#:.
Then, with the plain URI ss://bf-cfb:test/!@#:@192.168.100.1:8888, we can generate the BASE64 encoded URI:
> console.log( “ss://” + btoa(“bf-cfb:test/!@#:@192.168.100.1:8888”) )
ss://YmYtY2ZiOnRlc3QvIUAjOkAxOTIuMTY4LjEwMC4xOjg4ODg
To help organize and identify these URIs, you can append a tag after the BASE64 encoded string:
ss://YmYtY2ZiOnRlc3QvIUAjOkAxOTIuMTY4LjEwMC4xOjg4ODg#example-server
Addressing
Shadowsocks uses the addresses found in the SOCKS5 address format:
[1-byte type][variable-length host][2-byte port]
Here are the address types defined:
- 0x01 : host is a 4-byte IPv4 address.
- 0x03 : host is a variable length string, starting with a 1-byte length, followed by a max 255-byte domain name.
- 0x04 : host is a 16-byte IPv6 address.
The port number is a 2-byte big-endian unsigned integer.
TCP
The ss-local client initiates a connection to ss-remote by sending encrypted data starting with the target address followed by the payload data. The encryption will be different depending on the cipher used.
[target address][payload]
The ss-remote receives the encrypted data, then decrypts and parses the target address. Then it creates a new TCP connection to the target and forwards the payload data to it. ss-remote receives a reply from the target then encrypts the data and forwards it back to ss-local until it is disconnected.
For obfuscation purposes, local and remote should send the handshake data with some payload in the first packet.
UDP
ss-local sends the encrypted data packet containing the target address and payload to ss-remote.
[target address][payload]
Once the encrypted packet is received, ss-remote decrypts and parses the target address. It then sends a new data packet with the payload to the target. ss-remote receives the data packets from the target and prepends the target address to the payload in each packet. Encrypted copies are sent back to ss-local.
[target address][payload]
This process can be boiled down to ss-remote performing a network address translation for ss-local.
