psiphon-tunnel-core

Psiphon is an Internet censorship circumvention system.

1,041

307

1,041

View on GitHub

Top Related Projects

lantern

15,315

Open-source VPN for speed, privacy, and censorship circumvention. Free to download on Android, iOS, Windows, macOS, and Linux.

v2ray-core

33,454

A platform for building proxies to bypass network restrictions.

trojan

19,661

An unidentifiable mechanism that helps you bypass GFW.

Quick Overview

Psiphon-tunnel-core is an open-source library that provides the core functionality for the Psiphon circumvention system. It enables developers to create applications that can bypass internet censorship and access blocked content. The library is written in Go and supports various platforms, including mobile devices.

Pros

Robust circumvention capabilities for bypassing internet censorship
Cross-platform support, including mobile devices
Actively maintained and regularly updated
Well-documented codebase with extensive comments

Cons

Complex setup process for newcomers
Limited documentation for advanced use cases
Potential legal concerns in some jurisdictions
May require frequent updates to stay ahead of censorship techniques

Code Examples

Creating a new Psiphon client:

import "github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon"

config := &psiphon.Config{
    PropagationChannelId: "...",
    SponsorId:            "...",
    // Add other configuration options
}

client, err := psiphon.NewClient(config)
if err != nil {
    // Handle error
}

Starting a Psiphon tunnel:

err := client.Start()
if err != nil {
    // Handle error
}
defer client.Stop()

Making a request through the Psiphon tunnel:

httpClient := client.GetHTTPClient()
resp, err := httpClient.Get("https://example.com")
if err != nil {
    // Handle error
}
defer resp.Body.Close()
// Process the response

Getting Started

To use psiphon-tunnel-core in your Go project:

Install the library:

go get -u github.com/Psiphon-Labs/psiphon-tunnel-core

Import the package in your code:

import "github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon"

Create a configuration file with your Psiphon credentials and server information.
Initialize and start the Psiphon client as shown in the code examples above.
Use the provided HTTP client to make requests through the Psiphon tunnel.

For more detailed instructions and advanced usage, refer to the project's documentation and examples in the GitHub repository.

Competitor Comparisons

lantern

15,315

Open-source VPN for speed, privacy, and censorship circumvention. Free to download on Android, iOS, Windows, macOS, and Linux.

Pros of Lantern

User-friendly interface with a simple one-click connection process
Supports both censorship circumvention and general privacy protection
Offers a free tier with limited data and paid plans for unlimited usage

Cons of Lantern

Less focus on protocol obfuscation compared to Psiphon
May be more easily detected by censorship systems due to its popularity
Limited customization options for advanced users

Code Comparison

Psiphon:

func (controller *Controller) runTunnels() {
    for {
        select {
        case <-controller.shutdownBroadcast:
            return
        case serverEntry := <-controller.serverEntryChannel:
            controller.establishTunnel(serverEntry)
        }
    }
}

Lantern:

func (client *Client) connectAndServe(ctx context.Context) error {
    for {
        err := client.connect(ctx)
        if err != nil {
            return err
        }
        err = client.serve(ctx)
        if err != nil {
            return err
        }
    }
}

Both projects use Go and implement similar connection loop structures, but Psiphon's code focuses on tunnel establishment, while Lantern's emphasizes client-server interaction. Psiphon's approach appears more tailored to circumvention, whereas Lantern's code suggests a broader networking focus.

shadowsocks-rust

10,426

A Rust port of shadowsocks

Pros of shadowsocks-rust

Written in Rust, offering better performance and memory safety
Supports multiple ciphers and plugins for enhanced flexibility
Active development with frequent updates and improvements

Cons of shadowsocks-rust

Limited to shadowsocks protocol, less versatile than psiphon-tunnel-core
May require more setup and configuration for advanced features
Smaller community and ecosystem compared to psiphon-tunnel-core

Code Comparison

psiphon-tunnel-core (Go):

func (tunnel *Tunnel) Dial(remoteAddr string) (net.Conn, error) {
    conn, err := tunnel.transport.Dial(remoteAddr)
    if err != nil {
        return nil, errors.Trace(err)
    }
    return conn, nil
}

shadowsocks-rust (Rust):

pub async fn connect(
    &self,
    addr: &Address,
) -> io::Result<TcpStream> {
    let stream = TcpStream::connect(addr).await?;
    Ok(stream)
}

Both projects implement connection handling, but shadowsocks-rust uses Rust's async/await syntax for potentially better performance in high-concurrency scenarios. psiphon-tunnel-core's implementation is more straightforward but may be less efficient in handling multiple connections simultaneously.

v2ray-core

33,454

A platform for building proxies to bypass network restrictions.

Pros of v2ray-core

More flexible and customizable with support for multiple protocols and transport layers
Better performance and lower latency due to its efficient design
Active development with frequent updates and improvements

