path: root/share/man/man4/wg.4

.\" $OpenBSD: wg.4,v 1.2 2020/06/21 15:23:59 jmc Exp $
.\" Copyright (c) 2020 Matt Dunwoodie <ncon@noconroy.net>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 21 2020 $
.Dt WG 4
.Os
.Sh NAME
.Nm wg
.Nd WireGuard pseudo-device
.Sh SYNOPSIS
.Cd "pseudo-device wg"
.Sh DESCRIPTION
The
.Nm wg
driver provides a simple Virtual Private Network (VPN) interface for
securely communicating with other WireGuard endpoints.
.Nm wg
interfaces implement the WireGuard protocol, heavily relying on the
Noise protocol framework.
.Pp
Each interface is able to connect to a number of endpoints, relying on
an internal routing table to direct outgoing IP traffic to the correct
endpoint.
Incoming traffic is also matched against this routing table
and dropped if the source does not match the corresponding output route.
.Pp
The interfaces can be created at runtime using the
.Ic ifconfig Cm wg Ns Ar N Cm create
command or by setting up a
.Xr hostname.if 5
configuration file for
.Xr netstart 8 .
The interface itself can be configured with
.Xr ifconfig 8 .
Support is also available in the
.Nm wireguard-tools
package by using the
.Nm wg
and
.Nm wg-quick
utilities.
.Pp
.Nm wg
interfaces support the following
.Xr ioctl 2 Ns s :
.Bl -tag -width Ds -offset indent
.It Dv SIOCSWG Fa "struct wg_data_io *"
Set the device configuration.
.It Dv SIOCGWG Fa "struct wg_data_io *"
Get the device configuration.
.El
.Ss Design
WireGuard is designed as a small, secure, easy to use VPN.
It operates at the IP level, supporting both IPv4 and IPv6.
.Pp
The following list provides a brief overview of WireGuard terminology:
.Bl -tag -width indent -offset 3n
.It Peer
A peer is a host that the interface creates a connection with.
There is no concept of client/server as both ends of the connection
are equal.
An interface may have multiple peers.
.It Key
Each interface has a private key and corresponding public key.
The public key is used to identify the interface to other peers.
.It Preshared key
In addition to the interface keys, each peer pair can have a
unique preshared key.
This key is used in the handshake to provide post-quantum security.
It is optional, but recommended.
.It Allowed IPs
Allowed IPs dictate the tunneled IP addresses each peer is allowed to
send from.
After decryption, all packets have their source IP address
checked against the sending peer's allowed IPs list.
This list is hierarchical, allowing peers to have overlapping ranges,
with the most specific range taking precedence.
They can be thought of like a routing
table, as outgoing packets are also matched against this list to
determine which peer to send to.
.Pp
This does not correspond to the IP address that UDP
packets are sent to or received from, but rather the IP addresses that
are encapsulated in the tunnel.
.It Handshake
In order to establish a set of shared secret keys, two peers perform a
handshake.
This occurs every 2 minutes while traffic is being sent.
If no traffic is being sent, then no handshake occurs.
When traffic resumes, a new handshake is performed.
Each handshake generates a new
set of ephemeral keys to provide forward secrecy.
.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 preshared 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
Note that not all 32-byte strings are valid Curve25519 keys.
Specific bits must be set in the string.
All the same, a random 32-byte string can be passed because
the interface automatically sets the required bits.
This does not apply to the preshared key.
.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, like so:
.Bd -literal -offset indent
wgkey (pub) NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps=
.Ed
.Sh EXAMPLES
Create two
.Nm wg
interfaces in separate
.Xr rdomain 4 Ns s ,
which is of no practical use
but demonstrates two interfaces on the same machine:
.Bd -literal
#!/bin/sh

ifconfig wg1 create wgport 111 wgkey `openssl rand -base64 32` rdomain 1
ifconfig wg2 create wgport 222 wgkey `openssl rand -base64 32` rdomain 2

PUB1="`ifconfig wg1 | grep 'wgkey (pub)' | cut -d ' ' -f 3`"
PUB2="`ifconfig wg2 | grep 'wgkey (pub)' | cut -d ' ' -f 3`"

ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 222 wgaip 192.168.5.2/32
ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 111 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
which resides in the default
.Xr rdomain 4 .
.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 hostname.if 5 ,
.Xr pf.conf 5 ,
.Xr ifconfig 8 ,
.Xr netstart 8 ,
.Xr wg 8 ,
.Xr wg-quick 8
.Rs
.%T WireGuard whitepaper
.%U https://www.wireguard.com/papers/wireguard.pdf
.Re
.Sh AUTHORS
.An -nosplit
The
.Ox
.Nm
driver was developed by
.An Matt Dunwoodie Aq Mt ncon@noconroy.net
and
.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com ,
based on code written by
.An Jason A. Donenfeld.