Shadowsocks

https://shadowsocks.org/doc/what-is-shadowsocks.html
Admin
Shadowsocks is a secure split proxy loosely based on SOCKS5. It encrypts and forwards data streams...
Tokens:9,703
Snippets:50
Trust Score:5.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install go-shadowsocks2 via Go Get

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs the go-shadowsocks2 library using the Go package manager. This is the recommended Go implementation for Shadowsocks.

```bash
go get -u -v github.com/shadowsocks/go-shadowsocks2
```

--------------------------------

### Build and Install shadowsocks-libev from Source

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs build dependencies and compiles the shadowsocks-libev project from its Git repository. This process involves cloning the repository, updating submodules, running autogen.sh, configuring the build, and finally compiling and installing the software.

```bash
$ sudo apt-get install --no-install-recommends build-essential autoconf libtool \
        libssl-dev gawk debhelper dh-systemd init-system-helpers pkg-config asciidoc \
        xmlto apg libpcre3-dev zlib1g-dev libev-dev libudns-dev libsodium-dev libmbedtls-dev libc-ares-dev automake
$ git clone https://github.com/shadowsocks/shadowsocks-libev.git
$ cd shadowsocks-libev
$ git submodule update --init
$ ./autogen.sh && ./configure && make
$ sudo make install
```

--------------------------------

### Build and Install libQtShadowsocks (C++ Qt)

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Clones the libQtShadowsocks C++ Qt library from GitHub, configures the build using qmake, compiles it with parallel jobs, and installs the library. This is for users who want to build the Qt-based Shadowsocks client from source.

```bash
$ git clone https://github.com/shadowsocks/libQtShadowsocks.git
$ cd libQtShadowsocks
$ qmake
$ make -j4
$ sudo make install
```

--------------------------------

### Install Net::Shadowsocks Perl Module (Unix-like)

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Provides two common methods for installing the Net::Shadowsocks Perl module on Unix-like systems. The first uses the Perl Build.PL script, and the second uses Makefile.PL. Both involve building, testing, and installing the module.

```perl
# Method 1: Using Build.PL
$ perl Build.PL
$ ./Build
$ ./Build test
$ ./Build install

# Method 2: Using Makefile.PL
$ perl Makefile.PL
$ make
$ make test
$ make install
```

--------------------------------

### Install Shadowsocks Python via Pip

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs the shadowsocks-python package using pip. This method requires Python 2.6 or 2.7 to be installed on the system.

```bash
python --version
pip install shadowsocks
```

--------------------------------

### Install Shadowsocks-libev on Debian/Ubuntu

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs shadowsocks-libev from official Debian/Ubuntu repositories. For Debian Jessie, it requires adding backports.

```bash
sudo apt update
sudo apt install shadowsocks-libev
```

```bash
sudo sh -c 'printf "deb http://httpredir.debian.org/debian jessie-backports\nmain" > /etc/apt/sources.list.d/jessie-backports.list'
sudo apt-get update
sudo apt-get -t jessie-backports install shadowsocks-libev
```

--------------------------------

### Run outline-ss-server

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs and runs the outline-ss-server, a Shadowsocks implementation used by Outline Server. It supports multiple users, ports, and Prometheus monitoring.

```bash
go get github.com/Jigsaw-code/outline-ss-server
$(go env GOPATH)/bin/outline-ss-server -config=config.yml -metrics=127.0.0.1:9091
```

--------------------------------

### Install Net::Shadowsocks Perl Module via CPAN

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Installs the Net::Shadowsocks Perl module directly from the Comprehensive Perl Archive Network (CPAN) using the cpan client. This is a convenient method if CPAN is configured and accessible.

```perl
$ cpan Net::Shadowsocks
```

--------------------------------

### SIP008 JSON Document Format

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip008

An example of a standard SIP008 JSON document format for Shadowsocks server configurations. It includes mandatory server details and optional fields for data usage tracking.

```json
{
    "version": 1,
    "servers": [
        {
            "id": "27b8a625-4f4b-4428-9f0f-8a2317db7c79",
            "remarks": "Name of the server",
            "server": "example.com",
            "server_port": 8388,
            "password": "example",
            "method": "chacha20-ietf-poly1305",
            "plugin": "xxx",
            "plugin_opts": "xxxxx"
        },
        {
            "id": "7842c068-c667-41f2-8f7d-04feece3cb67",
            "remarks": "Name of the server",
            "server": "example.com",
            "server_port": 8388,
            "password": "example",
            "method": "chacha20-ietf-poly1305",
            "plugin": "xxx",
            "plugin_opts": "xxxxx"
        }
    ],
    "bytes_used": 274877906944,
    "bytes_remaining": 824633720832
}
```

--------------------------------

