basket2

README

basket2 - Obfsy McObfsface

Yawning Angel (yawning at schwanenlied dot me)

basket2 is the next transport in the obfs series. It derives inspiration primarily from obfs4 and predecessors, and incorporates ideas initially prototyped in the experimental basket transport.

Features:

• Authentication, data integrity, and confidentiality.
• Active probing resistance.
• Passive fingerprinting resistance, improved over obfs4.
• Client driven dynamic negotiation of runtime padding to better suit various adversary models.
• Better separation between the handshake obfuscation and the authenticated key exchange mechanisms.
• Significantly improved link layer framing.
• Optional user authentication.
• Post-quantum forward secrecy.
• License switch from 3BSD to AGPL for more Freedom.

Dependencies:

The more obsucre dependencies are included using the Go 1.6 vendor scheme, and are managed via git-subtree. Certain larger dependencies likely to be already packaged are not included (as opposed to vendor-ing everything).

• Go 1.6.x or later - (May work with older versions, don't care if they don't)
• golang.org/x/crypto - SHA3, Curve25519, Poly1305
• golang.org/x/net - Only for basket2proxy.
• git.torproject.org/pluggable-transports/goptlib.git - Only for basket2proxy.

Notes:

• I am waiving the remote network interaction requirements specified in Section 13 ("Remote Network Interaction; Use with the GNU General Public License") of the AGPL, per the terms of Section 7 ("Additional Terms"), for users that:

  • Are using the software exclusively to operate a publically accessible Bridge to provide access to the public Tor network as a Tor Pluggable Transport server. This means:

    The Bridge publishes a descriptor to the Bridge Authority, and is available via BridgeDB OR is a default Bridge pre-configured and distributed with Tor Browser, and uses basket2 as a server side Pluggable Transport for said Bridge.

• All other users MUST comply with the AGPL in it's entirety as a general rule, though other licensing arrangements may be possible on request. I will likely be fairly liberal here, so please contact me if the current licensing is unsuitable for your use case.

• All bundled external dependencies have different (more permissive) licenses that should be followed as appropriate.

• The post-quantum cryptography does not apply to active attackers in posession of a quantum computer, and only will protect pre-existing data from later decryption.

• If your system has busted PMTUD, this probably won't work at all. Not my problem. Complain to your OS vendor.

• This could have been based on Trevor Perin's noise protocol framework, with a decent amount of work and extensions, but certain properties and behavior I need aren't formally specified yet. This is something I will strongly consider if/when I design basket3.

Documentation

Overview

Package basket2 implements the basket2 authenticated/encrypted/obfuscated network transport protocol.

Note that the package will block during init() if the system entropy pool is not properly initialized on systems where there is support for determining this information. This is a feature, and "working around" this "bug" will likely totally destroy security.

Index

• Variables
• func DefaultPaddingParams(method PaddingMethod) ([]byte, error)
• type AuthPolicy
• type ClientConfig
• type ClientConn
  • func NewClientConn(config *ClientConfig) (*ClientConn, error)
  • func (c *ClientConn) Close() error
  • func (c *ClientConn) Handshake(conn net.Conn) (err error)
  • func (c *ClientConn) LocalAddr() net.Addr
  • func (c *ClientConn) PaddingMethod() PaddingMethod
  • func (c *ClientConn) Read(p []byte) (n int, err error)
  • func (c *ClientConn) RecvRawRecord() (cmd byte, msg []byte, err error)
  • func (c *ClientConn) RemoteAddr() net.Addr
  • func (c *ClientConn) SendRawRecord(cmd byte, msg []byte, padLen int) (err error)
  • func (c *ClientConn) SetCopyBufferSize(sz int)
  • func (c *ClientConn) SetDeadline(t time.Time) error
  • func (c *ClientConn) SetReadDeadline(t time.Time) error
  • func (c *ClientConn) SetWriteDeadline(t time.Time) error
  • func (c *ClientConn) Stats() *ConnStats
  • func (c *ClientConn) Write(p []byte) (n int, err error)
• type ConnStats
  • func (s *ConnStats) ToString() string
• type PaddingMethod
  • func PaddingMethodFromString(s string) PaddingMethod
  • func SupportedPaddingMethods() []PaddingMethod
  • func (m PaddingMethod) ToHexString() string
  • func (m PaddingMethod) ToString() string
• type ServerConfig
• type ServerConn
  • func NewServerConn(config *ServerConfig) (*ServerConn, error)
  • func (c *ServerConn) Close() error
  • func (s *ServerConn) Handshake(conn net.Conn) (err error)
  • func (c *ServerConn) LocalAddr() net.Addr
  • func (c *ServerConn) PaddingMethod() PaddingMethod
  • func (c *ServerConn) Read(p []byte) (n int, err error)
  • func (c *ServerConn) RecvRawRecord() (cmd byte, msg []byte, err error)
  • func (c *ServerConn) RemoteAddr() net.Addr
  • func (c *ServerConn) SendRawRecord(cmd byte, msg []byte, padLen int) (err error)
  • func (c *ServerConn) SetCopyBufferSize(sz int)
  • func (c *ServerConn) SetDeadline(t time.Time) error
  • func (c *ServerConn) SetReadDeadline(t time.Time) error
  • func (c *ServerConn) SetWriteDeadline(t time.Time) error
  • func (c *ServerConn) Stats() *ConnStats
  • func (c *ServerConn) Write(p []byte) (n int, err error)

Variables

var (
	// ErrInvalidState is the error returned on an invalid state or transition.
	ErrInvalidState = errors.New("basket2: invalid state")

	// ErrInvalidCmd is the error returned on decoding a framing packet with
	// an invalid command.
	ErrInvalidCmd = errors.New("basket2: invalid command")

	// ErrInvalidPadding is the error returned when the client requests no
	// compatible padding methods, or the server specifies a incompatible
	// padding method.
	ErrInvalidPadding = errors.New("basket2: invalid padding")

	// ErrMsgSize is the error returned on a message size violation.
	ErrMsgSize = errors.New("basket2: oversized message")

	// ErrInvalidExtData is the error returned when the req/resp handshake
	// extData is invalid.
	ErrInvalidExtData = errors.New("basket2: invalid ext data")

	// ErrInvalidAuth is the error returned when the authentication credentials
	// or signature was invalid, or the client authentication otherwise failed.
	ErrInvalidAuth = errors.New("basket2: invalid auth")

	// ErrNotSupported is the error returned on an unsupported call.
	ErrNotSupported = errors.New("basket2: operation not supported")
)

Functions

func DefaultPaddingParams

func DefaultPaddingParams(method PaddingMethod) ([]byte, error)

DefaultPaddingParams returns "sensible" parameters for each supported padding method that requires parameterization.

Types

type AuthPolicy

type AuthPolicy byte

AuthPolicy is the server authentication policy.

const (
	// AuthNone indicates that the client must not authenticate.
	AuthNone AuthPolicy = iota

	// AuthMust indicates that the client must authenticate.
	AuthMust
)

type ClientConfig

type ClientConfig struct {
	KEXMethod       handshake.KEXMethod
	PaddingMethods  []PaddingMethod
	ServerPublicKey ecdh.PublicKey

	// AuthFn is the function called at handshake time to authenticate with
	// the remote peer.  It is expected to return the authentication request
	// message, the amount of padding to add, or an error if it is not
	// possible to authenticate.
	AuthFn func(conn *ClientConn, transcriptDigest []byte) (reqMsg []byte, padLen int, err error)
}

ClientConfig is the client configuration parameters to use when constructing a ClientConn.

type ClientConn

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

ClientConn is a client connection instance, that implements the net.Conn interface.

func NewClientConn

func NewClientConn(config *ClientConfig) (*ClientConn, error)

NewClientConn initializes a ClientConn. This step should be done offline, as timing variation due to the Elligator 2 rejection sampling may leak information regarding the obfuscation method.

func (*ClientConn) Close

func (c *ClientConn) Close() error

Close closes the connection and purges cryptographic keying material from memory.

func (*ClientConn) Handshake

func (c *ClientConn) Handshake(conn net.Conn) (err error)

Handshake associates a ClientConn with an established net.Conn, and executes the authenticated/encrypted/obfuscated key exchange, and optionally authenticates the client with the server.

func (*ClientConn) LocalAddr

func (c *ClientConn) LocalAddr() net.Addr

LocalAddr returns the local address of the connection.

func (*ClientConn) PaddingMethod

func (c *ClientConn) PaddingMethod() PaddingMethod

PaddingMethod returns the padding method negotiated with the peer. This will only be set to something useful after a Handshake() call completes successfully.

func (*ClientConn) Read

func (c *ClientConn) Read(p []byte) (n int, err error)

Read reads up to len(p) bytes from the stream, and returns the number of bytes read, or an error. All errors must be considered fatal.

func (*ClientConn) RecvRawRecord

func (c *ClientConn) RecvRawRecord() (cmd byte, msg []byte, err error)

RecvRawRecord receives a raw record from the peer. This call should NOT be interleaved/mixed with the net.Conn Read/Write interface.

func (*ClientConn) RemoteAddr

func (c *ClientConn) RemoteAddr() net.Addr

RemoteAddr returns the remote address of the connection.

func (*ClientConn) SendRawRecord

func (c *ClientConn) SendRawRecord(cmd byte, msg []byte, padLen int) (err error)

SendRawRecord sends a raw record to the peer with the specified command, payload and padding length. This call should NOT be interleaved/mixed with the net.Conn Read/Write interface.

