quic

package
v0.42.0-beta.3 Latest Latest
Warning

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

 Go to latest Published: Apr 23, 2024 License: MIT Imports: 43 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	NoError                   = qerr.NoError
	InternalError             = qerr.InternalError
	ConnectionRefused         = qerr.ConnectionRefused
	FlowControlError          = qerr.FlowControlError
	StreamLimitError          = qerr.StreamLimitError
	StreamStateError          = qerr.StreamStateError
	FinalSizeError            = qerr.FinalSizeError
	FrameEncodingError        = qerr.FrameEncodingError
	TransportParameterError   = qerr.TransportParameterError
	ConnectionIDLimitError    = qerr.ConnectionIDLimitError
	ProtocolViolation         = qerr.ProtocolViolation
	InvalidToken              = qerr.InvalidToken
	ApplicationErrorErrorCode = qerr.ApplicationErrorErrorCode
	CryptoBufferExceeded      = qerr.CryptoBufferExceeded
	KeyUpdateError            = qerr.KeyUpdateError
	AEADLimitReached          = qerr.AEADLimitReached
	NoViablePathError         = qerr.NoViablePathError
)
View Source 
const (
	// Version1 is RFC 9000
	Version1 = protocol.Version1
	// Version2 is RFC 9369
	Version2 = protocol.Version2
)
View Source 
const DatagramFrameMaxPeekTimes = 10

Variables

View Source 
var ConnectionTracingKey = connTracingCtxKey{}

ConnectionTracingKey can be used to associate a ConnectionTracer with a Connection. It is set on the Connection.Context() context, as well as on the context passed to logging.Tracer.NewConnectionTracer.

View Source 
var Err0RTTRejected = errors.New("0-RTT rejected")

Err0RTTRejected is the returned from: * Open{Uni}Stream{Sync} * Accept{Uni}Stream * Stream.Read and Stream.Write when the server rejects a 0-RTT connection attempt.

View Source 
var ErrServerClosed = errors.New("quic: server closed")

ErrServerClosed is returned by the Listener or EarlyListener's Accept method after a call to Close.

View Source 
var QUICVersionContextKey = handshake.QUICVersionContextKey

QUICVersionContextKey can be used to find out the QUIC version of a TLS handshake from the context returned by tls.Config.ClientHelloInfo.Context.

Functions

This section is empty.

Types

type ApplicationError 

type ApplicationError = qerr.ApplicationError

type ApplicationErrorCode 

type ApplicationErrorCode = qerr.ApplicationErrorCode

type ClientHelloInfo 

type ClientHelloInfo = quic.ClientHelloInfo

type ClientToken 

type ClientToken = quic.ClientToken

A ClientToken is a token received by the client. It can be used to skip address validation on future connection attempts.

type Config 

type Config = quic.Config

Config contains all configuration data needed for a QUIC server or client.

type Connection 

type Connection = quic.Connection

A Connection is a QUIC connection between two peers. Calls to the connection (and to streams) can return the following types of errors: * ApplicationError: for errors triggered by the application running on top of QUIC * TransportError: for errors triggered by the QUIC transport (in many cases a misbehaving peer) * IdleTimeoutError: when the peer goes away unexpectedly (this is a net.Error timeout error) * HandshakeTimeoutError: when the cryptographic handshake takes too long (this is a net.Error timeout error) * StatelessResetError: when we receive a stateless reset (this is a net.Error temporary error) * VersionNegotiationError: returned by the client, when there's no version overlap between the peers

func Dial 

func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)

Dial establishes a new QUIC connection to a server using a net.PacketConn. If the PacketConn satisfies the OOBCapablePacketConn interface (as a net.UDPConn does), ECN and packet info support will be enabled. In this case, ReadMsgUDP and WriteMsgUDP will be used instead of ReadFrom and WriteTo to read/write packets. The tls.Config must define an application protocol (using NextProtos).

This is a convenience function. More advanced use cases should instantiate a Transport, which offers configuration options for a more fine-grained control of the connection establishment, including reusing the underlying UDP socket for multiple QUIC connections.

func DialAddr 

func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (Connection, error)

DialAddr establishes a new QUIC connection to a server. It resolves the address, and then creates a new UDP connection to dial the QUIC server. When the QUIC connection is closed, this UDP connection is closed. See Dial for more details.