### Shadowsocks Plugin Environment Variables

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip003

Defines the essential environment variables used to pass configuration and connection details from the Shadowsocks client/server to its child plugin process. These variables facilitate communication and setup for the plugin.

```APIDOC
SS_REMOTE_HOST: The hostname or IP address of the remote plugin service.
SS_REMOTE_PORT: The port number of the remote plugin service.
SS_LOCAL_HOST: The hostname or IP address of the local Shadowsocks or plugin service.
SS_LOCAL_PORT: The port number of the local Shadowsocks or plugin service.
SS_PLUGIN_OPTIONS: Optional. A formatted string containing additional arguments for the plugin, such as configuration file paths or specific obfuscation parameters. Values are typically key=value pairs separated by semicolons. Special characters like semicolons, equal signs, and backslashes within values must be escaped with a backslash.
```

--------------------------------

### SIP002 URI Scheme Definition

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip002

Defines the structure and components of the Shadowsocks SIP002 URI scheme, including user info, host, port, plugins, and tags. It specifies encoding rules for user information and provides examples for both Base64URL encoded and plain user info.

```APIDOC
SIP002 URI Scheme:

SS-URI = "ss://" userinfo "@" hostname ":" port [ "/" ] [ "?" plugin ] [ "#" tag ]

userinfo = websafe-base64-encode-utf8(method ":" password)
           | method ":" password

Notes:
- Base64URL encoding for userinfo is recommended but optional for Stream and AEAD ciphers.
- For AEAD-2022 ciphers, userinfo MUST NOT be encoded with Base64URL.
- When userinfo is not encoded, method and password MUST be percent encoded.
- The last '/' is appended if a plugin is present, optional if only a tag is present.
- Plugin arguments use a format similar to TOR_PT_SERVER_TRANSPORT_OPTIONS, e.g., "simple-obfs;obfs=http;obfs-host=example.com". Colons, semicolons, equal signs, and backslashes in plugin arguments MUST be escaped with a backslash.

Examples:

With user info encoded with Base64URL:
- ss://[email protected]:8888#Example1
- ss://[email protected]:8888/?plugin=obfs-local%3Bobfs%3Dhttp#Example2

Plain user info:
- ss://2022-blake3-aes-256-gcm:YctPZ6U7xPPcU%2Bgp3u%2B0tx%2FtRizJN9K8y%2BuKlW2qjlI%[[email protected]](https://github.com/shadowsocks/shadowsocks-org/issues/196):8888#Example3
- ss://2022-blake3-aes-256-gcm:YctPZ6U7xPPcU%2Bgp3u%2B0tx%2FtRizJN9K8y%2BuKlW2qjlI%[[email protected]](https://github.com/shadowsocks/shadowsocks-org/issues/196):8888/?plugin=v2ray-plugin%3Bserver#Example3

FAQ:
- Q1: Why parse user info to Base64URL? A1: To safely encode all characters in the key string. It does not encrypt the key.
- Q2: Why not parse hostname and port number into Base64URL? A2: Additional parsing is not necessary as nothing is being encrypted.
- Q3: Why not every client supports SIP002 URI scheme? A3: SIP002 is an optional feature, especially if the client doesn't support SIP003 plugins.
- Q4: Why tags with spaces are truncated? A4: Whitespace is illegal in URIs and must be escaped (e.g., "shadowsocks%20server%201").
```

--------------------------------

### Generate PSK using OpenSSL

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Example command to generate a cryptographically-secure pre-shared key (PSK) using OpenSSL, which is required for Shadowsocks 2022 implementations.

```bash
openssl rand -base64 <key_size>
```

--------------------------------

### Increase File Descriptor Limits for Shadowsocks

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/advanced

This section explains how to increase the maximum number of open file descriptors for the Shadowsocks server to handle thousands of concurrent TCP connections. It involves editing `/etc/security/limits.conf` and setting `ulimit` before starting the server.

```bash
vi /etc/security/limits.conf

* soft nofile 51200
* hard nofile 51200

# for server running in root:
root soft nofile 51200
root hard nofile 51200
```

```bash
ulimit -n 51200
```

--------------------------------

### Shadowsocks Plugin Command Line Usage

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip003

Demonstrates how to launch Shadowsocks server and client processes with custom plugins using command-line arguments. This includes specifying the plugin executable and its options.

```bash
# On the server:
ss-server --plugin obfs-server --plugin-opts "obfs=http"

# On the client:
ss-local -c config.json --plugin obfs-local --plugin-opts "obfs=http;obfs-host=www.baidu.com"
```

--------------------------------

### Run Shadowsocks-libev Docker Container

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/deploying

Deploys shadowsocks-libev using a Docker container. It maps server ports and allows configuration via environment variables.

