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 session has exactly one stream, which is the equivilent of a TCP stream.

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

Conns returned from Dial have an established QUIC session 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 Listen(logger common.Logger, address string, obfuscationKey string) (net.Listener, error)
• type Conn
  • func (conn *Conn) Close() error
  • 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) Addr() net.Addr
  • func (listener Listener) Close() error
• type ObfuscatedPacketConn
  • func NewObfuscatedPacketConn(conn net.PacketConn, isServer bool, obfuscationKey string, ...) (*ObfuscatedPacketConn, error)
  • func (conn *ObfuscatedPacketConn) Close() error
  • func (conn *ObfuscatedPacketConn) ReadFrom(p []byte) (int, net.Addr, 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_QUIC_IPV4_PACKET_SIZE            = 1252
	MAX_QUIC_IPV6_PACKET_SIZE            = 1232
	MAX_OBFUSCATED_QUIC_IPV4_PACKET_SIZE = 1372
	MAX_OBFUSCATED_QUIC_IPV6_PACKET_SIZE = 1352
	MAX_PADDING                          = 64
	NONCE_SIZE                           = 12
	RANDOM_STREAM_LIMIT                  = 1<<38 - 64
)

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,
	negotiateQUICVersion string,
	obfuscationKey string,
	obfuscationPaddingSeed *prng.Seed) (net.Conn, error)

Dial establishes a new QUIC session 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.

Keep alive and idle timeout functionality in QUIC is disabled as these aspects are expected to be handled at a higher level.

func Enabled

func Enabled() bool

Enabled indicates if QUIC functionality is enabled.

func Listen

func Listen(
	logger common.Logger,
	address string,
	obfuscationKey string) (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) 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 session 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) Addr

func (listener Listener) Addr() net.Addr

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 frusctrate 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 NewObfuscatedPacketConn

func NewObfuscatedPacketConn(
	conn net.PacketConn,
	isServer bool,
	obfuscationKey string,
	paddingSeed *prng.Seed) (*ObfuscatedPacketConn, error)

NewObfuscatedPacketConn creates a new ObfuscatedPacketConn.

func (*ObfuscatedPacketConn) Close

func (conn *ObfuscatedPacketConn) Close() error

func (*ObfuscatedPacketConn) ReadFrom

func (conn *ObfuscatedPacketConn) ReadFrom(p []byte) (int, net.Addr, 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,
	negotiateQUICVersion string) (*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)