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