Cons of v2ray-core

Steeper learning curve and more complex configuration
Less focus on censorship circumvention compared to psiphon-tunnel-core
May require more server resources due to its extensive feature set

Code Comparison

psiphon-tunnel-core:

func (tunnel *Tunnel) Dial(remoteAddr string) (net.Conn, error) {
    return tunnel.sshClient.Dial("tcp", remoteAddr)
}

v2ray-core:

func (d *DefaultDispatcher) Dispatch(ctx context.Context, dest net.Destination) (internet.Connection, error) {
    dispatcher := d.ohm.GetDefaultHandler()
    return dispatcher.Dispatch(ctx, dest)
}

The code snippets show that psiphon-tunnel-core uses a simpler approach for establishing connections, while v2ray-core employs a more complex dispatcher system for handling various protocols and destinations.

trojan

19,661

An unidentifiable mechanism that helps you bypass GFW.

Pros of trojan

Lightweight and efficient, with minimal resource usage
Simple configuration and easy deployment
Strong focus on evading detection and censorship

Cons of trojan

Limited protocol support compared to psiphon-tunnel-core
Smaller community and fewer contributors
Less comprehensive documentation and user guides

Code Comparison

psiphon-tunnel-core (Go):

func (tunnel *Tunnel) Dial(remoteAddr string) (net.Conn, error) {
    conn, err := tunnel.dialTCP(remoteAddr)
    if err != nil {
        return nil, errors.Trace(err)
    }
    return conn, nil
}

trojan (C++):

int trojan::start(bool test) {
    try {
        service.run();
    } catch (const std::exception &e) {
        Log::log_with_date_time(std::string("fatal: ") + e.what(), Log::FATAL);
        return -1;
    }
    return 0;
}

The code snippets show different approaches to handling connections and error management. psiphon-tunnel-core uses Go's error handling pattern, while trojan uses C++ exception handling. psiphon-tunnel-core's code appears more focused on establishing connections, while trojan's code snippet shows the main service loop.

Both projects aim to provide secure and censorship-resistant communication, but they differ in implementation languages, features, and target use cases. psiphon-tunnel-core offers a more comprehensive solution with broader protocol support, while trojan focuses on simplicity and efficiency.

netch

17,310

A simple proxy client

Pros of Netch

User-friendly GUI for easy configuration and management
Supports multiple protocols (Shadowsocks, ShadowsocksR, Socks5, etc.)
Includes game mode for optimized gaming traffic routing

Cons of Netch

Less focus on censorship circumvention compared to Psiphon
May require more manual configuration for advanced use cases
Smaller development community and potentially slower updates

Code Comparison

Psiphon (Go):

func (tunnel *Tunnel) Activate(params *Parameters) {
    tunnel.operateWaitGroup.Add(1)
    go tunnel.operateTunnel(params)
}

Netch (C#):

public void Start()
{
    State = State.Starting;
    Task.Run(() => { StartAsync().Wait(); });
}

Both projects use asynchronous programming to handle tunnel operations, but Psiphon uses Go's goroutines while Netch utilizes C#'s Task-based asynchronous pattern.

Psiphon focuses on a core tunneling library, while Netch provides a more comprehensive networking tool with a graphical interface. Psiphon is primarily designed for censorship circumvention, whereas Netch offers a broader range of networking capabilities, including game traffic optimization.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Psiphon Tunnel Core README

Overview

Psiphon 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 Psiphon and beyond censorship.

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.

For more information about Psiphon Inc., please visit our web site at www.psiphon.ca.

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

Technical Summary

Psiphon 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

Psiphon 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 Psiphon 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 Psiphon server.

Clients binaries may be built with embedded server lists. Clients may also "discover" new server entries when they successfully connect to a server.

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.

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 Psiphon 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, 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.

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.

Psiphon uses a mechanism called "tactics" to remotely deliver targeted, optimized configuration and obfuscation parameters to clients.

Running Psiphon

Get the programs

Official binaries are avaiable at:

For these instructions, use:

Generate configuration data

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.

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

$ ls
psiphond
psiphond.config
psiphond-osl.config
psiphond-tactics.config
psiphond-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 psiphond

$ ./psiphond 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 Psiphon

Use the local SOCKS proxy (port 1080) or HTTP proxy (port 8080) to tunnel traffic.

Using Psiphon with Go modules

The github.com/Psiphon-Labs/psiphon-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 psiphon-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/Psiphon-Labs/psiphon-tunnel-core@staging-client
go: added github.com/Psiphon-Labs/psiphon-tunnel-core v1.0.11-0.20240424194431-3612a5a6fb4c

Acknowledgements

Psiphon Tunnel Core uses the following Go modules: https://github.com/Psiphon-Labs/psiphon-tunnel-core/blob/master/go.mod

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot