basket2

package module
v0.0.0-...-796008b Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2016 License: AGPL-3.0 Imports: 16 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
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 (
	// 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.

Source Files

View all Source files

Directories

Path Synopsis
Tor Pluggable Transport that uses the `basket2` protocol.
 Tor Pluggable Transport that uses the `basket2` protocol.
internal/log
Package log implements a simple leveled logging scheme.
 Package log implements a simple leveled logging scheme.
internal/plpmtud
Package plpmtud allows force enabling Packetization Layer Path MTU Discovery for a given connection, if supported by the operating system.
 Package plpmtud allows force enabling Packetization Layer Path MTU Discovery for a given connection, if supported by the operating system.
internal/proxyextras
internal/ptextras
Package ptextras implements extra goodies useful for writing Tor Pluggable Transports that are not included in goptlib as of verson 0.0.6.
 Package ptextras implements extra goodies useful for writing Tor Pluggable Transports that are not included in goptlib as of verson 0.0.6.
ecdh
Package ecdh provides support for ECDH with the IETF CFRG Curves as specified in RFC 7748.
 Package ecdh provides support for ECDH with the IETF CFRG Curves as specified in RFC 7748.
rand
Package rand provides various utitilies related to generating cryptographically secure random numbers and byte vectors.
 Package rand provides various utitilies related to generating cryptographically secure random numbers and byte vectors.
tentp
Package tentp implements the framing layer portion of the Trivial Encrypted Network Transport Protocol, a lightweight XChaCha20 + Poly1305 based authentication/encryption protocol for streams with reliable-in-order delivery semantics.
 Package tentp implements the framing layer portion of the Trivial Encrypted Network Transport Protocol, a lightweight XChaCha20 + Poly1305 based authentication/encryption protocol for streams with reliable-in-order delivery semantics.
Package handshake implements the basket2 obfuscated/authenticated key exchange.
 Package handshake implements the basket2 obfuscated/authenticated key exchange.
internal
discretedist
Package discretedist implements finite discrete distribution sampling suitable for protocol parameterization.
 Package discretedist implements finite discrete distribution sampling suitable for protocol parameterization.
ext/x25519
ext/x25519/edwards25519
Package edwards25519 implements operations in GF(2**255-19) and on an Edwards curve that is isomorphic to curve25519.
 Package edwards25519 implements operations in GF(2**255-19) and on an Edwards curve that is isomorphic to curve25519.
ext/x25519/elligator2
Package elligator2 implements the Elligator 2 forward/reverse mapping for Curve25519.
 Package elligator2 implements the Elligator 2 forward/reverse mapping for Curve25519.
tcpinfo
Package tcpinfo queries the per-connection low level TCP/IP metrics for useful information like congestion control values.
 Package tcpinfo queries the per-connection low level TCP/IP metrics for useful information like congestion control values.

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.