psiphon-tunnel-core is the client and server behind a censorship circumvention network

How the tunnel is built

Psiphon tunnels Internet traffic through a network of proxy servers with the goal of circumventing Internet censorship. The mechanics are described plainly: users run a client program which connects to a proxy server and routes client host Internet traffic through a tunnel established to the proxy, and traffic egresses from the proxy, which is located beyond the entity censoring the user's Internet. At the core of all tunnels is an SSH connection which protects the confidentiality and integrity of client traffic between the client host and the proxy server. Clients authenticate the SSH server using pre-shared public keys, ensuring that clients connect only to authentic Psiphon servers. So the transport is SSH, the censorship is assumed to be an active one, and the authentication model is a fixed set of public keys rather than a certificate authority.

Two routing modes, local proxy or packet tunnel

There are two ways to get traffic into the tunnel. In port forward mode, the client runs localhost SOCKS and HTTPS proxies, and the client host or individual applications are configured to use these local proxies, with each connection to a local proxy related through the tunnel to the server. In packet tunnel mode, the client relays IP packets between a host tun device and the server, which is the transparent option that does not require the applications to know anything about a proxy. The choice matters in practice: the proxy mode works for a browser you configure by hand, and the packet mode works for everything on the machine without configuration, at the cost of needing the tun device and the privileges to create it.

Server entries, discovery and encrypted lists

The set of servers a client can reach is data, and the distribution of that data is where much of the work is. Server connection information, including SSH public keys, addresses and obfuscation parameters, is distributed to clients in the form of a list of server entries, and each server entry fully describes one Psiphon server. Client binaries may be built with embedded server lists, and clients may also discover new server entries when they successfully connect to a server. Beyond that, Psiphon uses out-of-band server list delivery mechanisms, including fetching server lists from drops which are configured in the clients, and all out-of-band mechanisms perform additional server list verification using public keys configured in the clients. All delivery mechanisms use partitioning to prevent trivial enumeration of all server entries, and some out-of-band lists, called obfuscated server lists, are encrypted so that only clients granted sufficient keys can access the included servers.

Obfuscation as a set of separate techniques

The core SSH protocol is wrapped in optional obfuscation layers which transform traffic in order to evade blocking of Psiphon servers, and the README names the attacks this is aimed at: endpoint blocking, keyword-based blocking, DPI-based blocking and more. The techniques are listed as four options. Traffic on the wire can look fully random. It can look like popular implementations of popular protocols, which defeats a censor who is looking for something that does not match anything they know. Traffic shaping can obscure the size and timing properties of the encapsulated traffic, which defeats a censor who is fingerprinting on packet size. And connecting to proxy servers indirectly, via intermediaries, defeats a censor who blocks the addresses he can see. Each is optional and each is a different assumption about what the adversary can observe, which is why the client tries several at once.

Concurrent attempts replace a central load balancer

The circumvention optimisation is a piece of distributed systems design. To minimise connection time, Psiphon makes multiple concurrent connection attempts to different servers using different obfuscation techniques, and this process generally selects the fastest working obfuscation technique and server. The README notes that this is how Psiphon load balances clients across its network of servers without using a centralised load balancing mechanism, which matters because a central component is a single point of failure for a censorship circumvention system. A successful connection may be subject to further quality tests before selection, and the client remembers which servers and which obfuscation techniques and parameters are successful, prioritising the same on subsequent connections. On top of that, the mechanism called tactics allows targeted, optimised configuration and obfuscation parameters to be delivered remotely to clients, so the network can be retuned without shipping a new binary.

The repository holds five deliverables

The layout in the README shows what the project actually ships:

psiphon-tunnel-core
  └── ClientLibrary  General client libraries
  └── ConsoleClient  CLI client program
  └── MobileLibrary  Android/iOS client libraries
  └── Server         Server program
  └── psiphon        Client code package
    └── common\...   Common code packages
    └── server       Server code package

There is a general client library, a command line client, mobile client libraries for Android and iOS, a server program, and the shared `psiphon` package holding the common code and the server code package. The top level of the repository matches: a `ClientLibrary/` directory, `ConsoleClient/`, `MobileLibrary/`, `Server/`, and the `psiphon/` package. The README also notes that the complete open source code for the Android, iOS and Windows clients is found in a separate organisation, and that a Go module may be imported into other Go projects, so the tunnel core is usable as a library rather than only as the programs in this repository.

Building and running it locally

The running instructions start by getting the programs, from the binaries repository or from the releases for the libraries, and then generating configuration data with the generate mode of the server daemon:

$ ./psiphond -ipaddress 127.0.0.1 -protocol OSSH:9999 generate

That produces a set of files, including the server entry data, the obfuscated server list config and the tactics config. You then copy the contents of `server-entry.dat` into the `TargetServerEntry` field of a client config, which also carries the local proxy ports, a propagation channel identifier and a sponsor identifier:

$ cat client.config
{
    "LocalHttpProxyPort" : 8080,
    "LocalSocksProxyPort" : 1080,

    "PropagationChannelId" : "24BCA4EE20BEB92C",
    "SponsorId" : "721AE60D76700F5A",

    "TargetServerEntry" : "3132372e302e302e31202020207b22746167223a22222c2269[...]"
}

With that in place, the server runs and the console client connects, and traffic goes through the local SOCKS proxy on port 1080 or the HTTP proxy on port 8080. The module itself declares go 1.26.0 with a go1.26.9 toolchain directive, and the dependency list is heavily forked, with Psiphon maintaining its own versions of the TLS, QUIC, ICE and WebRTC libraries, which is what lets the client control the fingerprints it presents.

Editorial conclusion

Adopt psiphon-tunnel-core if you are building a client for the Psiphon network, since it implements the tunnelling, the server entry distribution and the obfuscation layer that the official clients rely on. Do not adopt it as a general purpose VPN, because the design assumes a censoring adversary and its security model, including pre-shared public key authentication and encrypted server lists, is specific to that setting. Verify first which Go toolchain you need, since the module declares go 1.26.0 with a go1.26.9 toolchain directive, and that the build tags you need are enabled, since several dependencies are replaced only when a specific build tag is set.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Psiphon-Labs/psiphon-tunnel-core on GitHub
4. README
5. Releases