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 June 12, 2023 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 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 recognizes 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 wg 8 . 56.Pp 57The following glossary provides a brief overview of WireGuard 58terminology: 59.Bl -tag -width indent -offset 3n 60.It Peer 61Peers exchange IPv4 or IPv6 traffic over secure tunnels. 62Each 63.Nm 64interface may be configured to recognize one or more peers. 65.It Key 66Each peer uses its private key and corresponding public key to 67identify itself to others. 68A peer configures a 69.Nm 70interface with its own private key and with the public keys of its peers. 71.It Pre-shared key 72In addition to the public keys, each peer pair may be configured with a 73unique pre-shared symmetric key. 74This is used in their handshake to guard against future compromise of the 75peers' encrypted tunnel if an attack on their 76Diffie-Hellman exchange becomes feasible. 77It is optional, but recommended. 78.It Allowed IP addresses 79A single 80.Nm 81interface may maintain concurrent tunnels connecting diverse networks. 82The interface therefore implements rudimentary routing and reverse-path 83filtering functions for its tunneled traffic. 84These functions reference a set of allowed IP address ranges configured 85against each peer. 86.Pp 87The interface will route outbound tunneled traffic to the peer configured 88with the most specific matching allowed IP address range, or drop it 89if no such match exists. 90.Pp 91The interface will accept tunneled traffic only from the peer 92configured with the most specific matching allowed IP address range 93for the incoming traffic, or drop it if no such match exists. 94That is, tunneled traffic routed to a given peer cannot return through 95another peer of the same 96.Nm 97interface. 98This ensures that peers cannot spoof one another's traffic. 99.It Handshake 100Two peers handshake to mutually authenticate each other and to 101establish a shared series of secret ephemeral encryption keys. 102Either peer may initiate a handshake. 103Handshakes occur only when there is traffic to send, and recur every 104two minutes during transfers. 105.It Connectionless 106Due to the handshake behavior, there is no connected or disconnected 107state. 108.El 109.Ss Keys 110Private keys for WireGuard can be generated from any sufficiently 111secure random source. 112The Curve25519 keys and the pre-shared keys are both 32 bytes 113long and are commonly encoded in base64 for ease of use. 114.Pp 115Keys can be generated with 116.Xr wg 8 117as follows: 118.Pp 119.Dl $ wg genkey 120.Pp 121Although a valid Curve25519 key must have 5 bits set to 122specific values, this is done by the interface and so it 123will accept any random 32-byte base64 string. 124.Sh EXAMPLES 125Create a 126.Nm 127interface and set random private key. 128.Bd -literal -offset indent 129# ifconfig wg0 create 130# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin 131.Ed 132.Pp 133Retrieve the associated public key from a 134.Nm 135interface. 136.Bd -literal -offset indent 137$ wg show wg0 public-key 138.Ed 139.Pp 140Connect to a specific endpoint using its public-key and set the allowed IP address 141.Bd -literal -offset indent 142# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32 143.Ed 144.Pp 145Remove a peer 146.Bd -literal -offset indent 147# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove 148.Ed 149.Sh DIAGNOSTICS 150The 151.Nm 152interface supports runtime debugging, which can be enabled with: 153.Pp 154.D1 Ic ifconfig Cm wg Ns Ar N Cm debug 155.Pp 156Some common error messages include: 157.Bl -diag 158.It "Handshake for peer X did not complete after 5 seconds, retrying" 159Peer X did not reply to our initiation packet, for example because: 160.Bl -bullet 161.It 162The peer does not have the local interface configured as a peer. 163Peers must be able to mutually authenticate each other. 164.It 165The peer endpoint IP address is incorrectly configured. 166.It 167There are firewall rules preventing communication between hosts. 168.El 169.It "Invalid handshake initiation" 170The incoming handshake packet could not be processed. 171This is likely due to the local interface not containing 172the correct public key for the peer. 173.It "Invalid initiation MAC" 174The incoming handshake initiation packet had an invalid MAC. 175This is likely because the initiation sender has the wrong public key 176for the handshake receiver. 177.It "Packet has unallowed src IP from peer X" 178After decryption, an incoming data packet has a source IP address that 179is not assigned to the allowed IPs of Peer X. 180.El 181.Sh SEE ALSO 182.Xr inet 4 , 183.Xr ip 4 , 184.Xr ipsec 4 , 185.Xr netintro 4 , 186.Xr ovpn 4 , 187.Xr ipf 5 , 188.Xr pf.conf 5 , 189.Xr ifconfig 8 , 190.Xr ipfw 8 , 191.Xr wg 8 192.Rs 193.%T WireGuard whitepaper 194.%U https://www.wireguard.com/papers/wireguard.pdf 195.Re 196.Sh HISTORY 197The 198.Nm 199device driver first appeared in 200.Fx 13.2 . 201.Sh AUTHORS 202.An -nosplit 203The 204.Nm 205device driver was written by 206.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , 207.An Matt Dunwoodie Aq Mt ncon@nconroy.net , 208.An Kyle Evans Aq Mt kevans@FreeBSD.org , 209and 210.An Matt Macy Aq Mt mmacy@FreeBSD.org . 211.Pp 212This manual page was written by 213.An Gordon Bergling Aq Mt gbe@FreeBSD.org 214and is based on the 215.Ox 216manual page written by 217.An David Gwynne Aq Mt dlg@openbsd.org . 218