diff options
authorMatt Dunwoodie <ncon@mail.noconroy.net>2019-09-22 19:43:28 +0200
committerMatt Dunwoodie <ncon@mail.noconroy.net>2019-09-22 21:03:53 +0200
commit5afb0003b0b0da71bf9234c2d7da3e01eb166413 (patch)
parentUse solock rather than NET_LOCK (diff)
Add more documentation :)
1 files changed, 126 insertions, 16 deletions
diff --git a/src/wg.4 b/src/wg.4
index 49587a0..6750d93 100644
--- a/src/wg.4
+++ b/src/wg.4
@@ -70,6 +70,75 @@ Delete allowed IP from peer.
Clear all allowed IPs from peer.
+WireGuard is designed as a small, easy to use VPN. Some features may be
+foreign to new users, however the concepts are not difficult.
+The following items highlight the purpose of WireGuard specific features:
+.Bl -tag -width indent -offset 3n
+.It Peer
+A peer is a host that the interface creates a connection with. It is
+identified by a 32 byte public key. There is no concept of client/server
+as both ends of the connection are equal. An interface may have multiple
+.It Allowed-IPs
+Allowed-IPs dictate which IP addresses each peer is responsible for.
+Thus, they form a routing table for outgoing packets and are necessary
+to have multple peers per interface. Incoming packets are also matched
+against this routing table, to verify they originate from the correct
+.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 Connection
+Due to the handshake behavior, there is no connected/disconnected state.
+Thus WireGuard is considered "connection-less".
+.It Key
+Each interface has a static private key. This key is used to perform
+Curve25519 operations which is an asymmetric crypto algorithm.
+The corresponding public key is used
+to identify the local interface to other peers. The key is used in the
+.It Preshared-Key
+In addition to the Curve25519 interface keys, each peer can have a
+unique static preshared key. The preshared key is also used in the
+handshake in order to mitigate the post-quantum weakness of Curve25519.
+The forward secrecy property of the handshake is defeated in a
+post-quantum world without a preshared key.
+A peer with no set preshared key will just use an empty, all 0's key.
+Keys for WireGuard can be generated from any sufficient secure random
+source. The Curve25519 keys and preshared keys are both 32 bytes long
+and are commonly encoded in base64 for ease of use.
+Keys can be generated with
+.Xr openssl 1
+as such:
+.Dl $ openssl rand -base64 32
+It should be noted that not all 32 byte strings are valid Curve25519
+keys. The key must be an element of a finite set, which is achieved by
+setting specific bits in the string. The interface will perform this for
+you, so you may just pass a 32 byte random string. This does not apply
+to the preshared key.
+It goes without saying that these keys must be kept private. Also, the
+root user is able to retrieve these keys from a running interface.
+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=
.Xr ifconfig 8
supports a number of directives, (*) indicates wgpeer must be set:
@@ -83,23 +152,68 @@ supports a number of directives, (*) indicates wgpeer must be set:
.It Dv *wgpka - set peer persistent keepalive
-Create a
+The following script will create two
.Nm wg
-interface and add a remote peer at
+interfaces in separate
+.Xr rdomain 4
.Bd -literal -offset indent
+KEY1="`openssl rand -base64 32`"
+KEY2="`openssl rand -base64 32`"
-ifconfig wg0 create
-ifconfig wg0 wgport 3689
-ifconfig wg0 wgkey KmDUgApHqim36Iqwyph6SE90GIZx0Hq38mz1m8kpWfg=
+ifconfig wg1 create
+ifconfig wg1 wgport 11111 wgkey $KEY1 rdomain 1
-ifconfig wg0 wgpeer $PEER_KEY wgpsk $PEER_PSK
-ifconfig wg0 wgpeer $PEER_KEY wgaip
-ifconfig wg0 wgpeer $PEER_KEY wgaip fc01::/16
-ifconfig wg0 wgpeer $PEER_KEY wgpka 25
-ifconfig wg0 wgpeer $PEER_KEY wgpip 12913
+ifconfig wg2 create
+ifconfig wg2 wgport 22222 wgkey $KEY2 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 wgpip 22222 wgaip
+ifconfig wg2 wgpeer $PUB1 wgpip 11111 wgaip
+ifconfig wg1
+ifconfig wg2
+The two interfaces are able to communicate over the UDP tunnel which
+resides in
+.Xr rdomain 4
+by default. This example carries no practical use apart from
+demonstrating two interfaces on the same machine.
+The most common use-case is to connect two separate hosts over a
+network. Keys must be generated and distributed manually over a secure
+channel such as
+.Xr ssh 1
+or out-of-band. A regular
+.Xr hostname.if 5
+file can be used to configure the interface. The following values are an
+example. It goes without saying that you should generate your own unique
+.Bd -literal -offset indent
+wgport 3689
+wgkey KmDUgApHqim36Iqwyph6SE90GIZx0Hq38mz1m8kpWfg=
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgpsk
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgaip
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgaip fc01::/16
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgpip peer 9863
+inet6 fc01::1/16
.Xr inet 4 ,
.Xr ip 4 ,
@@ -117,10 +231,6 @@ ifconfig wg0 wgpeer $PEER_KEY wgpip 12913
.An Matt Dunwoodie <ncon@noconroy.net> .
-There is currently no rate limiting on handshake packets. While the
-WireGuard cookie implementation ties initiation and response packets to
-remote IPs, there is no limitation on incoming rates.
Due to queuing in the kernel, in order to reduce packet loss, the
following command may be necessary to achieve good performance.