Date: Tue, 2 Feb 2021 19:14:14 GMT From: Gordon Bergling <gbe@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: e59d9cb41284 - main - Add a wg(4) manual page Message-ID: <202102021914.112JEEqM088768@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by gbe (doc committer): URL: https://cgit.FreeBSD.org/src/commit/?id=e59d9cb412846cb5d2bc4c641d3cc44d243cd52d commit e59d9cb412846cb5d2bc4c641d3cc44d243cd52d Author: Gordon Bergling <gbe@FreeBSD.org> AuthorDate: 2021-02-02 19:13:53 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2021-02-02 19:13:53 +0000 Add a wg(4) manual page Reviewed by: brueffer, donner, debdrup, ygy MFC after: 2 days --- share/man/man4/Makefile | 1 + share/man/man4/wg.4 | 244 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+) diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 9b6ec7998fc3..4929ec9fd3f6 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -584,6 +584,7 @@ MAN= aac.4 \ vtnet.4 \ watchdog.4 \ ${_wbwd.4} \ + wg.4 \ witness.4 \ wlan.4 \ wlan_acl.4 \ diff --git a/share/man/man4/wg.4 b/share/man/man4/wg.4 new file mode 100644 index 000000000000..e343dceaa0d6 --- /dev/null +++ b/share/man/man4/wg.4 @@ -0,0 +1,244 @@ +.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org +.\" +.\" 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 February 2, 2021 +.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 +The following parameters are available: +.Bl -tag -width indent +.It Cm listen-port +The listing port of the +.Nm +interface. +.It Cm public-key +The public key of the +.Nm +interface. +.It Cm private-key +The private key of the +.Nm +interface. +.It Cm pre-shared-key +Defines a pre-shared key for the +.Nm +interface. +.It Cm allowed-ips +A list of allowed IP addresses. +.It Cm endpoint +The IP address of the WiredGuard to connect to. +.It Cm peer-list +A list of peering IP addresses to connect to. +.El +.Pp +The +.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 public-key , +the corresponding +public key is shown in the status output of the interface: +.Bd -literal -offset indent +# ifconfig wg0 | grep public-key + public-key: 7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw= +.Ed +.Sh EXAMPLES +Create a +.Nm +interface and set random private key. +.Bd -literal -offset indent +# ifconfig wg0 create listen-port 54321 private-key `openssl rand -base64 32` +.Ed +.Pp +Retrieve the associated public key from a +.Nm +interface. +.Bd -literal -offset indent +$ ifconfig wg0 | awk '/public-key/ { print $2 }'` +.Ed +.Pp +Connect to a specific endpoint using its public-key and set the allowed IP address +.Bd -literal -offset indent +# ifconfig wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100 allowed-ips 192.168.2.100/32 +.Ed +.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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202102021914.112JEEqM088768>