quicwrapper

README

quicwrapper

implements several net interfaces using the quic-go library

Note this library expects to use the getlantern fork of quic-go here: https://github.com/getlantern/quic-go

Follow instructions found in the fork's README

Documentation

Overview

Wraps quic structures in standard net interfaces and improves context awareness. Conn instances created by this package may be multiplexed

Index

• Constants
• Variables
• func DecodesAsDecoy(p []byte, config *OQuicConfig) bool
• func DialUDPNetx(addr string) (net.PacketConn, *net.UDPAddr, error)
• func Listen(pconn net.PacketConn, tlsConf *tls.Config, config *Config) (net.Listener, error)
• func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (net.Listener, error)
• func ListenAddrOQuic(addr string, tlsConf *tls.Config, config *quic.Config, oqConfig *OQuicConfig) (net.Listener, error)
• func MakeHighEntropyDecoy(size int, config *OQuicConfig) []byte
• func NewSalsa20Enveloper(conn net.PacketConn, config *OQuicConfig) (*salsa20Enveloper, error)
• type Bandwidth
• type BandwidthEstimator
• type Client
  • func NewClient(addr string, tlsConf *tls.Config, config *Config, dial QuicDialFn) *Client
  • func NewClientWithPinnedCert(addr string, tlsConf *tls.Config, config *Config, dial QuicDialFn, ...) *Client
  • func (c *Client) Close() error
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) Dial() (*Conn, error)
  • func (c *Client) DialContext(ctx context.Context) (*Conn, error)
• type Config
• type Conn
  • func (c *Conn) BandwidthEstimate() Bandwidth
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) PeerCertificates() []*x509.Certificate
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) Write(b []byte) (int, error)
• type EMABandwidthSampler
  • func NewEMABandwidthSampler(from BandwidthEstimator) *EMABandwidthSampler
  • func NewEMABandwidthSamplerParams(from BandwidthEstimator, period time.Duration, window time.Duration) *EMABandwidthSampler
  • func (bs *EMABandwidthSampler) BandwidthEstimate() Bandwidth
  • func (bs *EMABandwidthSampler) Clear()
  • func (bs *EMABandwidthSampler) Start()
  • func (bs *EMABandwidthSampler) Stop()
• type Enveloper
• type OQuicConfig
  • func DefaultOQuicConfig(key []byte) *OQuicConfig
• type QuicDialFn
  • func NewOQuicDialer(config *OQuicConfig) (QuicDialFn, error)
  • func NewOQuicDialerWithUDPDialer(dial UDPDialFn, config *OQuicConfig) (QuicDialFn, error)
• type UDPDialFn

Constants

const (
	EMABandwidthSamplerDefaultPeriod = 1 * time.Second
	EMABandwidthSamplerDefaultWindow = 15 * time.Second
)

const (
	CipherXSalsa20 = "XSALSA20"
	CipherSalsa20  = "SALSA20"
)

const (

	// This the value represents HTTP/3 protocol (explicitly over draft-24).
	// This is usually what browser will send (including the quic-go http3
	// implementation, chrome canaries supporting draft-24 etc.)
	AlpnH3 = "h3-24"
)

const (
	Mib = 1024 * 1024 // 1 Mebibit Bandwidth
)

Variables

var (
	ErrListenerClosed = errors.New("listener closed")
)

Functions

func DecodesAsDecoy

func DecodesAsDecoy(p []byte, config *OQuicConfig) bool

DecodesAsDecoy tests whether a packet decodes as a decoy packet with the given configuration.

func DialUDPNetx

func DialUDPNetx(addr string) (net.PacketConn, *net.UDPAddr, error)

DialUDPNetx is a UDPDialFn that resolves addresses and obtains the net.PacketConn using the netx package.

func Listen

func Listen(pconn net.PacketConn, tlsConf *tls.Config, config *Config) (net.Listener, error)

Listen creates a QUIC server listening on a given net.PacketConn The net.Conn instances returned by the net.Listener may be multiplexed connections. The caller is responsible for closing the net.PacketConn after the listener has been closed.

func ListenAddr

func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (net.Listener, error)

ListenAddr creates a QUIC server listening on a given address. The net.Conn instances returned by the net.Listener may be multiplexed connections.

func ListenAddrOQuic

func ListenAddrOQuic(addr string, tlsConf *tls.Config, config *quic.Config, oqConfig *OQuicConfig) (net.Listener, error)

ListenAddrOQuic creates a QUIC server listening on a given address. all outbound packets are obfuscated using the 256 bit (32 byte) key given, all inbound packets are expected to have been obfuscated using the same key. The net.Conn instances returned by the net.Listener may be multiplexed connections.

func MakeHighEntropyDecoy

func MakeHighEntropyDecoy(size int, config *OQuicConfig) []byte

MakeHighEntropyDecoy creates a decoy packet of the indicated size. The packet is run through the same obfuscation as a normal packet and is thus 'high entropy' (appears encrypted or compressed)

func NewSalsa20Enveloper

func NewSalsa20Enveloper(conn net.PacketConn, config *OQuicConfig) (*salsa20Enveloper, error)

NewSalsa20Enveloper creates a new net.PacketConn that obfuscates an existing net.PacketConn according to the configuraton given.

Types

type Bandwidth

type Bandwidth = quic.Bandwidth

type BandwidthEstimator

type BandwidthEstimator interface {
	BandwidthEstimate() Bandwidth
}

