psiphon

package
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2018 License: GPL-3.0 Imports: 56 Imported by: 55

Documentation

Overview

Package psiphon implements the core tunnel functionality of a Psiphon client. The main function is RunForever, which runs a Controller that obtains lists of servers, establishes tunnel connections, and runs local proxies through which tunneled traffic may be sent.

Index

Constants

View Source 
const (
	DATA_STORE_FILENAME                     = "psiphon.boltdb"
	LEGACY_DATA_STORE_FILENAME              = "psiphon.db"
	DATA_STORE_LAST_CONNECTED_KEY           = "lastConnected"
	DATA_STORE_LAST_SERVER_ENTRY_FILTER_KEY = "lastServerEntryFilter"
	PERSISTENT_STAT_TYPE_REMOTE_SERVER_LIST = remoteServerListStatsBucket
)
View Source 
const (
	FEEDBACK_UPLOAD_MAX_RETRIES         = 5
	FEEDBACK_UPLOAD_RETRY_DELAY_SECONDS = 300
	FEEDBACK_UPLOAD_TIMEOUT_SECONDS     = 30
)
View Source 
const (
	MAX_FRAGMENTOR_NOTICES               = 3
	MAX_FRAGMENTOR_ITERATIONS_PER_NOTICE = 5
)
View Source 
const (
	URL_PROXY_TUNNELED_REQUEST_PATH         = "/tunneled/"
	URL_PROXY_TUNNELED_REWRITE_REQUEST_PATH = "/tunneled-rewrite/"
	URL_PROXY_TUNNELED_ICY_REQUEST_PATH     = "/tunneled-icy/"
	URL_PROXY_DIRECT_REQUEST_PATH           = "/direct/"
)
View Source 
const (
	MEEK_PROTOCOL_VERSION           = 3
	MEEK_MAX_REQUEST_PAYLOAD_LENGTH = 65536
)
View Source 
const DNS_PORT = 53
View Source 
const (
	TUNNEL_POOL_SIZE = 1
)

Variables

This section is empty.

Functions

func ClearReportedPersistentStats 

func ClearReportedPersistentStats(stats map[string][][]byte) error

ClearReportedPersistentStats deletes a list of persistent stat records that were successfully reported.

func CountNonImpairedProtocols 

func CountNonImpairedProtocols(
	region string,
	limitTunnelProtocols, impairedProtocols []string) int

CountNonImpairedProtocols returns the number of distinct tunnel protocols supported by stored server entries, excluding the specified impaired protocols.

func CountSLOKs 

func CountSLOKs() int

CountSLOKs returns the total number of SLOK records.

func CountServerEntries 

func CountServerEntries(region string, tunnelProtocols []string) int

CountServerEntries returns a count of stored servers for the specified region and tunnel protocols.

func CountUnreportedPersistentStats 

func CountUnreportedPersistentStats() int

CountUnreportedPersistentStats returns the number of persistent stat records in StateUnreported.

func CustomTLSDial 

func CustomTLSDial(
	ctx context.Context,
	network, addr string,
	config *CustomTLSConfig) (net.Conn, error)

CustomTLSDial is a customized replacement for tls.Dial. Based on tlsdialer.DialWithDialer which is based on crypto/tls.DialWithDialer.

To ensure optimal TLS profile selection when using CustomTLSDial for tunnel protocols, call SelectTLSProfile first and set its result into config.TLSProfile.

tlsdialer comment: 

Note - if sendServerName is false, the VerifiedChains field on the
connection's ConnectionState will never get populated.

func DecodeCertificate 

func DecodeCertificate(encodedCertificate string) (certificate *x509.Certificate, err error)

func DeleteSLOKs 

func DeleteSLOKs() error

DeleteSLOKs deletes all SLOK records.

func DialTCP 

func DialTCP(
	ctx context.Context, addr string, config *DialConfig) (net.Conn, error)

DialTCP creates a new, connected TCPConn.

func DialTCPFragmentor added in v1.0.5 

func DialTCPFragmentor(
	ctx context.Context,
	addr string,
	config *DialConfig,
	tunnelProtocol string,
	clientParameters *parameters.ClientParameters,
	coinFlip *bool) (net.Conn, error)

DialTCPFragmentor performs a DialTCP and wraps the dialed conn in a FragmentorConn, subject to FragmentorProbability and FragmentorLimitProtocols.

func DoGarbageCollection added in v1.0.5 

func DoGarbageCollection()

func DownloadUpgrade 

func DownloadUpgrade(
	ctx context.Context,
	config *Config,
	attempt int,
	handshakeVersion string,
	tunnel *Tunnel,
	untunneledDialConfig *DialConfig) error

DownloadUpgrade performs a resumable download of client upgrade files.

While downloading/resuming, a temporary file is used. Once the download is complete, a notice is issued and the upgrade is available at the destination specified in config.UpgradeDownloadFilename.

The upgrade download may be either tunneled or untunneled. As the untunneled case may happen with no handshake request response, the downloader cannot rely on having the upgrade_client_version output from handshake and instead this logic performs a comparison between the config.ClientVersion and the client version recorded in the remote entity's UpgradeDownloadClientVersionHeader. A HEAD request is made to check the version before proceeding with a full download.

NOTE: This code does not check that any existing file at config.UpgradeDownloadFilename is actually the version specified in handshakeVersion.

TODO: This logic requires the outer client to *omit* config.UpgradeDownloadFilename when there's already a downloaded upgrade pending. Because the outer client currently handles the authenticated package phase, and because the outer client deletes the intermediate files (including config.UpgradeDownloadFilename), if the outer client does not omit config.UpgradeDownloadFilename then the new version will be downloaded repeatedly. Implement a new scheme where tunnel core does the authenticated package phase and tracks the the output by version number so that (a) tunnel core knows when it's not necessary to re-download; (b) newer upgrades will be downloaded even when an older upgrade is still pending install by the outer client.

func FetchCommonRemoteServerList 

func FetchCommonRemoteServerList(
	ctx context.Context,
	config *Config,
	attempt int,
	tunnel *Tunnel,
	untunneledDialConfig *DialConfig) error

FetchCommonRemoteServerList downloads the common remote server list from config.RemoteServerListUrl. It validates its digital signature using the public key config.RemoteServerListSignaturePublicKey and parses the data field into ServerEntry records. config.RemoteServerListDownloadFilename is the location to store the download. As the download is resumed after failure, this filename must be unique and persistent.

func FetchObfuscatedServerLists 

func FetchObfuscatedServerLists(
	ctx context.Context,
	config *Config,
	attempt int,
	tunnel *Tunnel,
	untunneledDialConfig *DialConfig) error

FetchObfuscatedServerLists downloads the obfuscated remote server lists from config.ObfuscatedServerListRootURL. It first downloads the OSL registry, and then downloads each seeded OSL advertised in the registry. All downloads are resumable, ETags are used to skip both an unchanged registry or unchanged OSL files, and when an individual download fails, the fetch proceeds if it can. Authenticated package digital signatures are validated using the public key config.RemoteServerListSignaturePublicKey. config.ObfuscatedServerListDownloadDirectory is the location to store the downloaded files. As downloads are resumed after failure, this directory must be unique and persistent.

func FilterUrlError 

func FilterUrlError(err error) error

FilterUrlError transforms an error, when it is a url.Error, removing the URL value. This is to avoid logging private user data in cases where the URL may be a user input value. This function is used with errors returned by net/http and net/url, which are (currently) of type url.Error. In particular, the round trip function used by our HttpProxy, http.Client.Do, returns errors of type url.Error, with the URL being the url sent from the user's tunneled applications: https://github.com/golang/go/blob/release-branch.go1.4/src/net/http/client.go#L394

func GetEmitDiagnoticNotices 

func GetEmitDiagnoticNotices() bool

GetEmitDiagnoticNotices returns the current state of emitting diagnostic notices.

func GetKeyValue 

func GetKeyValue(key string) (value string, err error)

GetKeyValue retrieves the value for a given key. If not found, it returns an empty string value.

func GetNotice 

func GetNotice(notice []byte) (
	noticeType string, payload map[string]interface{}, err error)

GetNotice receives a JSON encoded object and attempts to parse it as a Notice. The type is returned as a string and the payload as a generic map.

func GetSLOK 

func GetSLOK(id []byte) (key []byte, err error)

GetSLOK returns a SLOK key for the specified ID. The return value is nil if the SLOK is not found.

func GetServerEntryIpAddresses 

func GetServerEntryIpAddresses() (ipAddresses []string, err error)

GetServerEntryIpAddresses returns an array containing all stored server IP addresses.

func GetSplitTunnelRoutesData 

func GetSplitTunnelRoutesData(region string) (data []byte, err error)

GetSplitTunnelRoutesData retrieves the cached routes data for the specified region. If not found, it returns a nil value.

func GetSplitTunnelRoutesETag 

func GetSplitTunnelRoutesETag(region string) (etag string, err error)

GetSplitTunnelRoutesETag retrieves the etag for cached routes data for the specified region. If not found, it returns an empty string value.

func GetUrlETag 

func GetUrlETag(url string) (etag string, err error)

GetUrlETag retrieves a previously stored an ETag for the specfied URL. If not found, it returns an empty string value.

func HandleOSLRequest 

func HandleOSLRequest(
	tunnelOwner TunnelOwner, tunnel *Tunnel, payload []byte) error

func HandleServerRequest 

func HandleServerRequest(
	tunnelOwner TunnelOwner, tunnel *Tunnel, name string, payload []byte) error

func InitDataStore 

func InitDataStore(config *Config) (err error)

InitDataStore initializes the singleton instance of dataStore. This function uses a sync.Once and is safe for use by concurrent goroutines. The underlying sql.DB connection pool is also safe.

Note: the sync.Once was more useful when initDataStore was private and called on-demand by the public functions below. Now we require an explicit InitDataStore() call with the filename passed in. The on-demand calls have been replaced by checkInitDataStore() to assert that Init was called.

func IsAddressInUseError 

func IsAddressInUseError(err error) bool

IsAddressInUseError returns true when the err is due to EADDRINUSE/WSAEADDRINUSE.

func LocalProxyRelay 

func LocalProxyRelay(proxyType string, localConn, remoteConn net.Conn)

LocalProxyRelay sends to remoteConn bytes received from localConn, and sends to localConn bytes received from remoteConn.

func LookupIP 

func LookupIP(ctx context.Context, host string, config *DialConfig) ([]net.IP, error)

LookupIP resolves a hostname. When BindToDevice is not required, it simply uses net.LookupIP. When BindToDevice is required, LookupIP explicitly creates a UDP socket, binds it to the device, and makes an explicit DNS request to the specified DNS resolver.

func MakeCompatibleServerEntry 

func MakeCompatibleServerEntry(serverEntry *protocol.ServerEntry) *protocol.ServerEntry

MakeCompatibleServerEntry provides backwards compatibility with old server entries which have a single meekFrontingDomain and not a meekFrontingAddresses array. By copying this one meekFrontingDomain into meekFrontingAddresses, this client effectively uses that single value as legacy clients do.

func MakeDownloadHTTPClient added in v1.0.5 

func MakeDownloadHTTPClient(
	ctx context.Context,
	config *Config,
	tunnel *Tunnel,
	untunneledDialConfig *DialConfig,
	skipVerify bool) (*http.Client, error)

MakeDownloadHTTPClient is a helper that sets up a http.Client for use either untunneled or through a tunnel.

func MakePsiphonUserAgent 

func MakePsiphonUserAgent(config *Config) string

MakePsiphonUserAgent constructs a User-Agent value to use for web service requests made by the tunnel-core client. The User-Agent includes useful stats information; it is to be used only for HTTPS requests, where the header cannot be seen by an adversary.

func MakeSessionId 

func MakeSessionId() (sessionId string, err error)