```dockerfile
docker pull shadowsocks/shadowsocks-libev
docker run -e PASSWORD=<password> -p<server-port>:8388 -p<server-port>:8388/udp -d shadowsocks/shadowsocks-libev
```

--------------------------------

### Tune Kernel Parameters for Shadowsocks Performance

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/advanced

This section provides recommended kernel parameter tuning for Shadowsocks servers on Linux to improve port reuse, enlarge queues/buffers, and select an optimal TCP congestion algorithm for high throughput. The configurations are applied via `/etc/sysctl.conf`.

```bash
fs.file-max = 51200

net.core.rmem_max = 67108864
net.core.wmem_max = 67108864
net.core.netdev_max_backlog = 250000
net.core.somaxconn = 4096

net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_tw_recycle = 0
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_keepalive_time = 1200
net.ipv4.ip_local_port_range = 10000 65000
net.ipv4.tcp_max_syn_backlog = 8192
net.ipv4.tcp_max_tw_buckets = 5000
net.ipv4.tcp_fastopen = 3
net.ipv4.tcp_mem = 25600 51200 102400
net.ipv4.tcp_rmem = 4096 87380 67108864
net.ipv4.tcp_wmem = 4096 65536 67108864
net.ipv4.tcp_mtu_probing = 1
net.ipv4.tcp_congestion_control = hybla
```

```bash
sysctl -p
```

--------------------------------

### Shadowsocks Architecture Diagram

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/what-is-shadowsocks

Illustrates the basic data flow between the client, local Shadowsocks component (ss-local), remote Shadowsocks component (ss-remote), and the target server.

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

--------------------------------

### Shadowsocks Network Scenario Diagram

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip023

Visual representation of a Shadowsocks network topology, showing multiple clients connecting to servers via a relay. It highlights the distribution of PSKs (Pre-Shared Keys) among clients, relays, and servers, illustrating the communication flow.

```ascii
client0       >---+ 
(iPSK0:iPSK1:uPSK0)      \
                          \
      client1       >------\                        +--->    server0 [iPSK1] 
(iPSK0:iPSK1:uPSK1)         \                      /      [uPSK0, uPSK1, uPSK2]
                             >-> relay0 [iPSK0] >-<
      client2               /    [iPSK1, uPSK3]    \
(iPSK0:iPSK1:uPSK2) >------/                        +--->    server1 [uPSK3]
                          /
      client3            /
   (iPSK0:uPSK3)    >---+

```

--------------------------------

### SIP002 URI Scheme

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/configs

Introduces the SIP002 URI scheme for Shadowsocks, which is recommended for clients and servers supporting SIP003 plugins. This scheme offers an alternative to the standard URI format.

```apidoc
SIP002 URI Scheme:
Recommended for clients/servers supporting SIP003 plugins.

See also:
- SIP002: /doc/sip002.html
- SIP003 Plugin: /doc/sip003.html
```

--------------------------------

### Recommended AEAD Ciphers for Shadowsocks

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/aead

Lists the recommended AEAD ciphers for Shadowsocks implementations, including their key, salt, nonce, and tag sizes. Compliant implementations must support AEAD_CHACHA20_POLY1305.

```APIDOC
AEAD Cipher Specifications:

| Name                       | Alias                   | Key Size (bytes) | Salt Size (bytes) | Nonce Size (bytes) | Tag Size (bytes) |
| ---------------------------- | ----------------------- | ---------------- | ----------------- | ------------------ | ---------------- |
| AEAD_CHACHA20_POLY1305       | chacha20-ietf-poly1305  | 32               | 32                | 12                 | 16               |
| AEAD_AES_256_GCM             | aes-256-gcm             | 32               | 32                | 12                 | 16               |
| AEAD_AES_128_GCM             | aes-128-gcm             | 16               | 16                | 12                 | 16               |

Notes:
- Compliant Shadowsocks implementations must support AEAD_CHACHA20_POLY1305.
- Implementations for devices with hardware AES acceleration should also implement AEAD_AES_128_GCM and AEAD_AES_256_GCM.
- Refer to IANA AEAD registry for naming scheme and specification.
- Usage is specified in SIP004 and amended in SIP007.
```

--------------------------------

### Shadowsocks Encryption Methods

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/configs

Provides information on supported encryption methods for Shadowsocks. It highlights AEAD ciphers as the strongest and recommends specific ones, while also mentioning stream ciphers and the insecure default.

```apidoc
Encryption Methods:
- AEAD Ciphers: Recommended for strongest security and integrity (e.g., "chacha20-ietf-poly1305", "aes-256-gcm").
- Stream Ciphers: Implemented but do not provide integrity and authenticity.
- Default Method: "table" (not secure).

See also:
- AEAD ciphers: /doc/aead.html
- Stream ciphers: /doc/stream.html
```

