gitwtfhub

wtf is ech-tls-tunnel?

shadowsocks/ech-tls-tunnel — explained in plain English

Analysis updated 2026-05-18

13RustAudience · developerComplexity · 4/5Setup · hard

TL;DR

A Shadowsocks plugin that disguises proxy traffic as ordinary HTTPS by hiding the real destination using Encrypted Client Hello.

Mindmap

mindmap
  root((ech-tls-tunnel))
    What it does
      Disguises proxy traffic
      Hides tunnel domain
    Tech stack
      Rust
      BoringSSL
      TLS ECH
    How it works
      WebSocket wrapping
      Automatic Let's Encrypt cert
      Fake error page for probes
    Use cases
      Bypass traffic inspection
      Resist basic probing
    Limits
      Not against advanced traffic analysis

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Hide a Shadowsocks tunnel's real destination from network observers using ECH.

REASON 2

Automatically obtain and renew a TLS certificate for the tunnel server on port 443 only.

REASON 3

Present a fake error page to probes that don't know the plugin's secret path.

What's in the stack?

RustBoringSSLTLSWebSocket

How it stacks up

shadowsocks/ech-tls-tunnelanthropics/cargo-nix-pluginbrassworks-smp/brassworkslauncher
Stars131313
LanguageRustRustRust
Setup difficultyhardhard
Complexity4/54/53/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · hard Time to first run · 1h+

Requires running on both server and client with port 443 available for automatic certificate issuance.

Wtf does this do

This is a plugin for Shadowsocks, a tool people use to route internet traffic through a server when direct access is restricted. The plugin's job is to disguise that traffic so it looks, to anyone watching the network, like an ordinary HTTPS connection to a harmless website rather than a tunnel. It does this by wrapping each connection in a combination of two technologies: WebSockets (a way to keep a two-way connection open inside normal web traffic) and a TLS feature called Encrypted Client Hello (ECH). When a browser or app connects to a website over TLS, it normally sends the destination's name in plain text at the start of the handshake so routing equipment can direct the request. ECH encrypts that name. This plugin uses ECH so the real tunnel domain is hidden, and only the decoy domain name is visible to outside observers. On the server side, the plugin automatically requests and renews a TLS certificate from Let's Encrypt using a method that works entirely on port 443, so no other ports need to be open. Any connection that does not arrive on the correct secret path gets a fake error page that mimics a default web server response, making it harder for automated probes to detect that a tunnel is running. To use it, you run the plugin alongside Shadowsocks on both a server and a client device. The server generates a cryptographic key pair, and the client receives a small configuration string derived from that key pair. Once both sides are configured, the client gets a local proxy that routes its traffic through the disguised connection. The plugin is written in Rust and uses BoringSSL, a TLS library from Cloudflare, for the ECH functionality. It is intended to resist passive traffic inspection and basic active probing, but is not designed to defeat more sophisticated traffic analysis techniques.

Yoink these prompts

Prompt 1
Walk me through setting up this plugin alongside Shadowsocks on a server and client.
Prompt 2
How does Encrypted Client Hello hide the tunnel domain from network observers here?
Prompt 3
Show me how the server generates a key pair and what config string the client needs.
Prompt 4
Help me understand what happens when a probe connects without the correct secret path.

Frequently asked questions

wtf is ech-tls-tunnel?

A Shadowsocks plugin that disguises proxy traffic as ordinary HTTPS by hiding the real destination using Encrypted Client Hello.

What language is ech-tls-tunnel written in?

Mainly Rust. The stack also includes Rust, BoringSSL, TLS.

How hard is ech-tls-tunnel to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is ech-tls-tunnel for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.