quic

Documentation

Overview

Package quic wraps github.com/lucas-clemente/quic-go with net.Listener and net.Conn types that provide a drop-in replacement for net.TCPConn.

Each QUIC connection has exactly one stream, which is the equivilent of a TCP stream.

Conns returned from Accept will have an established QUIC connection and are configured to perform a deferred AcceptStream on the first Read or Write.

Conns returned from Dial have an established QUIC connection and stream. Dial accepts a Context input which may be used to cancel the dial.

Conns mask or translate qerr.PeerGoingAway to io.EOF as appropriate.

QUIC idle timeouts and keep alives are tuned to mitigate aggressive UDP NAT timeouts on mobile data networks while accounting for the fact that mobile devices in standby/sleep may not be able to initiate the keep alive.

Index

• Constants
• func Dial(ctx context.Context, packetConn net.PacketConn, remoteAddr *net.UDPAddr, ...) (net.Conn, error)
• func Enabled() bool
• func GQUICEnabled() bool
• func Listen(logger common.Logger, ...) (net.Listener, error)
• type Conn
  • func (conn *Conn) Close() error
  • func (conn *Conn) GetMetrics() common.LogFields
  • func (conn *Conn) IsClosed() bool
  • func (conn *Conn) LocalAddr() net.Addr
  • func (conn *Conn) Read(b []byte) (int, error)
  • func (conn *Conn) RemoteAddr() net.Addr
  • func (conn *Conn) SetDeadline(t time.Time) error
  • func (conn *Conn) SetReadDeadline(t time.Time) error
  • func (conn *Conn) SetWriteDeadline(t time.Time) error
  • func (conn *Conn) Write(b []byte) (int, error)
• type Listener
  • func (listener *Listener) Accept() (net.Conn, error)
  • func (listener *Listener) Close() error
• type ObfuscatedPacketConn
  • func NewClientObfuscatedPacketConn(packetConn net.PacketConn, remoteAddr *net.UDPAddr, isIETFClient bool, ...) (*ObfuscatedPacketConn, error)
  • func NewServerObfuscatedPacketConn(packetConn net.PacketConn, isIETFClient bool, isDecoyClient bool, ...) (*ObfuscatedPacketConn, error)
  • func (conn *ObfuscatedPacketConn) Close() error
  • func (conn *ObfuscatedPacketConn) GetMetrics() common.LogFields
  • func (conn *ObfuscatedPacketConn) Read(_ []byte) (int, error)
  • func (conn *ObfuscatedPacketConn) ReadBatch(ms []ipv4.Message, _ int) (int, error)
  • func (conn *ObfuscatedPacketConn) ReadFrom(p []byte) (int, net.Addr, error)
  • func (conn *ObfuscatedPacketConn) ReadMsgUDP(p, oob []byte) (int, int, int, *net.UDPAddr, error)
  • func (conn *ObfuscatedPacketConn) RemoteAddr() net.Addr
  • func (conn *ObfuscatedPacketConn) Write(_ []byte) (int, error)
  • func (conn *ObfuscatedPacketConn) WriteMsgUDP(p, oob []byte, addr *net.UDPAddr) (int, int, error)
  • func (conn *ObfuscatedPacketConn) WriteTo(p []byte, addr net.Addr) (int, error)
• type QUICTransporter
  • func NewQUICTransporter(ctx context.Context, noticeEmitter func(string), ...) (*QUICTransporter, error)
  • func (t *QUICTransporter) CloseIdleConnections()
  • func (t *QUICTransporter) SetRequestContext(ctx context.Context)

Constants

const (
	MAX_PACKET_SIZE = 1452

	MAX_PRE_DISCOVERY_PACKET_SIZE_IPV4 = 1252
	MAX_PRE_DISCOVERY_PACKET_SIZE_IPV6 = 1232

	OBFUSCATED_MAX_PACKET_SIZE_ADJUSTMENT = NONCE_SIZE + 1

	MIN_INITIAL_PACKET_SIZE = 1200

	MAX_PADDING_SIZE       = 255
	MAX_GQUIC_PADDING_SIZE = 64

	MIN_DECOY_PACKETS = 0
	MAX_DECOY_PACKETS = 10

	NONCE_SIZE = 12

	RANDOM_STREAM_LIMIT = 1<<38 - 64

	CONCURRENT_WRITER_LIMIT = 5000
)

const (
	SERVER_HANDSHAKE_TIMEOUT = 30 * time.Second
	SERVER_IDLE_TIMEOUT      = 5 * time.Minute
	CLIENT_IDLE_TIMEOUT      = 30 * time.Second
)

Functions

func Dial

func Dial(
	ctx context.Context,
	packetConn net.PacketConn,
	remoteAddr *net.UDPAddr,
	quicSNIAddress string,
	quicVersion string,
	clientHelloSeed *prng.Seed,
	obfuscationKey string,
	obfuscationPaddingSeed *prng.Seed,
	obfuscationNonceTransformerParameters *transforms.ObfuscatorSeedTransformerParameters,
	disablePathMTUDiscovery bool) (net.Conn, error)

Dial establishes a new QUIC connection and stream to the server specified by address.

packetConn is used as the underlying packet connection for QUIC. The dial may be cancelled by ctx; packetConn will be closed if the dial is cancelled or fails.

When packetConn is a *net.UDPConn, QUIC ECN bit operations are supported, unless the specified QUIC version is obfuscated.

func Enabled

func Enabled() bool

Enabled indicates if QUIC functionality is enabled.

func GQUICEnabled