--------------------------------

### Shadowsocks JSON Configuration

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/configs

Defines the structure and fields for a Shadowsocks client configuration file in JSON format. It includes server details, ports, password, and encryption method.

```json
{
    "server":"my_server_ip",
    "server_port":8388,
    "local_port":1080,
    "password":"barfoo!",
    "method":"chacha20-ietf-poly1305"
}
```

--------------------------------

### Derive Session Subkey using BLAKE3

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Demonstrates the subkey derivation process for Shadowsocks 2022. It utilizes BLAKE3's key derivation mode, appending a random salt to the pre-shared key as key material. The salt has the same length as the pre-shared key.

```Rust
session_subkey := blake3::derive_key(context: "shadowsocks 2022 session subkey", key_material: key + salt)
```

--------------------------------

### TCP Identity Header Generation

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip023

Describes the process for generating an identity header within TCP connections for Shadowsocks. It involves deriving a subkey from an identity PSK and salt, creating plaintext from the next PSK's hash, and encrypting it using AES.

```pseudocode
identity_subkey := blake3::derive_key(context: "shadowsocks 2022 identity subkey", key_material: iPSKn + salt)
plaintext := blake3::hash(iPSKn+1)[0..16] // Take the first 16 bytes of the next iPSK's hash.
identity_header := aes_encrypt(key: identity_subkey, plaintext: plaintext)
```

--------------------------------

### Shadowsocks Key Derivation (EVP_BytesToKey)

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/aead

Details the key derivation process used in Shadowsocks, which follows OpenSSL's EVP_BytesToKey(3) method. It explains the role of HKDF_SHA1 and the required 'info' string.

```APIDOC
Key Derivation Specification:

Method: EVP_BytesToKey(3) from OpenSSL.

Function: HKDF_SHA1(key, salt, info) => subkey

Parameters:
  - key: The input secret key (e.g., master key).
  - salt: A non-secret salt, must be unique for the lifetime of the master key.
  - info: An application-specific context string. For Shadowsocks, this must be "ss-subkey".

Purpose:
- Derives a cryptographically strong subkey from a potentially weak input key.
- The 'info' string binds the subkey to the specific application context (Shadowsocks).

Usage:
- A per-session subkey is derived from a pre-shared master key using HKDF_SHA1.
- Reference: RFC5869 for HKDF_SHA1.
```

--------------------------------

### Shadowsocks URI Scheme and QR Code

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/configs

Details the BASE64 encoded URI format used for Shadowsocks configuration on mobile clients (Android/iOS). It explains the plain URI structure and how to generate the encoded version, including optional tagging for organization.

```apidoc
URI Scheme:
ss://BASE64-ENCODED-STRING-WITHOUT-PADDING#TAG

Plain URI Format:
ss://method:password@hostname:port

Example:
Plain URI: ss://bf-cfb:test/!@#:@192.168.100.1:8888
Encoded URI: ss://YmYtY2ZiOnRlc3QvIUAjOkAxOTIuMTY4LjEwMC4xOjg4ODg
Tagged Encoded URI: ss://YmYtY2ZiOnRlc3QvIUAjOkAxOTIuMTY4LjEwMC4xOjg4ODg#example-server

Note: The password in the plain URI is not percent-encoded.
```

```javascript
console.log( "ss://" + btoa("bf-cfb:test/!@#:@192.168.100.1:8888") )
```

--------------------------------

### Historic Stream Ciphers

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/stream

Lists historical stream ciphers supported by Shadowsocks, detailing their name, key size in bytes, and IV length in bytes. This information is for educational purposes as stream ciphers are deprecated.

```APIDOC
Historic Stream Ciphers:

| Name            | Key Size | IV Length |
|-----------------|----------|-----------|
| aes-128-ctr     | 16       | 16        |
| aes-192-ctr     | 24       | 16        |
| aes-256-ctr     | 32       | 16        |
| aes-128-cfb     | 16       | 16        |
| aes-192-cfb     | 24       | 16        |
| aes-256-cfb     | 32       | 16        |
| camellia-128-cfb| 16       | 16        |
| camellia-192-cfb| 24       | 16        |
| camellia-256-cfb| 32       | 16        |
| chacha20-ietf   | 32       | 12        |
| bf-cfb          | 16       | 8         |
| chacha20        | 32       | 8         |
| salsa20         | 32       | 8         |
| rc4-md5         | 16       | 16        |
```

--------------------------------

### Shadowsocks AEAD Encryption/Decryption Functions

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/aead

Defines the abstract functions for AEAD encryption and decryption as used in Shadowsocks. It specifies the inputs and outputs for each operation.

