README.md
1[](https://travis-ci.org/Psiphon-Labs/psiphon-tunnel-core) [](https://coveralls.io/github/Psiphon-Labs/psiphon-tunnel-core?branch=master)
2
3Psiphon Tunnel Core README
4================================================================================
5
6Overview
7--------------------------------------------------------------------------------
8
9Psiphon is an Internet censorship circumvention system.
10
11The tunnel core project includes a tunneling client and server, which together implement key aspects of evading blocking and relaying client traffic through Psiphon and beyond censorship.
12
13All Psiphon open source projects, including the complete open source code for Android, iOS, and Windows clients may be found at [www.github.com/Psiphon-Inc/psiphon](https://www.github.com/Psiphon-Inc/psiphon).
14
15For more information about Psiphon Inc., please visit our web site at [www.psiphon.ca](https://www.psiphon.ca).
16
17```
18psiphon-tunnel-core
19 └── ClientLibrary General client libraries
20 └── ConsoleClient CLI client program
21 └── MobileLibrary Android/iOS client libraries
22 └── Server Server program
23 └── psiphon Client code package
24 └── common\... Common code packages
25 └── server Server code package
26```
27
28
29Technical Summary
30--------------------------------------------------------------------------------
31
32Psiphon tunnels Internet traffic through a network of proxy servers with the goal of circumventing Internet censorship.
33
34Users run a client program which connects to a proxy server and routes client host Internet traffic through a tunnel established to the proxy. Traffic egresses from the proxy, which is located beyond the entity censoring the user's Internet.
35
36### Traffic Routing
37
38Psiphon has multiple routing modes:
39- Port forward mode: the client runs localhost SOCKS and HTTPS proxies and the client host or individual apps are configured to use these local proxies; each connection to a local proxy is related through the tunnel to the server.
40- Packet tunnel mode: the client relays IP packets between a host "tun" device and the server.
41
42### Traffic Security
43
44At 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 clients connect only to authentic Psiphon servers.
45
46### Server Entries
47
48Server connection information, including SSH public keys, addresses, and obfuscation parameters are distributed to clients in the form of a list of "server entries". Each server entry fully describes one Psiphon server.
49
50Clients binaries may be built with embedded server lists. Clients may also "discover" new server entries when they successfully connect to a server.
51
52Psiphon also uses out-of-band server list delivery mechanisms, including fetching server lists from drops which are configured in the clients. All out-of-band mechanisms perform additional server list verification using public keys configured in the clients.
53
54All delivery mechanisms use partitioning to prevent trivial enumeration of all server entries.
55
56Some out-of-band server server lists, called ["obfuscated server lists"](psiphon/common/osl/README.md), are encrypted and only clients that have been granted sufficient required keys can access the included servers.
57
58### Traffic Obfuscation
59
60The core SSH protocol is wrapped in optional obfuscation layers which transform traffic in order to evade blocking of Psiphon servers. Mitigated attacks include endpoint blocking, keyword-based blocking, DPI-based blocking, and more.
61
62Obfuscation techniques include:
63- Making traffic on the wire look fully random.
64- Making traffic on the wire look like popular implementations of popular protocols.
65- Performing traffic shaping to obscure the size and timing properties of encapsulated traffic.
66- Connecting to proxy servers indirectly, via intermediaries.
67
68### Circumvention Optimizations
69
70To minimize connection time, Psiphon makes multiple concurrent connection attempts to different servers using different obfuscation techniques. This process generally selects the fastest working obfuscation technique and server. This process is how Psiphon load balances clients across its network of servers without using a centralized load balancing mechanism.
71
72A successful connection may be subject to further quality tests before selection. The Psiphon client remembers which servers and which obfuscation techniques and parameters are successful and prioritizes using the same on subsequent connections.
73
74Psiphon uses a mechanism called ["tactics"](psiphon/common/tactics) to remotely deliver targeted, optimized configuration and obfuscation parameters to clients.
75
76
77Running Psiphon
78--------------------------------------------------------------------------------
79
80### Get the programs
81
82Official binaries are avaiable at:
83- https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries
84- https://github.com/Psiphon-Labs/psiphon-tunnel-core/releases, for libraries
85
86For these instructions, use:
87- [psiphond](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/psiphond/psiphond)
88- [ConsoleClient](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/linux/psiphon-tunnel-core-x86_64)
89
90### Generate configuration data
91
92Run the "generate" mode of psiphond to generate configs, setting the IP address as appropriate; this is the address the client will use to connect to the server.
93
94```
95$ ./psiphond -ipaddress 127.0.0.1 -protocol OSSH:9999 -protocol generate
96
97$ ls
98psiphond
99psiphond.config
100psiphond-osl.config
101psiphond-tactics.config
102psiphond-traffic-rules.config
103server-entry.dat
104```
105
106Create a client config file, copying the contents of `server-entry.dat` to the `TargetServerEntry` field.
107
108```
109$ cat server-entry.dat
1103132372e302e302e31202020207b22746167223a22222c2269[...]
111
112$ cat client.config
113{
114 "LocalHttpProxyPort" : 8080,
115 "LocalSocksProxyPort" : 1080,
116
117 "PropagationChannelId" : "24BCA4EE20BEB92C",
118 "SponsorId" : "721AE60D76700F5A",
119
120 "TargetServerEntry" : "3132372e302e302e31202020207b22746167223a22222c2269[...]"
121}
122```
123
124### Run psiphond
125
126```
127$ ./psiphond run
128{"localAddress":"127.0.0.1:9999","msg":"listening","tunnelProtocol":"OSSH",[...]}
129{"localAddress":"127.0.0.1:9999","msg":"running","tunnelProtocol":"OSSH",[...]}
130[...]
131```
132
133### Run the console client
134
135```
136$ ./ConsoleClient -config ./client.config
137{"data":{"port":1080},"noticeType":"ListeningSocksProxyPort",[...]}
138{"data":{"port":8080},"noticeType":"ListeningHttpProxyPort",[...]}
139[...]
140{"data":{"count":1},"noticeType":"Tunnels",[...]}
141```
142
143### Tunnel traffic through Psiphon
144
145Use the local SOCKS proxy (port 1080) or HTTP proxy (port 8080) to tunnel traffic.
146
147
148Acknowledgements
149--------------------------------------------------------------------------------
150
151Psiphon Tunnel Core uses:
152
153* [Go](https://golang.org)
154* [agl/ed25519](https://github.com/agl/ed25519)
155* [AndreasBriese/bbloom](https://github.com/AndreasBriese/bbloom)
156* [aristanetworks/goarista/monotime](https://github.com/aristanetworks/goarista)
157* [armon/go-proxyproto](https://github.com/armon/go-proxyproto)
158* [armon/go-socks](https://github.com/armon/go-socks5)
159* [bifurcation/mint](https://github.com/bifurcation/mint)
160* [boltdb/bolt](https://github.com/boltdb/bolt)
161* [cheekybits/genny/generic](https://github.com/cheekybits/genny/generic)
162* [cloudflare/tls-tris](https://github.com/cloudflare/tls-tris)
163* [codahale/sss](https://github.com/codahale/sss)
164* [cognusion/go-cache-lru](https://github.com/cognusion/go-cache-lru)
165* [creack/goselect](https://github.com/creack/goselect)
166* [davecgh/go-spew/spew](https://github.com/davecgh/go-spew/spew)
167* [deckarep/golang-set](https://github.com/deckarep/golang-set)
168* [dgraph-io/badger](https://github.com/dgraph-io/badger)
169* [dgryski/go-farm](https://github.com/dgryski/go-farm)
170* [elazarl/goproxy](https://github.com/elazarl/goproxy)
171* [florianl/go-nfqueue](https://github.com/florianl/go-nfqueue)
172* [gobwas/glob](https://github.com/gobwas/glob)
173* [golang/protobuf](https://github.com/golang/protobuf)
174* [google/gopacket](https://github.com/google/gopacket)
175* [grafov/m3u8](https://github.com/grafov/m3u8)
176* [hashicorp/golang-lru](https://github.com/hashicorp/golang-lru)
177* [juju/ratelimit](https://github.com/juju/ratelimit)
178* [kardianos/osext](https://github.com/kardianos/osext)
179* [groupcache/lru]("github.com/golang/groupcache/lru")
180* [lucas-clemente/quic-go](https://github.com/lucas-clemente/quic-go)
181* [marusama/semaphore](https://github.com/marusama/semaphore)
182* [mdlayher/netlink)](https://github.com/mdlayher/netlink)
183* [miekg/dns](https://github.com/miekg/dns)
184* [mitchellh/panicwrap](https://github.com/mitchellh/panicwrap)
185* [oschwald/maxminddb-golang](https://github.com/oschwald/maxminddb-golang)
186* [patrickmn/go-cache](https://github.com/patrickmn/go-cache)
187* [pkg/errors](https://github.com/pkg/errors)
188* [pmezard/go-difflib](https://github.com/pmezard/go-difflib)
189* [redjack/marionette](https://github.com/redjack/marionette)
190* [refraction-networking/gotapdance](https://github.com/refraction-networking/gotapdance)
191* [refraction-networking/utls](https://github.com/refraction-networking/utls)
192* [ryanuber/go-glob](https://github.com/ryanuber/go-glob)
193* [sergeyfrolov/bsbuffer](https://github.com/sergeyfrolov/bsbuffer)
194* [sirupsen/logrus](https://github.com/sirupsen/logrus)
195* [stretchr/testify](https://github.com/stretchr/testify)
196* [syndtr/gocapability/capability](https://github.com/syndtr/gocapability/capability)
197* [ThomsonReutersEikon/go-ntlm](https://github.com/ThomsonReutersEikon/go-ntlm)
198* [wader/filtertransport](https://github.com/wader/filtertransport)
199* [Yawning/chacha20](https://github.com/Yawning/chacha20)
200* [Yawning/goptlib](https://github.com/Yawning/goptlib)
201* [yawning/obfs4](https://gitlab.com/yawning/obfs4)
202* [zach-klippenstein/goregen](https://github.com/zach-klippenstein/goregen)
203* [zap](https://go.uber.org/zap)
204
205
){kind=link}
){kind=link}