func GQUICEnabled() bool

func Listen

func Listen(
	logger common.Logger,
	irregularTunnelLogger func(string, error, common.LogFields),
	address string,
	obfuscationKey string,
	enableGQUIC bool) (net.Listener, error)

Listen creates a new Listener.

Types

type Conn

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

Conn is a net.Conn and psiphon/common.Closer.

func (*Conn) Close

func (conn *Conn) Close() error

func (*Conn) GetMetrics

func (conn *Conn) GetMetrics() common.LogFields

GetMetrics implements the common.MetricsSource interface.

func (*Conn) IsClosed

func (conn *Conn) IsClosed() bool

func (*Conn) LocalAddr

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

func (*Conn) Read

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

func (*Conn) RemoteAddr

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

func (*Conn) SetDeadline

func (conn *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (conn *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (conn *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write

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

type Listener

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

Listener is a net.Listener.

func (*Listener) Accept

func (listener *Listener) Accept() (net.Conn, error)

Accept returns a net.Conn that wraps a single QUIC connection and stream. The stream establishment is deferred until the first Read or Write, allowing Accept to be called in a fast loop while goroutines spawned to handle each net.Conn will perform the blocking AcceptStream.

func (*Listener) Close

func (listener *Listener) Close() error

type ObfuscatedPacketConn

type ObfuscatedPacketConn struct {
	net.PacketConn
	// contains filtered or unexported fields
}

ObfuscatedPacketConn wraps a QUIC net.PacketConn with an obfuscation layer that obscures QUIC packets, adding random padding and producing uniformly random payload.

The crypto performed by ObfuscatedPacketConn is purely for obfuscation to frustrate wire-speed DPI and does not add privacy/security. The small nonce space and single key per server is not cryptographically secure.

A server-side ObfuscatedPacketConn performs simple QUIC DPI to distinguish between obfuscated and non-obfsucated peer flows and responds accordingly.

The header and padding added by ObfuscatedPacketConn on top of the QUIC payload will increase UDP packets beyond the QUIC max of 1280 bytes, introducing some risk of fragmentation and/or dropped packets.

func NewClientObfuscatedPacketConn

func NewClientObfuscatedPacketConn(
	packetConn net.PacketConn,
	remoteAddr *net.UDPAddr,
	isIETFClient bool,
	isDecoyClient bool,
	obfuscationKey string,
	paddingSeed *prng.Seed,
	obfuscationNonceTransformerParameters *transforms.ObfuscatorSeedTransformerParameters,
) (*ObfuscatedPacketConn, error)

func NewServerObfuscatedPacketConn

func NewServerObfuscatedPacketConn(
	packetConn net.PacketConn,
	isIETFClient bool,
	isDecoyClient bool,
	obfuscationKey string,
	paddingSeed *prng.Seed) (*ObfuscatedPacketConn, error)

func (*ObfuscatedPacketConn) Close

func (conn *ObfuscatedPacketConn) Close() error

func (*ObfuscatedPacketConn) GetMetrics

func (conn *ObfuscatedPacketConn) GetMetrics() common.LogFields

GetMetrics implements the common.MetricsSource interface.

func (*ObfuscatedPacketConn) Read

func (conn *ObfuscatedPacketConn) Read(_ []byte) (int, error)

func (*ObfuscatedPacketConn) ReadBatch

func (conn *ObfuscatedPacketConn) ReadBatch(ms []ipv4.Message, _ int) (int, error)

func (*ObfuscatedPacketConn) ReadFrom

func (conn *ObfuscatedPacketConn) ReadFrom(p []byte) (int, net.Addr, error)

func (*ObfuscatedPacketConn) ReadMsgUDP

func (conn *ObfuscatedPacketConn) ReadMsgUDP(p, oob []byte) (int, int, int, *net.UDPAddr, error)

func (*ObfuscatedPacketConn) RemoteAddr

func (conn *ObfuscatedPacketConn) RemoteAddr() net.Addr

func (*ObfuscatedPacketConn) Write

func (conn *ObfuscatedPacketConn) Write(_ []byte) (int, error)

func (*ObfuscatedPacketConn) WriteMsgUDP

func (conn *ObfuscatedPacketConn) WriteMsgUDP(p, oob []byte, addr *net.UDPAddr) (int, int, error)

func (*ObfuscatedPacketConn) WriteTo

func (conn *ObfuscatedPacketConn) WriteTo(p []byte, addr net.Addr) (int, error)

type QUICTransporter

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

QUICTransporter implements the psiphon.transporter interface, used in psiphon.MeekConn for HTTP requests, which requires a RoundTripper and CloseIdleConnections.

func NewQUICTransporter

func NewQUICTransporter(
	ctx context.Context,
	noticeEmitter func(string),
	udpDialer func(ctx context.Context) (net.PacketConn, *net.UDPAddr, error),
	quicSNIAddress string,
	quicVersion string,
	clientHelloSeed *prng.Seed,
	disablePathMTUDiscovery bool) (*QUICTransporter, error)

NewQUICTransporter creates a new QUICTransporter.

func (*QUICTransporter) CloseIdleConnections

func (t *QUICTransporter) CloseIdleConnections()

CloseIdleConnections wraps QUIC RoundTripper.Close, which provides the necessary functionality for psiphon.transporter as used by psiphon.MeekConn. Note that, unlike http.Transport.CloseIdleConnections, the connections are closed regardless of idle status.

func (*QUICTransporter) SetRequestContext

func (t *QUICTransporter) SetRequestContext(ctx context.Context)