WG(4) FreeBSD Kernel Interfaces Manual WG(4)
NAME
wg - WireGuard pseudo-device
SYNOPSIS
pseudo-device wg
DESCRIPTION
The wg driver provides Virtual Private Network (VPN) interfaces for the
secure exchange of layer 3 traffic with other WireGuard peers using the
WireGuard protocol.
A wg interface recognises one or more peers, establishes a secure tunnel
with each on demand, and tracks each peer's UDP endpoint for exchanging
encrypted traffic with.
The interfaces can be created at runtime using the ifconfig wgN create
command or by setting up a hostname.if(5) configuration file for
netstart(8). The interface itself can be configured with ifconfig(8).
wg interfaces support the following ioctl(2)s:
SIOCSWG struct wg_data_io *
Set the device configuration.
SIOCGWG struct wg_data_io *
Get the device configuration.
The following glossary provides a brief overview of WireGuard
terminology:
Peer Peers exchange IPv4 or IPv6 traffic over secure tunnels. Each
wg interface may be configured to recognise one or more peers.
Key Each peer uses its private key and corresponding public key to
identify itself to others. A peer configures a wg interface
with its own private key and with the public keys of its
peers.
Preshared key
In addition to the public keys, each peer pair may be
configured with a unique pre-shared symmetric key. This is
used in their handshake to guard against future compromise of
the peers' encrypted tunnel if a quantum-computational attack
on their Diffie-Hellman exchange becomes feasible. It is
optional, but recommended.
Allowed IPs
A single wg interface may maintain concurrent tunnels
connecting diverse networks. The interface therefore
implements rudimentary routing and reverse-path filtering
functions for its tunneled traffic. These functions reference
a set of allowed IP ranges configured against each peer.
The interface will route outbound tunneled traffic to the peer
configured with the most specific matching allowed IP address
range, or drop it if no such match exists.
The interface will accept tunneled traffic only from the peer
configured with the most specific matching allowed IP address
range for the incoming traffic, or drop it if no such match
exists. That is, tunneled traffic routed to a given peer
cannot return through another peer of the same wg interface.
This ensures that peers cannot spoof another's traffic.
Handshake
Two peers handshake to mutually authenticate each other and to
establish a shared series of secret ephemeral encryption keys.
Any peer may initiate a handshake. Handshakes occur only when
there is traffic to send, and recur every two minutes during
transfers.
Connectionless
Due to the handshake behavior, there is no connected or
disconnected state.
Keys
Private keys for WireGuard can be generated from any sufficiently secure
random source. The Curve25519 keys and the preshared keys are both 32
bytes long and are commonly encoded in base64 for ease of use.
Keys can be generated with openssl(1) as follows:
$ openssl rand -base64 32
Although a valid Curve25519 key must have 5 bits set to specific values,
this is done by the interface and so it will accept any random 32-byte
base64 string.
When an interface has a private key set with wgkey, the corresponding
public key is shown in the status output of the interface:
# ifconfig wg1 | grep wgpubkey
wgpubkey NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps=
EXAMPLES
Create two wg interfaces in separate rdomain(4)s, which is of no
practical use but demonstrates two interfaces on the same machine:
#!/bin/sh
# create interfaces; set random private keys
ifconfig wg1 create wgport 7111 wgkey `openssl rand -base64 32` rdomain 1
ifconfig wg2 create wgport 7222 wgkey `openssl rand -base64 32` rdomain 2
# retrieve the public keys associated with the private keys
PUB1="`ifconfig wg1 | grep 'wgpubkey' | cut -d ' ' -f 2`"
PUB2="`ifconfig wg2 | grep 'wgpubkey' | cut -d ' ' -f 2`"
ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 7222 wgaip 192.168.5.2/32
ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 7111 wgaip 192.168.5.1/32
ifconfig wg1 192.168.5.1/24
ifconfig wg2 192.168.5.2/24
After this, ping one interface from the other:
$ route -T1 exec ping 192.168.5.2
The two interfaces are able to communicate through the UDP tunnel which
resides in the default rdomain(4).
Show the listening sockets:
$ netstat -ln
DIAGNOSTICS
The wg interface supports runtime debugging, which can be enabled with:
ifconfig wgN debug
Some common error messages include:
Handshake for peer X did not complete after 5 seconds, retrying Peer X
did not reply to our initiation packet, for example because:
o The peer does not have the local interface configured as a peer.
Peers must be able to mutually authenticate each other.
o The peer endpoint IP address is incorrectly configured.
o There are firewall rules preventing communication between hosts.
Invalid handshake initiation The incoming handshake packet could not be
processed. This is likely due to the local interface not containing the
correct public key for the peer.
Invalid initiation MAC The incoming handshake initiation packet had an
invalid MAC. This is likely because the initiation sender has the wrong
public key for the handshake receiver.
Packet has unallowed src IP from peer X After decryption, an incoming
data packet has a source IP address that is not assigned to the allowed
IPs of Peer X.
SEE ALSO
inet(4), ip(4), netintro(4), hostname.if(5), pf.conf(5), ifconfig(8),
netstart(8)
WireGuard whitepaper, https://www.wireguard.com/papers/wireguard.pdf.
HISTORY
The wg driver first appeared in OpenBSD 6.8.
AUTHORS
The OpenBSD wg driver was developed by Matt Dunwoodie <
[email protected]>
and Jason A. Donenfeld <
[email protected]>, based on code written by Jason
A. Donenfeld.
FreeBSD 14.1-RELEASE-p8 March 14, 2021 FreeBSD 14.1-RELEASE-p8