Documentation
¶
Overview ¶
Package conn implements WireGuard's network connections.
Index ¶
- Constants
- Variables
- type Bind
- type BindSocketToInterface
- type Endpoint
- type ErrUDPGSODisabled
- type InitiationAwareEndpoint
- type PeekLookAtSocketFd
- type PeerAwareEndpoint
- type ReceiveFunc
- type ReceivedPacket
- type StdNetBind
- func (s *StdNetBind) BatchSize() int
- func (s *StdNetBind) Close() error
- func (s *StdNetBind) Open(uport uint16) ([]ReceiveFunc, uint16, error)
- func (*StdNetBind) ParseEndpoint(s string) (Endpoint, error)
- func (s *StdNetBind) Send(bufs [][]byte, endpoint Endpoint, offset int) error
- func (s *StdNetBind) SetMark(mark uint32) error
- type StdNetEndpoint
- func (e *StdNetEndpoint) ClearSrc()
- func (e *StdNetEndpoint) DstIP() netip.Addr
- func (e *StdNetEndpoint) DstToBytes() []byte
- func (e *StdNetEndpoint) DstToString() string
- func (e *StdNetEndpoint) SrcIP() netip.Addr
- func (e *StdNetEndpoint) SrcIfidx() int32
- func (e *StdNetEndpoint) SrcToString() string
Constants ¶
const (
IdealBatchSize = 128 // maximum number of packets handled per read and write
)
const StdNetSupportsStickySockets = true
Variables ¶
var ( ErrBindAlreadyOpen = errors.New("bind is already open") ErrWrongEndpointType = errors.New("endpoint type does not correspond with bind type") )
Functions ¶
This section is empty.
Types ¶
type Bind ¶
type Bind interface {
// Open puts the Bind into a listening state on a given port and reports the actual
// port that it bound to. Passing zero results in a random selection.
// fns is the set of functions that will be called to receive packets.
Open(port uint16) (fns []ReceiveFunc, actualPort uint16, err error)
// Close closes the Bind listener.
// All fns returned by Open must return net.ErrClosed after a call to Close.
Close() error
// SetMark sets the mark for each packet sent through this Bind.
// This mark is passed to the kernel as the socket option SO_MARK.
SetMark(mark uint32) error
// Send writes one or more packets in bufs to address ep. A nonzero offset
// can be used to instruct the Bind on where packet data begins in each
// element of the bufs slice. Space preceding offset is free to use for
// additional encapsulation. The length of bufs must not exceed BatchSize().
Send(bufs [][]byte, ep Endpoint, offset int) error
// ParseEndpoint creates a new endpoint from a string.
ParseEndpoint(s string) (Endpoint, error)
// BatchSize is the number of buffers expected to be passed to
// the ReceiveFuncs, and the maximum expected to be passed to SendBatch.
BatchSize() int
}
A Bind listens on a port for both IPv6 and IPv4 UDP traffic.
A Bind interface may also be a PeekLookAtSocketFd or BindSocketToInterface, depending on the platform-specific implementation.
func NewDefaultBind ¶
func NewDefaultBind() Bind
func NewStdNetBind ¶
func NewStdNetBind() Bind
type BindSocketToInterface ¶
type BindSocketToInterface interface {
BindSocketToInterface4(interfaceIndex uint32, blackhole bool) error
BindSocketToInterface6(interfaceIndex uint32, blackhole bool) error
}
BindSocketToInterface is implemented by Bind objects that support being tied to a single network interface. Used by wireguard-windows.
type Endpoint ¶
type Endpoint interface {
ClearSrc() // clears the source address
SrcToString() string // returns the local source address (ip:port)
DstToString() string // returns the destination address (ip:port)
DstToBytes() []byte // used for mac2 cookie calculations
DstIP() netip.Addr
SrcIP() netip.Addr
}
An Endpoint maintains the source/destination caching for a peer.
dst: the remote address of a peer ("endpoint" in uapi terminology)
src: the local address from which datagrams originate going to the peer
type ErrUDPGSODisabled ¶
type ErrUDPGSODisabled struct {
RetryErr error
// contains filtered or unexported fields
}
func (ErrUDPGSODisabled) Error ¶
func (e ErrUDPGSODisabled) Error() string
func (ErrUDPGSODisabled) Unwrap ¶
func (e ErrUDPGSODisabled) Unwrap() error
type InitiationAwareEndpoint ¶
type InitiationAwareEndpoint interface {
// InitiationMessagePublicKey is called when a handshake initiation message
// has been received, and the sender's public key has been identified, but
// BEFORE an attempt has been made to verify it.
InitiationMessagePublicKey(peerPublicKey [32]byte)
}
InitiationAwareEndpoint is an optional Endpoint specialization for integrations that want to know when a WireGuard handshake initiation message has been received, enabling just-in-time peer configuration before attempted decryption.
It's most useful when used in combination with PeerAwareEndpoint, enabling JIT peer configuration and post-decryption peer verification from a single implementer.
type PeekLookAtSocketFd ¶
type PeekLookAtSocketFd interface {
PeekLookAtSocketFd4() (fd int, err error)
PeekLookAtSocketFd6() (fd int, err error)
}
PeekLookAtSocketFd is implemented by Bind objects that support having their file descriptor peeked at. Used by wireguard-android.
type PeerAwareEndpoint ¶
type PeerAwareEndpoint interface {
// FromPeer is called at least once per successfully Cryptokey Routing ID'd
// [ReceiveFunc] packets batch for a given node key. wireguard-go will
// always call it for the latest/tail packet in the batch, only ever
// suppressing calls for older packets.
FromPeer(peerPublicKey [32]byte)
}
PeerAwareEndpoint is an optional Endpoint specialization for integrations that want to know about the outcome of Cryptokey Routing identification.
If they receive a packet from a source they had not pre-identified, to learn the identification WireGuard can derive from the session or handshake.
A PeerAwareEndpoint may be installed as the conn.Endpoint following successful decryption unless endpoint roaming has been disabled for the peer.
type ReceiveFunc ¶
type ReceiveFunc func(slab []byte, packets []ReceivedPacket) (n int, err error)
A ReceiveFunc receives at least one packet from the network and writes them into slab. On a successful read it returns the number of elements of packets that should be evaluated. Callers must pass a length of packets equal to the associated Bind.BatchSize.
func (ReceiveFunc) PrettyName ¶
func (fn ReceiveFunc) PrettyName() string
type ReceivedPacket ¶
type ReceivedPacket struct {
// Offset is the starting byte offset.
Offset int
// Size is the size of the packet.
Size int
// Endpoint is the associated [Endpoint].
Endpoint Endpoint
}
ReceivedPacket describes a packet read by a ReceiveFunc.
func (*ReceivedPacket) Bytes ¶
func (r *ReceivedPacket) Bytes(slab []byte) []byte
type StdNetBind ¶
type StdNetBind struct {
// contains filtered or unexported fields
}
StdNetBind implements Bind for all platforms. While Windows has its own Bind (see bind_windows.go), it may fall back to StdNetBind. TODO: Remove usage of ipv{4,6}.PacketConn when net.UDPConn has comparable methods for sending and receiving multiple datagrams per-syscall. See the proposal in https://github.com/golang/go/issues/45886#issuecomment-1218301564.
func (*StdNetBind) BatchSize ¶
func (s *StdNetBind) BatchSize() int
TODO: When all Binds handle IdealBatchSize, remove this dynamic function and rename the IdealBatchSize constant to BatchSize.
func (*StdNetBind) Close ¶
func (s *StdNetBind) Close() error
func (*StdNetBind) Open ¶
func (s *StdNetBind) Open(uport uint16) ([]ReceiveFunc, uint16, error)
func (*StdNetBind) ParseEndpoint ¶
func (*StdNetBind) ParseEndpoint(s string) (Endpoint, error)
func (*StdNetBind) Send ¶
func (s *StdNetBind) Send(bufs [][]byte, endpoint Endpoint, offset int) error
func (*StdNetBind) SetMark ¶
func (s *StdNetBind) SetMark(mark uint32) error
type StdNetEndpoint ¶
type StdNetEndpoint struct {
// AddrPort is the endpoint destination.
netip.AddrPort
// contains filtered or unexported fields
}
func (*StdNetEndpoint) ClearSrc ¶
func (e *StdNetEndpoint) ClearSrc()
func (*StdNetEndpoint) DstIP ¶
func (e *StdNetEndpoint) DstIP() netip.Addr
func (*StdNetEndpoint) DstToBytes ¶
func (e *StdNetEndpoint) DstToBytes() []byte
func (*StdNetEndpoint) DstToString ¶
func (e *StdNetEndpoint) DstToString() string
func (*StdNetEndpoint) SrcIP ¶
func (e *StdNetEndpoint) SrcIP() netip.Addr
func (*StdNetEndpoint) SrcIfidx ¶
func (e *StdNetEndpoint) SrcIfidx() int32
func (*StdNetEndpoint) SrcToString ¶
func (e *StdNetEndpoint) SrcToString() string