type ConnectionID 

type ConnectionID = quic.ConnectionID

A ConnectionID is a QUIC Connection ID, as defined in RFC 9000. It is not able to handle QUIC Connection IDs longer than 20 bytes, as they are allowed by RFC 8999.

func ConnectionIDFromBytes 

func ConnectionIDFromBytes(b []byte) ConnectionID

ConnectionIDFromBytes interprets b as a Connection ID. It panics if b is longer than 20 bytes.

type ConnectionIDGenerator 

type ConnectionIDGenerator = quic.ConnectionIDGenerator

A ConnectionIDGenerator is an interface that allows clients to implement their own format for the Connection IDs that servers/clients use as SrcConnectionID in QUIC packets.

Connection IDs generated by an implementation should always produce IDs of constant size.

type ConnectionState 

type ConnectionState = quic.ConnectionState

ConnectionState records basic details about a QUIC connection

type DatagramTooLargeError added in v0.45.1 

type DatagramTooLargeError = quic.DatagramTooLargeError

DatagramTooLargeError is returned from Connection.SendDatagram if the payload is too large to be sent.

type EarlyConnection 

type EarlyConnection = quic.EarlyConnection

An EarlyConnection is a connection that is handshaking. Data sent during the handshake is encrypted using the forward secure keys. When using client certificates, the client's identity is only verified after completion of the handshake.

func DialAddrEarly 

func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)

DialAddrEarly establishes a new 0-RTT QUIC connection to a server. See DialAddr for more details.

func DialEarly 

func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)

DialEarly establishes a new 0-RTT QUIC connection to a server using a net.PacketConn. See Dial for more details.

type EarlyListener 

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

An EarlyListener listens for incoming QUIC connections, and returns them before the handshake completes. For connections that don't use 0-RTT, this allows the server to send 0.5-RTT data. This data is encrypted with forward-secure keys, however, the client's identity has not yet been verified. For connection using 0-RTT, this allows the server to accept and respond to streams that the client opened in the 0-RTT data it sent. Note that at this point during the handshake, the live-ness of the client has not yet been confirmed, and the 0-RTT data could have been replayed by an attacker.

func ListenAddrEarly 

func ListenAddrEarly(addr string, tlsConf *tls.Config, config *Config) (*EarlyListener, error)

ListenAddrEarly works like ListenAddr, but it returns connections before the handshake completes.

func ListenEarly 

func ListenEarly(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*EarlyListener, error)

ListenEarly works like Listen, but it returns connections before the handshake completes.

func (*EarlyListener) Accept 

func (l *EarlyListener) Accept(ctx context.Context) (EarlyConnection, error)

Accept returns a new connections. It should be called in a loop.

func (*EarlyListener) Addr 

func (l *EarlyListener) Addr() net.Addr

Addr returns the local network addr that the server is listening on.

func (*EarlyListener) Close 

func (l *EarlyListener) Close() error

Close the server. All active connections will be closed.

type HandshakeTimeoutError 

type HandshakeTimeoutError = qerr.HandshakeTimeoutError

type IdleTimeoutError 

type IdleTimeoutError = qerr.IdleTimeoutError

type Listener 

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

A Listener listens for incoming QUIC connections. It returns connections once the handshake has completed.

func Listen 

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

Listen listens for QUIC connections on a given net.PacketConn. If the PacketConn satisfies the OOBCapablePacketConn interface (as a net.UDPConn does), ECN and packet info support will be enabled. In this case, ReadMsgUDP and WriteMsgUDP will be used instead of ReadFrom and WriteTo to read/write packets. A single net.PacketConn can only be used for a single call to Listen.

The tls.Config must not be nil and must contain a certificate configuration. Furthermore, it must define an application control (using NextProtos). The quic.Config may be nil, in that case the default values will be used.

This is a convenience function. More advanced use cases should instantiate a Transport, which offers configuration options for a more fine-grained control of the connection establishment, including reusing the underlying UDP socket for outgoing QUIC connections. When closing a listener created with Listen, all established QUIC connections will be closed immediately.

func ListenAddr 

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

ListenAddr creates a QUIC server listening on a given address. See Listen for more details.

func (*Listener) Accept 

func (l *Listener) Accept(ctx context.Context) (Connection, error)

Accept returns new connections. It should be called in a loop.

func (*Listener) Addr 

