wgtypes

Documentation

Overview

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

Index

• Constants
• Variables
• type Config
  • func (cfg *Config) GenerateAmneziaParams()
  • func (cfg *Config) Validate() error
• 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
• type UintRange
  • func ParseUintRange(s string) (UintRange, error)
  • func UintRangeFromPackedU16(v uint32) UintRange
  • func (r UintRange) IsZero() bool
  • func (r UintRange) PackU16() uint32
  • func (r UintRange) String() string

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

	// Junk Packet parameters
	Jc   *int // Count
	Jmin *int // Min size
	Jmax *int // Max size

	// Message Padding parameters (bytes)
	S1 *int // Init
	S2 *int // Response
	S3 *int // Cookie
	S4 *int // Transport

	// Message Magic Headers
	// In AmneziaWG 2.0 these should be ranges (e.g., "123456-123999")
	H1 *string // Init
	H2 *string // Response
	H3 *string // Cookie
	H4 *string // Transport

	// Init Packet Magic / Custom Signature (AWG 2.0 only).
	// If I1 is nil, the entire chain is skipped and AWG behaves as 1.0.
	// Each field uses tag syntax — see Device.I1 for full reference.
	// GenerateAmneziaParams() fills all five with "<r N>" (random bytes).
	I1 *string
	I2 *string
	I3 *string
	I4 *string
	I5 *string

	// HeaderProtectionKey is the 32-byte key used for packet header protection.
	HeaderProtectionKey *Key

	// ContentPaddingAddition is extra transport padding in bytes (AWG 3 range).
	ContentPaddingAddition *UintRange

	// Timeouts and limits for the noise protocol (AWG 3 ranges, seconds / attempts).
	RekeyAfterTime       *UintRange
	RekeyTimeout         *UintRange
	RejectAfterTime      *UintRange
	KeepaliveTimeout     *UintRange
	MaxHandshakeAttempts *UintRange

	// Additional obfuscation flags
	RandomTrailers *bool
	DisableCookies *bool
}

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.

func (*Config) GenerateAmneziaParams

func (cfg *Config) GenerateAmneziaParams()

GenerateAmneziaParams populates the config with obfuscation values optimized for AWG 2.0.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks that the AmneziaWG-specific fields in Config are within the documented kernel limits. Returns a non-nil error describing the first violation found.

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

	IsAmnezia bool

	// Jc is the number of junk packets sent before each real handshake (0-10).
	Jc int
	// Jmin is the minimum junk packet size in bytes (64-1024).
	Jmin int
	// Jmax is the maximum junk packet size in bytes (64-1024, >= Jmin).
	Jmax int

	// S1 is the number of padding bytes prepended to the Initiation packet (0-64).
	S1 int
	// S2 is the number of padding bytes prepended to the Response packet (0-64).
	S2 int
	// S3 is the number of padding bytes prepended to the Cookie packet (0-64).
	S3 int
	// S4 is the number of padding bytes prepended to the Transport packet (0-32).
	S4 int

	// H1-H4 are the magic header values (or ranges "min-max") for each packet type.
	H1 string // Initiation
	H2 string // Response
	H3 string // Cookie
	H4 string // Transport

	// I1–I5 are the custom init packet chain (AWG 2.0 only).
	// If I1 is absent, the entire chain is skipped and AWG behaves as 1.0.
	//
	// Each field is a string describing one or more packet segments using tags:
	//
	//   <r N>       — N random bytes
	//   <b 0xHEX>   — literal bytes in hex (e.g. "<b 0xdeadbeef>")
	//   <c>         — 4-byte packet counter (big-endian uint32)
	//   <t VAL>     — timestamp-based field
	//   <rc VAL>    — random bytes, count-based
	//   <rd VAL>    — random bytes, deterministic
	//
	// Multiple tags can be combined: "<r 10><b 0xff><c>"
	// GenerateAmneziaParams() uses "<r N>" for simplicity.
	I1 string
	I2 string
	I3 string
	I4 string
	I5 string

	// HeaderProtectionKey is the 32-byte key used for packet header protection.
	HeaderProtectionKey Key

	// ContentPaddingAddition is extra transport padding in bytes (AWG 3 range).
	ContentPaddingAddition UintRange

	// Timeouts and limits for the noise protocol (AWG 3 ranges, seconds / attempts).
	RekeyAfterTime       UintRange
	RekeyTimeout         UintRange
	RejectAfterTime      UintRange
	KeepaliveTimeout     UintRange
	MaxHandshakeAttempts UintRange

	// Additional obfuscation flags
	RandomTrailers bool
	DisableCookies bool

	// 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

	// AdvancedSecurity indicates whether this peer uses AmneziaWG obfuscation.
	// This is read-only — set by the kernel based on the device's advanced_security
	// flag and whether the peer was configured with WGPEER_F_HAS_ADVANCED_SECURITY.
	AdvancedSecurity bool
}

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

	// AdvancedSecurity enables AmneziaWG obfuscation for this peer.
	// When true, the kernel sets WGPEER_F_HAS_ADVANCED_SECURITY and
	// WGPEER_A_ADVANCED_SECURITY on the peer. Only effective when the
	// device itself has AWG parameters configured.
	AdvancedSecurity bool
}

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.

type UintRange

type UintRange struct {
	Min int
	Max int
}

UintRange is an AWG 3 inclusive range (Min..Max).

The zero value (Min == Max == 0) means the field is unset, matching kernel u16_range_is_zero. A single value uses Min == Max.

On the wire:

• Kernel netlink: packed u16_range_t as NLA_U32 (hi<<16 | lo)
• Userspace UAPI: "10" or "10-100"

func ParseUintRange

func ParseUintRange(s string) (UintRange, error)

ParseUintRange parses a UAPI/wg-quick range: "10" or "10-100".

func UintRangeFromPackedU16

func UintRangeFromPackedU16(v uint32) UintRange

UintRangeFromPackedU16 unpacks a kernel u16_range_t.

If the high 16 bits are 0, the value is treated as a single number (legacy dumps that stored lo only): Min == Max == lo. Packed 0 stays zero.

func (UintRange) IsZero

func (r UintRange) IsZero() bool

IsZero reports whether r is the unset zero value.

func (UintRange) PackU16

func (r UintRange) PackU16() uint32

PackU16 packs r as a kernel u16_range_t (hi<<16 | lo).

func (UintRange) String

func (r UintRange) String() string

String renders the UAPI form: "10" or "10-100".