```APIDOC
AEAD Encryption/Decryption Functions:

AE_encrypt(key, nonce, message) => (ciphertext, tag)
  - Encrypts a message using a secret key and a unique nonce.
  - Produces ciphertext and an authentication tag.
  - Parameters:
    - key: The secret encryption key.
    - nonce: A unique, non-secret nonce for each encryption with the same key.
    - message: The plaintext message to encrypt.
  - Returns:
    - ciphertext: The encrypted data.
    - tag: The authentication tag.

AE_decrypt(key, nonce, ciphertext, tag) => message
  - Decrypts ciphertext and verifies its integrity and authenticity using the secret key, nonce, and tag.
  - Decryption fails if any input is tampered with.
  - Parameters:
    - key: The secret decryption key.
    - nonce: The unique, non-secret nonce used during encryption.
    - ciphertext: The encrypted data.
    - tag: The authentication tag generated during encryption.
  - Returns:
    - message: The original plaintext message if verification succeeds.
    - Failure: If integrity or authenticity checks fail.
```

--------------------------------

### Shadowsocks Header Formats

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the structure of fixed and variable-length headers for client and server streams, including type, timestamp, length, address, port, and padding. These formats are crucial for establishing and maintaining communication channels.

```APIDOC
Request fixed-length header:
+------+------------------+--------+
| type |     timestamp    | length |
+------+------------------+--------+
|  1B  | u64be unix epoch |  u16be |
+------+------------------+--------+

Request variable-length header:
+------+----------+-------+----------------+----------+-----------------+
| ATYP |  address |  port | padding length |  padding | initial payload |
+------+----------+-------+----------------+----------+-----------------+
|  1B  | variable | u16be |     u16be      | variable |    variable     |
+------+----------+-------+----------------+----------+-----------------+

Response fixed-length header:
+------+------------------+----------------+--------+
| type |     timestamp    |  request salt  | length |
+------+------------------+----------------+--------+
|  1B  | u64be unix epoch |     16/32B     |  u16be |
+------+------------------+----------------+--------+

Header Field Descriptions:
- type: 1-byte, differentiates client (0) and server (1) messages.
- timestamp: 8-byte Unix epoch (u64be), messages >30s difference are replay.
- length: 2-byte (u16be), indicates next chunk's plaintext length (excluding auth tag).
- ATYP + address + port: Target address in SOCKS5 format (RFC 1928 Section 5).
- request salt: 16/32B in response header, maps response to request stream.
```

--------------------------------

### Shadowsocks AEAD UDP Packet Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/aead

Outlines the format of an AEAD encrypted UDP packet, specifying the role of the salt and the encryption process for each packet.

```APIDOC
UDP Encrypted Packet Structure:
  Format: [salt][encrypted payload][tag]

  salt:
    Purpose: Used to derive the per-session subkey.
    Generation: Must be generated randomly to ensure uniqueness.

  Encryption:
    Each UDP packet is encrypted/decrypted independently.
    Nonce: All zero bytes.
    Key: Derived from the salt.
```

--------------------------------

### Shadowsocks Header Field Descriptions and Requirements

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Details the purpose and constraints for key fields within the Shadowsocks message headers, including type, timestamp, and padding.

```APIDOC
* 1-byte type: Differentiates between client (0) and server (1) messages.
* 8-byte Unix epoch timestamp: Messages with over 30 seconds time difference MUST be treated as replay.
* Padding length: Specifies the length of optional padding. Implementations MAY allow users to select predefined padding policies. Care SHOULD be taken to not exceed the network path's MTU when padding packets.
```

--------------------------------

### SOCKS5 Address Format in Shadowsocks

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/what-is-shadowsocks

Defines the structure of addresses used within Shadowsocks, based on the SOCKS5 address format, specifying byte types for host representation and port.

```APIDOC
SOCKS5 Address Format:
  [1-byte type][variable-length host][2-byte port]

  Address Types:
    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.

  Port:
    A 2-byte big-endian unsigned integer.
```

--------------------------------

### Shadowsocks Detection Prevention Strategies

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Outlines methods to prevent protocol detection by managing socket behavior, buffering, and sending data in single write calls. It details strategies for handling decryption failures or header validation issues to avoid revealing protocol usage.