func (*ClientConn) SetCopyBufferSize

func (c *ClientConn) SetCopyBufferSize(sz int)

SetCopyBufferSize sets the hint used to detect large bulk transfers when the connection is the destination side of io.Copy()/io.CopyBuffer(). By default something sensible for io.Copy() will be used.

func (*ClientConn) SetDeadline

func (c *ClientConn) SetDeadline(t time.Time) error

SetDeadline returns ErrNotSupported.

func (*ClientConn) SetReadDeadline

func (c *ClientConn) SetReadDeadline(t time.Time) error

SetReadDeadline returns ErrNotSupported.

func (*ClientConn) SetWriteDeadline

func (c *ClientConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline returns ErrNotSupported.

func (*ClientConn) Stats

func (c *ClientConn) Stats() *ConnStats

Stats returns the connection's ConnStats structure.

func (*ClientConn) Write

func (c *ClientConn) Write(p []byte) (n int, err error)

Write writes len(p) bytes to the stream, and returns the number of bytes written, or an error. All errors must be considered fatal.

type ConnStats

type ConnStats struct {
	RxBytes         uint64
	RxOverheadBytes uint64
	RxPayloadBytes  uint64
	RxPaddingBytes  uint64

	TxBytes         uint64
	TxOverheadBytes uint64
	TxPayloadBytes  uint64
	TxPaddingBytes  uint64
}

ConnStats contains the per-connection metrics useful for examining the overhead/performance of the various padding algorithms.

func (*ConnStats) ToString

func (s *ConnStats) ToString() string

ToString returns the descriptive string representation of the connection statistics.

type PaddingMethod

type PaddingMethod byte

PaddingMethod is a given padding algorithm identifier.

const (
	// ProtocolVersion is the transport protocol version.
	ProtocolVersion = 0

	// PaddingInvalid is a invalid/undefined padding method.
	PaddingInvalid PaddingMethod = 0xff
)

const (
	// PaddingObfs4Burst is the obfs4 style padding algorithm, approximately
	// equivalent to the obfs4 `iat-mode=0` configuration.  No timing
	// obfuscation is done, and only a minimal amount of padding is
	// injected. on a per-burst basis.
	PaddingObfs4Burst PaddingMethod = 1

	// PaddingObfs4BurstIAT is the obfs4 style padding algorithm,
	// approximately equivalent to the obfs4 `iat-mode=1` configuration.
	// Randomized delay is inserted after each "burst" except if the padding
	// code thinks we are in the middle of a large burst.
	PaddingObfs4BurstIAT PaddingMethod = 2

	// PaddingObfs4PacketIAT is the obfs4 style padding algorithm
	// approximately equivalent to the obfs4 `iat-mode=2` configuration.
	// Writes are broken up into random sized packets, and randomized
	// delay is inserted unconditionally.
	PaddingObfs4PacketIAT PaddingMethod = 3

	// Obfs4SeedLength is the length of the randomness to provide to the obfs4
	// padding algoriths to parameterize the distributions.
	Obfs4SeedLength = 32
)

const (
	// PaddingTamaraw is an implementation of a variant of the Tamaraw
	// website fingerprinting defense as specified in "A Systematic
	// Approach to Developing and Evaluating Website Fingerprinting
	// Defenses", with some ideas taken from CS-BuFLO  This method
	// should be avoided for "obfuscation" purposes as it is about
	// as subtle as going over to the DPI box and smashing it with
	// a brick, and guzzles bandwith like no tomorrow.
	//
	// Parameters are taken from Wang, T., "Website Fingerprinting:
	// Attacks and Defenses", and are tuned assuming the client is
	// primarily interested in things like web browsing, and that the
	// link MTU is 1500 bytes.
	PaddingTamaraw PaddingMethod = 0xf0

	// PaddingTamarawBulk is a variant of PaddingTamaraw with parameters
	// that are tuned for bulk transport in both directions.
	PaddingTamarawBulk PaddingMethod = 0xf1
)

const (
	// PaddingApe is the Adaptive Padding Early (APE) padding method,
	// designed to be an early implementation of an adaptive padding
	// based defense against website fingerprinting (WF) attacks,
	// related to the WTF-PAD defense by Juarez et al..
	// APE tries to make simple, but probably náive, changes
	// to the complex WTF-PAD design to be an improvement (in terms of overhead)
	// over Tamaraw while still offering significantly better protection
	// than the obfs4 censorship resistance methods against WF attacks.
	// Once WTF-PAD has a practical approach to, e.g. histogram generation,
	// APE should be abandoned.
	PaddingApe PaddingMethod = 0xa0
)

const (
	// PaddingNull is the "NULL" padding algorithm.  No packet length or
	// timing obfuscation will be done beyond the standard handshake
	// obfuscation.  This method SHOULD NOT currently be used, and is only
	// provided for testing, and in anticipation of Tor getting it's own
	// circuit level padding implementation.
	PaddingNull PaddingMethod = 0
)

func PaddingMethodFromString

func PaddingMethodFromString(s string) PaddingMethod

PaddingMethodFromString returns the PaddingMethod corresponding to a given string.

func SupportedPaddingMethods

func SupportedPaddingMethods() []PaddingMethod

SupportedPaddingMethods returns the list of supported padding methods in order of preference.

func (PaddingMethod) ToHexString

func (m PaddingMethod) ToHexString() string

ToHexString returns the hexdecimal string representation of a padding method.

func (PaddingMethod) ToString

func (m PaddingMethod) ToString() string

ToString returms the descriptive string representaiton of a padding method.

type ServerConfig

type ServerConfig struct {
	ServerPrivateKey ecdh.PrivateKey

	KEXMethods     []handshake.KEXMethod
	PaddingMethods []PaddingMethod
	AuthPolicy     AuthPolicy

	ReplayFilter handshake.ReplayFilter

	// PaddingParamFn is the function called at handshake time to obtain the
	// per-connection padding parameters used to instantiate the server side
	// padding algorithm (that will also be propagated back to the client).
	PaddingParamFn func(PaddingMethod) ([]byte, error)

	// AuthFn is the function called at handshake time to validate the
	// authentication received from the client.  It is expected to return if
	// the authentication was valid, and the amoung of padding to apply to
	// the response message.
	AuthFn func(conn *ServerConn, transcriptDigest []byte, reqMsg []byte) (ok bool, padLen int)
}

ServerConfig is the server configuration parameters to use when constructing a ServerConn.

type ServerConn

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

ServerConn is a server side client connection instance, that implements the net.Conn interface.

func NewServerConn

func NewServerConn(config *ServerConfig) (*ServerConn, error)

NewServerConn initializes a ServerConn. Unlike NewClientConn this step may and should be done right before Handshake is ready to be called.

func (*ServerConn) Close

func (c *ServerConn) Close() error

Close closes the connection and purges cryptographic keying material from memory.

func (*ServerConn) Handshake

func (s *ServerConn) Handshake(conn net.Conn) (err error)

Handshake associates a ServerConn with an established net.Conn, and executes the authenticated/encrypted/obfuscated key exchange, and optionally authenticates the client.

func (*ServerConn) LocalAddr

func (c *ServerConn) LocalAddr() net.Addr

LocalAddr returns the local address of the connection.

func (*ServerConn) PaddingMethod

func (c *ServerConn) PaddingMethod() PaddingMethod

PaddingMethod returns the padding method negotiated with the peer. This will only be set to something useful after a Handshake() call completes successfully.

func (*ServerConn) Read

func (c *ServerConn) Read(p []byte) (n int, err error)

Read reads up to len(p) bytes from the stream, and returns the number of bytes read, or an error. All errors must be considered fatal.

func (*ServerConn) RecvRawRecord

func (c *ServerConn) RecvRawRecord() (cmd byte, msg []byte, err error)

RecvRawRecord receives a raw record from the peer. This call should NOT be interleaved/mixed with the net.Conn Read/Write interface.

func (*ServerConn) RemoteAddr

func (c *ServerConn) RemoteAddr() net.Addr

RemoteAddr returns the remote address of the connection.

func (*ServerConn) SendRawRecord

func (c *ServerConn) SendRawRecord(cmd byte, msg []byte, padLen int) (err error)

SendRawRecord sends a raw record to the peer with the specified command, payload and padding length. This call should NOT be interleaved/mixed with the net.Conn Read/Write interface.

func (*ServerConn) SetCopyBufferSize

func (c *ServerConn) SetCopyBufferSize(sz int)

SetCopyBufferSize sets the hint used to detect large bulk transfers when the connection is the destination side of io.Copy()/io.CopyBuffer(). By default something sensible for io.Copy() will be used.

func (*ServerConn) SetDeadline

func (c *ServerConn) SetDeadline(t time.Time) error

SetDeadline returns ErrNotSupported.

func (*ServerConn) SetReadDeadline

func (c *ServerConn) SetReadDeadline(t time.Time) error

SetReadDeadline returns ErrNotSupported.

func (*ServerConn) SetWriteDeadline

func (c *ServerConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline returns ErrNotSupported.

func (*ServerConn) Stats

func (c *ServerConn) Stats() *ConnStats

Stats returns the connection's ConnStats structure.

func (*ServerConn) Write

func (c *ServerConn) Write(p []byte) (n int, err error)

Write writes len(p) bytes to the stream, and returns the number of bytes written, or an error. All errors must be considered fatal.