github.com/psiphon-labs/psiphon-tunnel-core@v2.0.28+incompatible/README.md (about)

     1  [![CI](https://github.com/Psiphon-Labs/psiphon-tunnel-core/actions/workflows/tests.yml/badge.svg)](https://github.com/Psiphon-Labs/psiphon-tunnel-core/actions/workflows/tests.yml) [![Coverage Status](https://coveralls.io/repos/github/Psiphon-Labs/psiphon-tunnel-core/badge.svg?branch=master)](https://coveralls.io/github/Psiphon-Labs/psiphon-tunnel-core?branch=master)
     2  
     3  
     4  Psiphon Tunnel Core README
     5  ================================================================================
     6  
     7  Overview
     8  --------------------------------------------------------------------------------
     9  
    10  Psiphon is an Internet censorship circumvention system.
    11  
    12  The 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.
    13  
    14  All 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).
    15  
    16  For more information about Psiphon Inc., please visit our web site at [www.psiphon.ca](https://www.psiphon.ca).
    17  
    18  ```
    19  psiphon-tunnel-core
    20    └── ClientLibrary  General client libraries
    21    └── ConsoleClient  CLI client program
    22    └── MobileLibrary  Android/iOS client libraries
    23    └── Server         Server program
    24    └── psiphon        Client code package
    25      └── common\...   Common code packages
    26      └── server       Server code package
    27  ```
    28  
    29  
    30  Technical Summary
    31  --------------------------------------------------------------------------------
    32  
    33  Psiphon tunnels Internet traffic through a network of proxy servers with the goal of circumventing Internet censorship.
    34  
    35  Users 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.
    36  
    37  ### Traffic Routing
    38  
    39  Psiphon has multiple routing modes:
    40  - 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.
    41  - Packet tunnel mode: the client relays IP packets between a host "tun" device and the server.
    42  
    43  ### Traffic Security
    44  
    45  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 clients connect only to authentic Psiphon servers.
    46  
    47  ### Server Entries
    48  
    49  Server 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.
    50  
    51  Clients binaries may be built with embedded server lists. Clients may also "discover" new server entries when they successfully connect to a server.
    52  
    53  Psiphon 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.
    54  
    55  All delivery mechanisms use partitioning to prevent trivial enumeration of all server entries.
    56  
    57  Some 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.
    58  
    59  ### Traffic Obfuscation
    60  
    61  The 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.
    62  
    63  Obfuscation techniques include:
    64  - Making traffic on the wire look fully random.
    65  - Making traffic on the wire look like popular implementations of popular protocols.
    66  - Performing traffic shaping to obscure the size and timing properties of encapsulated traffic.
    67  - Connecting to proxy servers indirectly, via intermediaries.
    68  
    69  ### Circumvention Optimizations
    70  
    71  To 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.
    72  
    73  A 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.
    74  
    75  Psiphon uses a mechanism called ["tactics"](psiphon/common/tactics) to remotely deliver targeted, optimized configuration and obfuscation parameters to clients.
    76  
    77  
    78  Running Psiphon
    79  --------------------------------------------------------------------------------
    80  
    81  ### Get the programs
    82  
    83  Official binaries are avaiable at:
    84  - https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries
    85  - https://github.com/Psiphon-Labs/psiphon-tunnel-core/releases, for libraries
    86  
    87  For these instructions, use:
    88  - [psiphond](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/psiphond/psiphond)
    89  - [ConsoleClient](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/linux/psiphon-tunnel-core-x86_64)
    90  
    91  ### Generate configuration data
    92  
    93  Run 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.
    94  
    95  ```
    96  $ ./psiphond -ipaddress 127.0.0.1 -protocol OSSH:9999 -protocol generate
    97  
    98  $ ls
    99  psiphond
   100  psiphond.config
   101  psiphond-osl.config
   102  psiphond-tactics.config
   103  psiphond-traffic-rules.config
   104  server-entry.dat
   105  ```
   106  
   107  Create a client config file, copying the contents of `server-entry.dat` to the `TargetServerEntry` field.
   108  
   109  ```
   110  $ cat server-entry.dat 
   111  3132372e302e302e31202020207b22746167223a22222c2269[...]
   112  
   113  $ cat client.config
   114  {
   115      "LocalHttpProxyPort" : 8080,
   116      "LocalSocksProxyPort" : 1080,
   117  
   118      "PropagationChannelId" : "24BCA4EE20BEB92C",
   119      "SponsorId" : "721AE60D76700F5A",
   120  
   121      "TargetServerEntry" : "3132372e302e302e31202020207b22746167223a22222c2269[...]"
   122  }
   123  ```
   124  
   125  ### Run psiphond
   126  
   127  ```
   128  $ ./psiphond run
   129  {"localAddress":"127.0.0.1:9999","msg":"listening","tunnelProtocol":"OSSH",[...]}
   130  {"localAddress":"127.0.0.1:9999","msg":"running","tunnelProtocol":"OSSH",[...]}
   131  [...]
   132  ```
   133  
   134  ### Run the console client
   135  
   136  ```
   137  $ ./ConsoleClient -config ./client.config
   138  {"data":{"port":1080},"noticeType":"ListeningSocksProxyPort",[...]}
   139  {"data":{"port":8080},"noticeType":"ListeningHttpProxyPort",[...]}
   140  [...]
   141  {"data":{"count":1},"noticeType":"Tunnels",[...]}
   142  ```
   143  
   144  ### Tunnel traffic through Psiphon
   145  
   146  Use the local SOCKS proxy (port 1080) or HTTP proxy (port 8080) to tunnel traffic.
   147  
   148  
   149  Acknowledgements
   150  --------------------------------------------------------------------------------
   151  
   152  Psiphon Tunnel Core uses:
   153  
   154  * [Go](https://golang.org)
   155  * [agl/ed25519](https://github.com/agl/ed25519)
   156  * [AndreasBriese/bbloom](https://github.com/AndreasBriese/bbloom)
   157  * [aristanetworks/goarista/monotime](https://github.com/aristanetworks/goarista)
   158  * [armon/go-proxyproto](https://github.com/armon/go-proxyproto)
   159  * [armon/go-socks](https://github.com/armon/go-socks5)
   160  * [bifurcation/mint](https://github.com/bifurcation/mint)
   161  * [boltdb/bolt](https://github.com/boltdb/bolt)
   162  * [cheekybits/genny/generic](https://github.com/cheekybits/genny/generic)
   163  * [cloudflare/tls-tris](https://github.com/cloudflare/tls-tris)
   164  * [codahale/sss](https://github.com/codahale/sss)
   165  * [cognusion/go-cache-lru](https://github.com/cognusion/go-cache-lru)
   166  * [creack/goselect](https://github.com/creack/goselect)
   167  * [davecgh/go-spew/spew](https://github.com/davecgh/go-spew/spew)
   168  * [deckarep/golang-set](https://github.com/deckarep/golang-set)
   169  * [dgraph-io/badger](https://github.com/dgraph-io/badger)
   170  * [dgryski/go-farm](https://github.com/dgryski/go-farm)
   171  * [elazarl/goproxy](https://github.com/elazarl/goproxy)
   172  * [florianl/go-nfqueue](https://github.com/florianl/go-nfqueue)
   173  * [gobwas/glob](https://github.com/gobwas/glob)
   174  * [golang/protobuf](https://github.com/golang/protobuf)
   175  * [google/gopacket](https://github.com/google/gopacket)
   176  * [grafov/m3u8](https://github.com/grafov/m3u8)
   177  * [hashicorp/golang-lru](https://github.com/hashicorp/golang-lru)
   178  * [juju/ratelimit](https://github.com/juju/ratelimit)
   179  * [kardianos/osext](https://github.com/kardianos/osext)
   180  * [groupcache/lru]("github.com/golang/groupcache/lru")
   181  * [lucas-clemente/quic-go](https://github.com/lucas-clemente/quic-go)
   182  * [marusama/semaphore](https://github.com/marusama/semaphore)
   183  * [mdlayher/netlink)](https://github.com/mdlayher/netlink)
   184  * [miekg/dns](https://github.com/miekg/dns)
   185  * [mitchellh/panicwrap](https://github.com/mitchellh/panicwrap)
   186  * [oschwald/maxminddb-golang](https://github.com/oschwald/maxminddb-golang)
   187  * [patrickmn/go-cache](https://github.com/patrickmn/go-cache)
   188  * [pkg/errors](https://github.com/pkg/errors)
   189  * [pmezard/go-difflib](https://github.com/pmezard/go-difflib)
   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