Sorry, this should have also included, Differential Revision: https://reviews.freebsd.org/D27783
--Gordon On Tue, Feb 02, 2021 at 07:14:14PM +0000, Gordon Bergling wrote: > The branch main has been updated by gbe (doc committer): > > URL: > https://cgit.FreeBSD.org/src/commit/?id=e59d9cb412846cb5d2bc4c641d3cc44d243cd52d > > commit e59d9cb412846cb5d2bc4c641d3cc44d243cd52d > Author: Gordon Bergling <g...@freebsd.org> > AuthorDate: 2021-02-02 19:13:53 +0000 > Commit: Gordon Bergling <g...@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 <g...@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 g...@freebsd.org > +and is based on the > +.Ox > +counterpart written by > +.An David Gwynne Aq Mt d...@openbsd.org . > _______________________________________________ > dev-commits-src-main@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/dev-commits-src-main > To unsubscribe, send any mail to > "dev-commits-src-main-unsubscr...@freebsd.org" -- _______________________________________________ dev-commits-src-main@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/dev-commits-src-main To unsubscribe, send any mail to "dev-commits-src-main-unsubscr...@freebsd.org"
