Shadowsocks 2022 explained: ciphers, keys, replay protection
Shadowsocks 2022 is the 2022 edition of the Shadowsocks protocol, defined in SIP022. It has three methods: 2022-blake3-aes-128-gcm (16-byte key), 2022-blake3-aes-256-gcm (32-byte key) and 2022-blake3-chacha20-poly1305 (32-byte key). The password is not a password any more: it is a random key of exactly that length, encoded in base64, which you make with openssl rand -base64 16 or 32. Replay protection is built in, so the client's and server's clocks must agree within 30 seconds. For most servers, 2022-blake3-aes-128-gcm is the method to use.
ST Muntaha11 min read
Shadowsocks 2022 fixes the known problems of the older AEAD edition, and it fails in new ways that confuse people the first time: a "password" that is rejected because it is 32 bytes instead of 16, a client that works on Wi-Fi and fails on a laptop with a wrong clock, a multi-user server that rejects a user who has the right key. This post explains what changed, then goes through keys, clocks, multi-user setups, links and migration, with the real error messages.
I tested the configs and errors here with shadowsocks-rust 1.24.0, Xray-core 26.10.31 and sing-box 1.13.8. At the time of writing the current releases are shadowsocks-rust 1.25.0, Xray-core 26.10.31 and sing-box 1.14.4.
What is Shadowsocks 2022?
Shadowsocks 2022 is a new edition of the protocol, published as SIP022, the "AEAD-2022" ciphers. Like every Shadowsocks edition, it is a proxy for TCP and UDP that encrypts everything with a pre-shared key, so the traffic looks like random bytes. What changed is everything around the encryption.
| AEAD (2017) | Shadowsocks 2022 | |
|---|---|---|
| Key | Any password, stretched with EVP_BytesToKey |
A random key of exact length, in base64 |
| Session subkey | HKDF-SHA1 | BLAKE3 key derivation |
| Replay protection | Not in the spec; left to implementations | Required: a timestamp check plus a 60-second salt store |
| Payload per chunk | Up to 16,383 bytes | Up to 65,535 bytes |
| Request header | Target address only | Type, timestamp, target address, 0 to 900 bytes of padding |
| Response | Not tied to the request | Carries the request's salt, so it can't be replayed onto another connection |
| UDP | Each packet encrypted on its own | Sessions with a session ID and packet counter, plus a sliding-window replay filter |
| Many users on one port | No standard | SIP023 identity headers |
The spec also adds rules against active probing. The server must not reveal how many bytes it read before it gave up on a bad connection. shadowsocks-rust handles this by closing a failed 2022 connection with a TCP reset, so a probe or a client with the wrong key gets a reset instead of a silent hang.
One thing did not change. The spec says plainly that Shadowsocks 2022 "does not provide forward secrecy". If the key leaks, recorded traffic can be decrypted. That is the trade for having no handshake at all.
Which Shadowsocks 2022 method should I use?
Use 2022-blake3-aes-128-gcm unless you have a reason not to. Almost every server CPU sold in the last decade has AES instructions, the key is short, and it is one of the two methods the spec says every implementation MUST support.
| Method | Key | Required by spec | Multi-user (SIP023) | When to pick it |
|---|---|---|---|---|
2022-blake3-aes-128-gcm |
16 bytes | Yes | Yes | The default choice |
2022-blake3-aes-256-gcm |
32 bytes | Yes | Yes | When a policy asks for 256-bit keys |
2022-blake3-chacha20-poly1305 |
32 bytes | No, optional | No | Devices without AES instructions, such as some ARM routers |
The ChaCha method cannot do multi-user, because SIP023 identity headers are built with an AES block cipher. Xray-core refuses the combination with shadowsocks 2022 (multi-user): only blake3-aes-*-gcm methods are supported. shadowsocks-rust also lists a 2022-blake3-chacha8-poly1305 method, but only in its non-standard "extra" build feature, so other implementations will not understand it.
If you are asking "what is the best Shadowsocks encryption method" for an older client that cannot do 2022, the answer is one of the 2017 AEAD methods: aes-256-gcm, aes-128-gcm or chacha20-ietf-poly1305. The old stream ciphers such as aes-256-cfb and rc4-md5 are deprecated; shadowsocks-rust's README calls them unsafe.
How do I generate a Shadowsocks 2022 key?
Generate random bytes of the method's key length and encode them in base64. Any of these works:
openssl rand -base64 16 # for 2022-blake3-aes-128-gcm
openssl rand -base64 32 # for aes-256-gcm and chacha20
ssservice genkey -m "2022-blake3-aes-128-gcm" # shadowsocks-rust
sing-box generate rand --base64 16 # sing-box
A 16-byte key is 24 base64 characters ending in ==, such as SltovJBRjzfjux/H+sIZdA==. A 32-byte key is 44 characters ending in one =. Make your own; never reuse a key from a blog post.
The key length must be exact, and implementations disagree about what happens when it isn't. This is what I got when I gave each one a 32-byte key for 2022-blake3-aes-128-gcm:
- shadowsocks-rust refuses to start:
invalid key length for 2022-blake3-aes-128-gcm, expecting 16 bytes, but found 32 bytes. A password that is not base64 at all givesinvalid key encoding for 2022-blake3-aes-128-gcm, Invalid symbol 45, offset 5. - Xray-core 26.10.31 refuses to start:
proxy/shadowsocks_2022: bad key. The Xray docs still say that 32-byte keys "always work" in the Go implementation. That was true while Xray used the sing-shadowsocks library, which sing-box also uses. Xray replaced it with its own 2022 code in release 26.9.30, and now the length must match. - sing-box 1.13.8 starts without complaint. Its Shadowsocks library hashes a key that is too long down to the right length with SHA-256.
The sing-box behaviour is the dangerous one. A config can run fine on a sing-box server for months and then fail the day you move the same key to shadowsocks-rust or a current Xray, or hand it to a client that checks the length. Generate keys of the exact length and the problem never appears.
How does Shadowsocks 2022 prevent replay attacks?
Every request header carries a Unix timestamp, and the server stores the random salt of every connection for 60 seconds. SIP022 says a message with "over 30 seconds of time difference MUST be treated as replay". A salt the server has already seen is rejected too. UDP packets carry a counter that is checked against a sliding window, the same technique WireGuard uses.
For an operator this means one new dependency: clocks. If a client's clock is more than 30 seconds away from the server's, every connection fails. shadowsocks-rust logs it clearly:
WARN tcp handshake failed. peer: 176.61.144.23:51874, invalid timestamp <client time> - now <server time> = <difference>
Xray-core and sing-box report bad timestamp. Compare this with a wrong key, which shadowsocks-rust logs as:
WARN tcp handshake failed. peer: 176.61.144.23:51874, decrypt header chunk failed
On the server, check that time sync is running:
timedatectl status
You want System clock synchronized: yes. On clients, the usual cause is a phone or laptop with automatic time turned off, or a router that lost its clock after a power cut. 30 seconds is tighter than VMess, which allows 120.
How do I run a Shadowsocks 2022 server with shadowsocks-rust?
shadowsocks-rust, the reference implementation, needs a small JSON file:
{
"server": "0.0.0.0",
"server_port": 8388,
"method": "2022-blake3-aes-128-gcm",
"password": "SltovJBRjzfjux/H+sIZdA==",
"mode": "tcp_and_udp"
}
Start it with ssserver -c /etc/shadowsocks-rust/config.json. The project publishes Docker images on GitHub's registry; the run command from the shadowsocks-rust README is:
docker run --name ssserver-rust \
--restart always \
-p 8388:8388/tcp \
-p 8388:8388/udp \
-v /etc/shadowsocks-rust/config.json:/etc/shadowsocks-rust/config.json \
-dit ghcr.io/shadowsocks/ssserver-rust:latest
Three Docker details: publish the port for UDP as well as TCP, or the UDP relay silently fails; keep "server": "0.0.0.0" inside the container, not 127.0.0.1; and pin a version tag instead of latest once it works, so a rebuild does not change your server under you. The README also warns that containers have no IPv6 by default.
The same server in Xray-core, as an inbound:
{
"listen": "0.0.0.0",
"port": 8388,
"protocol": "shadowsocks",
"settings": {
"method": "2022-blake3-aes-128-gcm",
"password": "SltovJBRjzfjux/H+sIZdA==",
"network": "tcp,udp"
}
}
Xray-core 26.x prints a warning when it loads any Shadowsocks inbound: The feature Shadowsocks (with no Forward Secrecy, etc.) is deprecated, not recommended for using and might be removed. Please migrate to VLESS Encryption as soon as possible. It is a warning, not an error, and the server works.
How do multiple users share one Shadowsocks 2022 port?
With SIP023 identity headers. The server has its own key (the iPSK), and each user has a user key (the uPSK) of the same length. The client adds a 16-byte identity header: a hash of its user key, encrypted with a subkey of the server key. The server decrypts it, finds the user, and uses that user's key for the rest of the connection.
In shadowsocks-rust the users go in a users list:
{
"servers": [
{
"server": "0.0.0.0",
"server_port": 8388,
"method": "2022-blake3-aes-128-gcm",
"password": "SltovJBRjzfjux/H+sIZdA==",
"mode": "tcp_and_udp",
"users": [
{ "name": "alice", "password": "xIvhoe0OugfqiUyp59SgIg==" },
{ "name": "bob", "password": "c3Rm9QwLq1x0ZbUe7YkTnA==" }
]
}
]
}
Xray-core and sing-box use the same idea with their own users arrays. The part people miss is the client side: the client's password is both keys joined by a colon, server key first:
SltovJBRjzfjux/H+sIZdA==:xIvhoe0OugfqiUyp59SgIg==
I tested this across implementations: an sslocal client against an Xray-core multi-user inbound, and a sing-box client against a shadowsocks-rust multi-user server. Both worked with iPSK:uPSK. A client with only the server key, or with a user key the server does not know, fails. shadowsocks-rust logs both cases as tcp handshake failed. peer: ..., invalid client user identity followed by a short byte string. When you delete a user from the list, this is what their client produces.
How do I write a Shadowsocks 2022 ss:// link?
Put method:password in the link in plain text, percent-encoded, not in base64. SIP002 says that for 2022 methods the user info "MUST NOT be encoded with Base64URL". The base64 key contains /, + and =, which become %2F, %2B and %3D:
ss://2022-blake3-aes-128-gcm:SltovJBRjzfjux%2FH%2BsIZdA%3D%3D@vpn.yourdomain.com:8388#ss2022
For a multi-user server, the password is iPSK:uPSK, and the colon between the keys is encoded too:
ss://2022-blake3-aes-128-gcm:SltovJBRjzfjux%2FH%2BsIZdA%3D%3D%3AxIvhoe0OugfqiUyp59SgIg%3D%3D@vpn.yourdomain.com:8388#alice
Don't build these by hand. Python's standard library does the encoding:
python3 -c 'import urllib.parse as u; print("ss://2022-blake3-aes-128-gcm:" + u.quote("SltovJBRjzfjux/H+sIZdA==", safe="") + "@vpn.yourdomain.com:8388#ss2022")'
To check a link, ssurl -d '<link>' from shadowsocks-rust prints the method and the decoded password. For a multi-user link it prints only the user key as password; the server key is still used, it just isn't shown. I tested both multi-user forms (colon encoded as %3A and left as a plain :) with sslocal against a multi-user server, and both connected. If a 2022 link reaches you with base64 user info, shadowsocks-rust still parses it, because it tries both forms, but a client that follows SIP002 strictly may not. That is one reason the same link can work in one app and fail in another. If your links come from a subscription, the subscription decoding guide shows how to pull them out and read each one. Plugins go in the same link with /?plugin=, as described in the SIP003 plugins post.
How do I migrate from aes-256-gcm to Shadowsocks 2022?
Run both side by side, then move users, then turn the old one off. A 2017 method and a 2022 method cannot share one inbound, so the new one needs its own port.
- Check your clients first. shadowsocks-rust, Xray-core, sing-box and Mihomo all support the 2022 methods. Apps inherit support from the core they embed, so an app on an old core version may not. Test the actual app versions your users have.
- Add a 2022 server on a second port. In shadowsocks-rust, add a second entry to the
serverslist; in Xray-core, a second inbound. Generate a new key of the right length; an old text password is not a valid 2022 key. - Publish both. Put the new link next to the old one in the subscription, with a name that makes the difference clear.
- Watch the logs.
invalid timestamplines on the new port are clients with bad clocks. You did not have this failure before, so warn users about it. - Remove the old method once the old port's traffic stops.
How do I check a Shadowsocks 2022 server is really working?
Run a real client with the real link and send a request through it. A TCP port check tells you nothing, because the server accepts the TCP connection before it reads a single byte of the key. With the wrong key, the client's SOCKS port still accepts connections, and only the traffic through it fails. In my tests, curl through a client with the wrong key failed with SSL_ERROR_SYSCALL, while the server logged decrypt header chunk failed.
From a machine outside the server's network:
sslocal -b 127.0.0.1:1080 --server-url 'ss://2022-blake3-aes-128-gcm:SltovJBRjzfjux%2FH%2BsIZdA%3D%3D@vpn.yourdomain.com:8388#ss2022' &
curl -s -m 10 --socks5-hostname 127.0.0.1:1080 -o /dev/null -w '%{http_code}\n' https://www.gstatic.com/generate_204
You want 204. To test the UDP relay as well, use sslocal's tunnel mode to send a DNS query through the server (-U turns on TCP and UDP):
sslocal --protocol tunnel -b 127.0.0.1:5353 -f 1.1.1.1:53 -U \
-s vpn.yourdomain.com:8388 -m 2022-blake3-aes-128-gcm -k 'SltovJBRjzfjux/H+sIZdA=='
dig +short @127.0.0.1 -p 5353 www.gstatic.com A
If TCP works and DNS times out, UDP is blocked somewhere: the Docker port mapping, the host firewall or the provider's network. If both work from your test machine but users in one country fail, the problem may be blocking on their network rather than your server; the blocked IP guide explains how to tell the difference.
Full disclosure: TunnelHQ runs this check from outside on a schedule. You paste the ss:// link, and it connects with the real client flow and sends requests through the tunnel every 1 to 5 minutes, depending on plan. Shadowsocks monitoring explains the check, every plan starts with a 14-day free trial, and the free tester checks one link without an account.


