git: e59d9cb41284 - main - Add a wg(4) manual page

Tue Feb 2 19:22:41 UTC 2021

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 <gbe at FreeBSD.org>
> AuthorDate: 2021-02-02 19:13:53 +0000
> Commit:     Gordon Bergling <gbe at 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 at 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 at FreeBSD.org
> +and is based on the
> +.Ox
> +counterpart written by
> +.An David Gwynne Aq Mt dlg at openbsd.org .
> _______________________________________________
> dev-commits-src-main at freebsd.org mailing list
> https://lists.freebsd.org/mailman/listinfo/dev-commits-src-main
> To unsubscribe, send any mail to "dev-commits-src-main-unsubscribe at freebsd.org"

-- 