Shadowsocks

Shadowsocks is a lightweight encrypted proxy protocol. Traffic is encrypted with a key derived from a shared password, and there is no handshake to fingerprint. MeowX supports the AEAD ciphers and the newer Shadowsocks 2022 ciphers, which add replay protection and use a random key in place of a password. It also supports the obfs (simple-obfs) and shadow-tls (v3) plugins for networks that block traffic that does not look like HTTP or TLS. UDP is relayed natively and is full-cone.

Examples

Minimal:

proxies:
  - name: ss-basic
    type: ss
    server: example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

Shadowsocks 2022 with UDP:

proxies:
  - name: ss-2022
    type: ss
    server: 192.0.2.1
    port: 8388
    cipher: 2022-blake3-aes-128-gcm
    password: "AAAAAAAAAAAAAAAAAAAAAA=="   # base64 of exactly 16 bytes
    udp: true

With the obfs plugin:

proxies:
  - name: ss-obfs
    type: ss
    server: example.com
    port: 8388
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true
    plugin: obfs
    plugin-opts:
      mode: tls          # http (default) or tls
      host: bing.com     # disguise domain

With the shadow-tls plugin:

proxies:
  - name: ss-shadowtls
    type: ss
    server: example.com
    port: 443
    cipher: 2022-blake3-aes-256-gcm
    password: "BASE64-32-BYTE-KEY"
    plugin: shadow-tls
    plugin-opts:
      host: www.example.com     # TLS handshake server the ShadowTLS server relays to
      password: "shadow-tls-password"
      version: 3
    dialer-proxy: relay-group   # optional proxy chain

Parameters

Field	Type	Required	Default	Description
name	string	yes	—	Node name.
type	string	yes	—	ss
server	string	yes	—	Server domain or IP.
port	integer	yes	—	Server port.
cipher	string	yes	—	Encryption method, see Ciphers.
password	string	yes	—	Password (AEAD ciphers) or base64 key (2022 ciphers), see below. An empty password drops the node.
udp	boolean	no	false	Relay UDP. UDP is always full-cone.
plugin	string	no	—	obfs or shadow-tls. Any other value drops the node.
plugin-opts	map	no	—	Plugin options, see Plugins.
dialer-proxy	string	no	—	Connect to the server through another proxy or group. TCP only; UDP is turned off on chained nodes.

Ciphers

cipher	Family	Key size
aes-128-gcm	AEAD	16 bytes
aes-256-gcm	AEAD	32 bytes
chacha20-ietf-poly1305	AEAD	32 bytes
2022-blake3-aes-128-gcm	Shadowsocks 2022	16 bytes
2022-blake3-aes-256-gcm	Shadowsocks 2022	32 bytes
2022-blake3-chacha20-poly1305	Shadowsocks 2022	32 bytes

Any other cipher, including none, aes-192-gcm, xchacha20-ietf-poly1305 and all legacy stream ciphers (aes-256-cfb, rc4-md5, chacha20-ietf, …), is not supported. Nodes using them are dropped with a warning.

AEAD ciphers take a normal text password. The key is derived from it the standard way (as every Shadowsocks implementation does).

Shadowsocks 2022 ciphers take a key, not a password. password must be the base64 encoding of exactly as many bytes as the key size above: 16 bytes for 2022-blake3-aes-128-gcm, 32 bytes for the other two. Missing = padding is accepted. Generate one with openssl rand -base64 16 (or 32).

Multi-user Shadowsocks 2022 servers give each user an identity chain. Write it as password: "<server key>:<user key>", with each part base64 and of the key size. Longer chains (<key1>:<key2>:<user key>) are also accepted, and the last part is always your own key. Multi-user keys are supported only with the two 2022-blake3-aes-* ciphers. A multi-user key with 2022-blake3-chacha20-poly1305 drops the node, because that combination has no standard definition.

Plugins

Plugins wrap the TCP connection only. UDP never goes through a plugin.

obfs (simple-obfs)

Makes the start of the connection look like an HTTP request or a TLS handshake.

plugin-opts field	Type	Default	Description
mode	string	http	http or tls. Any other value drops the node.
host	string	bing.com	Disguise domain, sent as the HTTP Host header (http mode) or the TLS SNI (tls mode).
path	string	/	Request path in http mode.

UDP on an obfs node is sent directly to the Shadowsocks server, without obfuscation, as simple-obfs servers expect.

shadow-tls (ShadowTLS v3)

MeowX first performs a real TLS 1.3 handshake through the ShadowTLS server with the handshake server you name, sending a Chrome-like ClientHello. Shadowsocks traffic then flows inside what looks like that TLS session.

plugin-opts field	Type	Default	Description
password	string	— (required)	ShadowTLS password. A missing or empty password drops the node.
host	string	the node’s server	Domain of the TLS handshake server (the site the ShadowTLS server relays the handshake to). Set it to the same domain as on the server.
version	integer	—	Not read. Only ShadowTLS v3 is implemented; a v1 or v2 server will not work.

Requirements and limitations:

• The handshake server must support TLS 1.3.
• If the password is wrong, the ShadowTLS server forwards the connection to the real website. MeowX detects this and fails with an authentication error instead of hanging.
• UDP is turned off on shadow-tls nodes, even with udp: true, because the plugin carries TCP only.

UDP

With udp: true, MeowX sends encrypted UDP datagrams straight to the server’s port. Each datagram carries its own destination, so UDP is full-cone. Both AEAD and 2022 ciphers (including multi-user keys) are supported for UDP.

UDP is unavailable, even with udp: true, when:

• the node uses the shadow-tls plugin, or
• the node uses dialer-proxy (native UDP cannot travel through a TCP chain).

Validation

Problem	Result
cipher missing or empty	The whole configuration is rejected.
password missing or empty	Node dropped with a warning.
Unsupported cipher	Node dropped with a warning.
2022 key that is not valid base64 or has the wrong length	Node dropped with a warning.
Multi-user 2022 key with 2022-blake3-chacha20-poly1305	Node dropped with a warning.
plugin other than obfs / shadow-tls (for example v2ray-plugin, gost-plugin, kcptun, restls)	Node dropped with a warning.
obfs with a mode other than http / tls	Node dropped with a warning.
shadow-tls without plugin-opts.password	Node dropped with a warning.

Ignored fields

udp-over-tcp, udp-over-tcp-version, client-fingerprint and smux are not read. plugin-opts.version for shadow-tls is not read (v3 is always used). Transport fields such as network and ws-opts do not apply to Shadowsocks.