README
¶
Vaipn Tunnel Core README
Overview
Vaipn is an Internet censorship circumvention system.
The tunnel core project includes a tunneling client and server, which together implement key aspects of evading blocking and relaying client traffic through Vaipn and beyond censorship.
All Vaipn 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.
For more information about Vaipn Inc., please visit our web site at www.vaipn.ca.
vaipn-tunnel-core
└── ClientLibrary General client libraries
└── ConsoleClient CLI client program
└── MobileLibrary Android/iOS client libraries
└── Server Server program
└── vaipn Client code package
└── common\... Common code packages
└── server Server code package
Technical Summary
Vaipn tunnels Internet traffic through a network of proxy servers with the goal of circumventing Internet censorship.
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.
Traffic Routing
Vaipn has multiple routing modes:
- 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.
- Packet tunnel mode: the client relays IP packets between a host "tun" device and the server.
Traffic Security
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 Vaipn servers.
Server Entries
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 Vaipn server.
Clients binaries may be built with embedded server lists. Clients may also "discover" new server entries when they successfully connect to a server.
Vaipn 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.
All delivery mechanisms use partitioning to prevent trivial enumeration of all server entries.
Some out-of-band server server lists, called "obfuscated server lists", are encrypted and only clients that have been granted sufficient required keys can access the included servers.
Traffic Obfuscation
The core SSH protocol is wrapped in optional obfuscation layers which transform traffic in order to evade blocking of Vaipn servers. Mitigated attacks include endpoint blocking, keyword-based blocking, DPI-based blocking, and more.
Obfuscation techniques include:
- Making traffic on the wire look fully random.
- Making traffic on the wire look like popular implementations of popular protocols.
- Performing traffic shaping to obscure the size and timing properties of encapsulated traffic.
- Connecting to proxy servers indirectly, via intermediaries.
Circumvention Optimizations
To minimize connection time, Vaipn 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 Vaipn load balances clients across its network of servers without using a centralized load balancing mechanism.
A successful connection may be subject to further quality tests before selection. The Vaipn client remembers which servers and which obfuscation techniques and parameters are successful and prioritizes using the same on subsequent connections.
Vaipn uses a mechanism called "tactics" to remotely deliver targeted, optimized configuration and obfuscation parameters to clients.
Running Vaipn
Get the programs
Official binaries are avaiable at:
- https://github.com/payske-dev/vaipn-tunnel-core-binaries
- https://github.com/payske-dev/vaipn-tunnel-core/releases, for libraries
For these instructions, use:
Generate configuration data
Run the "generate" mode of vaipnd to generate configs, setting the IP address as appropriate; this is the address the client will use to connect to the server.
$ ./vaipnd -ipaddress 127.0.0.1 -protocol OSSH:9999 generate
$ ls
vaipnd
vaipnd.config
vaipnd-osl.config
vaipnd-tactics.config
vaipnd-traffic-rules.config
server-entry.dat
Create a client config file, copying the contents of server-entry.dat to the TargetServerEntry field.
$ cat server-entry.dat
3132372e302e302e31202020207b22746167223a22222c2269[...]
$ cat client.config
{
"LocalHttpProxyPort" : 8080,
"LocalSocksProxyPort" : 1080,
"PropagationChannelId" : "24BCA4EE20BEB92C",
"SponsorId" : "721AE60D76700F5A",
"TargetServerEntry" : "3132372e302e302e31202020207b22746167223a22222c2269[...]"
}
Run vaipnd
$ ./vaipnd run
{"localAddress":"127.0.0.1:9999","msg":"listening","tunnelProtocol":"OSSH",[...]}
{"localAddress":"127.0.0.1:9999","msg":"running","tunnelProtocol":"OSSH",[...]}
[...]
Run the console client
$ ./ConsoleClient -config ./client.config
{"data":{"port":1080},"noticeType":"ListeningSocksProxyPort",[...]}
{"data":{"port":8080},"noticeType":"ListeningHttpProxyPort",[...]}
[...]
{"data":{"count":1},"noticeType":"Tunnels",[...]}
Tunnel traffic through Vaipn
Use the local SOCKS proxy (port 1080) or HTTP proxy (port 8080) to tunnel traffic.
Using Vaipn with Go modules
The github.com/payske-dev/vaipn-tunnel-core Go module may be imported into
other Go programs. Due to legacy release tags predating use of Go modules in
this repository, neither go get ...@latest nor go get ...@tag are
supported at this time. To use the vaipn-tunnel-core Go module and its
dependencies, reference a specific commit, or reference the staging-client
branch, which is the client-side, production-ready branch:
% go get github.com/payske-dev/vaipn-tunnel-core@staging-client
go: added github.com/payske-dev/vaipn-tunnel-core v1.0.11-0.20240424194431-3612a5a6fb4c
Acknowledgements
Vaipn Tunnel Core uses the following Go modules: https://github.com/payske-dev/vaipn-tunnel-core/blob/master/go.mod
Directories
¶
| Path | Synopsis |
|---|---|
|
MobileLibrary
|
|
|
logging/analysis
Package analysis implements heuristical frequency analysis of Vaipn Tunnel Core server logs.
|
Package analysis implements heuristical frequency analysis of Vaipn Tunnel Core server logs. |
|
Package vaipn implements the core tunnel functionality of a Vaipn client.
|
Package vaipn implements the core tunnel functionality of a Vaipn client. |
|
common/accesscontrol
Package accesscontrol implements an access control authorization scheme based on digital signatures.
|
Package accesscontrol implements an access control authorization scheme based on digital signatures. |
|
common/crypto/internal/poly1305
Package poly1305 implements Poly1305 one-time message authentication code as specified in https://cr.yp.to/mac/poly1305-20050329.pdf.
|
Package poly1305 implements Poly1305 one-time message authentication code as specified in https://cr.yp.to/mac/poly1305-20050329.pdf. |
|
common/crypto/internal/subtle
Package subtle implements functions that are often useful in cryptographic code but require careful thought to use correctly.
|
Package subtle implements functions that are often useful in cryptographic code but require careful thought to use correctly. |
|
common/crypto/nacl/secretbox
Package secretbox encrypts and authenticates small messages.
|
Package secretbox encrypts and authenticates small messages. |
|
common/crypto/ssh
Package ssh implements an SSH client and server.
|
Package ssh implements an SSH client and server. |
|
common/crypto/ssh/agent
Package agent implements the ssh-agent protocol, and provides both a client and a server.
|
Package agent implements the ssh-agent protocol, and provides both a client and a server. |
|
common/crypto/ssh/internal/bcrypt_pbkdf
Package bcrypt_pbkdf implements bcrypt_pbkdf(3) from OpenBSD.
|
Package bcrypt_pbkdf implements bcrypt_pbkdf(3) from OpenBSD. |
|
common/crypto/ssh/knownhosts
Package knownhosts implements a parser for the OpenSSH known_hosts host key database, and provides utility functions for writing OpenSSH compliant known_hosts files.
|
Package knownhosts implements a parser for the OpenSSH known_hosts host key database, and provides utility functions for writing OpenSSH compliant known_hosts files. |
|
common/crypto/ssh/terminal
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems.
|
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems. |
|
common/crypto/ssh/test
Package test contains integration tests for the github.com/payske-dev/vaipn-tunnel-core/vaipn/common/crypto/ssh package.
|
Package test contains integration tests for the github.com/payske-dev/vaipn-tunnel-core/vaipn/common/crypto/ssh package. |
|
common/errors
Package errors provides error wrapping helpers that add inline, single frame stack trace information to error messages.
|
Package errors provides error wrapping helpers that add inline, single frame stack trace information to error messages. |
|
common/inproxy
Package inproxy enables 3rd party, ephemeral proxies to help Vaipn clients connect to the Vaipn network.
|
Package inproxy enables 3rd party, ephemeral proxies to help Vaipn clients connect to the Vaipn network. |
|
common/monotime
Package monotime provides a fast monotonic clock source.
|
Package monotime provides a fast monotonic clock source. |
|
common/osl
Package osl implements the Obfuscated Server List (OSL) mechanism.
|
Package osl implements the Obfuscated Server List (OSL) mechanism. |
|
common/packetman
Package packetman implements low-level manipulation of TCP packets, enabling a variety of strategies to evade network censorship.
|
Package packetman implements low-level manipulation of TCP packets, enabling a variety of strategies to evade network censorship. |
|
common/parameters
Package parameters implements dynamic, concurrency-safe parameters that determine Vaipn client and server behaviors.
|
Package parameters implements dynamic, concurrency-safe parameters that determine Vaipn client and server behaviors. |
|
common/prng
Package prng implements a seeded, unbiased PRNG that is suitable for use cases including obfuscation, network jitter, load balancing.
|
Package prng implements a seeded, unbiased PRNG that is suitable for use cases including obfuscation, network jitter, load balancing. |
|
common/quic
Package quic wraps github.com/lucas-clemente/quic-go with net.Listener and net.Conn types that provide a drop-in replacement for net.TCPConn.
|
Package quic wraps github.com/lucas-clemente/quic-go with net.Listener and net.Conn types that provide a drop-in replacement for net.TCPConn. |
|
common/regen
Package regen is a library for generating random strings from regular expressions.
|
Package regen is a library for generating random strings from regular expressions. |
|
common/resolver
Package resolver implements a DNS stub resolver, or DNS client, which resolves domain names.
|
Package resolver implements a DNS stub resolver, or DNS client, which resolves domain names. |
|
common/sss
Package sss implements Shamir's Secret Sharing algorithm over GF(2^8).
|
Package sss implements Shamir's Secret Sharing algorithm over GF(2^8). |
|
common/stacktrace
Package stacktrace provides helpers for handling stack trace information.
|
Package stacktrace provides helpers for handling stack trace information. |
|
common/tactics
Package tactics provides dynamic Vaipn client configuration based on GeoIP attributes, API parameters, and speed test data.
|
Package tactics provides dynamic Vaipn client configuration based on GeoIP attributes, API parameters, and speed test data. |
|
common/transforms
Package transforms provides a mechanism to define and apply string data transformations, with the transformations defined by regular expressions to match data to be transformed, and regular expression generators to specify additional or replacement data.
|
Package transforms provides a mechanism to define and apply string data transformations, with the transformations defined by regular expressions to match data to be transformed, and regular expression generators to specify additional or replacement data. |
|
common/tun
Package tun is an IP packet tunnel server and client.
|
Package tun is an IP packet tunnel server and client. |
|
common/values
Package values provides a mechanism for specifying and selecting dynamic values employed by the Vaipn client and server.
|
Package values provides a mechanism for specifying and selecting dynamic values employed by the Vaipn client and server. |
|
common/wildcard
Package wildcard implements a very simple wildcard matcher which supports only the term '*', which matches any sequence of characters.
|
Package wildcard implements a very simple wildcard matcher which supports only the term '*', which matches any sequence of characters. |
|
server
Package server implements the core tunnel functionality of a Vaipn server.
|
Package server implements the core tunnel functionality of a Vaipn server. |
|
server/discovery
Package discovery implements the Vaipn discovery algorithms.
|
Package discovery implements the Vaipn discovery algorithms. |
|
server/psinet
Package psinet implements psinet database services.
|
Package psinet implements psinet database services. |
|
transferstats
Package transferstats counts and keeps track of session stats.
|
Package transferstats counts and keeps track of session stats. |
|
upstreamproxy/go-ntlm/ntlm
Package NTLM implements the interfaces used for interacting with NTLMv1 and NTLMv2.
|
Package NTLM implements the interfaces used for interacting with NTLMv1 and NTLMv2. |
|
upstreamproxy/go-ntlm/ntlm/md4
Package md4 implements the MD4 hash algorithm as defined in RFC 1320.
|
Package md4 implements the MD4 hash algorithm as defined in RFC 1320. |