func (l *Listener) Addr() net.Addr

Addr returns the local network address that the server is listening on.

func (*Listener) Close 

func (l *Listener) Close() error

Close closes the listener. Accept will return ErrServerClosed as soon as all connections in the accept queue have been accepted. QUIC handshakes that are still in flight will be rejected with a CONNECTION_REFUSED error. The effect of closing the listener depends on how it was created: * if it was created using Transport.Listen, already established connections will be unaffected * if it was created using the Listen convenience method, all established connection will be closed immediately

type OOBCapablePacketConn 

type OOBCapablePacketConn interface {
	net.PacketConn
	SyscallConn() (syscall.RawConn, error)
	SetReadBuffer(int) error
	ReadMsgUDP(b, oob []byte) (n, oobn, flags int, addr *net.UDPAddr, err error)
	WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, err error)
}

OOBCapablePacketConn is a connection that allows the reading of ECN bits from the IP header. If the PacketConn passed to Dial or Listen satisfies this interface, quic-go will use it. In this case, ReadMsgUDP() will be used instead of ReadFrom() to read packets.

type ReceiveStream 

type ReceiveStream = quic.ReceiveStream

A ReceiveStream is a unidirectional Receive Stream.

type SendStream 

type SendStream = quic.SendStream

A SendStream is a unidirectional Send Stream.

type StatelessResetError 

type StatelessResetError = qerr.StatelessResetError

type StatelessResetKey 

type StatelessResetKey = quic.StatelessResetKey

StatelessResetKey is a key used to derive stateless reset tokens.

type Stream 

type Stream = quic.Stream

Stream is the interface implemented by QUIC streams In addition to the errors listed on the Connection, calls to stream functions can return a StreamError if the stream is canceled.

type StreamError 

type StreamError = quic.StreamError

A StreamError is used for Stream.CancelRead and Stream.CancelWrite. It is also returned from Stream.Read and Stream.Write if the peer canceled reading or writing.

type StreamErrorCode 

type StreamErrorCode = qerr.StreamErrorCode

type StreamID 

type StreamID = protocol.StreamID

The StreamID is the ID of a QUIC stream.

type TokenGeneratorKey 

type TokenGeneratorKey = handshake.TokenProtectorKey

TokenGeneratorKey is a key used to encrypt session resumption tokens.

type TokenStore 

type TokenStore = quic.TokenStore

func NewLRUTokenStore 

func NewLRUTokenStore(maxOrigins, tokensPerOrigin int) TokenStore

NewLRUTokenStore creates a new LRU cache for tokens received by the client. maxOrigins specifies how many origins this cache is saving tokens for. tokensPerOrigin specifies the maximum number of tokens per origin.

type Transport 

