tactics

package
v2.0.28+incompatible Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2022 License: GPL-3.0 Imports: 18 Imported by: 30

Documentation

Overview

Package tactics provides dynamic Psiphon client configuration based on GeoIP attributes, API parameters, and speed test data. The tactics implementation works in concert with the "parameters" package, allowing contextual optimization of Psiphon client parameters; for example, customizing NetworkLatencyMultiplier to adjust timeouts for clients on slow networks; or customizing LimitTunnelProtocols and ConnectionWorkerPoolSize to circumvent specific blocking conditions.

Clients obtain tactics from a Psiphon server. Tactics are configured with a hot- reloadable, JSON format server config file. The config file specifies default tactics for all clients as well as a list of filtered tactics. For each filter, if the client's attributes satisfy the filter then additional tactics are merged into the tactics set provided to the client.

Tactics configuration is optimized for a modest number of filters -- dozens -- and very many GeoIP matches in each filter.

A Psiphon client "tactics request" is an an untunneled, pre-establishment request to obtain tactics, which will in turn be applied and used in the normal tunnel establishment sequence; the tactics request may result in custom timeouts, protocol selection, and other tunnel establishment behavior.

The client will delay its normal establishment sequence and launch a tactics request only when it has no stored, valid tactics for its current network context. The normal establishment sequence will begin, regardless of tactics request outcome, after TacticsWaitPeriod; this ensures that the client will not stall its establishment process when the tactics request cannot complete.

Tactics are configured with a TTL, which is converted to an expiry time on the client when tactics are received and stored. When the client starts its establishment sequence and finds stored, unexpired tactics, no tactics request is made. The expiry time serves to prevent execess tactics requests and avoid a fingerprintable network sequence that would result from always performing the tactics request.

The client calls UseStoredTactics to check for stored tactics; and if none is found (there is no record or it is expired) the client proceeds to call FetchTactics to make the tactics request.

In the Psiphon client and server, the tactics request is transported using the meek protocol. In this case, meek is configured as a simple HTTP round trip transport and does not relay arbitrary streams of data and does not allocate resources required for relay mode. On the Psiphon server, the same meek component handles both tactics requests and tunnel relays. Anti-probing for tactics endpoints are thus provided as usual by meek. A meek request is routed based on an routing field in the obfuscated meek cookie.

As meek may be plaintext and as TLS certificate verification is sometimes skipped, the tactics request payload is wrapped with NaCl box and further wrapped in a padded obfuscator. Distinct request and response nonces are used to mitigate replay attacks. Clients generate ephemeral NaCl key pairs and the server public key is obtained from the server entry. The server entry also contains capabilities indicating that a Psiphon server supports tactics requests and which meek protocol is to be used.

The Psiphon client requests, stores, and applies distinct tactics based on its current network context. The client uses platform-specific APIs to obtain a fine grain network ID based on, for example BSSID for WiFi or MCC/MNC for mobile. These values provides accurate detection of network context changes and can be obtained from the client device without any network activity. As the network ID is personally identifying, this ID is only used by the client and is never sent to the Psiphon server. The client obtains the current network ID from a callback made from tunnel-core to native client code.

Tactics returned to the Psiphon client are accompanied by a "tag" which is a hash digest of the merged tactics data. This tag uniquely identifies the tactics. The client reports the tactics it is employing through the "applied_tactics" common metrics API parameter. When fetching new tactics, the client reports the stored (and possibly expired) tactics it has through the "stored_tactics" API parameter. The stored tactics tag is used to avoid redownloading redundant tactics data; when the tactics response indicates the tag is unchanged, no tactics data is returned and the client simply extends the expiry of the data is already has.

The Psiphon handshake API returns tactics in its response. This enabled regular tactics expiry extension without requiring any distinct tactics request or tactics data transfer when the tag is unchanged. Psiphon clients that connect regularly and successfully with make almost no untunnled tactics requests except for new network IDs. Returning tactics in the handshake reponse also provides tactics in the case where a client is unable to complete an untunneled tactics request but can otherwise establish a tunnel. Clients will abort any outstanding untunneled tactics requests or scheduled retries once a handshake has completed.