MakeSessionId creates a new session ID. The same session ID is used across multi-tunnel controller runs, where each tunnel has its own ServerContext instance. In server-side stats, we now consider a "session" to be the lifetime of the Controller (e.g., the user's commanded start and stop) and we measure this duration as well as the duration of each tunnel within the session.

func MakeTunneledHTTPClient added in v1.0.5 

func MakeTunneledHTTPClient(
	config *Config,
	tunnel *Tunnel,
	skipVerify bool) (*http.Client, error)

MakeTunneledHTTPClient returns a net/http.Client which is configured to use custom dialing features including tunneled dialing and, optionally, UseTrustedCACertificatesForStockTLS. This http.Client uses stock TLS for HTTPS.

func MakeUntunneledHTTPClient added in v1.0.5 

func MakeUntunneledHTTPClient(
	ctx context.Context,
	config *Config,
	untunneledDialConfig *DialConfig,
	verifyLegacyCertificate *x509.Certificate,
	skipVerify bool) (*http.Client, error)

MakeUntunneledHTTPClient returns a net/http.Client which is configured to use custom dialing features -- including BindToDevice, UseIndistinguishableTLS, etc. If verifyLegacyCertificate is not nil, it's used for certificate verification. The context is applied to underlying TCP dials. The caller is responsible for applying the context to requests made with the returned http.Client.

func NewReadCloseSignaller added in v1.0.5 

func NewReadCloseSignaller(
	context context.Context,
	reader io.Reader) *readCloseSignaller

func NoticeActiveAuthorizationIDs added in v1.0.5 

func NoticeActiveAuthorizationIDs(activeAuthorizationIDs []string)

NoticeActiveAuthorizationIDs reports the authorizations the server has accepted. Each ID is a base64-encoded accesscontrol.Authorization.ID value.

func NoticeActiveTunnel 

func NoticeActiveTunnel(ipAddress, protocol string, isTCS bool)

NoticeActiveTunnel is a successful connection that is used as an active tunnel for port forwarding

func NoticeAlert 

func NoticeAlert(format string, args ...interface{})

NoticeAlert is an alert message; typically a recoverable error condition

func NoticeAvailableEgressRegions 

func NoticeAvailableEgressRegions(regions []string)

NoticeAvailableEgressRegions is what regions are available for egress from. Consecutive reports of the same list of regions are suppressed.

func NoticeBindToDevice added in v1.0.5 

func NoticeBindToDevice(deviceInfo string)

func NoticeBuildInfo 

func NoticeBuildInfo()

NoticeBuildInfo reports build version info.

func NoticeBytesTransferred 

func NoticeBytesTransferred(ipAddress string, sent, received int64)

NoticeBytesTransferred reports how many tunneled bytes have been transferred since the last NoticeBytesTransferred, for the tunnel to the server at ipAddress. This is not a diagnostic notice: the user app has requested this notice with EmitBytesTransferred for functionality such as traffic display; and this frequent notice is not intended to be included with feedback.

func NoticeCandidateServers 

func NoticeCandidateServers(region string, protocols []string, count int)

NoticeCandidateServers is how many possible servers are available for the selected region and protocols

func NoticeClientIsLatestVersion 

func NoticeClientIsLatestVersion(availableVersion string)

NoticeClientIsLatestVersion reports that an upgrade check was made and the client is already the latest version. availableVersion is the version available for download, if known.

func NoticeClientRegion 

func NoticeClientRegion(region string)

NoticeClientRegion is the client's region, as determined by the server and reported to the client in the handshake.

func NoticeClientUpgradeAvailable 

func NoticeClientUpgradeAvailable(version string)

NoticeClientUpgradeAvailable is an available client upgrade, as per the handshake. The client should download and install an upgrade.

func NoticeClientUpgradeDownloaded 

func NoticeClientUpgradeDownloaded(filename string)

NoticeClientUpgradeDownloaded indicates that a client upgrade download is complete and available at the destination specified.

func NoticeClientUpgradeDownloadedBytes 

func NoticeClientUpgradeDownloadedBytes(bytes int64)

NoticeClientUpgradeDownloadedBytes reports client upgrade download progress.

func NoticeCommonLogger added in v1.0.5 

func NoticeCommonLogger() common.Logger

NoticeCommonLogger maps the common.Logger interface to the notice facility. This is used to make the notice facility available to other packages that don't import the "psiphon" package.

func NoticeConnectedServer 

func NoticeConnectedServer(ipAddress, region, protocol string, dialStats *DialStats)

NoticeConnectedServer reports parameters and details for a single successful connection

func NoticeConnectingServer 

func NoticeConnectingServer(ipAddress, region, protocol string, dialStats *DialStats)

NoticeConnectingServer reports parameters and details for a single connection attempt

func NoticeError 

func NoticeError(format string, args ...interface{})

NoticeError is an error message; typically an unrecoverable error condition

func NoticeExiting 

func NoticeExiting()

NoticeExiting indicates that tunnel-core is exiting imminently.

func NoticeHomepages added in v1.0.5 

func NoticeHomepages(urls []string)

NoticeHomepages emits a series of NoticeHomepage, the sponsor homepages. The client should display the sponsor's homepages.

func NoticeHttpProxyPortInUse 

func NoticeHttpProxyPortInUse(port int)

NoticeHttpProxyPortInUse is a failure to use the configured LocalHttpProxyPort

func NoticeImpairedProtocolClassification 

func NoticeImpairedProtocolClassification(impairedProtocolClassification map[string]int)

func NoticeInfo 

func NoticeInfo(format string, args ...interface{})

NoticeInfo is an informational message

func NoticeListeningHttpProxyPort 

func NoticeListeningHttpProxyPort(port int)

NoticeListeningHttpProxyPort is the selected port for the listening local HTTP proxy

func NoticeListeningSocksProxyPort 

func NoticeListeningSocksProxyPort(port int)

NoticeListeningSocksProxyPort is the selected port for the listening local SOCKS proxy

func NoticeLocalProxyError 

func NoticeLocalProxyError(proxyType string, err error)

NoticeLocalProxyError reports a local proxy error message. Repetitive errors for a given proxy type are suppressed.

func NoticeNetworkID added in v1.0.5 

func NoticeNetworkID(networkID string)

func NoticeRemoteServerListResourceDownloaded 

func NoticeRemoteServerListResourceDownloaded(url string)

NoticeRemoteServerListResourceDownloaded indicates that a remote server list download completed successfully.

func NoticeRemoteServerListResourceDownloadedBytes 

func NoticeRemoteServerListResourceDownloadedBytes(url string, bytes int64)

NoticeRemoteServerListResourceDownloadedBytes reports remote server list download progress.

func NoticeRequestedTactics added in v1.0.5 

func NoticeRequestedTactics(ipAddress, region, protocol string, dialStats *DialStats)

NoticeRequestedTactics reports parameters and details for a successful tactics request

func NoticeRequestingTactics added in v1.0.5 

func NoticeRequestingTactics(ipAddress, region, protocol string, dialStats *DialStats)

NoticeRequestingTactics reports parameters and details for a tactics request attempt

func NoticeSLOKSeeded 

func NoticeSLOKSeeded(slokID string, duplicate bool)

NoticeSLOKSeeded indicates that the SLOK with the specified ID was received from the Psiphon server. The "duplicate" flags indicates whether the SLOK was previously known.

func NoticeServerTimestamp added in v1.0.5 

func NoticeServerTimestamp(timestamp string)

NoticeServerTimestamp reports server side timestamp as seen in the handshake.

func NoticeSessionId 

func NoticeSessionId(sessionId string)

NoticeSessionId is the session ID used across all tunnels established by the controller.

func NoticeSocksProxyPortInUse 

func NoticeSocksProxyPortInUse(port int)

NoticeSocksProxyPortInUse is a failure to use the configured LocalSocksProxyPort

func NoticeSplitTunnelRegion 

func NoticeSplitTunnelRegion(region string)

NoticeSplitTunnelRegion reports that split tunnel is on for the given region.

func NoticeTotalBytesTransferred 

func NoticeTotalBytesTransferred(ipAddress string, sent, received int64)

NoticeTotalBytesTransferred reports how many tunneled bytes have been transferred in total up to this point, for the tunnel to the server at ipAddress. This is a diagnostic notice.

func NoticeTunnels 

func NoticeTunnels(count int)

NoticeTunnels is how many active tunnels are available. The client should use this to determine connecting/unexpected disconnect state transitions. When count is 0, the core is disconnected; when count > 1, the core is connected.

func NoticeUntunneled 

func NoticeUntunneled(address string)

NoticeUntunneled indicates than an address has been classified as untunneled and is being accessed directly.

Note: "address" should remain private; this notice should only be used for alerting users, not for diagnostics logs.

func NoticeUpstreamProxyError 

func NoticeUpstreamProxyError(err error)

NoticeUpstreamProxyError reports an error when connecting to an upstream proxy. The user may have input, for example, an incorrect address or incorrect credentials.

func NoticeUserLog added in v1.0.5 

func NoticeUserLog(message string)

NoticeUserLog is a log message from the outer client user of tunnel-core

func PromoteServerEntry 

func PromoteServerEntry(config *Config, ipAddress string) error

PromoteServerEntry assigns the top rank (one more than current max rank) to the specified server entry. Server candidates are iterated in decending rank order, so this server entry will be the first candidate in a subsequent tunnel establishment.

func PutBackUnreportedPersistentStats 

func PutBackUnreportedPersistentStats(stats map[string][][]byte) error

PutBackUnreportedPersistentStats restores a list of persistent stat records to StateUnreported.

func RecordRemoteServerListStat 

func RecordRemoteServerListStat(
	url, etag string) error

RecordRemoteServerListStat records a completed common or OSL remote server list resource download.

The RSL download event could occur when the client is unable to immediately send a status request to a server, so these records are stored in the persistent datastore and reported via subsequent status requests sent to any Psiphon server.

Note that common event field values may change between the stat recording and reporting include client geo data, propagation channel, sponsor ID, client version. These are not stored in the datastore (client region, in particular, since that would create an on-disk record of user location). TODO: the server could encrypt, with a nonce and key unknown to the client, a blob containing this data; return it in the handshake response; and the client could store and later report this blob with its tunnel stats records.

Multiple "status" requests may be in flight at once (due to multi-tunnel, asynchronous final status retry, and aggressive status requests for pre-registered tunnels), To avoid duplicate reporting, persistent stats records are "taken-out" by a status request and then "put back" in case the request fails.

Duplicate reporting may also occur when a server receives and processes a status request but the client fails to receive the response.

func RegisterSSHClientVersionPicker 

func RegisterSSHClientVersionPicker(picker func() string)

func RegisterUserAgentPicker 

func RegisterUserAgentPicker(picker func() string)

func ReportAvailableRegions 

func ReportAvailableRegions(config *Config)

ReportAvailableRegions prints a notice with the available egress regions.

func ResetRepetitiveNotices added in v1.0.5 

func ResetRepetitiveNotices()

ResetRepetitiveNotices resets the repetitive notice state, so the next instance of any notice will not be supressed.

func ResolveIP 

func ResolveIP(host string, conn net.Conn) (addrs []net.IP, ttls []time.Duration, err error)

ResolveIP uses a custom dns stack to make a DNS query over the given TCP or UDP conn. This is used, e.g., when we need to ensure that a DNS connection bypasses a VPN interface (BindToDevice) or when we need to ensure that a DNS connection is tunneled. Caller must set timeouts or interruptibility as required for conn.

func ResumeDownload 

func ResumeDownload(
	ctx context.Context,
	httpClient *http.Client,
	downloadURL string,
	userAgent string,
	downloadFilename string,
	ifNoneMatchETag string) (int64, string, error)

ResumeDownload is a reusable helper that downloads requestUrl via the httpClient, storing the result in downloadFilename when the download is complete. Intermediate, partial downloads state is stored in downloadFilename.part and downloadFilename.part.etag. Any existing downloadFilename file will be overwritten.

In the case where the remote object has changed while a partial download is to be resumed, the partial state is reset and resumeDownload fails. The caller must restart the download.

When ifNoneMatchETag is specified, no download is made if the remote object has the same ETag. ifNoneMatchETag has an effect only when no partial download is in progress.

func SelectTLSProfile 

func SelectTLSProfile(
	useIndistinguishableTLS bool,
	tunnelProtocol string,
	clientParameters *parameters.ClientParameters) string

func SendFeedback 

func SendFeedback(configJson, diagnosticsJson, b64EncodedPublicKey, uploadServer, uploadPath, uploadServerHeaders string) error

Encrypt feedback and upload to server. If upload fails the feedback thread will sleep and retry multiple times.

func SetEmitDiagnosticNotices 

func SetEmitDiagnosticNotices(enable bool)

SetEmitDiagnosticNotices toggles whether diagnostic notices are emitted. Diagnostic notices contain potentially sensitive circumvention network information; only enable this in environments where notices are handled securely (for example, don't include these notices in log files which users could post to public forums).

func SetKeyValue 

func SetKeyValue(key, value string) error

SetKeyValue stores a key/value pair.

func SetNoticeFiles added in v1.0.5 

func SetNoticeFiles(
	homepageFilename string,
	rotatingFilename string,
	rotatingFileSize int,
	rotatingSyncFrequency int) error

SetNoticeFiles configures files for notice writing.

  • When homepageFilename is not "", homepages are written to the specified file and omitted from the writer. The file may be read after the Tunnels notice with count of 1. The file should be opened read-only for reading.
  • When rotatingFilename is not "", all notices are are written to the specified file. Diagnostic notices are omitted from the writer. The file is rotated when its size exceeds rotatingFileSize. One rotated older file, <rotatingFilename>.1, is retained. The files may be read at any time; and should be opened read-only for reading. rotatingSyncFrequency specifies how many notices are written before syncing the file. If either rotatingFileSize or rotatingSyncFrequency are <= 0, default values are used.
  • If an error occurs when writing to a file, an InternalError notice is emitted to the writer.

SetNoticeFiles closes open homepage or rotating files before applying the new configuration.

func SetNoticeWriter added in v1.0.5 

func SetNoticeWriter(writer io.Writer)

SetNoticeWriter sets a target writer to receive notices. By default, notices are written to stderr. Notices are newline delimited.

writer specifies an alternate io.Writer where notices are to be written.

Notices are encoded in JSON. Here's an example:

{"data":{"message":"shutdown operate tunnel"},"noticeType":"Info","showUser":false,"timestamp":"2006-01-02T15:04:05.999999999Z07:00"}

All notices have the following fields: - "noticeType": the type of notice, which indicates the meaning of the notice along with what's in the data payload. - "data": additional structured data payload. For example, the "ListeningSocksProxyPort" notice type has a "port" integer data in its payload. - "showUser": whether the information should be displayed to the user. For example, this flag is set for "SocksProxyPortInUse" as the user should be informed that their configured choice of listening port could not be used. Core clients should anticipate that the core will add additional "showUser"=true notices in the future and emit at least the raw notice. - "timestamp": UTC timezone, RFC3339Milli format timestamp for notice event

See the Notice* functions for details on each notice meaning and payload.

func SetSLOK 

func SetSLOK(id, key []byte) (bool, error)

SetSLOK stores a SLOK key, referenced by its ID. The bool return value indicates whether the SLOK was already stored.

func SetSplitTunnelRoutes 

func SetSplitTunnelRoutes(region, etag string, data []byte) error

SetSplitTunnelRoutes updates the cached routes data for the given region. The associated etag is also stored and used to make efficient web requests for updates to the data.

func SetUrlETag 

func SetUrlETag(url, etag string) error

SetUrlETag stores an ETag for the specfied URL. Note: input URL is treated as a string, and is not encoded or decoded or otherwise canonicalized.

func StorePersistentStat 

func StorePersistentStat(statType string, stat []byte) error

StorePersistentStat adds a new persistent stat record, which is set to StateUnreported and is an immediate candidate for reporting.

The stat is a JSON byte array containing fields as required by the Psiphon server API. It's assumed that the JSON value contains enough unique information for the value to function as a key in the key/value datastore. This assumption is currently satisfied by the fields sessionId + tunnelNumber for tunnel stats, and URL + ETag for remote server list stats.

func StoreServerEntries 

func StoreServerEntries(
	config *Config,
	serverEntries []*protocol.ServerEntry,
	replaceIfExists bool) error

StoreServerEntries stores a list of server entries. There is an independent transaction for each entry insert/update.

func StoreServerEntry 

func StoreServerEntry(serverEntry *protocol.ServerEntry, replaceIfExists bool) error

StoreServerEntry adds the server entry to the data store. A newly stored (or re-stored) server entry is assigned the next-to-top rank for iteration order (the previous top ranked entry is promoted). The purpose of inserting at next-to-top is to keep the last selected server as the top ranked server.

When a server entry already exists for a given server, it will be replaced only if replaceIfExists is set or if the the ConfigurationVersion field of the new entry is strictly higher than the existing entry.

If the server entry data is malformed, an alert notice is issued and the entry is skipped; no error is returned.

func StreamingStoreServerEntries added in v1.0.5 

func StreamingStoreServerEntries(
	config *Config,
	serverEntries *protocol.StreamingServerEntryDecoder,
	replaceIfExists bool) error

StreamingStoreServerEntries stores a list of server entries. There is an independent transaction for each entry insert/update.

func TakeOutUnreportedPersistentStats 

func TakeOutUnreportedPersistentStats(maxCount int) (map[string][][]byte, error)

TakeOutUnreportedPersistentStats returns up to maxCount persistent stats records that are in StateUnreported. The records are set to StateReporting. If the records are successfully reported, clear them with ClearReportedPersistentStats. If the records are not successfully reported, restore them with PutBackUnreportedPersistentStats.

func TrimError 

func TrimError(err error) error

TrimError removes the middle of over-long error message strings

func UserAgentIfUnset 

func UserAgentIfUnset(
	clientParameters *parameters.ClientParameters, headers http.Header) bool

UserAgentIfUnset selects and sets a User-Agent header if one is not set.

func WaitForNetworkConnectivity 

func WaitForNetworkConnectivity(
	ctx context.Context, connectivityChecker NetworkConnectivityChecker) bool

WaitForNetworkConnectivity uses a NetworkConnectivityChecker to periodically check for network connectivity. It returns true if no NetworkConnectivityChecker is provided (waiting is disabled) or when NetworkConnectivityChecker.HasNetworkConnectivity() indicates connectivity. It waits and polls the checker once a second. When the context is done, false is returned immediately.

Types

type Config 

type Config struct {

	// DataStoreDirectory is the directory in which to store the persistent
	// database, which contains information such as server entries. By
	// default, current working directory.
	//
	// Warning: If the datastore file, DataStoreDirectory/DATA_STORE_FILENAME,
	// exists but fails to open for any reason (checksum error, unexpected
	// file format, etc.) it will be deleted in order to pave a new datastore
	// and continue running.
	DataStoreDirectory string

	// PropagationChannelId is a string identifier which indicates how the
	// Psiphon client was distributed. This parameter is required. This value
	// is supplied by and depends on the Psiphon Network, and is typically
	// embedded in the client binary.
	PropagationChannelId string

	// SponsorId is a string identifier which indicates who is sponsoring this
	// Psiphon client. One purpose of this value is to determine the home
	// pages for display. This parameter is required. This value is supplied
	// by and depends on the Psiphon Network, and is typically embedded in the
	// client binary.
	SponsorId string

	// ClientVersion is the client version number that the client reports to
	// the server. The version number refers to the host client application,
	// not the core tunnel library. One purpose of this value is to enable
	// automatic updates. This value is supplied by and depends on the Psiphon
	// Network, and is typically embedded in the client binary.
	//
	// Note that sending a ClientPlatform string which includes "windows"
	// (case insensitive) and a ClientVersion of <= 44 will cause an error in
	// processing the response to DoConnectedRequest calls.
	ClientVersion string

	// ClientPlatform is the client platform ("Windows", "Android", etc.) that
	// the client reports to the server.
	ClientPlatform string

	// TunnelWholeDevice is a flag that is passed through to the handshake
	// request for stats purposes. Set to 1 when the host application is
	// tunneling the whole device, 0 otherwise.
	TunnelWholeDevice int

	// EgressRegion is a ISO 3166-1 alpha-2 country code which indicates which
	// country to egress from. For the default, "", the best performing server
	// in any country is selected.
	EgressRegion string

	// ListenInterface specifies which interface to listen on.  If no
	// interface is provided then listen on 127.0.0.1. If 'any' is provided
	// then use 0.0.0.0. If there are multiple IP addresses on an interface
	// use the first IPv4 address.
	ListenInterface string

	// DisableLocalSocksProxy disables running the local SOCKS proxy.
	DisableLocalSocksProxy bool

	// LocalSocksProxyPort specifies a port number for the local SOCKS proxy
	// running at 127.0.0.1. For the default value, 0, the system selects a
	// free port (a notice reporting the selected port is emitted).
	LocalSocksProxyPort int

	// LocalHttpProxyPort specifies a port number for the local HTTP proxy
	// running at 127.0.0.1. For the default value, 0, the system selects a
	// free port (a notice reporting the selected port is emitted).
	LocalHttpProxyPort int

	// DisableLocalHTTPProxy disables running the local HTTP proxy.
	DisableLocalHTTPProxy bool

	// NetworkLatencyMultiplier is a multiplier that is to be applied to
	// default network event timeouts. Set this to tune performance for
	// slow networks.
	// When set, must be >= 1.0.
	NetworkLatencyMultiplier float64

	// TunnelProtocol indicates which protocol to use. For the default, "",
	// all protocols are used.
	//
	// Deprecated: Use TunnelProtocols. When TunnelProtocols is not nil, this
	// parameter is ignored.
	TunnelProtocol string

	// TunnelProtocols indicates which protocols to use. Valid values include:
	// "SSH", "OSSH", "UNFRONTED-MEEK-OSSH", "UNFRONTED-MEEK-HTTPS-OSSH",
	// "UNFRONTED-MEEK-SESSION-TICKET-OSSH", "FRONTED-MEEK-OSSH", "FRONTED-
	// MEEK-HTTP-OSSH".
	//
	// For the default, an empty list, all protocols are used.
	TunnelProtocols []string

	// EstablishTunnelTimeoutSeconds specifies a time limit after which to
	// halt the core tunnel controller if no tunnel has been established. The
	// default is parameters.EstablishTunnelTimeoutSeconds.
	EstablishTunnelTimeoutSeconds *int

	// EstablishTunnelPausePeriodSeconds specifies the delay between attempts
	// to establish tunnels. Briefly pausing allows for network conditions to
	// improve and for asynchronous operations such as fetch remote server
	// list to complete. If omitted, a default value is used. This value is
	// typical overridden for testing.
	EstablishTunnelPausePeriodSeconds *int

	// ConnectionWorkerPoolSize specifies how many connection attempts to
	// attempt in parallel. If omitted of when 0, a default is used; this is
	// recommended.
	ConnectionWorkerPoolSize int

	// TunnelPoolSize specifies how many tunnels to run in parallel. Port
	// forwards are multiplexed over multiple tunnels. If omitted or when 0,
	// the default is TUNNEL_POOL_SIZE, which is recommended.
	TunnelPoolSize int

	// StaggerConnectionWorkersMilliseconds adds a specified delay before
	// making each server candidate available to connection workers. This
	// option is enabled when StaggerConnectionWorkersMilliseconds > 0.
	StaggerConnectionWorkersMilliseconds int

	// LimitMeekConnectionWorkers limits the number of concurrent connection
	// workers attempting connections with meek protocols. This option is
	// enabled when LimitMeekConnectionWorkers > 0.
	LimitMeekConnectionWorkers int

	// LimitMeekBufferSizes selects smaller buffers for meek protocols.
	LimitMeekBufferSizes bool

	// IgnoreHandshakeStatsRegexps skips compiling and using stats regexes.
	IgnoreHandshakeStatsRegexps bool

	// UpstreamProxyURL is a URL specifying an upstream proxy to use for all
	// outbound connections. The URL should include proxy type and
	// authentication information, as required. See example URLs here:
	// https://github.com/Psiphon-Labs/psiphon-tunnel-core/tree/master/psiphon/upstreamproxy
	UpstreamProxyURL string

	// CustomHeaders is a set of additional arbitrary HTTP headers that are
	// added to all plaintext HTTP requests and requests made through an HTTP
	// upstream proxy when specified by UpstreamProxyURL.
	CustomHeaders http.Header

	// Deprecated: Use CustomHeaders. When CustomHeaders is not nil, this
	// parameter is ignored.
	UpstreamProxyCustomHeaders http.Header

	// NetworkConnectivityChecker is an interface that enables tunnel-core to
	// call into the host application to check for network connectivity. See:
	// NetworkConnectivityChecker doc.
	//
	// This parameter is only applicable to library deployments.
	NetworkConnectivityChecker NetworkConnectivityChecker

	// DeviceBinder is an interface that enables tunnel-core to call into the
	// host application to bind sockets to specific devices. See: DeviceBinder
	// doc.
	//
	// This parameter is only applicable to library deployments.
	DeviceBinder DeviceBinder

	// IPv6Synthesizer is an interface that allows tunnel-core to call into
	// the host application to synthesize IPv6 addresses. See: IPv6Synthesizer
	// doc.
	//
	// This parameter is only applicable to library deployments.
	IPv6Synthesizer IPv6Synthesizer

	// DnsServerGetter is an interface that enables tunnel-core to call into
	// the host application to discover the native network DNS server
	// settings. See: DnsServerGetter doc.
	//
	// This parameter is only applicable to library deployments.
	DnsServerGetter DnsServerGetter

	// NetworkIDGetter in an interface that enables tunnel-core to call into
	// the host application to get an identifier for the host's current active
	// network. See: NetworkIDGetter doc.
	//
	// This parameter is only applicable to library deployments.
	NetworkIDGetter NetworkIDGetter

	// NetworkID, when not blank, is used as the identifier for the host's
	// current active network.
	// NetworkID is ignored when NetworkIDGetter is set.
	NetworkID string

	// DisableTactics disables tactics operations including requests, payload
	// handling, and application of parameters.
	DisableTactics bool

	// TransformHostNames specifies whether to use hostname transformation
	// circumvention strategies. Set to "always" to always transform, "never"
	// to never transform, and "", the default, for the default transformation
	// strategy.
	TransformHostNames string

	// TargetServerEntry is an encoded server entry. When specified, this
	// server entry is used exclusively and all other known servers are
	// ignored.
	TargetServerEntry string

	// DisableApi disables Psiphon server API calls including handshake,
	// connected, status, etc. This is used for special case temporary tunnels
	// (Windows VPN mode).
	DisableApi bool

	// TargetApiProtocol specifies whether to force use of "ssh" or "web" API
	// protocol. When blank, the default, the optimal API protocol is used.
	// Note that this capability check is not applied before the
	// "CandidateServers" count is emitted.
	//
	// This parameter is intended for testing and debugging only. Not all
	// parameters are supported in the legacy "web" API protocol, including
	// speed test samples.
	TargetApiProtocol string

	// RemoteServerListUrl is a URL which specifies a location to fetch out-
	// of-band server entries. This facility is used when a tunnel cannot be
	// established to known servers. This value is supplied by and depends on
	// the Psiphon Network, and is typically embedded in the client binary.
	//
	// Deprecated: Use RemoteServerListURLs. When RemoteServerListURLs is not
	// nil, this parameter is ignored.
	RemoteServerListUrl string

	// RemoteServerListURLs is list of URLs which specify locations to fetch
	// out-of-band server entries. This facility is used when a tunnel cannot
	// be established to known servers. This value is supplied by and depends
	// on the Psiphon Network, and is typically embedded in the client binary.
	// All URLs must point to the same entity with the same ETag. At least one
	// DownloadURL must have OnlyAfterAttempts = 0.
	RemoteServerListURLs parameters.DownloadURLs

	// RemoteServerListDownloadFilename specifies a target filename for
	// storing the remote server list download. Data is stored in co-located
	// files (RemoteServerListDownloadFilename.part*) to allow for resumable
	// downloading.
	RemoteServerListDownloadFilename string

	// RemoteServerListSignaturePublicKey specifies a public key that's used
	// to authenticate the remote server list payload. This value is supplied
	// by and depends on the Psiphon Network, and is typically embedded in the
	// client binary.
	RemoteServerListSignaturePublicKey string

	// DisableRemoteServerListFetcher disables fetching remote server lists.
	// This is used for special case temporary tunnels.
	DisableRemoteServerListFetcher bool

	// FetchRemoteServerListRetryPeriodMilliseconds specifies the delay before
	// resuming a remote server list download after a failure. If omitted, a
	// default value is used. This value is typical overridden for testing.
	FetchRemoteServerListRetryPeriodMilliseconds *int

	// ObfuscatedServerListRootURL is a URL which specifies the root location
	// from which to fetch obfuscated server list files. This value is
	// supplied by and depends on the Psiphon Network, and is typically
	// embedded in the client binary.
	//
	// Deprecated: Use ObfuscatedServerListRootURLs. When
	// ObfuscatedServerListRootURLs is not nil, this parameter is ignored.
	ObfuscatedServerListRootURL string

	// ObfuscatedServerListRootURLs is a list of URLs which specify root
	// locations from which to fetch obfuscated server list files. This value
	// is supplied by and depends on the Psiphon Network, and is typically
	// embedded in the client binary. All URLs must point to the same entity
	// with the same ETag. At least one DownloadURL must have
	// OnlyAfterAttempts = 0.
	ObfuscatedServerListRootURLs parameters.DownloadURLs

	// ObfuscatedServerListDownloadDirectory specifies a target directory for
	// storing the obfuscated remote server list downloads. Data is stored in
	// co-located files (<OSL filename>.part*) to allow for resumable
	// downloading.
	ObfuscatedServerListDownloadDirectory string

	// SplitTunnelRoutesURLFormat is a URL which specifies the location of a
	// routes file to use for split tunnel mode. The URL must include a
	// placeholder for the client region to be supplied. Split tunnel mode
	// uses the routes file to classify port forward destinations as foreign
	// or domestic and does not tunnel domestic destinations. Split tunnel
	// mode is on when all the SplitTunnel parameters are supplied. This value
	// is supplied by and depends on the Psiphon Network, and is typically
	// embedded in the client binary.
	SplitTunnelRoutesURLFormat string

	// SplitTunnelRoutesSignaturePublicKey specifies a public key that's used
	// to authenticate the split tunnel routes payload. This value is supplied
	// by and depends on the Psiphon Network, and is typically embedded in the
	// client binary.
	SplitTunnelRoutesSignaturePublicKey string

	// SplitTunnelDNSServer specifies a DNS server to use when resolving port
	// forward target domain names to IP addresses for classification. The DNS
	// server must support TCP requests.
	SplitTunnelDNSServer string

	// UpgradeDownloadUrl specifies a URL from which to download a host client
	// upgrade file, when one is available. The core tunnel controller
	// provides a resumable download facility which downloads this resource
	// and emits a notice when complete. This value is supplied by and depends
	// on the Psiphon Network, and is typically embedded in the client binary.
	//
	// Deprecated: Use UpgradeDownloadURLs. When UpgradeDownloadURLs is not
	// nil, this parameter is ignored.
	UpgradeDownloadUrl string

	// UpgradeDownloadURLs is list of URLs which specify locations from which
	// to download a host client upgrade file, when one is available. The core
	// tunnel controller provides a resumable download facility which
	// downloads this resource and emits a notice when complete. This value is
	// supplied by and depends on the Psiphon Network, and is typically
	// embedded in the client binary. All URLs must point to the same entity
	// with the same ETag. At least one DownloadURL must have
	// OnlyAfterAttempts = 0.
	UpgradeDownloadURLs parameters.DownloadURLs

	// UpgradeDownloadClientVersionHeader specifies the HTTP header name for
	// the entity at UpgradeDownloadURLs which specifies the client version
	// (an integer value). A HEAD request may be made to check the version
	// number available at UpgradeDownloadURLs.
	// UpgradeDownloadClientVersionHeader is required when UpgradeDownloadURLs
	// is specified.
	UpgradeDownloadClientVersionHeader string

	// UpgradeDownloadFilename is the local target filename for an upgrade
	// download. This parameter is required when UpgradeDownloadURLs (or
	// UpgradeDownloadUrl) is specified. Data is stored in co-located files
	// (UpgradeDownloadFilename.part*) to allow for resumable downloading.
	UpgradeDownloadFilename string

	// FetchUpgradeRetryPeriodMilliseconds specifies the delay before resuming
	// a client upgrade download after a failure. If omitted, a default value
	// is used. This value is typical overridden for testing.
	FetchUpgradeRetryPeriodMilliseconds *int

	// EmitBytesTransferred indicates whether to emit periodic notices showing
	// bytes sent and received.
	EmitBytesTransferred bool

	// UseIndistinguishableTLS enables use of alternative TLS profiles with a
	// less distinct fingerprint (ClientHello content) than the stock Go TLS.
	UseIndistinguishableTLS bool

	// UseTrustedCACertificatesForStockTLS toggles use of the trusted CA
	// certs, specified in TrustedCACertificatesFilename, for tunneled TLS
	// connections that expect server certificates signed with public
	// certificate authorities (currently, only upgrade downloads). This
	// option is used with stock Go TLS in cases where Go may fail to obtain a
	// list of root CAs from the operating system. Requires
	// TrustedCACertificatesFilename to be set.
	UseTrustedCACertificatesForStockTLS bool

	// TrustedCACertificatesFilename specifies a file containing trusted CA
	// certs.
	TrustedCACertificatesFilename string

	// DisablePeriodicSshKeepAlive indicates whether to send an SSH keepalive
	// every 1-2 minutes, when the tunnel is idle. If the SSH keepalive times
	// out, the tunnel is considered to have failed.
	DisablePeriodicSshKeepAlive bool

	// DeviceRegion is the optional, reported region the host device is
	// running in. This input value should be a ISO 3166-1 alpha-2 country
	// code. The device region is reported to the server in the connected
	// request and recorded for Psiphon stats.
	//
	// When provided, this value may be used, pre-connection, to select
	// performance or circumvention optimization strategies for the given
	// region.
	DeviceRegion string

	// EmitDiagnosticNotices indicates whether to output notices containing
	// detailed information about the Psiphon session. As these notices may
	// contain sensitive network information, they should not be insecurely
	// distributed or displayed to users. Default is off.
	EmitDiagnosticNotices bool

	// RateLimits specify throttling configuration for the tunnel.
	RateLimits common.RateLimits

	// EmitSLOKs indicates whether to emit notices for each seeded SLOK. As
	// this could reveal user browsing activity, it's intended for debugging
	// and testing only.
	EmitSLOKs bool

	// PacketTunnelTunDeviceFileDescriptor specifies a tun device file
	// descriptor to use for running a packet tunnel. When this value is > 0,
	// a packet tunnel is established through the server and packets are
	// relayed via the tun device file descriptor. The file descriptor is
	// duped in NewController. When PacketTunnelTunDeviceFileDescriptor is
	// set, TunnelPoolSize must be 1.
	PacketTunnelTunFileDescriptor int

	// SessionID specifies a client session ID to use in the Psiphon API. The
	// session ID should be a randomly generated value that is used only for a
	// single session, which is defined as the period between a user starting
	// a Psiphon client and stopping the client.
	//
	// A session ID must be 32 hex digits (lower case). When blank, a random
	// session ID is automatically generated. Supply a session ID when a
	// single client session will cross multiple Controller instances.
	SessionID string

	// Authorizations is a list of encoded, signed access control
	// authorizations that the client has obtained and will present to the
	// server.
	Authorizations []string

	// UseFragmentor and associated Fragmentor fields are for testing
	// purposes.
	UseFragmentor                  string
	FragmentorMinTotalBytes        *int
	FragmentorMaxTotalBytes        *int
	FragmentorMinWriteBytes        *int
	FragmentorMaxWriteBytes        *int
	FragmentorMinDelayMicroseconds *int
	FragmentorMaxDelayMicroseconds *int

	// ObfuscatedSSHAlgorithms and associated ObfuscatedSSH fields are for
	// testing purposes. If specified, ObfuscatedSSHAlgorithms must have 4 SSH
	// KEX elements in order: the kex algorithm, cipher, MAC, and server host
	// key algorithm.
	ObfuscatedSSHAlgorithms []string
	ObfuscatedSSHMinPadding *int
	ObfuscatedSSHMaxPadding *int
	// contains filtered or unexported fields
}

Config is the Psiphon configuration specified by the application. This configuration controls the behavior of the core tunnel functionality.

To distinguish omitted timeout params from explicit 0 value timeout params, corresponding fieldss are int pointers. nil means no value was supplied and to use the default; a non-nil pointer to 0 means no timeout.

func LoadConfig 

func LoadConfig(configJson []byte) (*Config, error)

LoadConfig parses a JSON format Psiphon config JSON string and returns a Config struct populated with config values.

The Config struct may then be programmatically populated with additional values, including callbacks such as DeviceBinder.

Before using the Config, Commit must be called, which will perform further validation and initialize internal data structures.

func (*Config) Commit added in v1.0.5 

func (config *Config) Commit() error

Commit validates Config fields finalizes initialization.

Config fields should not be set after calling Config, as any changes may not be reflected in internal data structures.

func (*Config) GetAuthorizations added in v1.0.5 

func (config *Config) GetAuthorizations() []string

GetAuthorizations returns the current client authorizations. The caller must not modify the returned slice.

func (*Config) GetClientParameters added in v1.0.5 

func (config *Config) GetClientParameters() *parameters.ClientParametersSnapshot

GetClientParameters returns a snapshot of the current client parameters.

func (*Config) GetSponsorID added in v1.0.5 

func (config *Config) GetSponsorID() string

GetSponsorID returns the current client sponsor ID.

func (*Config) IsCommitted added in v1.0.5 

func (config *Config) IsCommitted() bool

IsCommitted checks if Commit was called.

func (*Config) SetClientParameters added in v1.0.5 

func (config *Config) SetClientParameters(tag string, skipOnError bool, applyParameters map[string]interface{}) error

SetClientParameters resets Config.clientParameters to the default values, applies any config file values, and then applies the input parameters (from tactics, etc.)

Set skipOnError to false when initially applying only config values, as this will validate the values and should fail. Set skipOnError to true when applying tactics to ignore invalid or unknown parameter values from tactics.

In the case of applying tactics, do not call Config.clientParameters.Set directly as this will not first apply config values.

If there is an error, the existing Config.clientParameters are left entirely unmodified.

func (*Config) SetDynamicConfig added in v1.0.5 

func (config *Config) SetDynamicConfig(sponsorID string, authorizations []string)

SetDynamicConfig sets the current client sponsor ID and authorizations. Invalid values for sponsor ID are ignored. The caller must not modify the input authorizations slice.

type Controller 

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

Controller is a tunnel lifecycle coordinator. It manages lists of servers to connect to; establishes and monitors tunnels; and runs local proxies which route traffic through the tunnels.

func NewController 

func NewController(config *Config) (controller *Controller, err error)

NewController initializes a new controller.

func (*Controller) Dial 

func (controller *Controller) Dial(
	remoteAddr string, alwaysTunnel bool, downstreamConn net.Conn) (conn net.Conn, err error)

Dial selects an active tunnel and establishes a port forward connection through the selected tunnel. Failure to connect is considered a port forward failure, for the purpose of monitoring tunnel health.

func (*Controller) DirectDial added in v1.0.5 

func (controller *Controller) DirectDial(remoteAddr string) (conn net.Conn, err error)

DirectDial dials an untunneled TCP connection within the controller run context.

func (*Controller) Run 

func (controller *Controller) Run(ctx context.Context)

Run executes the controller. Run exits if a controller component fails or the parent context is canceled.

func (*Controller) SetDynamicConfig added in v1.0.5 

func (controller *Controller) SetDynamicConfig(sponsorID string, authorizations []string)

SetDynamicConfig overrides the sponsor ID and authorizations fields of the Controller config with the input values. The new values will be used in the next tunnel connection.

func (*Controller) SignalComponentFailure 

func (controller *Controller) SignalComponentFailure()

SignalComponentFailure notifies the controller that an associated component has failed. This will terminate the controller.

func (*Controller) SignalSeededNewSLOK 

func (controller *Controller) SignalSeededNewSLOK()

SignalSeededNewSLOK implements the TunnelOwner interface. This function is called by Tunnel.operateTunnel when the tunnel has received a new, previously unknown SLOK from the server. The Controller triggers an OSL fetch, as the new SLOK may be sufficient to access new OSLs.

func (*Controller) SignalTunnelFailure 

func (controller *Controller) SignalTunnelFailure(tunnel *Tunnel)

SignalTunnelFailure implements the TunnelOwner interface. This function is called by Tunnel.operateTunnel when the tunnel has detected that it has failed. The Controller will signal runTunnels to create a new tunnel and/or remove the tunnel from the list of active tunnels.

func (*Controller) TerminateNextActiveTunnel added in v1.0.5 

func (controller *Controller) TerminateNextActiveTunnel()

TerminateNextActiveTunnel terminates the active tunnel, which will initiate establishment of a new tunnel.

type CustomTLSConfig 

type CustomTLSConfig struct {

	// ClientParameters is the active set of client parameters to use
	// for the TLS dial.
	ClientParameters *parameters.ClientParameters

	// Dial is the network connection dialer. TLS is layered on
	// top of a new network connection created with dialer.
	Dial Dialer

	// DialAddr overrides the "addr" input to Dial when specified
	DialAddr string

	// UseDialAddrSNI specifies whether to always use the dial "addr"
	// host name in the SNI server_name field. When DialAddr is set,
	// its host name is used.
	UseDialAddrSNI bool

	// SNIServerName specifies the value to set in the SNI
	// server_name field. When blank, SNI is omitted. Note that
	// underlying TLS code also automatically omits SNI when
	// the server_name is an IP address.
	// SNIServerName is ignored when UseDialAddrSNI is true.
	SNIServerName string

	// SkipVerify completely disables server certificate verification.
	SkipVerify bool

	// VerifyLegacyCertificate is a special case self-signed server
	// certificate case. Ignores IP SANs and basic constraints. No
	// certificate chain. Just checks that the server presented the
	// specified certificate. SNI is disbled when this is set.
	VerifyLegacyCertificate *x509.Certificate

	// UseIndistinguishableTLS specifies whether to try to use an
	// alternative profile for TLS dials. From a circumvention perspective,
	// Go's TLS has a distinct fingerprint that may be used for blocking.
	UseIndistinguishableTLS bool

	// TLSProfile specifies a particular indistinguishable TLS profile
	// to use for the TLS dial. UseIndistinguishableTLS must be set for
	// TLSProfile to take effect.
	// When TLSProfile is "" and UseIndistinguishableTLS is set, a profile
	// is selected at random. Setting TLSProfile allows the caller to pin
	// the selection so all TLS connections in a certain context (e.g. a
	// single meek connection) use a consistent value.
	// The value should be selected by calling SelectTLSProfile, which
	// will pick a value at random, subject to compatibility constraints.
	TLSProfile string

	// TrustedCACertificatesFilename specifies a file containing trusted
	// CA certs. Directory contents should be compatible with OpenSSL's
	// SSL_CTX_load_verify_locations
	// Only applies to UseIndistinguishableTLS connections.
	TrustedCACertificatesFilename string

	// ObfuscatedSessionTicketKey enables obfuscated session tickets
	// using the specified key.
	ObfuscatedSessionTicketKey string
}

CustomTLSConfig contains parameters to determine the behavior of CustomTLSDial.

type DeviceBinder 

type DeviceBinder interface {
	BindToDevice(fileDescriptor int) (string, error)
}

DeviceBinder defines the interface to the external BindToDevice provider which calls into the host application to bind sockets to specific devices. This is used for VPN routing exclusion. The string return value should report device information for diagnostics.

type DialConfig 

type DialConfig struct {

	// UpstreamProxyURL specifies a proxy to connect through.
	// E.g., "http://proxyhost:8080"
	//       "socks5://user:password@proxyhost:1080"
	//       "socks4a://proxyhost:1080"
	//       "http://NTDOMAIN\NTUser:password@proxyhost:3375"
	//
	// Certain tunnel protocols require HTTP CONNECT support
	// when a HTTP proxy is specified. If CONNECT is not
	// supported, those protocols will not connect.
	UpstreamProxyURL string

	// CustomHeaders is a set of additional arbitrary HTTP headers that are
	// added to all plaintext HTTP requests and requests made through an HTTP
	// upstream proxy when specified by UpstreamProxyURL.
	CustomHeaders http.Header

	// BindToDevice parameters are used to exclude connections and
	// associated DNS requests from VPN routing.
	// When DeviceBinder is set, any underlying socket is
	// submitted to the device binding servicebefore connecting.
	// The service should bind the socket to a device so that it doesn't route
	// through a VPN interface. This service is also used to bind UDP sockets used
	// for DNS requests, in which case DnsServerGetter is used to get the
	// current active untunneled network DNS server.
	DeviceBinder    DeviceBinder
	DnsServerGetter DnsServerGetter
	IPv6Synthesizer IPv6Synthesizer

	// UseIndistinguishableTLS specifies whether to try to use an
	// alternative stack for TLS. From a circumvention perspective,
	// Go's TLS has a distinct fingerprint that may be used for blocking.
	// Only applies to TLS connections.
	UseIndistinguishableTLS bool

	// TrustedCACertificatesFilename specifies a file containing trusted
	// CA certs. The file contents should be compatible with OpenSSL's
	// SSL_CTX_load_verify_locations.
	// Only applies to UseIndistinguishableTLS connections.
	TrustedCACertificatesFilename string

	// DeviceRegion is the reported region the host device is running in.
	// When set, this value may be used, pre-connection, to select performance
	// or circumvention optimization strategies for the given region.
	DeviceRegion string

	// ResolvedIPCallback, when set, is called with the IP address that was
	// dialed. This is either the specified IP address in the dial address,
	// or the resolved IP address in the case where the dial address is a
	// domain name.
	// The callback may be invoked by a concurrent goroutine.
	ResolvedIPCallback func(string)
}

DialConfig contains parameters to determine the behavior of a Psiphon dialer (TCPDial, MeekDial, etc.)

type DialStats added in v1.0.5 

type DialStats struct {
	SelectedSSHClientVersion       bool
	SSHClientVersion               string
	UpstreamProxyType              string
	UpstreamProxyCustomHeaderNames []string
	MeekDialAddress                string
	MeekResolvedIPAddress          atomic.Value
	MeekSNIServerName              string
	MeekHostHeader                 string
	MeekTransformedHostName        bool
	SelectedUserAgent              bool
	UserAgent                      string
	SelectedTLSProfile             bool
	TLSProfile                     string
}

DialStats records additional dial config that is sent to the server for stats recording. This data is used to analyze which configuration settings are successful in various circumvention contexts, and includes meek dial params and upstream proxy params.

For upstream proxy, only proxy type and custom header names are recorded; proxy address and custom header values are considered PII.

MeekResolvedIPAddress is set asynchronously, as it is not known until the dial process has begun. The atomic.Value will contain a string, initialized to "", and set to the resolved IP address once that part of the dial process has completed.

type Dialer 

type Dialer func(context.Context, string, string) (net.Conn, error)

Dialer is a custom network dialer.

func NewCustomTLSDialer 

func NewCustomTLSDialer(config *CustomTLSConfig) Dialer

func NewTCPDialer 

func NewTCPDialer(config *DialConfig) Dialer

NewTCPDialer creates a TCPDialer.

Note: do not set an UpstreamProxyURL in the config when using NewTCPDialer as a custom dialer for NewProxyAuthTransport (or http.Transport with a ProxyUrl), as that would result in double proxy chaining.

func NewTCPFragmentorDialer added in v1.0.5 

func NewTCPFragmentorDialer(
	config *DialConfig,
	tunnelProtocol string,
	clientParameters *parameters.ClientParameters) Dialer

NewTCPFragmentorDialer creates a TCP dialer that wraps dialed conns in FragmentorConn. A single FragmentorProbability coin flip is made and all conns get the same treatment.

type DnsServerGetter 

type DnsServerGetter interface {
	GetPrimaryDnsServer() string
	GetSecondaryDnsServer() string
}

DnsServerGetter defines the interface to the external GetDnsServer provider which calls into the host application to discover the native network DNS server settings.

type FragmentorConn added in v1.0.5 

type FragmentorConn struct {
	net.Conn
	// contains filtered or unexported fields
}

FragmentorConn implements simple fragmentation of application-level messages/packets into multiple TCP packets by splitting writes into smaller sizes and adding delays between writes.

The intent of FragmentorConn is both to frustrate firewalls that perform DPI on application-level messages that cross TCP packets as well as to perform a simple size and timing transformation to the traffic shape of the initial portion of a TCP flow.

func (*FragmentorConn) Close added in v1.0.5 

func (fragmentor *FragmentorConn) Close() (err error)

func (*FragmentorConn) IsClosed added in v1.0.5 

func (fragmentor *FragmentorConn) IsClosed() bool

func (*FragmentorConn) Write added in v1.0.5 

func (fragmentor *FragmentorConn) Write(buffer []byte) (int, error)

type HttpProxy 

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

HttpProxy is a HTTP server that relays HTTP requests through the Psiphon tunnel. It includes support for HTTP CONNECT.

This proxy also offers a "URL proxy" mode that relays requests for HTTP or HTTPS or URLs specified in the proxy request path. This mode relays either through the Psiphon tunnel, or directly.

An example use case for tunneled URL proxy relays is to craft proxied URLs to pass to components that don't support HTTP or SOCKS proxy settings. For example, the Android Media Player (http://developer.android.com/reference/android/media/MediaPlayer.html). To make the Media Player use the Psiphon tunnel, construct a URL such as: "http://127.0.0.1:<proxy-port>/tunneled/<origin media URL>"; and pass this to the player. The <origin media URL> must be escaped in such a way that it can be used inside a URL query.

An example use case for direct, untunneled, relaying is to make use of Go's TLS stack for HTTPS requests in cases where the native TLS stack is lacking (e.g., WinHTTP on Windows XP). The URL for direct relaying is: "http://127.0.0.1:<proxy-port>/direct/<origin URL>". Again, the <origin URL> must be escaped in such a way that it can be used inside a URL query.

An example use case for tunneled relaying with rewriting (/tunneled-rewrite/) is when the content of retrieved files contains URLs that also need to be modified to be tunneled. For example, in iOS 10 the UIWebView media player does not put requests through the NSURLProtocol, so they are not tunneled. Instead, we rewrite those URLs to use the URL proxy, and rewrite retrieved playlist files so they also contain proxied URLs.

The URL proxy offers /tunneled-icy/ which is compatible with both HTTP and ICY protocol resources.

Origin URLs must include the scheme prefix ("http://" or "https://") and must be URL encoded.

func NewHttpProxy 

func NewHttpProxy(
	config *Config,
	tunneler Tunneler,
	listenIP string) (proxy *HttpProxy, err error)

NewHttpProxy initializes and runs a new HTTP proxy server.

func (*HttpProxy) Close 

func (proxy *HttpProxy) Close()

Close terminates the HTTP server.

func (*HttpProxy) ServeHTTP 

func (proxy *HttpProxy) ServeHTTP(responseWriter http.ResponseWriter, request *http.Request)

ServeHTTP receives HTTP requests and proxies them. CONNECT requests are hijacked and all data is relayed. Other HTTP requests are proxied with explicit round trips. In both cases, the tunnel is used for proxied traffic.

Implementation is based on:

https://github.com/justmao945/mallory Copyright (c) 2014 JianjunMao The MIT License (MIT)

https://golang.org/src/pkg/net/http/httputil/reverseproxy.go Copyright 2011 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

type IPv6Synthesizer 

type IPv6Synthesizer interface {
	IPv6Synthesize(IPv4Addr string) string
}

IPv6Synthesizer defines the interface to the external IPv6Synthesize provider which calls into the host application to synthesize IPv6 addresses from IPv4 ones. This is used to correctly lookup IPs on DNS64/NAT64 networks.

type MeekConfig 

type MeekConfig struct {

	// ClientParameters is the active set of client parameters to use
	// for the meek dial.
	ClientParameters *parameters.ClientParameters

	// DialAddress is the actual network address to dial to establish a
	// connection to the meek server. This may be either a fronted or
	// direct address. The address must be in the form "host:port",
	// where host may be a domain name or IP address.
	DialAddress string

	// UseHTTPS indicates whether to use HTTPS (true) or HTTP (false).
	UseHTTPS bool

	// TLSProfile specifies the TLS profile to use for all underlying
	// TLS connections created by this meek connection. Valid values
	// are the possible values for CustomTLSConfig.TLSProfile.
	// TLSProfile will be used only when DialConfig.UseIndistinguishableTLS
	// is set in the DialConfig passed in to DialMeek.
	TLSProfile string

	// UseObfuscatedSessionTickets indicates whether to use obfuscated
	// session tickets. Assumes UseHTTPS is true.
	UseObfuscatedSessionTickets bool

	// SNIServerName is the value to place in the TLS SNI server_name
	// field when HTTPS is used.
	SNIServerName string

	// HostHeader is the value to place in the HTTP request Host header.
	HostHeader string

	// TransformedHostName records whether a hostname transformation is
	// in effect. This value is used for stats reporting.
	TransformedHostName bool

	// ClientTunnelProtocol is the protocol the client is using. It's
	// included in the meek cookie for optional use by the server, in
	// cases where the server cannot unambiguously determine the
	// tunnel protocol.
	ClientTunnelProtocol string

	// RoundTripperOnly sets the MeekConn to operate in round tripper
	// mode, which is used for untunneled tactics requests. In this
	// mode, a connection is established to the meek server as usual,
	// but instead of relaying tunnel traffic, the RoundTrip function
	// may be used to make requests. In this mode, no relay resources
	// incuding buffers are allocated.
	RoundTripperOnly bool

	MeekCookieEncryptionPublicKey string
	MeekObfuscatedKey             string
}

MeekConfig specifies the behavior of a MeekConn

type MeekConn 

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

MeekConn is a network connection that tunnels TCP over HTTP and supports "fronting". Meek sends client->server flow in HTTP request bodies and receives server->client flow in HTTP response bodies. Polling is used to achieve full duplex TCP.

Fronting is an obfuscation technique in which the connection to a web server, typically a CDN, is indistinguishable from any other HTTPS connection to the generic "fronting domain" -- the HTTP Host header is used to route the requests to the actual destination. See https://trac.torproject.org/projects/tor/wiki/doc/meek for more details.

MeekConn also operates in unfronted mode, in which plain HTTP connections are made without routing through a CDN.

func DialMeek 

func DialMeek(
	ctx context.Context,
	meekConfig *MeekConfig,
	dialConfig *DialConfig) (meek *MeekConn, err error)

DialMeek returns an initialized meek connection. A meek connection is an HTTP session which does not depend on an underlying socket connection (although persistent HTTP connections are used for performance). This function does not wait for the connection to be "established" before returning. A goroutine is spawned which will eventually start HTTP polling. When frontingAddress is not "", fronting is used. This option assumes caller has already checked server entry capabilities.

func (*MeekConn) Close 

func (meek *MeekConn) Close() (err error)

Close terminates the meek connection. Close waits for the relay goroutine to stop (in relay mode) and releases HTTP transport resources. A mutex is required to support net.Conn concurrency semantics.

func (*MeekConn) IsClosed 

func (meek *MeekConn) IsClosed() bool

IsClosed implements the Closer iterface. The return value indicates whether the MeekConn has been closed.

func (*MeekConn) LocalAddr 

func (meek *MeekConn) LocalAddr() net.Addr

LocalAddr is a stub implementation of net.Conn.LocalAddr

func (*MeekConn) Read 

func (meek *MeekConn) Read(buffer []byte) (n int, err error)

Read reads data from the connection. net.Conn Deadlines are ignored. net.Conn concurrency semantics are supported.

func (*MeekConn) RemoteAddr 

func (meek *MeekConn) RemoteAddr() net.Addr

RemoteAddr is a stub implementation of net.Conn.RemoteAddr

func (*MeekConn) RoundTrip added in v1.0.5 

func (meek *MeekConn) RoundTrip(
	ctx context.Context, endPoint string, requestBody []byte) ([]byte, error)

RoundTrip makes a request to the meek server and returns the response. A new, obfuscated meek cookie is created for every request. The specified end point is recorded in the cookie and is not exposed as plaintext in the meek traffic. The caller is responsible for obfuscating the request body.

RoundTrip is not safe for concurrent use, and Close must not be called concurrently. The caller must ensure onlt one RoundTrip call is active at once and that it completes before calling Close.

RoundTrip is only available in round tripper mode.

func (*MeekConn) SetDeadline 

func (meek *MeekConn) SetDeadline(t time.Time) error

SetDeadline is a stub implementation of net.Conn.SetDeadline

func (*MeekConn) SetReadDeadline 

func (meek *MeekConn) SetReadDeadline(t time.Time) error

SetReadDeadline is a stub implementation of net.Conn.SetReadDeadline

func (*MeekConn) SetWriteDeadline 

func (meek *MeekConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline is a stub implementation of net.Conn.SetWriteDeadline

func (*MeekConn) Write 

func (meek *MeekConn) Write(buffer []byte) (n int, err error)

Write writes data to the connection. net.Conn Deadlines are ignored. net.Conn concurrency semantics are supported.

type NetworkConnectivityChecker 

type NetworkConnectivityChecker interface {
	// TODO: change to bool return value once gobind supports that type
	HasNetworkConnectivity() int
}

NetworkConnectivityChecker defines the interface to the external HasNetworkConnectivity provider, which call into the host application to check for network connectivity.

type NetworkIDGetter added in v1.0.5 

type NetworkIDGetter interface {
	GetNetworkID() string
}

NetworkIDGetter defines the interface to the external GetNetworkID provider, which returns an identifier for the host's current active network.

The identifier is a string that should indicate the network type and identity; for example "WIFI-<BSSID>" or "MOBILE-<MCC/MNC>". As this network ID is personally identifying, it is only used locally in the client to determine network context and is not sent to the Psiphon server. The identifer will be logged in diagnostics messages; in this case only the substring before the first "-" is logged, so all PII must appear after the first "-".

NetworkIDGetter.GetNetworkID should always return an identifier value, as logic that uses GetNetworkID, including tactics, is intended to proceed regardless of whether an accurate network identifier can be obtained. By convention, the provider should return "UNKNOWN" when an accurate network identifier cannot be obtained. Best-effort is acceptable: e.g., return just "WIFI" when only the type of the network but no details can be determined.

type NoticeReceiver 

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

NoticeReceiver consumes a notice input stream and invokes a callback function for each discrete JSON notice object byte sequence.

func NewNoticeConsoleRewriter 

func NewNoticeConsoleRewriter(writer io.Writer) *NoticeReceiver

NewNoticeConsoleRewriter consumes JSON-format notice input and parses each notice and rewrites in a more human-readable format more suitable for console output. The data payload field is left as JSON.

func NewNoticeReceiver 

func NewNoticeReceiver(callback func([]byte)) *NoticeReceiver

NewNoticeReceiver initializes a new NoticeReceiver

func (*NoticeReceiver) Write 

func (receiver *NoticeReceiver) Write(p []byte) (n int, err error)

Write implements io.Writer.

type NoticeWriter 

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

NoticeWriter implements io.Writer and emits the contents of Write() calls as Notices. This is to transform logger messages, if they can be redirected to an io.Writer, to notices.

func NewNoticeWriter 

func NewNoticeWriter(noticeType string) *NoticeWriter

NewNoticeWriter initializes a new NoticeWriter

func (*NoticeWriter) Write 

func (writer *NoticeWriter) Write(p []byte) (n int, err error)

Write implements io.Writer.

type PacketTunnelTransport added in v1.0.5 

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

PacketTunnelTransport is an integration layer that presents an io.ReadWriteCloser interface to a tun.Client as the transport for relaying packets. The Psiphon client may periodically disconnect from and reconnect to the same or different Psiphon servers. PacketTunnelTransport allows the Psiphon client to substitute new transport channels on-the-fly.

func NewPacketTunnelTransport added in v1.0.5 

func NewPacketTunnelTransport() *PacketTunnelTransport

NewPacketTunnelTransport initializes a PacketTunnelTransport.

func (*PacketTunnelTransport) Close added in v1.0.5 

func (p *PacketTunnelTransport) Close() error

Close implements the io.Closer interface. Any underlying transport channel is closed and any blocking Read/Write calls will be interrupted.

func (*PacketTunnelTransport) Read added in v1.0.5 

func (p *PacketTunnelTransport) Read(data []byte) (int, error)

Read implements the io.Reader interface. It uses the current transport channel to read packet data, or waits for a new transport channel to be established after a failure.

func (*PacketTunnelTransport) UseTunnel added in v1.0.5 

func (p *PacketTunnelTransport) UseTunnel(tunnel *Tunnel)

UseTunnel sets the PacketTunnelTransport to use a new transport channel within the specified tunnel. UseTunnel does not block on the open channel call; it spawns a worker that calls tunnel.DialPacketTunnelChannel and uses the resulting channel.

func (*PacketTunnelTransport) Write added in v1.0.5 

func (p *PacketTunnelTransport) Write(data []byte) (int, error)

Write implements the io.Writer interface. It uses the current transport channel to write packet data, or waits for a new transport channel to be established after a failure.

type RemoteServerListFetcher 

type RemoteServerListFetcher func(
	ctx context.Context, config *Config, attempt int, tunnel *Tunnel, untunneledDialConfig *DialConfig) error

type ServerContext 

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

ServerContext is a utility struct which holds all of the data associated with a Psiphon server connection. In addition to the established tunnel, this includes data and transport mechanisms for Psiphon API requests. Legacy servers offer the Psiphon API through a web service; newer servers offer the Psiphon API through SSH requests made directly through the tunnel's SSH client.

func NewServerContext 

func NewServerContext(tunnel *Tunnel) (*ServerContext, error)

NewServerContext makes the tunneled handshake request to the Psiphon server and returns a ServerContext struct for use with subsequent Psiphon server API requests (e.g., periodic connected and status requests).

func (*ServerContext) DoConnectedRequest 

func (serverContext *ServerContext) DoConnectedRequest() error

DoConnectedRequest performs the "connected" API request. This request is used for statistics. The server returns a last_connected token for the client to store and send next time it connects. This token is a timestamp (using the server clock, and should be rounded to the nearest hour) which is used to determine when a connection represents a unique user for a time period.

func (*ServerContext) DoStatusRequest 

func (serverContext *ServerContext) DoStatusRequest(tunnel *Tunnel) error

DoStatusRequest makes a "status" API request to the server, sending session stats.

func (*ServerContext) StatsRegexps 

func (serverContext *ServerContext) StatsRegexps() *transferstats.Regexps

StatsRegexps gets the Regexps used for the statistics for this tunnel.

type ServerEntryIterator 

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

ServerEntryIterator is used to iterate over stored server entries in rank order.

func NewServerEntryIterator 

func NewServerEntryIterator(config *Config) (bool, *ServerEntryIterator, error)

NewServerEntryIterator creates a new ServerEntryIterator.

The boolean return value indicates whether to treat the first server(s) as affinity servers or not. When the server entry selection filter changes such as from a specific region to any region, or when there was no previous filter/iterator, the the first server(s) are arbitrary and should not be given affinity treatment.

NewServerEntryIterator and any returned ServerEntryIterator are not designed for concurrent use as not all related datastore operations are performed in a single transaction.

func NewTacticsServerEntryIterator added in v1.0.5 

func NewTacticsServerEntryIterator(config *Config) (*ServerEntryIterator, error)

func (*ServerEntryIterator) Close 

func (iterator *ServerEntryIterator) Close()

Close cleans up resources associated with a ServerEntryIterator.

func (*ServerEntryIterator) Next 

func (iterator *ServerEntryIterator) Next() (*protocol.ServerEntry, error)

Next returns the next server entry, by rank, for a ServerEntryIterator. Returns nil with no error when there is no next item.

func (*ServerEntryIterator) Reset 

func (iterator *ServerEntryIterator) Reset() error

Reset a NewServerEntryIterator to the start of its cycle. The next call to Next will return the first server entry.

type SocksProxy 

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

SocksProxy is a SOCKS server that accepts local host connections and, for each connection, establishes a port forward through the tunnel SSH client and relays traffic through the port forward.

func NewSocksProxy 

func NewSocksProxy(
	config *Config,
	tunneler Tunneler,
	listenIP string) (proxy *SocksProxy, err error)

NewSocksProxy initializes a new SOCKS server. It begins listening for connections, starts a goroutine that runs an accept loop, and returns leaving the accept loop running.

func (*SocksProxy) Close 

func (proxy *SocksProxy) Close()

Close terminates the listener and waits for the accept loop goroutine to complete.

type SplitTunnelClassifier 

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

SplitTunnelClassifier determines whether a network destination should be accessed through a tunnel or accessed directly.

The classifier uses tables of IP address data, routes data, to determine if a given IP is to be tunneled or not. If presented with a hostname, the classifier performs a tunneled (uncensored) DNS request to first determine the IP address for that hostname; then a classification is made based on the IP address.

Classification results (both the hostname resolution and the following IP address classification) are cached for the duration of the DNS record TTL.

Classification is by geographical region (country code). When the split tunnel feature is configured to be on, and if the IP address is within the user's region, it may be accessed untunneled. Otherwise, the IP address must be accessed through a tunnel. The user's current region is revealed to a Tunnel via the Psiphon server API handshake.

When a Tunnel has a blank region (e.g., when DisableApi is set and the tunnel registers without performing a handshake) then no routes data is set and all IP addresses are classified as requiring tunneling.

Split tunnel is made on a best effort basis. After the classifier is started, but before routes data is available for the given region, all IP addresses will be classified as requiring tunneling.

Routes data is fetched asynchronously after Start() is called. Routes data is cached in the data store so it need not be downloaded in full when fresh data is in the cache.

func NewSplitTunnelClassifier 

func NewSplitTunnelClassifier(config *Config, tunneler Tunneler) *SplitTunnelClassifier

func (*SplitTunnelClassifier) IsUntunneled 

func (classifier *SplitTunnelClassifier) IsUntunneled(targetAddress string) bool

IsUntunneled takes a destination hostname or IP address and determines if it should be accessed through a tunnel. When a hostname is presented, it is first resolved to an IP address which can be matched against the routes data. Multiple goroutines may invoke RequiresTunnel simultaneously. Multi-reader locks are used in the implementation to enable concurrent access, with no locks held during network access.

func (*SplitTunnelClassifier) Shutdown 

func (classifier *SplitTunnelClassifier) Shutdown()

Shutdown waits until the background setRoutes() goroutine is finished. There is no explicit shutdown signal sent to setRoutes() -- instead we assume that in an overall shutdown situation, the tunnel used for network access in setRoutes() is closed and network events won't delay the completion of the goroutine.

func (*SplitTunnelClassifier) Start 

func (classifier *SplitTunnelClassifier) Start(fetchRoutesTunnel *Tunnel)

Start resets the state of the classifier. In the default state, all IP addresses are classified as requiring tunneling. With sufficient configuration and region info, this function starts a goroutine to asynchronously fetch and install the routes data.

type SyncFileWriter 

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

SyncFileWriter wraps a file and exposes an io.Writer. At predefined steps, the file is synced (flushed to disk) while writing.

func NewSyncFileWriter 

func NewSyncFileWriter(file *os.File) *SyncFileWriter

NewSyncFileWriter creates a SyncFileWriter.

func (*SyncFileWriter) Write 

func (writer *SyncFileWriter) Write(p []byte) (n int, err error)

Write implements io.Writer with periodic file syncing.

type TCPConn 

type TCPConn struct {
	net.Conn
	// contains filtered or unexported fields
}

TCPConn is a customized TCP connection that supports the Closer interface and which may be created using options in DialConfig, including UpstreamProxyURL, DeviceBinder, IPv6Synthesizer, and ResolvedIPCallback. DeviceBinder is implemented using SO_BINDTODEVICE/IP_BOUND_IF, which requires syscall-level socket code.

func (*TCPConn) Close 

func (conn *TCPConn) Close() (err error)

Close terminates a connected TCPConn or interrupts a dialing TCPConn.

func (*TCPConn) CloseWrite 

func (conn *TCPConn) CloseWrite() (err error)

CloseWrite calls net.TCPConn.CloseWrite when the underlying conn is a *net.TCPConn.

func (*TCPConn) IsClosed 

func (conn *TCPConn) IsClosed() bool

IsClosed implements the Closer iterface. The return value indicates whether the TCPConn has been closed.

type TacticsStorer added in v1.0.5 

type TacticsStorer struct {
}

TacticsStorer implements tactics.Storer.

func GetTacticsStorer added in v1.0.5 

func GetTacticsStorer() *TacticsStorer

GetTacticsStorer creates a TacticsStorer.

func (*TacticsStorer) GetSpeedTestSamplesRecord added in v1.0.5 

func (t *TacticsStorer) GetSpeedTestSamplesRecord(networkID string) ([]byte, error)

func (*TacticsStorer) GetTacticsRecord added in v1.0.5 

func (t *TacticsStorer) GetTacticsRecord(networkID string) ([]byte, error)

func (*TacticsStorer) SetSpeedTestSamplesRecord added in v1.0.5 

func (t *TacticsStorer) SetSpeedTestSamplesRecord(networkID string, record []byte) error

func (*TacticsStorer) SetTacticsRecord added in v1.0.5 

func (t *TacticsStorer) SetTacticsRecord(networkID string, record []byte) error

type Tunnel 

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

Tunnel is a connection to a Psiphon server. An established tunnel includes a network connection to the specified server and an SSH session built on top of that transport.

func ConnectTunnel added in v1.0.5 

func ConnectTunnel(
	ctx context.Context,
	config *Config,
	sessionId string,
	serverEntry *protocol.ServerEntry,
	selectedProtocol string,
	adjustedEstablishStartTime monotime.Time) (*Tunnel, error)

ConnectTunnel first makes a network transport connection to the Psiphon server and then establishes an SSH client session on top of that transport. The SSH server is authenticated using the public key in the server entry. Depending on the server's capabilities, the connection may use plain SSH over TCP, obfuscated SSH over TCP, or obfuscated SSH over HTTP (meek protocol). When requiredProtocol is not blank, that protocol is used. Otherwise, the a random supported protocol is used.

Call Activate on a connected tunnel to complete its establishment before using.

Tunnel establishment is split into two phases: connection, and activation. The Controller will run many ConnectTunnel calls concurrently and then, to avoid unnecessary overhead from making handshake requests and starting operateTunnel from tunnels which may be discarded, call Activate on connected tunnels sequentially as necessary.

func (*Tunnel) Activate added in v1.0.5 

func (tunnel *Tunnel) Activate(
	ctx context.Context,
	tunnelOwner TunnelOwner) error

Activate completes the tunnel establishment, performing the handshake request and starting operateTunnel, the worker that monitors the tunnel and handles periodic management.

func (*Tunnel) Close 

func (tunnel *Tunnel) Close(isDiscarded bool)

Close stops operating the tunnel and closes the underlying connection. Supports multiple and/or concurrent calls to Close(). When isDiscarded is set, operateTunnel will not attempt to send final status requests.

func (*Tunnel) Dial 

func (tunnel *Tunnel) Dial(
	remoteAddr string, alwaysTunnel bool, downstreamConn net.Conn) (conn net.Conn, err error)

Dial establishes a port forward connection through the tunnel This Dial doesn't support split tunnel, so alwaysTunnel is not referenced

func (*Tunnel) DialPacketTunnelChannel added in v1.0.5 

func (tunnel *Tunnel) DialPacketTunnelChannel() (net.Conn, error)

func (*Tunnel) IsActivated added in v1.0.5 

func (tunnel *Tunnel) IsActivated() bool

IsActivated returns the tunnel's activated flag.

func (*Tunnel) IsDiscarded 

func (tunnel *Tunnel) IsDiscarded() bool

IsDiscarded returns the tunnel's discarded flag.

func (*Tunnel) SendAPIRequest 

func (tunnel *Tunnel) SendAPIRequest(
	name string, requestPayload []byte) ([]byte, error)

SendAPIRequest sends an API request as an SSH request through the tunnel. This function blocks awaiting a response. Only one request may be in-flight at once; a concurrent SendAPIRequest will block until an active request receives its response (or the SSH connection is terminated).

func (*Tunnel) SignalComponentFailure 

func (tunnel *Tunnel) SignalComponentFailure()

SignalComponentFailure notifies the tunnel that an associated component has failed. This will terminate the tunnel.

type TunnelOwner 

type TunnelOwner interface {
	SignalSeededNewSLOK()
	SignalTunnelFailure(tunnel *Tunnel)
}

TunnelOwner specifies the interface required by Tunnel to notify its owner when it has failed. The owner may, as in the case of the Controller, remove the tunnel from its list of active tunnels.

type TunneledConn 

type TunneledConn struct {
	net.Conn
	// contains filtered or unexported fields
}

TunneledConn implements net.Conn and wraps a port forward connection. It is used to hook into Read and Write to observe I/O errors and report these errors back to the tunnel monitor as port forward failures. TunneledConn optionally tracks a peer connection to be explicitly closed when the TunneledConn is closed.

func (*TunneledConn) Close 

func (conn *TunneledConn) Close() error

func (*TunneledConn) Read 

func (conn *TunneledConn) Read(buffer []byte) (n int, err error)

func (*TunneledConn) Write 

func (conn *TunneledConn) Write(buffer []byte) (n int, err error)

type Tunneler 

type Tunneler interface {

	// Dial creates a tunneled connection.
	//
	// alwaysTunnel indicates that the connection should always be tunneled. If this
	// is not set, the connection may be made directly, depending on split tunnel
	// classification, when that feature is supported and active.
	//
	// downstreamConn is an optional parameter which specifies a connection to be
	// explicitly closed when the Dialed connection is closed. For instance, this
	// is used to close downstreamConn App<->LocalProxy connections when the related
	// LocalProxy<->SshPortForward connections close.
	Dial(remoteAddr string, alwaysTunnel bool, downstreamConn net.Conn) (conn net.Conn, err error)

	DirectDial(remoteAddr string) (conn net.Conn, err error)

	SignalComponentFailure()
}

Tunneler specifies the interface required by components that use a tunnel. Components which use this interface may be serviced by a single Tunnel instance, or a Controller which manages a pool of tunnels, or any other object which implements Tunneler.

Source Files

View all Source files

Directories

Path Synopsis
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.
crypto/acme
Package acme provides an implementation of the Automatic Certificate Management Environment (ACME) spec.
 Package acme provides an implementation of the Automatic Certificate Management Environment (ACME) spec.
crypto/acme/autocert
Package autocert provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.
 Package autocert provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.
crypto/bcrypt
Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm.
 Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm.
crypto/blake2b
Package blake2b implements the BLAKE2b hash algorithm defined by RFC 7693 and the extendable output function (XOF) BLAKE2Xb.
 Package blake2b implements the BLAKE2b hash algorithm defined by RFC 7693 and the extendable output function (XOF) BLAKE2Xb.
crypto/blake2s
Package blake2s implements the BLAKE2s hash algorithm defined by RFC 7693 and the extendable output function (XOF) BLAKE2Xs.
 Package blake2s implements the BLAKE2s hash algorithm defined by RFC 7693 and the extendable output function (XOF) BLAKE2Xs.
crypto/blowfish
Package blowfish implements Bruce Schneier's Blowfish encryption algorithm.
 Package blowfish implements Bruce Schneier's Blowfish encryption algorithm.
crypto/bn256
Package bn256 implements a particular bilinear group at the 128-bit security level.
 Package bn256 implements a particular bilinear group at the 128-bit security level.
crypto/cast5
Package cast5 implements CAST5, as defined in RFC 2144.
 Package cast5 implements CAST5, as defined in RFC 2144.
crypto/chacha20poly1305
Package chacha20poly1305 implements the ChaCha20-Poly1305 AEAD as specified in RFC 7539.
 Package chacha20poly1305 implements the ChaCha20-Poly1305 AEAD as specified in RFC 7539.
crypto/chacha20poly1305/internal/chacha20
Package ChaCha20 implements the core ChaCha20 function as specified in https://tools.ietf.org/html/rfc7539#section-2.3.
 Package ChaCha20 implements the core ChaCha20 function as specified in https://tools.ietf.org/html/rfc7539#section-2.3.
crypto/cryptobyte
Package cryptobyte implements building and parsing of byte strings for DER-encoded ASN.1 and TLS messages.
 Package cryptobyte implements building and parsing of byte strings for DER-encoded ASN.1 and TLS messages.
crypto/curve25519
Package curve25519 provides an implementation of scalar multiplication on the elliptic curve known as curve25519.
 Package curve25519 provides an implementation of scalar multiplication on the elliptic curve known as curve25519.
crypto/ed25519
Package ed25519 implements the Ed25519 signature algorithm.
 Package ed25519 implements the Ed25519 signature algorithm.
crypto/ed25519/internal/edwards25519
crypto/hkdf
Package hkdf implements the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.
 Package hkdf implements the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.
crypto/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.
crypto/nacl/box
Package box authenticates and encrypts messages using public-key cryptography.
 Package box authenticates and encrypts messages using public-key cryptography.
crypto/nacl/secretbox
Package secretbox encrypts and authenticates small messages.
 Package secretbox encrypts and authenticates small messages.
crypto/ocsp
Package ocsp parses OCSP responses as specified in RFC 2560.
 Package ocsp parses OCSP responses as specified in RFC 2560.
crypto/openpgp
Package openpgp implements high level operations on OpenPGP messages.
 Package openpgp implements high level operations on OpenPGP messages.
crypto/openpgp/armor
Package armor implements OpenPGP ASCII Armor, see RFC 4880.
 Package armor implements OpenPGP ASCII Armor, see RFC 4880.
crypto/openpgp/clearsign
Package clearsign generates and processes OpenPGP, clear-signed data.
 Package clearsign generates and processes OpenPGP, clear-signed data.
crypto/openpgp/elgamal
Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v.
 Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v.
crypto/openpgp/errors
Package errors contains common error types for the OpenPGP packages.
 Package errors contains common error types for the OpenPGP packages.
crypto/openpgp/packet
Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880.
 Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880.
crypto/openpgp/s2k
Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1.
 Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1.
crypto/otr
Package otr implements the Off The Record protocol as specified in http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html
 Package otr implements the Off The Record protocol as specified in http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html
crypto/pbkdf2
Package pbkdf2 implements the key derivation function PBKDF2 as defined in RFC 2898 / PKCS #5 v2.0.
 Package pbkdf2 implements the key derivation function PBKDF2 as defined in RFC 2898 / PKCS #5 v2.0.
crypto/pkcs12
Package pkcs12 implements some of PKCS#12.
 Package pkcs12 implements some of PKCS#12.
crypto/pkcs12/internal/rc2
Package rc2 implements the RC2 cipher https://www.ietf.org/rfc/rfc2268.txt http://people.csail.mit.edu/rivest/pubs/KRRR98.pdf This code is licensed under the MIT license.
 Package rc2 implements the RC2 cipher https://www.ietf.org/rfc/rfc2268.txt http://people.csail.mit.edu/rivest/pubs/KRRR98.pdf This code is licensed under the MIT license.
crypto/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.
crypto/ripemd160
Package ripemd160 implements the RIPEMD-160 hash algorithm.
 Package ripemd160 implements the RIPEMD-160 hash algorithm.
crypto/salsa20
Package salsa20 implements the Salsa20 stream cipher as specified in https://cr.yp.to/snuffle/spec.pdf.
 Package salsa20 implements the Salsa20 stream cipher as specified in https://cr.yp.to/snuffle/spec.pdf.
crypto/salsa20/salsa
Package salsa provides low-level access to functions in the Salsa family.
 Package salsa provides low-level access to functions in the Salsa family.
crypto/scrypt
Package scrypt implements the scrypt key derivation function as defined in Colin Percival's paper "Stronger Key Derivation via Sequential Memory-Hard Functions" (https://www.tarsnap.com/scrypt/scrypt.pdf).
 Package scrypt implements the scrypt key derivation function as defined in Colin Percival's paper "Stronger Key Derivation via Sequential Memory-Hard Functions" (https://www.tarsnap.com/scrypt/scrypt.pdf).
crypto/sha3
Package sha3 implements the SHA-3 fixed-output-length hash functions and the SHAKE variable-output-length hash functions defined by FIPS-202.
 Package sha3 implements the SHA-3 fixed-output-length hash functions and the SHAKE variable-output-length hash functions defined by FIPS-202.
crypto/ssh
Package ssh implements an SSH client and server.
 Package ssh implements an SSH client and server.
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.
crypto/ssh/knownhosts
Package knownhosts implements a parser for the OpenSSH known_hosts host key database.
 Package knownhosts implements a parser for the OpenSSH known_hosts host key database.
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.
crypto/ssh/test
This package contains integration tests for the github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/ssh package.
 This package contains integration tests for the github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/ssh package.
crypto/tea
crypto/twofish
Package twofish implements Bruce Schneier's Twofish encryption algorithm.
 Package twofish implements Bruce Schneier's Twofish encryption algorithm.
crypto/xtea
Package xtea implements XTEA encryption, as defined in Needham and Wheeler's 1997 technical report, "Tea extensions."
 Package xtea implements XTEA encryption, as defined in Needham and Wheeler's 1997 technical report, "Tea extensions."
crypto/xts
Package xts implements the XTS cipher mode as specified in IEEE P1619/D16.
 Package xts implements the XTS cipher mode as specified in IEEE P1619/D16.
obfuscator
osl
Package osl implements the Obfuscated Server List (OSL) mechanism.
 Package osl implements the Obfuscated Server List (OSL) mechanism.
osl/paver
parameters
Package parameters implements dynamic, concurrency-safe parameters that determine Psiphon client behavior.
 Package parameters implements dynamic, concurrency-safe parameters that determine Psiphon client behavior.
protocol
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).
tactics
Package tactics provides dynamic Psiphon client configuration based on GeoIP attributes, API parameters, and speed test data.
 Package tactics provides dynamic Psiphon client configuration based on GeoIP attributes, API parameters, and speed test data.
tun
Package tun is an IP packet tunnel server and client.
 Package tun is an IP packet tunnel server and client.
Package server implements the core tunnel functionality of a Psiphon server.
 Package server implements the core tunnel functionality of a Psiphon server.
psinet
Package psinet implements psinet database services.
 Package psinet implements psinet database services.
Package transferstats counts and keeps track of session stats.
 Package transferstats counts and keeps track of session stats.
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.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.