```APIDOC
Detection Prevention Strategies:

1.  **Buffering and Single Writes**: Random salt and header chunks MUST be buffered and sent in one write call to the underlying socket. Separate writes can lead to predictable packet sizes, revealing the protocol.

2.  **Single Read Call**: Servers and clients MUST make exactly one read call to process the salt and fixed-length header. If data is insufficient for decryption, decryption fails, or header validation fails, the server MUST act in a way that does not exhibit the amount of bytes consumed.

3.  **Handling Failures (Socket Behavior)**:
    *   **Strategy 1 (RST)**: To consistently send RST even when the receive buffer is empty, set `SO_LINGER` to true with a zero timeout, then close the socket.
    *   **Strategy 2 (FIN, drain)**: To consistently send FIN even when the receive buffer has unread data, shut down the write half of the connection by calling `shutdown(SHUT_WR)`, then drain the connection for any further received data.
    *   **Strategy 3 (FIN, limit writes)**: To consistently send FIN but disallow unlimited writes, shut down the write half of the connection by calling `shutdown(SHUT_WR)`, then `epoll` for `EPOLLRDHUP`. Read until EOF, then close. This limits data sent by the other party to the socket receive buffer size.

4.  **Padding Requirements**:
    *   **Request Header**: Either initial payload or padding MUST be present. If payload is not available, add non-zero random length padding.
    *   **Client Padding**: A simple approach is to always send random length padding. Clients MAY wait a short time (<1s) for client-first protocols to write payload before establishing a proxy connection and writing the header (for TCP Fast Open).
    *   **Server Rejection**: Servers MUST reject requests if the variable-length header chunk lacks payload and padding length is 0. Servers MUST enforce that the request header (including padding) does not exceed header chunk limits.
    *   **Response Streams**: Header is always sent with payload. No padding is needed.
```

--------------------------------

### AEAD Encryption and Decryption Operations

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Illustrates the core encryption and decryption steps for each proxy stream in Shadowsocks 2022. It involves creating an AEAD cipher instance with the session subkey and using a 12-byte little-endian counter, which is incremented after each operation.

```Pseudocode
u96le counter
aead := aead_new(key: session_subkey)
ciphertext := aead.seal(nonce: counter, plaintext)
plaintext := aead.open(nonce: counter, ciphertext)
```

--------------------------------

### Shadowsocks Session Management and Replay Protection

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Outlines requirements for Shadowsocks servers and clients regarding session ID based routing, relay session management, and sliding window replay protection.

```APIDOC
Server Routing:
Servers MUST route packets based on client session ID, not packet source address. A new relay session is created for new client session IDs.

Relay Session Management:
A relay session MUST keep track of the last seen client address. Return packets MUST be sent to this address. Each relay session MUST be remembered for at least 60 seconds.

Client Session Handling:
Clients MUST allow each client session to be associated with more than one server session. Each association MUST be remembered for no less than the NAT timeout (at least 60 seconds). Alternatively, clients MAY track one old and one current server session.

Replay Protection:
Clients and servers MUST employ a sliding window filter for each relay session to check incoming packets for duplicate or out-of-window packet IDs. The sliding window state MUST NOT be updated before successful header validation.
```

--------------------------------

### Stream Encryption/Decryption Functions

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/stream

Defines the conceptual functions for stream encryption and decryption used in Shadowsocks. Stream_encrypt takes a key, IV, and message to produce ciphertext. Stream_decrypt reverses this process. Key derivation follows OpenSSL's EVP_BytesToKey.

```APIDOC
Stream_encrypt(key, IV, message) => ciphertext
  - Encrypts a message using a secret key and initialization vector.
  - The output ciphertext has the same length as the input message.

Stream_decrypt(key, IV, ciphertext) => message
  - Decrypts ciphertext using a secret key and initialization vector.
  - Returns the original message.

Key Derivation:
  - Key can be derived from a password using OpenSSL's EVP_BytesToKey(3).
  - Reference: https://wiki.openssl.org/index.php/Manual:EVP_BytesToKey(3)
```

--------------------------------

### UDP Identity Header Generation

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip023

Details the method for creating an identity header in UDP packets for Shadowsocks. It involves XORing the next PSK's hash with session/packet IDs to create unique plaintext, which is then AES encrypted using the current layer's PSK.

```pseudocode
plaintext := blake3::hash(iPSKn+1)[0..16] ^ session_id_packet_id // XOR to make it different for each packet.
identity_header := aes_encrypt(key: iPSKn, plaintext: plaintext)
```

--------------------------------

### Shadowsocks 2022 UDP Encryption/Decryption

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Illustrates the encryption and decryption process for Shadowsocks 2022 UDP packets. It uses a pre-shared key (PSK) for the separate header and a derived session subkey with an AEAD cipher for the body. Dependencies include AES block cipher and BLAKE3 for key derivation.

```python
block_cipher := aes_new(psk)
encrypted_separate_header := block_cipher.encrypt(separate_header)
decrypted_separate_header := block_cipher.decrypt(encrypted_separate_header)

session_subkey := blake3::derive_key(context: "shadowsocks 2022 session subkey", key_material: key + separate_header[0..8])
session_aead_cipher := aes_gcm_new(session_subkey)
encrypted_body := session_aead_cipher.seal(nonce: separate_header[4..16], body)
decrypted_body := session_aead_cipher.open(nonce: separate_header[4..16], body)
```

