Trojan protocol explained: TLS, the password hash and fallback
Trojan is a proxy protocol that runs inside a normal TLS connection. After the TLS handshake, the client sends the hex SHA224 hash of its password (56 characters), a line break, a short SOCKS5-style request with the destination, another line break, and then the data. If the hash or the format is wrong, the server passes the connection to a fallback, usually a real web server, so a probe sees an ordinary HTTPS site. Trojan adds no encryption of its own: all of its security comes from TLS and a valid certificate.
ST Muntaha6 min read
Trojan is one of the simplest protocols in the V2Ray family, and that simplicity is the reason people misread its failures. A wrong password does not produce an authentication error. It produces a web page. An expired certificate does not show up in the server log at the default level. And an HTTPS check on port 443 can stay green while every Trojan user is cut off. This post explains the protocol from the spec, then the trojan-go extensions, the transports in Xray and sing-box, the trojan:// link, and how to test a server from the command line.
Versions: I tested with Xray-core 26.10.31 (the current release) and a sing-box 1.13.8 client, and checked sing-box 1.14.4's docs. The original implementations are trojan-gfw (last release v1.16.0, June 2020) and trojan-go (last release v0.10.6, September 2021).
What is the Trojan protocol?
Trojan is a proxy protocol designed to look exactly like HTTPS. It came from the trojan-gfw project, whose protocol page is still the spec. The design has two parts:
- Real TLS. The client makes a genuine TLS connection to the server, with a real certificate for a real domain. Everything after the handshake is encrypted by TLS.
- Fallback. Any connection that does not start with a valid Trojan request is handed to another service, normally a web server. The server then behaves "exactly the same as that endpoint" for anyone probing it.
Today the maintained implementations are in Xray-core, sing-box and Mihomo. The two original projects have had no release since 2020 and 2021.
Trojan is a proxy, not a VPN in the WireGuard sense. It carries individual TCP connections and UDP datagrams to destinations the client names. Apps that show a "VPN" switch run a TUN interface locally and send each connection through Trojan.
What does a Trojan request look like on the wire?
Inside TLS, the first thing the client sends is this structure, from the spec:
| Size | Field |
|---|---|
| 56 bytes | hex(SHA224(password)) |
| 2 bytes | CRLF (\r\n) |
| 1 byte | Command: 0x01 CONNECT or 0x03 UDP ASSOCIATE |
| 1 byte | Address type: 0x01 IPv4, 0x03 domain name, 0x04 IPv6 |
| variable | Destination address |
| 2 bytes | Destination port |
| 2 bytes | CRLF |
| variable | Payload |
The first packet carries payload, so a Trojan connection costs no extra round trip after TLS. For UDP, each datagram inside the stream is framed as address type, address, port, a 2-byte length, CRLF, then the payload.
You can compute the password hash yourself:
printf '%s' 'Pq7vR2kX9mWd4sLt' | openssl dgst -sha224 -r | cut -d' ' -f1
b96ce9b95221b441ac1975c17f7aa6b6fe01609b58271a1d229422e0
Use printf '%s', not echo, or the hash will include a newline. The 56-character length explains Xray's fallback rule. Xray's Trojan inbound docs say a connection falls back when "the length of the first packet < 58, OR the 57th byte is not \r ... OR authentication fails". 56 hex characters plus CRLF is 58 bytes.
Two properties follow from this format:
- There is no encryption in Trojan itself. The password hash, the destination and your data are protected only by TLS. Trojan without TLS sends all of it in clear text, which is why Xray-core refuses a Trojan client config with
"security": "none"to a public address:trojan without TLS is prohibited unless the server address is a private IP or domain. - The hash is not a secret. Anyone who sees it can use it, because the server compares hashes. It is safe only because TLS hides it, which makes certificate checking on the client essential.
How does Trojan fallback work?
When the server decides a connection is not Trojan, it opens a connection to the fallback address and relays the decrypted TLS traffic there. In trojan-gfw that is remote_addr and remote_port (default 127.0.0.1:80). In Xray it is the fallbacks list; in sing-box it is fallback and fallback_for_alpn.
I checked what that means in practice, with an Xray-core 26.10.31 server and a small web server as the fallback:
- A browser visiting
https://vpn.yourdomain.com/got the fallback web page. Xray loggedrejected proxy/trojan: not trojan protocol. - A Trojan client with a wrong or deleted password also got the fallback web server, not an error. Xray logged
rejected proxy/trojan: not a valid user. On the client side, curl through the tunnel failed withtlsv1 alert protocol versionfor an HTTPS URL andReceived HTTP/0.9 when not allowedfor an HTTP URL, because it was reading the web server's error page as proxied data.
The second point matters for support. When a user's Trojan password is removed or mistyped, they do not see "wrong password". They see strange TLS or HTTP errors, and the server log is the only place that says what happened.
The sing-box docs add an honest note on fallback: "There is no evidence that GFW detects and blocks Trojan servers based on HTTP responses." A fallback site still has practical value. It makes port 443 behave like a normal website, and it can be a real site you need anyway.
What did trojan-go add to Trojan?
trojan-go is a Go rewrite that stays compatible with Trojan and adds features the original lacked. From its documentation:
- WebSocket. A
websocketblock withenabled,pathandhost, so Trojan can pass through a CDN or a path-routing web server. The path must match on both sides. - Multiplexing. A
muxblock (enabled,concurrencydefault 8,idle_timeout) that carries many TCP connections in one TLS connection. Only the client turns it on; the server adapts. - A Shadowsocks AEAD layer. A
shadowsocksblock that adds a second encryption layer, meant for traffic that crosses an untrusted CDN. - Transport plugins. A
transport_pluginblock that can run SIP003 Shadowsocks plugins or replace TLS with plain TCP behind nginx. - Fallback on TLS failure.
fallback_addrandfallback_porthandle connections that fail the TLS handshake itself, in addition to the normal fallback.
The WebSocket block goes in both the server and the client config:
"websocket": {
"enabled": true,
"path": "/tj-7Rk2",
"host": "vpn.yourdomain.com"
}
These extras are specific to trojan-go. Its own URL draft says that once a server uses features that plain Trojan clients don't support, the link must use the trojan-go:// scheme instead of trojan://. A standard Trojan client cannot talk to a trojan-go server that requires its Shadowsocks layer. With no release since 2021, I would not start a new deployment on trojan-go; Xray-core and sing-box cover WebSocket and multiplexing natively.
Which transports can Trojan use in Xray-core and sing-box?
In Xray-core, Trojan works with the raw TCP, XHTTP, gRPC, WebSocket, HTTPUpgrade, mKCP and Hysteria transports. The security layer can be TLS or REALITY; none is allowed only for private addresses. In sing-box, Trojan takes a V2Ray transport (http, ws, quic, grpc, httpupgrade) and a tls block, and its inbound supports fallback.
Which one to pick depends on the path between users and the server:
- Raw TCP with TLS is the original Trojan and the simplest. It cannot pass through a CDN, because the CDN terminates TLS and Trojan's bytes are not HTTP.
- WebSocket, gRPC or XHTTP with TLS pass through CDNs and reverse proxies that route by path or service name.
Xray-core 26.x prints deprecation warnings for some of these. Loading a Trojan inbound prints The feature Trojan (with no Flow, etc.) is deprecated, not recommended for using and might be removed. Please migrate to VLESS with Flow & Seed as soon as possible. WebSocket and gRPC get similar warnings that point to XHTTP. These are warnings, not errors. The configs below run fine on 26.10.31, but it tells you where Xray's developers are going.
A minimal Xray-core server with TLS and a fallback web server on port 8080:
{
"log": {"loglevel": "warning"},
"inbounds": [
{
"listen": "0.0.0.0",
"port": 443,
"protocol": "trojan",
"settings": {
"clients": [
{"password": "Pq7vR2kX9mWd4sLt", "email": "alice@vpn.yourdomain.com"}
],
"fallbacks": [
{"dest": 8080}
]
},
"streamSettings": {
"security": "tls",
"tlsSettings": {
"alpn": ["http/1.1"],
"certificates": [
{"certificateFile": "/etc/ssl/vpn/fullchain.pem", "keyFile": "/etc/ssl/vpn/privkey.pem"}
]
}
}
}
],
"outbounds": [{"protocol": "freedom"}]
}
The current docs call the user list users. Xray-core 26.5.9 and later accept both names; older versions only know clients, so clients works everywhere. A matching client outbound:
{
"protocol": "trojan",
"settings": {
"address": "vpn.yourdomain.com",
"port": 443,
"password": "Pq7vR2kX9mWd4sLt"
},
"streamSettings": {
"security": "tls",
"tlsSettings": {
"serverName": "vpn.yourdomain.com",
"fingerprint": "chrome"
}
}
}
This flat settings form needs Xray-core 25.10.15 or later; older cores want a servers array. For WebSocket, add "network": "ws" and "wsSettings": {"path": "/tj"} to streamSettings on both sides. For gRPC, "network": "grpc" and "grpcSettings": {"serviceName": "tjgrpc"}, and change the server's alpn to ["h2"], because gRPC runs over HTTP/2. The same WebSocket client in sing-box, which I tested against the Xray server:
{
"type": "trojan",
"server": "vpn.yourdomain.com",
"server_port": 443,
"password": "Pq7vR2kX9mWd4sLt",
"tls": {"enabled": true, "server_name": "vpn.yourdomain.com"},
"transport": {"type": "ws", "path": "/tj"}
}
What does a trojan:// link contain?
The original trojan-gfw scheme is only trojan://password@host:port, with the password URL-encoded. V2Ray-family clients add the same query fields they use for vless:// links: security, sni, fp, alpn, type, and the transport fields host, path and serviceName. These follow the Xray share link proposal in discussion #716.
trojan://Pq7vR2kX9mWd4sLt@vpn.yourdomain.com:443?security=tls&sni=vpn.yourdomain.com&fp=chrome&type=tcp#trojan-tls
trojan://Pq7vR2kX9mWd4sLt@vpn.yourdomain.com:443?security=tls&sni=vpn.yourdomain.com&type=ws&host=vpn.yourdomain.com&path=%2Ftj#trojan-ws
trojan://Pq7vR2kX9mWd4sLt@vpn.yourdomain.com:443?security=tls&sni=vpn.yourdomain.com&type=grpc&serviceName=tjgrpc&mode=gun#trojan-grpc
Percent-encode a password that contains @, :, /, # or ?, or the client will split the link in the wrong place.
One change breaks many older links. Xray-core 26.2.6 removed allowInsecure, the setting behind allowInsecure=1 in links for servers with self-signed certificates. It stayed usable with a delay until 1 June 2026. On a current core, a config with it fails with The feature "allowInsecure" has been removed and migrated to "pinnedPeerCertSha256"(pcs) and "verifyPeerCertByName"(vcn). The replacement is to pin the certificate's SHA-256 hash, pinnedPeerCertSha256 in the config or pcs= in the link. xray tls hash --cert fullchain.pem prints it.
What breaks on a Trojan server?
These are the failures I check for, with the messages from my tests on Xray-core 26.10.31.
1. The certificate expired. The server keeps running and logs nothing useful. Clients that verify certificates fail; at Xray's info log level the client shows tls: failed to verify certificate: x509: certificate has expired or is not yet valid: current time 2026-11-01T20:40:21+05:00 is after 2026-10-01T00:00:00Z. In my experience this is the most common Trojan outage, because certificate renewal is a cron job that nobody watches.
2. The SNI does not match the certificate. After a domain change, or a link with the wrong sni: x509: certificate is valid for vpn.yourdomain.com, not sub.yourdomain.com.
3. The fallback is down. The fallback web server crashed or listens on another port. Browsers get an empty reply, Xray logs (at info level) proxy/trojan: failed to dial to localhost:8080 > common/retry: [dial tcp 127.0.0.1:8080: connect: connection refused], and Trojan clients keep working. Your website looks dead while the proxy is fine.
4. The proxy is broken behind a healthy fallback. The reverse case, and the dangerous one for monitoring. A user was removed, the password was changed in the panel, or the server's outbound is blocked. The fallback site still answers on 443, so an HTTPS uptime check returns 200 and stays green while Trojan users fail.
5. Old links with allowInsecure. As above: fine on old cores, refused by current Xray-core.
6. TLS-in-TLS fingerprinting. When the traffic inside Trojan is itself HTTPS, the pattern of a TLS handshake inside a TLS connection can be recognised. A USENIX Security 2024 paper showed this works against many proxy protocols. Xray's Trojan docs warn about it directly: "In public environments, Mux is also required; otherwise, once the inner payload is itself TLS, it becomes TiT and can be easily detected." If your users are on networks that block this way, it will look like random connection drops, not like an error.
How do I test a Trojan server from the command line?
Test the TLS layer first, then the fallback, then a real Trojan request. You need only openssl and curl.
TLS and the certificate:
echo | openssl s_client -connect vpn.yourdomain.com:443 -servername vpn.yourdomain.com 2>/dev/null | openssl x509 -noout -subject -enddate
Xray-core also has xray tls ping vpn.yourdomain.com:443, which shows the TLS version, the certificate's names, its SHA-256 hash, and whether verification fails.
The fallback: curl -sS https://vpn.yourdomain.com/ should return your fallback site.
A real Trojan request, by hand. This short script sends the hash, a CONNECT request for www.gstatic.com:80 and an HTTP request, all inside TLS, and prints the first line of the answer:
#!/bin/sh
# usage: trojan-probe.sh HOST PORT SNI PASSWORD
HOST=$1; PORT=$2; SNI=$3; PASS=$4
HASH=$(printf '%s' "$PASS" | openssl dgst -sha224 -r | cut -d' ' -f1)
{
printf '%s\r\n' "$HASH"
# CMD 01 (CONNECT), ATYP 03 (domain), length 15, "www.gstatic.com", port 80 (0x0050)
printf '\001\003\017www.gstatic.com\000\120\r\n'
printf 'GET /generate_204 HTTP/1.1\r\nHost: www.gstatic.com\r\nConnection: close\r\n\r\n'
sleep 3
} | openssl s_client -quiet -connect "$HOST:$PORT" -servername "$SNI" 2>/dev/null | head -n 1
$ ./trojan-probe.sh vpn.yourdomain.com 443 vpn.yourdomain.com 'Pq7vR2kX9mWd4sLt'
HTTP/1.1 204 No Content
$ ./trojan-probe.sh vpn.yourdomain.com 443 vpn.yourdomain.com 'wrong-password'
<!DOCTYPE HTML>
HTTP/1.1 204 No Content means TLS, the password and the server's outbound all work. HTML means the server did not accept the password and the fallback answered instead. Nothing at all means TLS failed or the fallback is down. The script tests raw TCP Trojan only; for WebSocket or gRPC, use a real client.
A full client test. Run Xray-core or sing-box with the client config above and a local SOCKS inbound, then:
curl -s -m 10 --socks5-hostname 127.0.0.1:1080 -o /dev/null -w '%{http_code}\n' https://www.gstatic.com/generate_204
If you are choosing between Trojan and VLESS for a new server, the VLESS explainer covers what VLESS adds: the Vision flow and REALITY, which removes the need for your own certificate. Trojan's strength is that it is simple and widely supported. Its weak spot is that it depends completely on a certificate that someone has to renew.
Full disclosure: TunnelHQ monitors Trojan servers with this same sequence from outside your network. You paste the trojan:// link, and it completes the TLS handshake, sends the password and a real request through the tunnel every 1 to 5 minutes, depending on plan. A server whose proxy is broken behind a working fallback site fails the check. Trojan monitoring explains the check, every plan starts with a 14-day free trial, and the free tester checks one link without an account.


