Index: share/man/man4/Makefile =================================================================== --- share/man/man4/Makefile +++ share/man/man4/Makefile @@ -570,6 +570,7 @@ ${_vtnet.4} \ watchdog.4 \ ${_wbwd.4} \ + wg.4 \ wi.4 \ witness.4 \ wlan.4 \ Index: share/man/man4/wg.4 =================================================================== --- /dev/null +++ share/man/man4/wg.4 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2020 Gordon Bergling +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 27, 2020 +.Dt WG 4 +.Os +.Sh NAME +.Nm wg +.Nd "WireGuard - pseudo-device" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_wg_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides Virtual Private Network (VPN) interfaces for the secure +exchange of layer 3 traffic with other WireGuard peers using the WireGuard +protocol. +.Pp +A +.Nm +interface recognises one or more peers, establishes a secure tunnel with +each on demand, and tracks each peer's UDP endpoint for exchanging encrypted +traffic with. +.Pp +The interfaces can be created at runtime using the +.Ic ifconfig Cm wg Ns Ar N Cm create +command. +The interface itself can be configured with +.Xr ifconfig 8 . +.Pp +.Nm +interfaces support the following +.Xr ioctl 2 Ns s : +.Bl -tag -width Ds -offset indent +.It Dv SIOCSWG Fa "struct wg_device_io *" +Set the device configuration. +.It Dv SIOCGWG Fa "struct wg_device_io *" +Get the device configuration. +.El +.Pp +The following glossary provides a brief overview of WireGuard +terminology: +.Bl -tag -width indent -offset 3n +.It Peer +Peers exchange IPv4 or IPv6 traffic over secure tunnels. +Each +.Nm +interface may be configured to recognise one or more peers. +.It Key +Each peer uses its private key and corresponding public key to +identify itself to others. +A peer configures a +.Nm +interface with its own private key and with the public keys of its peers. +.It Pre-shared key +In addition to the public keys, each peer pair may be configured with a +unique pre-shared symmetric key. +This is used in their handshake to guard against future compromise of the +peers' encrypted tunnel if a quantum-computational attack on their +Diffie-Hellman exchange becomes feasible. +It is optional, but recommended. +.It Allowed IPs +A single +.Nm +interface may maintain concurrent tunnels connecting diverse networks. +The interface therefore implements rudimentary routing and reverse-path +filtering functions for its tunneled traffic. +These functions reference a set of allowed IP ranges configured against +each peer. +.Pp +The interface will route outbound tunneled traffic to the peer configured +with the most specific matching allowed IP address range, or drop it +if no such match exists. +.Pp +The interface will accept tunneled traffic only from the peer +configured with the most specific matching allowed IP address range +for the incoming traffic, or drop it if no such match exists. +That is, tunneled traffic routed to a given peer cannot return through +another peer of the same +.Nm +interface. +This ensures that peers cannot spoof another's traffic. +.It Handshake +Two peers handshake to mutually authenticate each other and to +establish a shared series of secret ephemeral encryption keys. +Any peer may initiate a handshake. +Handshakes occur only when there is traffic to send, and recur every +two minutes during transfers. +.It Connectionless +Due to the handshake behavior, there is no connected or disconnected +state. +.El +.Ss Keys +Private keys for WireGuard can be generated from any sufficiently +secure random source. +The Curve25519 keys and the pre-shared keys are both 32 bytes +long and are commonly encoded in base64 for ease of use. +.Pp +Keys can be generated with +.Xr openssl 1 +as follows: +.Pp +.Dl $ openssl rand -base64 32 +.Pp +Although a valid Curve25519 key must have 5 bits set to +specific values, this is done by the interface and so it +will accept any random 32-byte base64 string. +.Pp +When an interface has a private key set with +.Nm wgkey , +the corresponding +public key is shown in the status output of the interface: +.Bd -literal -offset indent +# ifconfig wg1 | grep wgpubkey + wgpubkey NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps= +.Ed +.Sh EXAMPLES +Create two +.Nm +interfaces in separate +.Xr rdomain 4 Ns s , +which is of no practical use +but demonstrates two interfaces on the same machine: +.Bd -literal -offset indent +#!/bin/sh + +# create interfaces; set random private keys +ifconfig wg1 create wgport 7111 wgkey `openssl rand -base64 32` rdomain 1 +ifconfig wg2 create wgport 7222 wgkey `openssl rand -base64 32` rdomain 2 + +# retrieve the public keys associated with the private keys +PUB1="`ifconfig wg1 | grep 'wgpubkey' | cut -d ' ' -f 2`" +PUB2="`ifconfig wg2 | grep 'wgpubkey' | cut -d ' ' -f 2`" + +ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 7222 wgaip 192.168.5.2/32 +ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 7111 wgaip 192.168.5.1/32 +ifconfig wg1 192.168.5.1/24 +ifconfig wg2 192.168.5.2/24 +.Ed +.Pp +After this, ping one interface from the other: +.Pp +.Dl $ route -T1 exec ping 192.168.5.2 +.Pp +The two interfaces are able to communicate through the UDP tunnel. +.Pp +Show the listening sockets: +.Pp +.Dl $ netstat -ln +.Sh DIAGNOSTICS +The +.Nm +interface supports runtime debugging, which can be enabled with: +.Pp +.D1 Ic ifconfig Cm wg Ns Ar N Cm debug +.Pp +Some common error messages include: +.Bl -diag +.It "Handshake for peer X did not complete after 5 seconds, retrying" +Peer X did not reply to our initiation packet, for example because: +.Bl -bullet +.It +The peer does not have the local interface configured as a peer. +Peers must be able to mutually authenticate each other. +.It +The peer endpoint IP address is incorrectly configured. +.It +There are firewall rules preventing communication between hosts. +.El +.It "Invalid handshake initiation" +The incoming handshake packet could not be processed. +This is likely due to the local interface not containing +the correct public key for the peer. +.It "Invalid initiation MAC" +The incoming handshake initiation packet had an invalid MAC. +This is likely because the initiation sender has the wrong public key +for the handshake receiver. +.It "Packet has unallowed src IP from peer X" +After decryption, an incoming data packet has a source IP address that +is not assigned to the allowed IPs of Peer X. +.El +.Sh SEE ALSO +.Xr inet 4 , +.Xr ip 4 , +.Xr netintro 4 , +.Xr ipf 5 , +.Xr pf.conf 5 , +.Xr ifconfig 8 , +.Xr ipfw 8 +.Rs +.%T WireGuard whitepaper +.%U https://www.wireguard.com/papers/wireguard.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org +and is based on the +.Ox +counterpart written by +.An David Gwynne Aq Mt dlg@openbsd.org .