Changeset View
Changeset View
Standalone View
Standalone View
share/man/man4/wg.4
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | |||||
.\" | |||||
.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org> | .\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org> | ||||
.\" | .\" | ||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
Show All 9 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" 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 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd October 28, 2022 | .Dd October 29, 2022 | ||||
.Dt WG 4 | .Dt WG 4 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm wg | .Nm wg | ||||
.Nd "WireGuard - pseudo-device" | .Nd "WireGuard - pseudo-device" | ||||
mhorne: "pseudo-device" is a little strange for the description, IMO. I would suggest: "WireGuard… | |||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
To load the driver as a module at boot time, place the following line in | To load the driver as a module at boot time, place the following line in | ||||
.Xr loader.conf 5 : | .Xr loader.conf 5 : | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
if_wg_load="YES" | if_wg_load="YES" | ||||
.Ed | .Ed | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm | .Nm | ||||
driver provides Virtual Private Network (VPN) interfaces for the secure | driver provides Virtual Private Network (VPN) interfaces for the secure | ||||
exchange of layer 3 traffic with other WireGuard peers using the WireGuard | exchange of layer 3 traffic with other WireGuard peers using the WireGuard | ||||
protocol. | protocol. | ||||
.Pp | .Pp | ||||
A | A | ||||
.Nm | .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 | each on demand, and tracks each peer's UDP endpoint for exchanging encrypted | ||||
traffic with. | traffic with. | ||||
.Pp | .Pp | ||||
The interfaces can be created at runtime using the | The interfaces can be created at runtime using the | ||||
.Ic ifconfig Cm wg Ns Ar N Cm create | .Ic ifconfig Cm wg Ns Ar N Cm create | ||||
command. | command. | ||||
The interface itself can be configured with | The interface itself can be configured with | ||||
.Xr wg 8 . | .Xr wg 8 . | ||||
Show All 11 Lines | |||||
identify itself to others. | identify itself to others. | ||||
A peer configures a | A peer configures a | ||||
.Nm | .Nm | ||||
interface with its own private key and with the public keys of its peers. | interface with its own private key and with the public keys of its peers. | ||||
.It Pre-shared key | .It Pre-shared key | ||||
In addition to the public keys, each peer pair may be configured with a | In addition to the public keys, each peer pair may be configured with a | ||||
unique pre-shared symmetric key. | unique pre-shared symmetric key. | ||||
This is used in their handshake to guard against future compromise of the | 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. | Diffie-Hellman exchange becomes feasible. | ||||
It is optional, but recommended. | It is optional, but recommended. | ||||
.It Allowed IPs | .It Allowed IP addresses | ||||
A single | A single | ||||
.Nm | .Nm | ||||
interface may maintain concurrent tunnels connecting diverse networks. | interface may maintain concurrent tunnels connecting diverse networks. | ||||
The interface therefore implements rudimentary routing and reverse-path | The interface therefore implements rudimentary routing and reverse-path | ||||
filtering functions for its tunneled traffic. | 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 | ||||
each peer. | against each peer. | ||||
.Pp | .Pp | ||||
The interface will route outbound tunneled traffic to the peer configured | The interface will route outbound tunneled traffic to the peer configured | ||||
with the most specific matching allowed IP address range, or drop it | with the most specific matching allowed IP address range, or drop it | ||||
if no such match exists. | if no such match exists. | ||||
.Pp | .Pp | ||||
The interface will accept tunneled traffic only from the peer | The interface will accept tunneled traffic only from the peer | ||||
configured with the most specific matching allowed IP address range | configured with the most specific matching allowed IP address range | ||||
for the incoming traffic, or drop it if no such match exists. | for the incoming traffic, or drop it if no such match exists. | ||||
That is, tunneled traffic routed to a given peer cannot return through | That is, tunneled traffic routed to a given peer cannot return through | ||||
another peer of the same | another peer of the same | ||||
.Nm | .Nm | ||||
interface. | interface. | ||||
This ensures that peers cannot spoof another's traffic. | This ensures that peers cannot spoof one another's traffic. | ||||
.It Handshake | .It Handshake | ||||
Two peers handshake to mutually authenticate each other and to | Two peers handshake to mutually authenticate each other and to | ||||
establish a shared series of secret ephemeral encryption keys. | 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 | Handshakes occur only when there is traffic to send, and recur every | ||||
two minutes during transfers. | two minutes during transfers. | ||||
.It Connectionless | .It Connectionless | ||||
Due to the handshake behavior, there is no connected or disconnected | Due to the handshake behavior, there is no connected or disconnected | ||||
state. | state. | ||||
.El | .El | ||||
.Ss Keys | .Ss Keys | ||||
Private keys for WireGuard can be generated from any sufficiently | Private keys for WireGuard can be generated from any sufficiently | ||||
▲ Show 20 Lines • Show All 65 Lines • ▼ Show 20 Lines | |||||
for the handshake receiver. | for the handshake receiver. | ||||
.It "Packet has unallowed src IP from peer X" | .It "Packet has unallowed src IP from peer X" | ||||
After decryption, an incoming data packet has a source IP address that | After decryption, an incoming data packet has a source IP address that | ||||
is not assigned to the allowed IPs of Peer X. | is not assigned to the allowed IPs of Peer X. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr inet 4 , | .Xr inet 4 , | ||||
.Xr ip 4 , | .Xr ip 4 , | ||||
.Xr netintro 4 , | .Xr netintro 4 , | ||||
mhorneUnsubmitted Done Inline Actions.Xr ipsec 4 , and .Xr ovpn 4 , would both make sense here too. mhorne: `.Xr ipsec 4 ,` and `.Xr ovpn 4 ,` would both make sense here too. | |||||
.Xr ipf 5 , | .Xr ipf 5 , | ||||
.Xr pf.conf 5 , | .Xr pf.conf 5 , | ||||
.Xr ifconfig 8 , | .Xr ifconfig 8 , | ||||
.Xr ipfw 8 , | .Xr ipfw 8 , | ||||
.Xr wg 8 | .Xr wg 8 | ||||
.Rs | .Rs | ||||
.%T WireGuard whitepaper | .%T WireGuard whitepaper | ||||
.%U https://www.wireguard.com/papers/wireguard.pdf | .%U https://www.wireguard.com/papers/wireguard.pdf | ||||
.Re | .Re | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
device driver first appeared in | device driver first appeared in | ||||
.Fx 14.0 . | .Fx 14.0 . | ||||
.Sh AUTHORS | .Sh AUTHORS | ||||
.An -nosplit | |||||
The | The | ||||
.Nm | .Nm | ||||
device driver written by | device driver was written by | ||||
.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , | .An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , | ||||
.An Matt Dunwoodie Aq Mt ncon@nconroy.net , | .An Matt Dunwoodie Aq Mt ncon@nconroy.net , | ||||
and | and | ||||
.An Kyle Evans Aq Mt kevans@FreeBSD.org . | .An Kyle Evans Aq Mt kevans@FreeBSD.org . | ||||
.Pp | .Pp | ||||
This manual page was written by | This manual page was written by | ||||
.An Gordon Bergling Aq Mt gbe@FreeBSD.org | .An Gordon Bergling Aq Mt gbe@FreeBSD.org | ||||
and is based on the | and is based on the | ||||
.Ox | .Ox | ||||
manual page written by | manual page written by | ||||
.An David Gwynne Aq Mt dlg@openbsd.org . | .An David Gwynne Aq Mt dlg@openbsd.org . |
"pseudo-device" is a little strange for the description, IMO. I would suggest: "WireGuard protocol", or "WireGuard protocol driver" instead.