1.\" $OpenBSD: wg.4,v 1.10 2021/03/14 10:08:38 jmc Exp $ 2.\" Copyright (c) 2020 Matt Dunwoodie <ncon@noconroy.net> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: March 14 2021 $ 17.Dt WG 4 18.Os 19.Sh NAME 20.Nm wg 21.Nd WireGuard pseudo-device 22.Sh SYNOPSIS 23.Cd "pseudo-device wg" 24.Sh DESCRIPTION 25The 26.Nm wg 27driver provides Virtual Private Network (VPN) interfaces for the secure 28exchange of layer 3 traffic with other WireGuard peers using the WireGuard 29protocol. 30.Pp 31A 32.Nm wg 33interface recognises one or more peers, establishes a secure tunnel with 34each on demand, and tracks each peer's UDP endpoint for exchanging encrypted 35traffic with. 36.Pp 37The interfaces can be created at runtime using the 38.Ic ifconfig Cm wg Ns Ar N Cm create 39command or by setting up a 40.Xr hostname.if 5 41configuration file for 42.Xr netstart 8 . 43The interface itself can be configured with 44.Xr ifconfig 8 . 45.Pp 46.Nm wg 47interfaces support the following 48.Xr ioctl 2 Ns s : 49.Bl -tag -width Ds -offset indent 50.It Dv SIOCSWG Fa "struct wg_data_io *" 51Set the device configuration. 52.It Dv SIOCGWG Fa "struct wg_data_io *" 53Get the device configuration. 54.El 55.Pp 56The following glossary provides a brief overview of WireGuard 57terminology: 58.Bl -tag -width indent -offset 3n 59.It Peer 60Peers exchange IPv4 or IPv6 traffic over secure tunnels. 61Each 62.Nm wg 63interface may be configured to recognise one or more peers. 64.It Key 65Each peer uses its private key and corresponding public key to 66identify itself to others. 67A peer configures a 68.Nm wg 69interface with its own private key and with the public keys of its peers. 70.It Preshared key 71In addition to the public keys, each peer pair may be configured with a 72unique pre-shared symmetric key. 73This is used in their handshake to guard against future compromise of the 74peers' encrypted tunnel if a quantum-computational attack on their 75Diffie-Hellman exchange becomes feasible. 76It is optional, but recommended. 77.It Allowed IPs 78A single 79.Nm wg 80interface may maintain concurrent tunnels connecting diverse networks. 81The interface therefore implements rudimentary routing and reverse-path 82filtering functions for its tunneled traffic. 83These functions reference a set of allowed IP ranges configured against 84each peer. 85.Pp 86The interface will route outbound tunneled traffic to the peer configured 87with the most specific matching allowed IP address range, or drop it 88if no such match exists. 89.Pp 90The interface will accept tunneled traffic only from the peer 91configured with the most specific matching allowed IP address range 92for the incoming traffic, or drop it if no such match exists. 93That is, tunneled traffic routed to a given peer cannot return through 94another peer of the same 95.Nm wg 96interface. 97This ensures that peers cannot spoof another's traffic. 98.It Handshake 99Two peers handshake to mutually authenticate each other and to 100establish a shared series of secret ephemeral encryption keys. 101Any peer may initiate a handshake. 102Handshakes occur only when there is traffic to send, and recur every 103two minutes during transfers. 104.It Connectionless 105Due to the handshake behavior, there is no connected or disconnected 106state. 107.El 108.Ss Keys 109Private keys for WireGuard can be generated from any sufficiently 110secure random source. 111The Curve25519 keys and the preshared keys are both 32 bytes 112long and are commonly encoded in base64 for ease of use. 113.Pp 114Keys can be generated with 115.Xr openssl 1 116as follows: 117.Pp 118.Dl $ openssl rand -base64 32 119.Pp 120Although a valid Curve25519 key must have 5 bits set to 121specific values, this is done by the interface and so it 122will accept any random 32-byte base64 string. 123.Pp 124When an interface has a private key set with 125.Nm wgkey , 126the corresponding 127public key is shown in the status output of the interface: 128.Bd -literal -offset indent 129# ifconfig wg1 | grep wgpubkey 130 wgpubkey NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps= 131.Ed 132.Sh EXAMPLES 133Create two 134.Nm wg 135interfaces in separate 136.Xr rdomain 4 Ns s , 137which is of no practical use 138but demonstrates two interfaces on the same machine: 139.Bd -literal -offset indent 140#!/bin/sh 141 142# create interfaces; set random private keys 143ifconfig wg1 create wgport 7111 wgkey `openssl rand -base64 32` rdomain 1 144ifconfig wg2 create wgport 7222 wgkey `openssl rand -base64 32` rdomain 2 145 146# retrieve the public keys associated with the private keys 147PUB1="`ifconfig wg1 | grep 'wgpubkey' | cut -d ' ' -f 2`" 148PUB2="`ifconfig wg2 | grep 'wgpubkey' | cut -d ' ' -f 2`" 149 150ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 7222 wgaip 192.168.5.2/32 151ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 7111 wgaip 192.168.5.1/32 152ifconfig wg1 192.168.5.1/24 153ifconfig wg2 192.168.5.2/24 154.Ed 155.Pp 156After this, ping one interface from the other: 157.Pp 158.Dl $ route -T1 exec ping 192.168.5.2 159.Pp 160The two interfaces are able to communicate through the UDP tunnel 161which resides in the default 162.Xr rdomain 4 . 163.Pp 164Show the listening sockets: 165.Pp 166.Dl $ netstat -ln 167.Sh DIAGNOSTICS 168The 169.Nm 170interface supports runtime debugging, which can be enabled with: 171.Pp 172.D1 Ic ifconfig Cm wg Ns Ar N Cm debug 173.Pp 174Some common error messages include: 175.Bl -diag 176.It "Handshake for peer X did not complete after 5 seconds, retrying" 177Peer X did not reply to our initiation packet, for example because: 178.Bl -bullet 179.It 180The peer does not have the local interface configured as a peer. 181Peers must be able to mutually authenticate each other. 182.It 183The peer endpoint IP address is incorrectly configured. 184.It 185There are firewall rules preventing communication between hosts. 186.El 187.It "Invalid handshake initiation" 188The incoming handshake packet could not be processed. 189This is likely due to the local interface not containing 190the correct public key for the peer. 191.It "Invalid initiation MAC" 192The incoming handshake initiation packet had an invalid MAC. 193This is likely because the initiation sender has the wrong public key 194for the handshake receiver. 195.It "Packet has unallowed src IP from peer X" 196After decryption, an incoming data packet has a source IP address that 197is not assigned to the allowed IPs of Peer X. 198.El 199.Sh SEE ALSO 200.Xr inet 4 , 201.Xr ip 4 , 202.Xr netintro 4 , 203.Xr hostname.if 5 , 204.Xr pf.conf 5 , 205.Xr ifconfig 8 , 206.Xr netstart 8 207.Rs 208.%T WireGuard whitepaper 209.%U https://www.wireguard.com/papers/wireguard.pdf 210.Re 211.Sh HISTORY 212The 213.Nm 214driver first appeared in 215.Ox 6.8 . 216.Sh AUTHORS 217.An -nosplit 218The 219.Ox 220.Nm 221driver was developed by 222.An Matt Dunwoodie Aq Mt ncon@noconroy.net 223and 224.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , 225based on code written by 226.An Jason A. Donenfeld . 227