The client handshake request component calls SetTacticsAPIParameters to populate the handshake request parameters with tactics inputs, and calls HandleTacticsPayload to process the tactics payload in the handshake response.

The core tactics data is custom values for a subset of the parameters in parameters.Parameters. A client takes the default Parameters, applies any custom values set in its config file, and then applies any stored or received tactics. Each time the tactics changes, this process is repeated so that obsolete tactics parameters are not retained in the client's Parameters instance.

Tactics has a probability parameter that is used in a weighted coin flip to determine if the tactics is to be applied or skipped for the current client session. This allows for experimenting with provisional tactics; and obtaining non-tactic sample metrics in situations which would otherwise always use a tactic.

Speed test data is used in filtered tactics for selection of parameters such as timeouts.

A speed test sample records the RTT of an application-level round trip to a Psiphon server -- either a meek HTTP round trip or an SSH request round trip. The round trip should be preformed after an TCP, TLS, SSH, etc. handshake so that the RTT includes only the application-level round trip. Each sample also records the tunnel/meek protocol used, the Psiphon server region, and a timestamp; these values may be used to filter out outliers or stale samples. The samples record bytes up/down, although at this time the speed test is focused on latency and the payload is simply anti-fingerprint padding and should not be larger than an IP packet.

The Psiphon client records the latest SpeedTestMaxSampleCount speed test samples for each network context. SpeedTestMaxSampleCount should be a modest size, as each speed test sample is ~100 bytes when serialzied and all samples (for one network ID) are loaded into memory and sent as API inputs to tactics and handshake requests.

When a tactics request is initiated and there are no speed test samples for current network ID, the tactics request is proceeded by a speed test round trip, using the same meek round tripper, and that sample is stored and used for the tactics request. with a speed test The client records additional samples taken from regular SSH keep alive round trips and calls AddSpeedTestSample to store these.

The client sends all its speed test samples, for the current network context, to the server in tactics and handshake requests; this allows the server logic to handle outliers and aggregation. Currently, filtered tactics support filerting on speed test RTT maximum, minimum, and median.

Index

Constants

View Source 
const (
	SPEED_TEST_END_POINT               = "speedtest"
	TACTICS_END_POINT                  = "tactics"
	MAX_REQUEST_BODY_SIZE              = 65536
	SPEED_TEST_PADDING_MIN_SIZE        = 0
	SPEED_TEST_PADDING_MAX_SIZE        = 256
	TACTICS_PADDING_MAX_SIZE           = 256
	TACTICS_OBFUSCATED_KEY_SIZE        = 32
	SPEED_TEST_SAMPLES_PARAMETER_NAME  = "speed_test_samples"
	APPLIED_TACTICS_TAG_PARAMETER_NAME = "applied_tactics_tag"
	STORED_TACTICS_TAG_PARAMETER_NAME  = "stored_tactics_tag"
	TACTICS_METRIC_EVENT_NAME          = "tactics"
	NEW_TACTICS_TAG_LOG_FIELD_NAME     = "new_tactics_tag"
	IS_TACTICS_REQUEST_LOG_FIELD_NAME  = "is_tactics_request"
	AGGREGATION_MINIMUM                = "Minimum"
	AGGREGATION_MAXIMUM                = "Maximum"
	AGGREGATION_MEDIAN                 = "Median"
)
View Source 
const (
	GeoIPScopeRegion = 1
	GeoIPScopeISP    = 2
	GeoIPScopeASN    = 4
	GeoIPScopeCity   = 8
)

Variables

View Source 
var (
	TACTICS_REQUEST_NONCE  = []byte{1}
	TACTICS_RESPONSE_NONCE = []byte{2}
)

Functions

func AddSpeedTestSample 

func AddSpeedTestSample(
	params *parameters.Parameters,
	storer Storer,
	networkID string,
	endPointRegion string,
	endPointProtocol string,
	elaspedTime time.Duration,
	request []byte,
	response []byte) error

AddSpeedTestSample stores a new speed test sample. A maximum of SpeedTestMaxSampleCount samples per network ID are stored, so once that limit is reached, the oldest samples are removed to make room for the new sample.