type Transport struct {
	// A single net.PacketConn can only be handled by one Transport.
	// Bad things will happen if passed to multiple Transports.
	//
	// A number of optimizations will be enabled if the connections implements the OOBCapablePacketConn interface,
	// as a *net.UDPConn does.
	// 1. It enables the Don't Fragment (DF) bit on the IP header.
	//    This is required to run DPLPMTUD (Path MTU Discovery, RFC 8899).
	// 2. It enables reading of the ECN bits from the IP header.
	//    This allows the remote node to speed up its loss detection and recovery.
	// 3. It uses batched syscalls (recvmmsg) to more efficiently receive packets from the socket.
	// 4. It uses Generic Segmentation Offload (GSO) to efficiently send batches of packets (on Linux).
	//
	// After passing the connection to the Transport, it's invalid to call ReadFrom or WriteTo on the connection.
	Conn net.PacketConn

	// The length of the connection ID in bytes.
	// It can be any value between 1 and 20.
	// Due to the increased risk of collisions, it is not recommended to use connection IDs shorter than 4 bytes.
	// If unset, a 4 byte connection ID will be used.
	ConnectionIDLength int

	// Use for generating new connection IDs.
	// This allows the application to control of the connection IDs used,
	// which allows routing / load balancing based on connection IDs.
	// All Connection IDs returned by the ConnectionIDGenerator MUST
	// have the same length.
	ConnectionIDGenerator ConnectionIDGenerator

	// The StatelessResetKey is used to generate stateless reset tokens.
	// If no key is configured, sending of stateless resets is disabled.
	// It is highly recommended to configure a stateless reset key, as stateless resets
	// allow the peer to quickly recover from crashes and reboots of this node.
	// See section 10.3 of RFC 9000 for details.
	StatelessResetKey *StatelessResetKey

	// The TokenGeneratorKey is used to encrypt session resumption tokens.
	// If no key is configured, a random key will be generated.
	// If multiple servers are authoritative for the same domain, they should use the same key,
	// see section 8.1.3 of RFC 9000 for details.
	TokenGeneratorKey *TokenGeneratorKey

	// MaxTokenAge is the maximum age of the resumption token presented during the handshake.
	// These tokens allow skipping address resumption when resuming a QUIC connection,
	// and are especially useful when using 0-RTT.
	// If not set, it defaults to 24 hours.
	// See section 8.1.3 of RFC 9000 for details.
	MaxTokenAge time.Duration

	// DisableVersionNegotiationPackets disables the sending of Version Negotiation packets.
	// This can be useful if version information is exchanged out-of-band.
	// It has no effect for clients.
	DisableVersionNegotiationPackets bool

	// VerifySourceAddress decides if a connection attempt originating from unvalidated source
	// addresses first needs to go through source address validation using QUIC's Retry mechanism,
	// as described in RFC 9000 section 8.1.2.
	// Note that the address passed to this callback is unvalidated, and might be spoofed in case
	// of an attack.
	// Validating the source address adds one additional network roundtrip to the handshake,
	// and should therefore only be used if a suspiciously high number of incoming connection is recorded.
	// For most use cases, wrapping the Allow function of a rate.Limiter will be a reasonable
	// implementation of this callback (negating its return value).
	VerifySourceAddress func(net.Addr) bool

	// A Tracer traces events that don't belong to a single QUIC connection.
	// Tracer.Close is called when the transport is closed.
	Tracer *logging.Tracer
	// contains filtered or unexported fields
}

The Transport is the central point to manage incoming and outgoing QUIC connections. QUIC demultiplexes connections based on their QUIC Connection IDs, not based on the 4-tuple. This means that a single UDP socket can be used for listening for incoming connections, as well as for dialing an arbitrary number of outgoing connections. A Transport handles a single net.PacketConn, and offers a range of configuration options compared to the simple helper functions like Listen and Dial that this package provides.

func (*Transport) Close 

func (t *Transport) Close() error

Close closes the underlying connection. If any listener was started, it will be closed as well. It is invalid to start new listeners or connections after that.

func (*Transport) Dial 

func (t *Transport) Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)

Dial dials a new connection to a remote host (not using 0-RTT).

func (*Transport) DialEarly 

func (t *Transport) DialEarly(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)

DialEarly dials a new connection, attempting to use 0-RTT if possible.

func (*Transport) Listen 

func (t *Transport) Listen(tlsConf *tls.Config, conf *Config) (*Listener, error)

Listen starts listening for incoming QUIC connections. There can only be a single listener on any net.PacketConn. Listen may only be called again after the current Listener was closed.

func (*Transport) ListenEarly 

func (t *Transport) ListenEarly(tlsConf *tls.Config, conf *Config) (*EarlyListener, error)

ListenEarly starts listening for incoming QUIC connections. There can only be a single listener on any net.PacketConn. Listen may only be called again after the current Listener was closed.

func (*Transport) ReadNonQUICPacket 

func (t *Transport) ReadNonQUICPacket(ctx context.Context, b []byte) (int, net.Addr, error)

ReadNonQUICPacket reads non-QUIC packets received on the underlying connection. The detection logic is very simple: Any packet that has the first and second bit of the packet set to 0. Note that this is stricter than the detection logic defined in RFC 9443.

func (*Transport) WriteTo 

func (t *Transport) WriteTo(b []byte, addr net.Addr) (int, error)

WriteTo sends a packet on the underlying connection.

type TransportError 

type TransportError = qerr.TransportError

type TransportErrorCode 

type TransportErrorCode = qerr.TransportErrorCode

type Version added in v0.45.1 

type Version = protocol.Version

A Version is a QUIC version number.

type VersionNegotiationError 

type VersionNegotiationError = qerr.VersionNegotiationError

type VersionNumber 

type VersionNumber = Version

A VersionNumber is a QUIC version number. Deprecated: VersionNumber was renamed to Version.

Source Files

View all Source files

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.