1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd January 18, 2024 27.Dt WG 4 28.Os 29.Sh NAME 30.Nm wg 31.Nd WireGuard protocol driver 32.Sh SYNOPSIS 33To load the driver as a module at boot time, place the following line in 34.Xr rc.conf 5 : 35.Bd -literal -offset indent 36if_wg_load="YES" 37.Ed 38.Pp 39To compile this driver into the kernel, add the following line to 40.Xr kernconf 5 41kernel configuration file: 42.Bd -literal -offset indent 43.Cd pseudo-device wg 44.Ed 45.Sh DESCRIPTION 46The 47.Nm 48driver provides Virtual Private Network (VPN) interfaces for the secure 49exchange of layer 3 traffic with other WireGuard peers using the WireGuard 50protocol. 51.Pp 52A 53.Nm 54interface recognizes one or more peers, establishes a secure tunnel with 55each on demand, and tracks each peer's UDP endpoint for exchanging encrypted 56traffic with. 57.Pp 58The interfaces can be created at runtime using the 59.Ic ifconfig Cm wg Ns Ar N Cm create 60command, and then can be configured with 61.Xr ifconfig 8 . 62In addition, the 63.Nm 64.Xr rc 8 65script can be used to easily manage the interfaces; refer to 66.Xr rc.conf 5 67and 68.Xr wg.conf 5 69for the details. 70.Ss Terminology 71The following glossary provides a brief overview of WireGuard terminology: 72.Bl -tag -width indent -offset 3n 73.It Peer 74Peers exchange IPv4 or IPv6 traffic over secure tunnels. 75Each 76.Nm 77interface may be configured to recognize one or more peers. 78.It Key 79Each peer uses its private key and corresponding public key to 80identify itself to others. 81A peer configures a 82.Nm 83interface with its own private key and with the public keys of its peers. 84.It Pre-shared key 85In addition to the public keys, each peer pair may be configured with a 86unique pre-shared symmetric key. 87This is used in their handshake to guard against future compromise of the 88peers' encrypted tunnel if an attack on their Diffie-Hellman exchange 89becomes feasible. 90It is optional, but recommended. 91.It Allowed IP addresses 92A single 93.Nm 94interface may maintain concurrent tunnels connecting diverse networks. 95The interface therefore implements rudimentary routing and reverse-path 96filtering functions for its tunneled traffic. 97These functions reference a set of allowed IP address ranges configured 98against each peer. 99.Pp 100The interface will route outbound tunneled traffic to the peer configured 101with the most specific matching allowed IP address range, or drop it 102if no such match exists. 103The interface will accept tunneled traffic only from the peer 104configured with the most specific matching allowed IP address range 105for the incoming traffic, or drop it if no such match exists. 106That is, tunneled traffic routed to a given peer cannot return through 107another peer of the same 108.Nm 109interface. 110This ensures that peers cannot spoof one another's traffic. 111.It Handshake 112Two peers handshake to mutually authenticate each other and to 113establish a shared series of secret ephemeral encryption keys. 114Either peer may initiate a handshake. 115Handshakes occur only when there is traffic to send, and recur every 116two minutes during transfers. 117.It Connectionless 118Due to the handshake behavior, there is no connected or disconnected 119state. 120.El 121.Ss Keys 122Private keys for WireGuard can be generated from any sufficiently 123secure random source. 124The Curve25519 keys and the pre-shared keys are both 32 bytes 125long and are commonly encoded in base64 for ease of use. 126.Pp 127Keys can be generated with 128.Xr openssl 1 129as follows: 130.Pp 131.Dl $ openssl rand -base64 32 132.Pp 133Although a valid Curve25519 key must have 5 bits set to specific values, 134this is done by the 135.Nm 136interface and so it will accept any random 32-byte base64 string. 137.Sh EXAMPLES 138Create a 139.Nm 140interface and set random private key: 141.Bd -literal -offset indent 142# ifconfig wg0 create 143# ifconfig wg0 wgkey `openssl rand -base64 32` wgport 54321 144.Ed 145.Pp 146Retrieve the associated public key from a 147.Nm 148interface: 149.Bd -literal -offset indent 150$ ifconfig wg0 | grep 'wgpubkey:' 151.Ed 152.Pp 153By default, the private key and pre-shared key (if set) are hidden from 154the interface status output, but can be made to show up by specifying the 155.Fl k 156flag for 157.Xr ifconfig 8 : 158.Bd -literal -offset indent 159# ifconfig -k wg0 | grep -E 'wgkey:|wgpsk:' 160.Ed 161.Pp 162Connect to a specific endpoint using its public-key and set the 163allowed IP address: 164.Bd -literal -offset indent 165# ifconfig wg0 wgpeer <peer_pubkey> \\ 166 wgendpoint 10.0.1.100 54321 \\ 167 wgaip 192.168.2.100/32 168.Ed 169.Pp 170Set description for a peer: 171.Bd -literal -offset indent 172# ifconfig wg0 wgpeer <peer_pubkey> wgdescr <peer_description> 173.Ed 174.Pp 175Remove a peer: 176.Bd -literal -offset indent 177# ifconfig wg0 -wgpeer <peer_pubkey> 178.Ed 179.Sh DIAGNOSTICS 180The 181.Nm 182interface supports runtime debugging, which can be enabled with: 183.Pp 184.D1 Ic ifconfig Cm wg Ns Ar N Cm debug 185.Pp 186Some common error messages include: 187.Bl -tag -width indent 188.It Sy "Handshake for peer X did not complete after 5 seconds, retrying" 189Peer X did not reply to our initiation packet, for example because: 190.Bl -bullet -compact 191.It 192The peer does not have the local interface configured as a peer. 193Peers must be able to mutually authenticate each other. 194.It 195The peer's endpoint IP address is incorrectly configured. 196.It 197There are firewall rules preventing communication between hosts. 198.El 199.It Sy "Invalid handshake initiation" 200The incoming handshake packet could not be processed. 201This is likely due to the local interface not containing 202the correct public key for the peer. 203.It Sy "Invalid initiation MAC" 204The incoming handshake initiation packet had an invalid MAC. 205This is likely because the initiation sender has the wrong public key 206for the handshake receiver. 207.It Sy "Packet has disallowed src IP from peer X" 208After decryption, an incoming data packet has a source IP address that 209is not assigned to the allowed IPs of Peer X. 210.El 211.Sh SEE ALSO 212.Xr inet 4 , 213.Xr ip 4 , 214.Xr netintro 4 , 215.Xr wg.conf 5 , 216.Xr ifconfig 8 217.Rs 218.%T WireGuard whitepaper 219.%U https://www.wireguard.com/papers/wireguard.pdf 220.Re 221.Sh HISTORY 222The 223.Nm 224device driver first appeared in 225.Dx 6.5 , 226.Fx 13.2 , 227and 228.Ox 6.8 . 229.Sh AUTHORS 230.An -nosplit 231The 232.Nm 233device driver was written by 234.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , 235.An Matt Dunwoodie Aq Mt ncon@nconroy.net , 236.An Kyle Evans Aq Mt kevans@FreeBSD.org , 237and 238.An Matt Macy Aq Mt mmacy@FreeBSD.org . 239.Pp 240This manual page was written by 241.An Gordon Bergling Aq Mt gbe@FreeBSD.org 242and is based on the 243.Ox 244manual page written by 245.An David Gwynne Aq Mt dlg@openbsd.org . 246