func GenerateKeys 

func GenerateKeys() (encodedRequestPublicKey, encodedRequestPrivateKey, encodedObfuscatedKey string, err error)

GenerateKeys generates a tactics request key pair and obfuscation key.

func MakeSpeedTestResponse 

func MakeSpeedTestResponse(minPadding, maxPadding int) ([]byte, error)

MakeSpeedTestResponse creates a speed test response prefixed with a timestamp and followed by random padding. The timestamp enables the client performing the speed test to record the sample time with an accurate server clock; the random padding is to frustrate fingerprinting. The speed test timestamp is truncated as a privacy measure.

func SetTacticsAPIParameters 

func SetTacticsAPIParameters(
	storer Storer,
	networkID string,
	apiParams common.APIParameters) error

SetTacticsAPIParameters populates apiParams with the additional parameters for tactics. This is used by the Psiphon client when preparing its handshake request.

Types

type Filter 

type Filter struct {

	// Regions specifies a list of GeoIP regions/countries the client
	// must match.
	Regions []string

	// ISPs specifies a list of GeoIP ISPs the client must match.
	ISPs []string

	// ASNs specifies a list of GeoIP ASNs the client must match.
	ASNs []string

	// Cities specifies a list of GeoIP Cities the client must match.
	Cities []string

	// APIParameters specifies API, e.g. handshake, parameter names and
	// a list of values, one of which must be specified to match this
	// filter. Only scalar string API parameters may be filtered.
	// Values may be patterns containing the '*' wildcard.
	APIParameters map[string][]string

	// SpeedTestRTTMilliseconds specifies a Range filter field that the
	// client speed test samples must satisfy.
	SpeedTestRTTMilliseconds *Range
	// contains filtered or unexported fields
}

Filter defines a filter to match against client attributes. Each field within the filter is optional and may be omitted.

type ObfuscatedRoundTripper 

type ObfuscatedRoundTripper func(
	ctx context.Context,
	endPoint string,
	requestBody []byte) ([]byte, error)

ObfuscatedRoundTripper performs a round trip to the specified endpoint, sending the request body and returning the response body, with an obfuscation layer applied to the endpoint value. The context may be used to set a timeout or cancel the round trip.

The Psiphon client provides a ObfuscatedRoundTripper using MeekConn. The client will handle connection details including server selection, dialing details including device binding and upstream proxy, etc.

type Payload 

type Payload struct {

	// Tag is the hash  tag of the accompanying Tactics. When the Tag
	// is the same as the stored tag the client specified in its
	// request, the Tactics will be empty as the client already has the
	// correct data.
	Tag string

	// Tactics is a JSON-encoded Tactics struct and may be nil.
	Tactics json.RawMessage
}

Payload is the data to be returned to the client in response to a tactics request or in the handshake response.

type Range 

type Range struct {

	// Aggregation may be "Maximum", "Minimum", or "Median"
	Aggregation string

	// AtLeast specifies a lower bound for the aggregarted
	// client value.
	AtLeast *int

	// AtMost specifies an upper bound for the aggregarted
	// client value.
	AtMost *int
}

Range is a filter field which specifies that the aggregation of the a client attribute is within specified upper and lower bounds. At least one bound must be specified.

For example, Range is to aggregate and filter client speed test sample RTTs.

type Record 

type Record struct {

	// The Tag is the hash of the tactics data and is used as the
	// stored tag when making requests.
	Tag string

	// Expiry is the time when this perisisted tactics expires as
	// determined by the client applying the TTL against its local
	// clock when the tactics was stored.
	Expiry time.Time

	// Tactics is the core tactics data.
	Tactics Tactics
}

Record is the tactics data persisted by the client. There is one record for each network ID.

func FetchTactics 

func FetchTactics(
	ctx context.Context,
	params *parameters.Parameters,
	storer Storer,
	getNetworkID func() string,
	apiParams common.APIParameters,
	endPointRegion string,
	endPointProtocol string,
	encodedRequestPublicKey string,
	encodedRequestObfuscatedKey string,
	obfuscatedRoundTripper ObfuscatedRoundTripper) (*Record, error)

