share/man/man4/wg.4

   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 March 7, 2021
  27 .Dt WG 4
  28 .Os
  29 .Sh NAME
  30 .Nm wg
  31 .Nd "WireGuard - pseudo-device"
  32 .Sh SYNOPSIS
  33 To load the driver as a module at boot time, place the following line in
  34 .Xr loader.conf 5 :
  35 .Bd -literal -offset indent
  36 if_wg_load="YES"
  37 .Ed
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver provides Virtual Private Network (VPN) interfaces for the secure
  42 exchange of layer 3 traffic with other WireGuard peers using the WireGuard
  43 protocol.
  44 .Pp
  45 A
  46 .Nm
  47 interface recognises one or more peers, establishes a secure tunnel with
  48 each on demand, and tracks each peer's UDP endpoint for exchanging encrypted
  49 traffic with.
  50 .Pp
  51 The interfaces can be created at runtime using the
  52 .Ic ifconfig Cm wg Ns Ar N Cm create
  53 command.
  54 The interface itself can be configured with
  55 .Xr ifconfig 8 .
  56 .Pp
  57 The following parameters are available:
  58 .Bl -tag -width indent
  59 .It Cm listen-port
  60 The listing port of the
  61 .Nm
  62 interface.
  63 .It Cm public-key
  64 The public key of the
  65 .Nm
  66 interface.
  67 .It Cm private-key
  68 The private key of the
  69 .Nm
  70 interface.
  71 .It Cm pre-shared-key
  72 Defines a pre-shared key for the
  73 .Nm
  74 interface.
  75 .It Cm allowed-ips
  76 A list of allowed IP addresses.
  77 .It Cm endpoint
  78 The IP address of the WiredGuard to connect to.
  79 .It Cm peer-list
  80 A list of peering IP addresses to connect to.
  81 .El
  82 .Pp
  83 The
  84 .Nm
  85 interfaces 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 *"
  89 Set the device configuration.
  90 .It Dv SIOCGWG Fa "struct wg_device_io *"
  91 Get the device configuration.
  92 .El
  93 .Pp
  94 The following glossary provides a brief overview of WireGuard
  95 terminology:
  96 .Bl -tag -width indent -offset 3n
  97 .It Peer
  98 Peers exchange IPv4 or IPv6 traffic over secure tunnels.
  99 Each
 100 .Nm
 101 interface may be configured to recognise one or more peers.
 102 .It Key
 103 Each peer uses its private key and corresponding public key to
 104 identify itself to others.
 105 A peer configures a
 106 .Nm
 107 interface with its own private key and with the public keys of its peers.
 108 .It Pre-shared key
 109 In addition to the public keys, each peer pair may be configured with a
 110 unique pre-shared symmetric key.
 111 This is used in their handshake to guard against future compromise of the
 112 peers' encrypted tunnel if a quantum-computational attack on their
 113 Diffie-Hellman exchange becomes feasible.
 114 It is optional, but recommended.
 115 .It Allowed IPs
 116 A single
 117 .Nm
 118 interface may maintain concurrent tunnels connecting diverse networks.
 119 The interface therefore implements rudimentary routing and reverse-path
 120 filtering functions for its tunneled traffic.
 121 These functions reference a set of allowed IP ranges configured against
 122 each peer.
 123 .Pp
 124 The interface will route outbound tunneled traffic to the peer configured
 125 with the most specific matching allowed IP address range, or drop it
 126 if no such match exists.
 127 .Pp
 128 The interface will accept tunneled traffic only from the peer
 129 configured with the most specific matching allowed IP address range
 130 for the incoming traffic, or drop it if no such match exists.
 131 That is, tunneled traffic routed to a given peer cannot return through
 132 another peer of the same
 133 .Nm
 134 interface.
 135 This ensures that peers cannot spoof another's traffic.
 136 .It Handshake
 137 Two peers handshake to mutually authenticate each other and to
 138 establish a shared series of secret ephemeral encryption keys.
 139 Any peer may initiate a handshake.
 140 Handshakes occur only when there is traffic to send, and recur every
 141 two minutes during transfers.
 142 .It Connectionless
 143 Due to the handshake behavior, there is no connected or disconnected
 144 state.
 145 .El
 146 .Ss Keys
 147 Private keys for WireGuard can be generated from any sufficiently
 148 secure random source.
 149 The Curve25519 keys and the pre-shared keys are both 32 bytes
 150 long and are commonly encoded in base64 for ease of use.
 151 .Pp
 152 Keys can be generated with
 153 .Xr openssl 1
 154 as follows:
 155 .Pp
 156 .Dl $ openssl rand -base64 32
 157 .Pp
 158 Although a valid Curve25519 key must have 5 bits set to
 159 specific values, this is done by the interface and so it
 160 will accept any random 32-byte base64 string.
 161 .Pp
 162 When an interface has a private key set with
 163 .Nm public-key ,
 164 the corresponding
 165 public 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
 171 Create a
 172 .Nm
 173 interface 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
 178 Retrieve the associated public key from a
 179 .Nm
 180 interface.
 181 .Bd -literal -offset indent
 182 $ ifconfig wg0 | awk '/public-key/ { print $2 }'`
 183 .Ed
 184 .Pp
 185 Connect to a specific endpoint using its public-key and set the allowed IP address
 186 .Bd -literal -offset indent
 187 # ifconfig wg0 peer public-key '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32
 188 .Ed
 189 .Sh DIAGNOSTICS
 190 The
 191 .Nm
 192 interface supports runtime debugging, which can be enabled with:
 193 .Pp
 194 .D1 Ic ifconfig Cm wg Ns Ar N Cm debug
 195 .Pp
 196 Some common error messages include:
 197 .Bl -diag
 198 .It "Handshake for peer X did not complete after 5 seconds, retrying"
 199 Peer X did not reply to our initiation packet, for example because:
 200 .Bl -bullet
 201 .It
 202 The peer does not have the local interface configured as a peer.
 203 Peers must be able to mutually authenticate each other.
 204 .It
 205 The peer endpoint IP address is incorrectly configured.
 206 .It
 207 There are firewall rules preventing communication between hosts.
 208 .El
 209 .It "Invalid handshake initiation"
 210 The incoming handshake packet could not be processed.
 211 This is likely due to the local interface not containing
 212 the correct public key for the peer.
 213 .It "Invalid initiation MAC"
 214 The incoming handshake initiation packet had an invalid MAC.
 215 This is likely because the initiation sender has the wrong public key
 216 for the handshake receiver.
 217 .It "Packet has unallowed src IP from peer X"
 218 After decryption, an incoming data packet has a source IP address that
 219 is 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
 234 The
 235 .Nm
 236 device driver first appeared in
 237 .Fx 13.0 .
 238 .Sh AUTHORS
 239 The
 240 .Nm
 241 device driver was originally written for
 242 .Ox
 243 by
 244 .An Matt Dunwoodie Aq Mt ncon@nconroy.net
 245 and ported to
 246 .Fx
 247 by
 248 .An Matt Macy Aq Mt mmacy@FreeBSD.org .
 249 .Pp
 250 This manual page was written by
 251 .An Gordon Bergling Aq Mt gbe@FreeBSD.org
 252 and is based on the
 253 .Ox
 254 manual page written by
 255 .An David Gwynne Aq Mt dlg@openbsd.org .