--------------------------------

### UDP Message Headers

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Details the structure of client-to-server and server-to-client UDP message headers. These headers include session IDs, packet IDs, timestamps, padding, address type (ATYP), address, and port.

```ascii
Client-to-server message header:
+-------------------+------------------+------+------------------+----------------+----------+------+----------+-------+
| client session ID | client packet ID | type |     timestamp    | padding length |  padding | ATYP |  address |  port |
+-------------------+------------------+------+------------------+----------------+----------+------+----------+-------+
|         8B        |       u64be      |  1B  | u64be unix epoch |     u16be      | variable |  1B  | variable | u16be |
+-------------------+------------------+------+------------------+----------------+----------+------+----------+-------+

Server-to-client message header:
+-------------------+------------------+------+------------------+-------------------+----------------+----------+------+----------+-------+
| server session ID | server packet ID | type |     timestamp    | client session ID | padding length |  padding | ATYP |  address |  port |
+-------------------+------------------+------+------------------+-------------------+----------------+----------+------+----------+-------+
|         8B        |       u64be      |  1B  | u64be unix epoch |         8B        |     u16be      | variable |  1B  | variable | u16be |
+-------------------+------------------+------+------------------+-------------------+----------------+----------+------+----------+-------+
```

--------------------------------

### Shadowsocks Protocol Constants

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines key constants used within the Shadowsocks protocol for stream differentiation and padding management.

```APIDOC
HeaderTypeClientStream = 0
HeaderTypeServerStream = 1
MinPaddingLength = 0
MaxPaddingLength = 900
```

--------------------------------

### Shadowsocks Server-to-Client Message Header Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the byte layout for headers sent from a Shadowsocks server to a client. It includes all fields from the client-to-server header plus an additional client session ID field.

```APIDOC
+------+------------------+-------------------+----------------+----------+------+----------+-------+
| type |     timestamp    | client session ID | padding length |  padding | ATYP |  address |  port |
+------+------------------+-------------------+----------------+----------+------+----------+-------+
|  1B  | u64be unix epoch |         8B        |     u16be      | variable |  1B  | variable | u16be |
+------+------------------+-------------------+----------------+----------+------+----------+-------+
```

--------------------------------

### Shadowsocks AEAD TCP Chunk Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/aead

Defines the format of an AEAD encrypted TCP chunk, including the payload length encoding and nonce management for each operation.

```APIDOC
TCP Encrypted Chunk Structure:
  Format: [encrypted payload length][length tag][encrypted payload][payload tag]

  encrypted payload length:
    Type: 2-byte big-endian unsigned integer
    Maximum Value: 0x3FFF (16383)
    Reserved Bits: Higher two bits must be zero.
    Maximum Payload Size: 16*1024 - 1 bytes.

  Nonce Usage:
    Initial: Counting nonce starting from 0.
    Increment: Incremented by one (little-endian) after each AEAD operation.
    Operations per Chunk: Two AEAD operations (one for payload length, one for payload).
    Each chunk increases the nonce twice.
```

--------------------------------

### SIP022 AEAD-2022 Ciphers Specification

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the 2022 Edition of the Shadowsocks protocol, focusing on AEAD ciphers, security improvements, and key derivation. It mandates pre-shared keys and outlines requirements for AES-GCM and ChaCha-Poly1305 methods.

```APIDOC
SIP022 AEAD-2022 Ciphers

Abstract:
This document defines the 2022 Edition of the Shadowsocks protocol. Improving upon Shadowsocks AEAD (2017), Shadowsocks 2022 addresses well-known issues of the previous editions, drops usage of obsolete cryptography, optimizes for security and performance, and leaves room for future extensions.

Overview:
Shadowsocks 2022 is a secure proxy protocol for TCP and UDP traffic. The protocol uses AEAD with a pre-shared symmetric key to protect payload integrity and confidentiality. The proxy traffic is indistinguishable from a random byte stream, and therefore can circumvent firewalls and Internet censors that rely on DPI (Deep Packet Inspection).

Compared to previous editions of the protocol family, Shadowsocks 2022 allows and mandates full replay protection. Each message has its unique type and cannot be used for unintended purposes. The session-based UDP proxying significantly reduces protocol overhead and improves reliability and efficiency. Obsolete cryptographic functions have been replaced by their modern counterparts.

As with previous editions, Shadowsocks 2022 does not provide forward secrecy. It is believed that using a pre-shared key without performing handshakes is best for its use cases.

A Shadowsocks 2022 implementation consists of a server, a client, and optionally a relay. This document specifies requirements that implementations must follow.

Document Structure:
Section 2 describes requirements on the encryption key and how to derive session subkeys.
Section 3 defines the encoding details of the required AES-GCM methods and the process for handling requests and responses.
Section 4 defines the encoding details of the optional ChaCha-Poly1305 methods.

Terms and Definitions:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Commonly used terms in this document are described below.
Shadowsocks AEAD: The original AEAD construction of Shadowsocks, standardized in 2017.

Encryption/Decryption Keys:
A pre-shared key is used to derive session subkeys, which are subsequently used to encrypt/decrypt traffic for the session. The pre-shared key is also used directly in some places.

PSK:
Unlike previous editions, Shadowsocks 2022 requires that a cryptographically-secure fixed-length PSK to be directly provided by the user. Implementations MUST NOT use the old EVP_BytesToKey function or any other method to generate keys from passwords.

The PSK is encoded in base64 for convenience. Practically, it can be generated with openssl rand -base64 <key_size>. The key size depends on the chosen method. This change was inspired by WireGuard.

| Method                      | Key Bytes | Salt Bytes |
| --------------------------- | --------- | ---------- |
| 2022-blake3-aes-128-gcm     | 16        | 16         |
| 2022-blake3-aes-256-gcm     | 32        | 32         |
```

