psiphon

Documentation

Overview

Package psiphon provides adaptors to create StreamDialers that leverage Psiphon technology and infrastructure to bypass network interference.

You will need to provide your own Psiphon config file, which you must acquire from the Psiphon team. See the Psiphon End-User License Agreement. For more details, email them at sponsor@psiphon.ca.

For testing, you can generate a Psiphon config yourself.

License restrictions

Psiphon code is licensed as GPLv3, which you will have to take into account if you incorporate Psiphon logic into your app. If you don't want your app to be GPL, consider acquiring an appropriate license when acquiring their services.

Note that a few of Psiphon's dependencies may impose additional restrictions. For example, github.com/hashicorp/golang-lru is MPL-2.0 and github.com/juju/ratelimit is LGPL-3.0. You can use go-licenses to analyze the licenses of your Go code dependencies.

To prevent accidental inclusion of unvetted licenses, you must use the "psiphon" build tag in order to use this package. Typically you do that with "-tags psiphon".

Index

• type Dialer
  • func GetSingletonDialer() *Dialer
  • func (d *Dialer) DialStream(unusedContext context.Context, addr string) (transport.StreamConn, error)
  • func (d *Dialer) Start(ctx context.Context, config *DialerConfig) error
  • func (d *Dialer) Stop() error
• type DialerConfig

Types

type Dialer

type Dialer struct {
	// contains filtered or unexported fields
}

Dialer is a transport.StreamDialer that uses Psiphon to connect to a destination. There's only one possible Psiphon Dialer available at any time, which is accessible via GetSingletonDialer. The zero value of this type is invalid.

The Dialer must be configured first with Dialer.Start before it can be used, and Dialer.Stop must be called before you can start it again with a new configuration. Dialer.Stop should be called when you no longer need the Dialer in order to release resources.

func GetSingletonDialer

func GetSingletonDialer() *Dialer

GetSingletonDialer returns the single Psiphon dialer instance.

func (*Dialer) DialStream

func (d *Dialer) DialStream(unusedContext context.Context, addr string) (transport.StreamConn, error)

DialStream implements transport.StreamDialer. The context is not used because Psiphon's implementation doesn't support it. If you need cancellation, you will need to add it independently.

func (*Dialer) Start

func (d *Dialer) Start(ctx context.Context, config *DialerConfig) error

Start configures and runs the Dialer. It must be called before you can use the Dialer. It returns when the tunnel is ready.

func (*Dialer) Stop

func (d *Dialer) Stop() error

Stop stops the Dialer background processes, releasing resources and allowing it to be reconfigured. It returns when the Dialer is completely stopped.

type DialerConfig

type DialerConfig struct {
	// Used as the directory for the datastore, remote server list, and obfuscasted
	// server list.
	// Empty string means the default will be used (current working directory).
	// Strongly recommended.
	DataRootDirectory string

	// Raw JSON config provided by Psiphon.
	ProviderConfig json.RawMessage
}

DialerConfig specifies the parameters for Dialer.