FetchTactics performs a tactics request. When there are no stored speed test samples for the network ID, a speed test request is performed immediately before the tactics request, using the same ObfuscatedRoundTripper.

The ObfuscatedRoundTripper transport should be established in advance, so that calls to ObfuscatedRoundTripper don't take additional time in TCP, TLS, etc. handshakes.

The caller should first call UseStoredTactics and skip FetchTactics when there is an unexpired stored tactics record available. The caller is expected to set any overall timeout in the context input.

Limitation: it is assumed that the network ID obtained from getNetworkID is the one that is active when the tactics request is received by the server. However, it is remotely possible to switch networks immediately after invoking the GetNetworkID callback and initiating the request. This is partially mitigated by rechecking the network ID after the request and failing if it differs from the initial network ID.

FetchTactics modifies the apiParams input.

func HandleTacticsPayload 

func HandleTacticsPayload(
	storer Storer,
	networkID string,
	payload *Payload) (*Record, error)

HandleTacticsPayload updates the stored tactics with the given payload. If the payload has a new tag/tactics, this is stored and a new expiry time is set. If the payload has the same tag, the existing tactics are retained and the exipry is extended using the previous TTL. HandleTacticsPayload is called by the Psiphon client to handle the tactics payload in the handshake response.

func UseStoredTactics 

func UseStoredTactics(
	storer Storer, networkID string) (*Record, error)

UseStoredTactics checks for an unexpired stored tactics record for the given network ID that may be used immediately. When there is no error and the record is nil, the caller should proceed with FetchTactics.

When used, Record.Tag should be reported as the applied tactics tag.

type Server 

type Server struct {
	common.ReloadableFile

	// RequestPublicKey is the Server's tactics request NaCl box public key.
	RequestPublicKey []byte

	// RequestPublicKey is the Server's tactics request NaCl box private key.
	RequestPrivateKey []byte

	// RequestObfuscatedKey is the tactics request obfuscation key.
	RequestObfuscatedKey []byte

	// DefaultTactics is the baseline tactics for all clients. It must include a
	// TTL and Probability.
	DefaultTactics Tactics

	// FilteredTactics is an ordered list of filter/tactics pairs. For a client,
	// each fltered tactics is checked in order and merged into the clients
	// tactics if the client's attributes satisfy the filter.
	FilteredTactics []struct {
		Filter  Filter
		Tactics Tactics
	}
	// contains filtered or unexported fields
}

Server is a tactics server to be integrated with the Psiphon server meek and handshake components.

The meek server calls HandleEndPoint to handle untunneled tactics and speed test requests. The handshake handler calls GetTacticsPayload to obtain a tactics payload to include with the handsake response.

The Server is a reloadable file; its exported fields are read from the tactics configuration file.

Each client will receive at least the DefaultTactics. Client GeoIP, API parameter, and speed test sample attributes are matched against all filters and the tactics corresponding to any matching filter are merged into the client tactics.

The merge operation replaces any existing item in Parameter with a Parameter specified in the newest matching tactics. The TTL and Probability of the newest matching tactics is taken, although all but the DefaultTactics can omit the TTL and Probability fields.

func NewServer 

func NewServer(
	logger common.Logger,
	logFieldFormatter common.APIParameterLogFieldFormatter,
	apiParameterValidator common.APIParameterValidator,
	configFilename string) (*Server, error)

NewServer creates Server using the specified tactics configuration file.

The logger and logFieldFormatter callbacks are used to log errors and metrics. The apiParameterValidator callback is used to validate client API parameters submitted to the tactics request.

func (*Server) GetFilterGeoIPScope 

func (server *Server) GetFilterGeoIPScope(geoIPData common.GeoIPData) int

GetFilterGeoIPScope returns which GeoIP fields are relevent to tactics filters. The return value is a bit array containing some combination of the GeoIPScopeRegion, GeoIPScopeISP, GeoIPScopeASN, and GeoIPScopeCity flags. For the given geoIPData, all tactics filters reference only the flagged fields.

func (*Server) GetTactics 

func (server *Server) GetTactics(
	includeServerSideOnly bool,
	geoIPData common.GeoIPData,
	apiParams common.APIParameters) (*Tactics, error)

