Hi Matt, thanks for doing all this work. Note that i cannot provide feedback on the code or concepts, and also note that when the code is ready, a developer can commit it even if there are still issues to sort out with the documentation. We do value good documentation, but the exact point in time when it is polished matters little.
All the same, i looked through the wg(4) manual page and improved a few details. Please apply the following patch to what you sent. In addition to my changes, this line must be fixed before commit: .\" Copyright? Please just use the normal /usr/share/misc/license.template with the commenting method adjusted from C to roff(7) comments. If you wrote all the manual page text from scratch, use your own name and year(s). If it is a derivative work based on the work of others, retain the original Copyright and license and add your own name and date(s) if your changes are significant enough. I feel somewhat concerned that you recommend the openssl(1) command for production use. As far as i understand, the LibreSSL developers consider openssl(1) as a low-quality program purely intended for testing purposes that should not be used for production. But that does not need to be addressed now, it can be improved later. When providing exactly one example, it isn't ideal that that example doesn't actually do anything practically useful. Again, that's not a critical problem and can be improved later. Theo is right that .Ek and .nr nS are slightly awkward in manual pages, but they are still somewhat widespread in particular in driver and kernel manuals, so they wouldn't be a serious problem. However, the whole section containing them is useless in the first place, so the issue just vanishes with no additional effort. Rationale for my changes: * Add the missing $OpenBSD$ tag. * New sentence, new line. * Minor macro improvements. * At a few places, purge phrases that say nothing. * A few minor wording improvements. * Delete the DIRECTIVES section: it contains no new information and ifconfig(8) was already referenced prominently above. * Use the standard section name DIAGNOSTICS. To keep each mail small and focussed, i decided to not talk about the ifconfig(8) manual page in the same message. Yours, Ingo --- wg.4.matt Tue May 12 16:06:34 2020 +++ wg.4 Tue May 12 17:20:18 2020 @@ -1,3 +1,4 @@ +.\" $OpenBSD$ .\" Copyright? .Dd $Mdocdate: Feb 14 2020 $ .Dt WG 4 @@ -18,18 +19,18 @@ .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 +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 wg Ns Ar N Ic create +.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 ; -see it's manual page for more information. +.Xr ifconfig 8 . Support is also available in the .Nm wireguard-tools package by using the @@ -41,70 +42,75 @@ .Nm wg interfaces support the following .Xr ioctl 2 Ns s : -.Bl -tag -width indent -offset 3n +.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 -.Sh DESIGN -WireGuard is designed as a small, secure, easy to use VPN. It operates at IP -level, supporting both IPv4, IPv6. - -The following items give a brief overview of WireGuard features: +.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. +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 +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, however 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 +unique preshared key. +This key is used in the handshake to provide post-quantum security. +It is optional, however 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 -To make it clear, this does not correspond to the IP address that UDP +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 +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-less +.It Connectionless Due to the handshake behavior, there is no connected or disconnected -state. Thus WireGuard is considered "connection-less". +state. .El -.Sh KEYS -Keys for WireGuard can be generated from any sufficiently secure random -source. The Curve25519 keys and the preshared keys are both 32 bytes +.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 such: +as follows: .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. +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 string can be passed because +the interface automatically sets the required bits. +This does not apply to the preshared key. .Pp -It goes without saying that these keys must be kept private. -.Pp When an interface has a private key set with .Nm wgkey , the corresponding @@ -112,37 +118,14 @@ .Bd -literal -offset indent wgkey (pub) NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps= .Ed -.Sh DIRECTIVES -.Xr ifconfig 8 -supports a number of directives and can be summarised with: -.Pp -.Bd -filled -offset indent -.Bk -words -.Nm ifconfig -.Ar wg-interface -.Op Cm wgkey Ar privatekey -.Op Cm wgport Ar port -.Op Cm wgrtable Ar rtable -.Oo Oo Fl Oc Ns Cm wgpeer Ar publickey -.Op Cm wgpsk Ar presharedkey -.Op Fl wgpsk -.Op Cm wgpka Ar persistent-keepalive -.Op Cm wgpip Ar ip port -.Op Cm wgaip Ar allowed-ip/prefix -.Op Fl wgaipall Oc -.Op Fl wgpeerall -.Op Cm wgconf -.Ek -.Ed -.Pp -For further detail, please see -.Xr ifconfig 8 . .Sh EXAMPLES -The following script will create two +Create two .Nm wg interfaces in separate -.Xr rdomain 4 -.Bd -literal -offset indent +.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 @@ -157,61 +140,56 @@ ifconfig wg2 192.168.5.2/24 .Ed .Pp -After this, it should be possible to ping one interface from the other, -as such. +After this, ping one interface from the other: .Bd -literal -offset indent route -T1 exec ping 192.168.5.2 .Ed .Pp -The two interfaces are able to communicate over the UDP tunnel which -resides in the default +The two interfaces are able to communicate through the UDP tunnel +which resides in the default .Xr rdomain 4 . -This example carries no practical use apart from demonstrating two -interfaces on the same machine. You can see the listening sockets with -.Xr netstat 1 . +.Pp +Show the listening sockets: .Bd -literal -offset indent netstat -ln .Ed -.Sh TROUBLESHOOTING -.Pp +.Sh DIAGNOSTICS The .Nm interface supports runtime debugging, which can be enabled with: -.Bd -literal -offset indent -ifconfig wgN debug -.Ed .Pp -Some common error messages you may face are detailed below: -.Bl -tag -width indent -offset 3n +.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. This may be caused by -but not limited to the following: +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 mutally authenticate each other. +The peer does not have the local interface configured as a peer. +Peers must be able to mutally authenticate each other. .It The peer endpoint IP address is incorrectly configured. .It -There are firewall rules preventing communication between hosts +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. +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. +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" -An incoming data packet, after decryption has a source IP address that -is not assigned to Peer X's allowed-ips. +After decryption, an incoming data packet has a source IP address that +is not assigned to the allowed IPs of Peer X. .El .Pp -Addtionally, if you attempt to bring up the interface and it does not -appear to be working, More specifically the IFF_RUNNING flag is not set -on the interface, then check that no other services or daemons are -running on the chosen +If the +.Dv IFF_RUNNING +flag is not set on an interface after an attempt to bring it up, +check that no other services or daemons are running on the chosen .Nm port. .Sh SEE ALSO @@ -229,4 +207,11 @@ .%U https://www.wireguard.com/papers/wireguard.pdf .Re .Sh AUTHORS -.An Matt Dunwoodie <n...@noconroy.net> . +.An -nosplit +The +.Ox +.Nm +driver was developed by +.An Matt Dunwoodie Aq Mt n...@noconroy.net +based on code written by +.An Jason A. Donenfeld Aq Mt ja...@zx2c4.com .
