Differential D36909 Diff 112349 share/man/man4/wg.4

Changeset View

Standalone View

share/man/man4/wg.4

This file was added.

.\"

pauamma_chezdork.comUnsubmitted

Not Done

Unless I missed something, this matches the text at https://spdx.org/licenses/BSD-2-Clause.html, except that you wrote "author" instead of "copyright holders" but don't mention who the author is, only the copyright holder. (Not being an IP lawyer, I don't know what difference it makes.) If you meant (or decide to change to) "copyright holders", perhaps add

.\" SPDX-License-Identifier: BSD-2-Clause

at the top?

pauamma_chezdork.com: Unless I missed something, this matches the text at https://spdx.org/licenses/BSD-2-Clause.html…

jhbAuthorUnsubmitted

Done

This is the old manpage from before it was removed with only minor edits to reflect the use of wg(8) instead of ifconfig(8). For this commit restoring the oldmanpage is the goal. Subsequent edits to the manpage should be done as followup changes, not as part of this change to revert its removal.

It's also not mine to relicense and it would not be legal for me to change it without permission, that would be up to the copyright holder. We also do not require SPDX license tags.

jhb: This is the old manpage from before it was removed with only minor edits to reflect the use of…

.\" 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 October 28, 2022

.Dt WG 4

pauamma_chezdork.comUnsubmitted

Not Done

Bump.

pauamma_chezdork.com: Bump.

.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

.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

pauamma_chezdork.comUnsubmitted

Not Done

.Pp

.Nm

- interface recognises one or more peers, establishes a secure tunnel with

+ interface recognizes one or more peers, establishes a secure tunnel with

each on demand, and tracks each peer's UDP endpoint for exchanging encrypted

US spelling

pauamma_chezdork.com: US spelling

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 wg 8 .

.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.

pauamma_chezdork.comUnsubmitted

Not Done

This is used in their handshake to guard against future compromise of the

- peers' encrypted tunnel if a quantum-computational attack on their

+ peers' encrypted tunnel if an attack on their

Diffie-Hellman exchange becomes feasible.

There was a recent report in Schneier on Security of a supposedly quantum-resistant protocol being vulnerable to a classical attack, so I wouldn't limit it.

pauamma_chezdork.com: There was a recent report in Schneier on Security of a supposedly quantum-resistant protocol…

It is optional, but recommended.

.It Allowed IPs

A single

pauamma_chezdork.comUnsubmitted

Not Done

It is optional, but recommended.

- .It Allowed IPs

+ .It Allowed IP addresses

A single

pauamma_chezdork.com:

.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.

pauamma_chezdork.comUnsubmitted

Not Done

filtering functions for its tunneled traffic.

- These functions reference a set of allowed IP ranges configured against

+ These functions reference a set of allowed IP address ranges configured against

each peer.

pauamma_chezdork.com:

.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

pauamma_chezdork.comUnsubmitted

Not Done

interface.

- This ensures that peers cannot spoof another's traffic.

+ This ensures that peers cannot spoof one another's traffic.

.It Handshake

pauamma_chezdork.com:

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

pauamma_chezdork.comUnsubmitted

Not Done

establish a shared series of secret ephemeral encryption keys.

- Any peer may initiate a handshake.

+ Either peer may initiate a handshake.

Handshakes occur only when there is traffic to send, and recur every

pauamma_chezdork.com:

two minutes during transfers.

.It Connectionless

Due to the handshake behavior, there is no connected or disconnected

state.

.El

pauamma_chezdork.comUnsubmitted

Not Done

I don't understand what you're trying to say here. Do you mean that because handshaking happens automatically whenever there's traffic to send, there's no need for explicit requests to establish or dismantle peer connections? If so, I'd make it more explicit.

pauamma_chezdork.com: I don't understand what you're trying to say here. Do you mean that because handshaking happens…

.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 wg 8

as follows:

.Pp

.Dl $ wg genkey

.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.

.Sh EXAMPLES

Create a

.Nm

interface and set random private key.

.Bd -literal -offset indent

# ifconfig wg0 create

# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin

.Ed

.Pp

Retrieve the associated public key from a

.Nm

interface.

.Bd -literal -offset indent

$ wg show wg0 public-key

.Ed

.Pp

Connect to a specific endpoint using its public-key and set the allowed IP address

.Bd -literal -offset indent

# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32

.Ed

pauamma_chezdork.comUnsubmitted

Not Done

Worth adding an IPv6 example?

pauamma_chezdork.com: Worth adding an IPv6 example?

.Pp

Remove a peer

.Bd -literal -offset indent

# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove

.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

pauamma_chezdork.comUnsubmitted

Not Done

I'd remove either "mutually" or "each other", leaning toward removing "mutually".

pauamma_chezdork.com: I'd remove either "mutually" or "each other", leaning toward removing "mutually".

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 ,

.Xr wg 8

.Rs

.%T WireGuard whitepaper

.%U https://www.wireguard.com/papers/wireguard.pdf

.Re

.Sh HISTORY

The

.Nm

device driver first appeared in

.Fx 14.0 .

.Sh AUTHORS

pauamma_chezdork.comUnsubmitted

Not Done

Will the manual page get MFC'd? If not, I'd mention it's 14-only.

pauamma_chezdork.com: Will the manual page get MFC'd? If not, I'd mention it's 14-only.

jhbAuthorUnsubmitted

Done

It will get merged, but this part probably should be adjusted to be 14.0 for now.

jhb: It will get merged, but this part probably should be adjusted to be 14.0 for now.

The

.Nm

device driver written by

.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com ,

pauamma_chezdork.comUnsubmitted

Not Done

.Sh AUTHORS

The

.Nm

- device driver written by

+ device driver was written by

.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com ,

pauamma_chezdork.com:

.An Matt Dunwoodie Aq Mt ncon@nconroy.net ,

and

.An Kyle Evans Aq Mt kevans@FreeBSD.org .

.Pp

This manual page was written by

.An Gordon Bergling Aq Mt gbe@FreeBSD.org

and is based on the

.Ox

manual page written by

.An David Gwynne Aq Mt dlg@openbsd.org .