GetTactics assembles and returns tactics data for a client with the specified GeoIP, API parameter, and speed test attributes.

The tactics return value may be nil.

func (*Server) GetTacticsPayload 

func (server *Server) GetTacticsPayload(
	geoIPData common.GeoIPData,
	apiParams common.APIParameters) (*Payload, error)

GetTacticsPayload assembles and returns a tactics payload for a client with the specified GeoIP, API parameter, and speed test attributes.

The speed test samples are expected to be in apiParams, as is the stored tactics tag.

Unless no tactics configuration was loaded, GetTacticsPayload will always return a payload for any client. When the client's stored tactics tag is identical to the assembled tactics, the Payload.Tactics is nil.

Elements of the returned Payload, e.g., tactics parameters, will point to data in DefaultTactics and FilteredTactics and must not be modifed.

func (*Server) GetTacticsWithTag 

func (server *Server) GetTacticsWithTag(
	includeServerSideOnly bool,
	geoIPData common.GeoIPData,
	apiParams common.APIParameters) (*Tactics, string, error)

GetTacticsWithTag returns a GetTactics value along with the associated tag value.

func (*Server) HandleEndPoint 

func (server *Server) HandleEndPoint(
	endPoint string,
	geoIPData common.GeoIPData,
	w http.ResponseWriter,
	r *http.Request) bool

HandleEndPoint routes the request to either handleSpeedTestRequest or handleTacticsRequest; or returns false if not handled.

func (*Server) Validate 

func (server *Server) Validate() error

Validate checks for correct tactics configuration values.

type SpeedTestSample 

type SpeedTestSample struct {

	// Timestamp is the speed test event time, and may be used to discard
	// stale samples. The server supplies the speed test timestamp. This
	// value is truncated to the nearest hour as a privacy measure.
	Timestamp time.Time `json:"s"`

	// EndPointRegion is the region of the endpoint, the Psiphon server,
	// used for the speed test. This may be used to exclude outlier samples
	// using remote data centers.
	EndPointRegion string `json:"r"`

	// EndPointProtocol is the tactics or tunnel protocol use for the
	// speed test round trip. The protocol may impact RTT.
	EndPointProtocol string `json:"p"`

	// All speed test samples should measure RTT as the time to complete
	// an application-level round trip on top of a previously established
	// tactics or tunnel prococol connection. The RTT should not include
	// TCP, TLS, or SSH handshakes.
	// This value is truncated to the nearest millisecond as a privacy
	// measure.
	RTTMilliseconds int `json:"t"`

	// BytesUp is the size of the upstream payload in the round trip.
	// Currently, the payload is limited to anti-fingerprint padding.
	BytesUp int `json:"u"`

	// BytesDown is the size of the downstream payload in the round trip.
	// Currently, the payload is limited to anti-fingerprint padding.
	BytesDown int `json:"d"`
}

SpeedTestSample is speed test data for a single RTT event.

type Storer 

type Storer interface {
	SetTacticsRecord(networkID string, record []byte) error
	GetTacticsRecord(networkID string) ([]byte, error)
	SetSpeedTestSamplesRecord(networkID string, record []byte) error
	GetSpeedTestSamplesRecord(networkID string) ([]byte, error)
}

Storer provides a facility to persist tactics and speed test data.

type Tactics 

type Tactics struct {

	// TTL is a string duration (e.g., "24h", the syntax supported
	// by time.ParseDuration). This specifies how long the client
	// should use the accompanying tactics until it expires.
	//
	// The client stores the TTL to use for extending the tactics
	// expiry when a tactics request or handshake response returns
	// no tactics data when the tag is unchanged.
	TTL string

	// Probability specifies the probability [0.0 - 1.0] with which
	// the client should apply the tactics in a new session.
	Probability float64

	// Parameters specify client parameters to override. These must
	// be a subset of parameter.ClientParameter values and follow
	// the corresponding data type and minimum value constraints.
	Parameters map[string]interface{}
}

Tactics is the core tactics data. This is both what is set in in the server configuration file and what is stored and used by the cient.

Source Files

View all Source files

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.