type Client

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

func NewClient

func NewClient(addr string, tlsConf *tls.Config, config *Config, dial QuicDialFn) *Client

NewClient returns a client that creates multiplexed QUIC connections in a single Session with the given address using the provided configuration.

The Session is created using the QuicDialFn given, but is not established until the first call to Dial(), DialContext() or Connect()

if dial is nil, the default quic dialer is used

func NewClientWithPinnedCert

func NewClientWithPinnedCert(addr string, tlsConf *tls.Config, config *Config, dial QuicDialFn, cert *x509.Certificate) *Client

NewClientWithPinnedCert returns a new client configured as with NewClient, but accepting only a specific given certificate. If the certificate presented by the connected server does match the given certificate, the connection is rejected. This check is performed regardless of tls.Config settings (ie even if InsecureSkipVerify is true)

If a nil certificate is given, the check is not performed and any valid certificate according the tls.Config given is accepted (equivalent to NewClient behavior)

func (*Client) Close

func (c *Client) Close() error

closes the session established by this client (and all multiplexed connections)

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connect requests immediate handshaking regardless of whether any specific Dial has been initiated. It is called lazily on the first Dial if not otherwise called.

This can serve to pre-establish a multiplexed session, but will also initiate idle timeout tracking, keepalives etc. Returns any error encountered during handshake.

This may safely be called concurrently with Dial. The handshake is guaranteed to be completed when the call returns to any caller.

func (*Client) Dial

func (c *Client) Dial() (*Conn, error)

Dial creates a new multiplexed QUIC connection to the server configured for the client.

func (*Client) DialContext

func (c *Client) DialContext(ctx context.Context) (*Conn, error)

DialContext creates a new multiplexed QUIC connection to the server configured in the client. The given Context governs cancellation / timeout. If initial handshaking is performed, the operation is additionally governed by HandshakeTimeout value given in the client Config.

type Config

type Config = quic.Config

type Conn

type Conn struct {
	quic.Stream
	// contains filtered or unexported fields
}

wraps quic.Stream and other info to implement net.Conn

func (*Conn) BandwidthEstimate

func (c *Conn) BandwidthEstimate() Bandwidth

func (*Conn) Close

func (c *Conn) Close() error

implements net.Conn.Close

func (*Conn) LocalAddr

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

implements net.Conn.LocalAddr

func (*Conn) PeerCertificates

func (c *Conn) PeerCertificates() []*x509.Certificate

Returns certificates presented by peer

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

implements net.Conn.Read

func (*Conn) RemoteAddr

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

implements net.Conn.RemoteAddr

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

implements net.Conn.Write

type EMABandwidthSampler

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

Samples and averages bandwidth estimates from another BandwidthEstimator

func NewEMABandwidthSampler

func NewEMABandwidthSampler(from BandwidthEstimator) *EMABandwidthSampler

func NewEMABandwidthSamplerParams

func NewEMABandwidthSamplerParams(from BandwidthEstimator, period time.Duration, window time.Duration) *EMABandwidthSampler

func (*EMABandwidthSampler) BandwidthEstimate

func (bs *EMABandwidthSampler) BandwidthEstimate() Bandwidth

func (*EMABandwidthSampler) Clear

func (bs *EMABandwidthSampler) Clear()

func (*EMABandwidthSampler) Start

func (bs *EMABandwidthSampler) Start()

func (*EMABandwidthSampler) Stop

func (bs *EMABandwidthSampler) Stop()

type Enveloper

type Enveloper interface {
	net.PacketConn
	EnvelopeSize() uint64
}

type OQuicConfig

type OQuicConfig struct {
	Key               []byte // Salsa 256 bit (32 byte) key
	AggressivePadding int64  // if non-zero, enable large padding for this number of initial packets
	MaxPaddingHint    uint8  // if non-zero, use padding, but limit to this maximum after agressive phase where appropriate
	MinPadded         int    // if non-zero, do not pad packets under this size
	Cipher            string // default: Salsa20
}

func DefaultOQuicConfig

func DefaultOQuicConfig(key []byte) *OQuicConfig

type QuicDialFn

type QuicDialFn func(ctx context.Context, addr string, tlsConf *tls.Config, config *quic.Config) (quic.Session, error)

a QuicDialFn is a function that may be used to establish a new QUIC Session

var (
	DialWithNetx    QuicDialFn = newDialerWithUDPDialer(DialUDPNetx)
	DialWithoutNetx QuicDialFn = quic.DialAddrContext
)

func NewOQuicDialer

func NewOQuicDialer(config *OQuicConfig) (QuicDialFn, error)

Creates a QuicDialFn dialer that obfuscates packets using the given 256 bit (32 byte) key. all outbound packets are obfuscated using the 256 bit (32 byte) key given, all inbound packets are expected to have been obfuscated using the same key.

func NewOQuicDialerWithUDPDialer

func NewOQuicDialerWithUDPDialer(dial UDPDialFn, config *OQuicConfig) (QuicDialFn, error)

Creates a QuicDialFn dialer that obfuscates packets using the given 256 bit (32 byte) key. The underlying net.PacketConn is obtained using the UDPDialFn given. all outbound packets are obfuscated using the 256 bit (32 byte) key given, all inbound packets are expected to have been obfuscated using the same key.

type UDPDialFn

type UDPDialFn func(addr string) (net.PacketConn, *net.UDPAddr, error)