--------------------------------

### TCP and UDP Packet Structures

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/stream

Describes the structure of encrypted data packets for TCP and UDP protocols when using stream ciphers. Both protocols prepend a randomly generated initialization vector (IV) to the encrypted payload.

```APIDOC
TCP Packet Structure:
  [IV][encrypted payload]
  - A stream cipher encrypted TCP stream starts with a randomly generated IV, followed by encrypted payload data.

UDP Packet Structure:
  [IV][encrypted payload]
  - Each UDP packet is encrypted/decrypted independently with a randomly generated IV.
```

--------------------------------

### Shadowsocks Client-to-Server Message Header Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the byte layout for headers sent from a client to a Shadowsocks server. It includes fields for packet type, timestamp, padding length, address type, address, and port.

```APIDOC
+------+------------------+----------------+----------+------+----------+-------+
| type |     timestamp    | padding length |  padding | ATYP |  address |  port |
+------+------------------+----------------+----------+------+----------+-------+
|  1B  | u64be unix epoch |     u16be      | variable |  1B  | variable | u16be |
+------+------------------+----------------+----------+------+----------+-------+
```

--------------------------------

### Shadowsocks TCP Data Stream

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/what-is-shadowsocks

Describes the structure of the encrypted data stream initiated by ss-local to ss-remote for TCP traffic, including the target address and payload.

```APIDOC
TCP Data Stream Structure:
  [target address][payload]

  Description:
    ss-local sends an encrypted data stream starting with the target address followed by payload data.
    The exact encryption scheme depends on the cipher used.
    For obfuscation, handshake data should be sent with some payload in the first packet.
```

--------------------------------

### Shadowsocks Header Type Definitions

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Specifies the numerical values for differentiating between client and server packets within the Shadowsocks protocol.

```APIDOC
HeaderTypeClientPacket = 0
HeaderTypeServerPacket = 1
```

--------------------------------

### UDP Packet Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the layout of a UDP packet, consisting of a random nonce followed by an encrypted body. The encrypted body includes a 16-byte tag.

```ascii
+-------+---------------------------+
| nonce |       encrypted body      |
+-------+---------------------------+
|  24B  | variable length + 16B tag |
+-------+---------------------------+
```

--------------------------------

### Shadowsocks 2022 UDP Packet Structure

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/sip022

Defines the structure of a UDP packet in Shadowsocks 2022. It consists of an encrypted separate header and an AEAD-encrypted body. The separate header contains an 8-byte session ID and an 8-byte packet ID (u64 big-endian).

```APIDOC
Packet:
+---------------------------+---------------------------+
| encrypted separate header |       encrypted body      |
+---------------------------+---------------------------+
|            16B            | variable length + 16B tag |
+---------------------------+---------------------------+

Separate header:
+------------+-----------+
| session ID | packet ID |
+------------+-----------+
|     8B     |   u64be   |
+------------+-----------+
```

--------------------------------

### Shadowsocks UDP Data Packet

Source: https://shadowsocks.org/doc/what-is-shadowsocks.html/what-is-shadowsocks

Details the structure of encrypted data packets sent between ss-local and ss-remote for UDP traffic, including the target address and payload.

```APIDOC
UDP Data Packet Structure:
  [target address][payload]

  Description:
    ss-local sends an encrypted data packet containing the target address and payload to ss-remote.
    ss-remote decrypts, parses the target address, and sends only the payload to the target.
    Replies from the target are prepended with the target address and sent back encrypted.
```
Tokens:
Raw