wgtypes

Documentation

Overview

Package wgtypes provides shared types for the wgctrl family of packages.

Index

• Constants
• Variables
• type Config
• type Device
• type DeviceType
  • func (dt DeviceType) String() string
• type Key
  • func GenerateKey() (Key, error)
  • func GeneratePrivateKey() (Key, error)
  • func NewKey(b []byte) (Key, error)
  • func ParseKey(s string) (Key, error)
  • func (k Key) PublicKey() Key
  • func (k Key) String() string
• type Peer
• type PeerConfig

Constants

const KeyLen = 32 // wgh.KeyLen

KeyLen is the expected key length for a WireGuard key.

Variables

var ErrUpdateOnlyNotSupported = errors.New("the UpdateOnly flag is not supported by this platform")

ErrUpdateOnlyNotSupported is returned due to missing kernel support of the PeerConfig UpdateOnly flag.

Types

type Config

type Config struct {
	// PrivateKey specifies a private key configuration, if not nil.
	//
	// A non-nil, zero-value Key will clear the private key.
	PrivateKey *Key

	// ListenPort specifies a device's listening port, if not nil.
	ListenPort *int

	// FirewallMark specifies a device's firewall mark, if not nil.
	//
	// If non-nil and set to 0, the firewall mark will be cleared.
	FirewallMark *int

	// ReplacePeers specifies if the Peers in this configuration should replace
	// the existing peer list, instead of appending them to the existing list.
	ReplacePeers bool

	// Peers specifies a list of peer configurations to apply to a device.
	Peers []PeerConfig
}

A Config is a WireGuard device configuration.

Because the zero value of some Go types may be significant to WireGuard for Config fields, pointer types are used for some of these fields. Only pointer fields which are not nil will be applied when configuring a device.

type Device

type Device struct {
	// Name is the name of the device.
	Name string

	// Type specifies the underlying implementation of the device.
	Type DeviceType

	// PrivateKey is the device's private key.
	PrivateKey Key

	// PublicKey is the device's public key, computed from its PrivateKey.
	PublicKey Key

	// ListenPort is the device's network listening port.
	ListenPort int

	// FirewallMark is the device's current firewall mark.
	//
	// The firewall mark can be used in conjunction with firewall software to
	// take action on outgoing WireGuard packets.
	FirewallMark int

	// Peers is the list of network peers associated with this device.
	Peers []Peer
}

A Device is a WireGuard device.

type DeviceType

type DeviceType int

A DeviceType specifies the underlying implementation of a WireGuard device.

const (
	Unknown DeviceType = iota
	LinuxKernel
	OpenBSDKernel
	FreeBSDKernel
	WindowsKernel
	Userspace
)

Possible DeviceType values.

func (DeviceType) String

func (dt DeviceType) String() string

String returns the string representation of a DeviceType.

type Key

type Key [KeyLen]byte

A Key is a public, private, or pre-shared secret key. The Key constructor functions in this package can be used to create Keys suitable for each of these applications.

func GenerateKey

func GenerateKey() (Key, error)

GenerateKey generates a Key suitable for use as a pre-shared secret key from a cryptographically safe source.

The output Key should not be used as a private key; use GeneratePrivateKey instead.

func GeneratePrivateKey

func GeneratePrivateKey() (Key, error)

GeneratePrivateKey generates a Key suitable for use as a private key from a cryptographically safe source.

func NewKey

func NewKey(b []byte) (Key, error)

NewKey creates a Key from an existing byte slice. The byte slice must be exactly 32 bytes in length.

func ParseKey

func ParseKey(s string) (Key, error)

ParseKey parses a Key from a base64-encoded string, as produced by the Key.String method.

func (Key) PublicKey

func (k Key) PublicKey() Key

PublicKey computes a public key from the private key k.

PublicKey should only be called when k is a private key.

func (Key) String

func (k Key) String() string

String returns the base64-encoded string representation of a Key.

ParseKey can be used to produce a new Key from this string.

type Peer

type Peer struct {
	// PublicKey is the public key of a peer, computed from its private key.
	//
	// PublicKey is always present in a Peer.
	PublicKey Key

	// PresharedKey is an optional preshared key which may be used as an
	// additional layer of security for peer communications.
	//
	// A zero-value Key means no preshared key is configured.
	PresharedKey Key

	// Endpoint is the most recent source address used for communication by
	// this Peer.
	Endpoint *net.UDPAddr

	// PersistentKeepaliveInterval specifies how often an "empty" packet is sent
	// to a peer to keep a connection alive.
	//
	// A value of 0 indicates that persistent keepalives are disabled.
	PersistentKeepaliveInterval time.Duration

	// LastHandshakeTime indicates the most recent time a handshake was performed
	// with this peer.
	//
	// A zero-value time.Time indicates that no handshake has taken place with
	// this peer.
	LastHandshakeTime time.Time

	// ReceiveBytes indicates the number of bytes received from this peer.
	ReceiveBytes int64

	// TransmitBytes indicates the number of bytes transmitted to this peer.
	TransmitBytes int64

	// AllowedIPs specifies which IPv4 and IPv6 addresses this peer is allowed
	// to communicate on.
	//
	// 0.0.0.0/0 indicates that all IPv4 addresses are allowed, and ::/0
	// indicates that all IPv6 addresses are allowed.
	AllowedIPs []net.IPNet

	// ProtocolVersion specifies which version of the WireGuard protocol is used
	// for this Peer.
	//
	// A value of 0 indicates that the most recent protocol version will be used.
	ProtocolVersion int
}

A Peer is a WireGuard peer to a Device.

type PeerConfig

type PeerConfig struct {
	// PublicKey specifies the public key of this peer.  PublicKey is a
	// mandatory field for all PeerConfigs.
	PublicKey Key

	// Remove specifies if the peer with this public key should be removed
	// from a device's peer list.
	Remove bool

	// UpdateOnly specifies that an operation will only occur on this peer
	// if the peer already exists as part of the interface.
	UpdateOnly bool

	// PresharedKey specifies a peer's preshared key configuration, if not nil.
	//
	// A non-nil, zero-value Key will clear the preshared key.
	PresharedKey *Key

	// Endpoint specifies the endpoint of this peer entry, if not nil.
	Endpoint *net.UDPAddr

	// PersistentKeepaliveInterval specifies the persistent keepalive interval
	// for this peer, if not nil.
	//
	// A non-nil value of 0 will clear the persistent keepalive interval.
	PersistentKeepaliveInterval *time.Duration

	// ReplaceAllowedIPs specifies if the allowed IPs specified in this peer
	// configuration should replace any existing ones, instead of appending them
	// to the allowed IPs list.
	ReplaceAllowedIPs bool

	// AllowedIPs specifies a list of allowed IP addresses in CIDR notation
	// for this peer.
	AllowedIPs []net.IPNet
}

A PeerConfig is a WireGuard device peer configuration.

Because the zero value of some Go types may be significant to WireGuard for PeerConfig fields, pointer types are used for some of these fields. Only pointer fields which are not nil will be applied when configuring a peer.