kquic

README

kquic

Package kquic provides access to Linux kernel QUIC sockets (lxin/quic, IPPROTO_QUIC): the kernel owns the QUIC transport data path while the TLS 1.3 handshake is driven in userspace by crypto/tls. MIT Licensed.

This package is highly experimental and its API is unstable. The kernel QUIC module is out-of-tree and its UAPI may change.

Documentation

Overview

Package kquic provides access to Linux kernel QUIC sockets (IPPROTO_QUIC, https://github.com/lxin/quic): the kernel owns the QUIC transport while the TLS 1.3 handshake is driven in userspace by crypto/tls.

This package is highly experimental and its API is unstable. The kernel QUIC module is out-of-tree and its UAPI may change.

Index

• type Config
• type Conn
  • func Dial(ctx context.Context, raddr netip.AddrPort, cfg *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) ConnectionState() tls.ConnectionState
  • func (c *Conn) LocalAddr() netip.AddrPort
  • func (c *Conn) OpenStream(uni bool) (StreamID, error)
  • func (c *Conn) Receive(b []byte) (n int, sid StreamID, flags Flags, err error)
  • func (c *Conn) RemoteAddr() netip.AddrPort
  • func (c *Conn) Send(sid StreamID, flags Flags, b []byte) (int, error)
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) SyscallConn() (syscall.RawConn, error)
• type Flags
• type Listener
  • func Listen(laddr netip.AddrPort, cfg *Config) (*Listener, error)
  • func (l *Listener) Accept(ctx context.Context) (*Conn, error)
  • func (l *Listener) Addr() netip.AddrPort
  • func (l *Listener) Close() error
• type StreamID
  • func (id StreamID) IsServerInitiated() bool
  • func (id StreamID) IsUnidirectional() bool

Types

type Config

type Config struct {
	// TLSConfig is the TLS configuration used to perform the TLS 1.3 handshake
	// in userspace. It is required and must set NextProtos (ALPN). MinVersion
	// is defaulted to TLS 1.3 when unset; lower versions are rejected.
	//
	// The kernel uses the ALPN protocols from NextProtos to demultiplex
	// incoming connections between listeners.
	TLSConfig *tls.Config
}

Config configures a Conn or Listener.

type Conn

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

A Conn is a QUIC connection. The kernel multiplexes streams over the connection: each Send or Receive carries one message on one stream.

func Dial

func Dial(ctx context.Context, raddr netip.AddrPort, cfg *Config) (*Conn, error)

Dial dials a QUIC connection to raddr and completes the QUIC/TLS handshake before returning. cfg is required.

If cfg.TLSConfig.ServerName is empty and InsecureSkipVerify is false, the server name is defaulted to raddr's IP address for certificate verification.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() tls.ConnectionState

ConnectionState returns the TLS connection state of the completed handshake.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() netip.AddrPort

LocalAddr returns the local address of the connection.

func (*Conn) OpenStream

func (c *Conn) OpenStream(uni bool) (StreamID, error)

OpenStream opens the next available bidirectional or unidirectional stream and returns its ID.

func (*Conn) Receive

func (c *Conn) Receive(b []byte) (n int, sid StreamID, flags Flags, err error)

Receive reads one message from the connection into b, reporting the stream it arrived on and its flags. StreamFin is set when the peer finished the stream. If b is too small for the message, the remainder is returned by subsequent calls.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() netip.AddrPort

RemoteAddr returns the remote address of the connection.

func (*Conn) Send

func (c *Conn) Send(sid StreamID, flags Flags, b []byte) (int, error)

Send writes one message on stream sid. Pass StreamNew with the first message on a stream that was not opened with OpenStream, and StreamFin with the final message.

func (*Conn) SetDeadline

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

SetDeadline sets the read and write deadlines for the connection.

func (*Conn) SetReadDeadline

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

SetReadDeadline sets the read deadline for the connection.

func (*Conn) SetWriteDeadline

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

SetWriteDeadline sets the write deadline for the connection.

func (*Conn) SyscallConn

func (c *Conn) SyscallConn() (syscall.RawConn, error)

SyscallConn returns a raw network connection for direct access to the underlying socket.

type Flags

type Flags uint32

Flags are per-message stream flags for Conn.Send and Conn.Receive.

const (
	// StreamNew opens the stream on its first send. Use it with the first
	// message on a new stream ID, or open the stream with Conn.OpenStream.
	StreamNew Flags = 0x400 // MSG_SYN

	// StreamFin marks the final message on a stream. On receive, it reports
	// that the peer finished the stream.
	StreamFin Flags = 0x200 // MSG_FIN

	// StreamUni opens a unidirectional stream, in combination with StreamNew.
	StreamUni Flags = 0x800 // MSG_CONFIRM

	// StreamDontwait makes a send return immediately rather than blocking
	// when the stream is not yet available.
	StreamDontwait Flags = 0x80 // MSG_EOR

	// StreamSndblock blocks a send until the stream's data is acknowledged.
	StreamSndblock Flags = 0x2000 // MSG_ERRQUEUE
)

Possible Flags values. These alias the kernel's MSG_QUIC_STREAM_* flags, which in turn alias existing Linux MSG_* bits.

type Listener

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

A Listener listens for incoming QUIC connections.

func Listen

func Listen(laddr netip.AddrPort, cfg *Config) (*Listener, error)

Listen listens for incoming QUIC connections on laddr. cfg is required, and the ALPN protocols in cfg.TLSConfig.NextProtos are registered with the kernel to demultiplex incoming connections to this Listener.

func (*Listener) Accept

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

Accept accepts a connection and completes the server side of the QUIC/TLS handshake before returning. Handshakes are serialized: Accept does not return until the accepted connection is established.

func (*Listener) Addr

func (l *Listener) Addr() netip.AddrPort

Addr returns the local address of the Listener.

func (*Listener) Close

func (l *Listener) Close() error

Close stops listening. Already accepted connections are not closed.

type StreamID

type StreamID int64

A StreamID identifies a QUIC stream. Client-initiated bidirectional streams are 0, 4, 8, ...; server-initiated bidirectional streams are 1, 5, 9, ...; unidirectional streams add 2. The two low bits carry the type.

func (StreamID) IsServerInitiated

func (id StreamID) IsServerInitiated() bool

IsServerInitiated reports whether the stream was initiated by the server.

func (StreamID) IsUnidirectional

func (id StreamID) IsUnidirectional() bool

IsUnidirectional reports whether the stream is unidirectional.