aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
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)
tree041e033f8cc2086a325c8941e836c43cb2cbad44
parentUse solock rather than NET_LOCK (diff)
downloadwireguard-openbsd-5afb0003b0b0da71bf9234c2d7da3e01eb166413.tar.xz
wireguard-openbsd-5afb0003b0b0da71bf9234c2d7da3e01eb166413.zip
Add more documentation :)
-rw-r--r--src/wg.4142
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.
.El
.Pp
+.Sh DESIGN
+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
+peers.
+.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
+peer.
+.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
+handshake.
+.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.
+.El
+.Pp
+.Sh KEYS
+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.
+.Pp
+Keys can be generated with
+.Xr openssl 1
+as such:
+.Pp
+.Dl $ openssl rand -base64 32
+.Pp
+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.
+.Pp
+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.
+.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
+.Pp
.Sh EXAMPLES
.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
.El
.Pp
-Create a
+
+
+
+The following script will create two
.Nm wg
-interface and add a remote peer at 163.172.161.0:12913.
+interfaces in separate
+.Xr rdomain 4
.Bd -literal -offset indent
-PEER_KEY="xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc="
-PEER_PSK="+lg/KzRQQk1e939wMLlYRAAIxHuVz9dQkSoaOHumUxY="
+#!/bin/sh
+
+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 10.0.0.2/32
-ifconfig wg0 wgpeer $PEER_KEY wgaip fc01::/16
-ifconfig wg0 wgpeer $PEER_KEY wgpka 25
-ifconfig wg0 wgpeer $PEER_KEY wgpip 163.172.161.0 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 127.0.0.1 22222 wgaip 192.168.5.2/24
+ifconfig wg2 wgpeer $PUB1 wgpip 127.0.0.1 11111 wgaip 192.168.5.1/24
+ifconfig wg1 192.168.5.1/24
+ifconfig wg2 192.168.5.2/24
.Ed
+.Pp
+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.
+.Pp
+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
+keys.
+.Bd -literal -offset indent
+wgport 3689
+wgkey KmDUgApHqim36Iqwyph6SE90GIZx0Hq38mz1m8kpWfg=
+
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgpsk
++lg/KzRQQk1e939wMLlYRAAIxHuVz9dQkSoaOHumUxY=
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgaip 10.0.0.2/32
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgaip fc01::/16
+wgpeer xY28FIHnumyD5ZNksGscYOD23PX27e9niZsP4gh6kBc= wgpip peer 9863
+
+up
+10.0.0.1/30
+inet6 fc01::1/16
+.Ed
+.Pp
+
+
+
+
.Sh SEE ALSO
.Xr inet 4 ,
.Xr ip 4 ,
@@ -117,10 +231,6 @@ ifconfig wg0 wgpeer $PEER_KEY wgpip 163.172.161.0 12913
.Sh AUTHORS
.An Matt Dunwoodie <ncon@noconroy.net> .
.Sh CAVEATS
-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.
-.Pp
Due to queuing in the kernel, in order to reduce packet loss, the
following command may be necessary to achieve good performance.
.Pp