| wg.4 (744bfb213144c63cbaf38d91a1c4f7aebb9b9fbc) | wg.4 (19c03f4ab0d68788a561b91278fd13c760227a31) |
|---|---|
| 1.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 2.\" |
|
| 1.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright --- 9 unchanged lines hidden (view full) --- 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" | 3.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright --- 9 unchanged lines hidden (view full) --- 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" |
| 26.Dd October 28, 2022 | 28.Dd October 30, 2022 |
| 27.Dt WG 4 28.Os 29.Sh NAME 30.Nm wg | 29.Dt WG 4 30.Os 31.Sh NAME 32.Nm wg |
| 31.Nd "WireGuard - pseudo-device" | 33.Nd "WireGuard protocol driver" |
| 32.Sh SYNOPSIS 33To load the driver as a module at boot time, place the following line in 34.Xr loader.conf 5 : 35.Bd -literal -offset indent 36if_wg_load="YES" 37.Ed 38.Sh DESCRIPTION 39The 40.Nm 41driver provides Virtual Private Network (VPN) interfaces for the secure 42exchange of layer 3 traffic with other WireGuard peers using the WireGuard 43protocol. 44.Pp 45A 46.Nm | 34.Sh SYNOPSIS 35To load the driver as a module at boot time, place the following line in 36.Xr loader.conf 5 : 37.Bd -literal -offset indent 38if_wg_load="YES" 39.Ed 40.Sh DESCRIPTION 41The 42.Nm 43driver provides Virtual Private Network (VPN) interfaces for the secure 44exchange of layer 3 traffic with other WireGuard peers using the WireGuard 45protocol. 46.Pp 47A 48.Nm |
| 47interface recognises one or more peers, establishes a secure tunnel with | 49interface recognizes one or more peers, establishes a secure tunnel with |
| 48each on demand, and tracks each peer's UDP endpoint for exchanging encrypted 49traffic with. 50.Pp 51The interfaces can be created at runtime using the 52.Ic ifconfig Cm wg Ns Ar N Cm create 53command. 54The interface itself can be configured with 55.Xr wg 8 . --- 11 unchanged lines hidden (view full) --- 67identify itself to others. 68A peer configures a 69.Nm 70interface with its own private key and with the public keys of its peers. 71.It Pre-shared key 72In addition to the public keys, each peer pair may be configured with a 73unique pre-shared symmetric key. 74This is used in their handshake to guard against future compromise of the | 50each on demand, and tracks each peer's UDP endpoint for exchanging encrypted 51traffic with. 52.Pp 53The interfaces can be created at runtime using the 54.Ic ifconfig Cm wg Ns Ar N Cm create 55command. 56The interface itself can be configured with 57.Xr wg 8 . --- 11 unchanged lines hidden (view full) --- 69identify itself to others. 70A peer configures a 71.Nm 72interface with its own private key and with the public keys of its peers. 73.It Pre-shared key 74In addition to the public keys, each peer pair may be configured with a 75unique pre-shared symmetric key. 76This is used in their handshake to guard against future compromise of the |
| 75peers' encrypted tunnel if a quantum-computational attack on their | 77peers' encrypted tunnel if an attack on their |
| 76Diffie-Hellman exchange becomes feasible. 77It is optional, but recommended. | 78Diffie-Hellman exchange becomes feasible. 79It is optional, but recommended. |
| 78.It Allowed IPs | 80.It Allowed IP addresses |
| 79A single 80.Nm 81interface may maintain concurrent tunnels connecting diverse networks. 82The interface therefore implements rudimentary routing and reverse-path 83filtering functions for its tunneled traffic. | 81A single 82.Nm 83interface may maintain concurrent tunnels connecting diverse networks. 84The interface therefore implements rudimentary routing and reverse-path 85filtering functions for its tunneled traffic. |
| 84These functions reference a set of allowed IP ranges configured against 85each peer. | 86These functions reference a set of allowed IP address ranges configured 87against each peer. |
| 86.Pp 87The interface will route outbound tunneled traffic to the peer configured 88with the most specific matching allowed IP address range, or drop it 89if no such match exists. 90.Pp 91The interface will accept tunneled traffic only from the peer 92configured with the most specific matching allowed IP address range 93for the incoming traffic, or drop it if no such match exists. 94That is, tunneled traffic routed to a given peer cannot return through 95another peer of the same 96.Nm 97interface. | 88.Pp 89The interface will route outbound tunneled traffic to the peer configured 90with the most specific matching allowed IP address range, or drop it 91if no such match exists. 92.Pp 93The interface will accept tunneled traffic only from the peer 94configured with the most specific matching allowed IP address range 95for the incoming traffic, or drop it if no such match exists. 96That is, tunneled traffic routed to a given peer cannot return through 97another peer of the same 98.Nm 99interface. |
| 98This ensures that peers cannot spoof another's traffic. | 100This ensures that peers cannot spoof one another's traffic. |
| 99.It Handshake 100Two peers handshake to mutually authenticate each other and to 101establish a shared series of secret ephemeral encryption keys. | 101.It Handshake 102Two peers handshake to mutually authenticate each other and to 103establish a shared series of secret ephemeral encryption keys. |
| 102Any peer may initiate a handshake. | 104Either peer may initiate a handshake. |
| 103Handshakes occur only when there is traffic to send, and recur every 104two minutes during transfers. 105.It Connectionless 106Due to the handshake behavior, there is no connected or disconnected 107state. 108.El 109.Ss Keys 110Private keys for WireGuard can be generated from any sufficiently --- 65 unchanged lines hidden (view full) --- 176for the handshake receiver. 177.It "Packet has unallowed src IP from peer X" 178After decryption, an incoming data packet has a source IP address that 179is not assigned to the allowed IPs of Peer X. 180.El 181.Sh SEE ALSO 182.Xr inet 4 , 183.Xr ip 4 , | 105Handshakes occur only when there is traffic to send, and recur every 106two minutes during transfers. 107.It Connectionless 108Due to the handshake behavior, there is no connected or disconnected 109state. 110.El 111.Ss Keys 112Private keys for WireGuard can be generated from any sufficiently --- 65 unchanged lines hidden (view full) --- 178for the handshake receiver. 179.It "Packet has unallowed src IP from peer X" 180After decryption, an incoming data packet has a source IP address that 181is not assigned to the allowed IPs of Peer X. 182.El 183.Sh SEE ALSO 184.Xr inet 4 , 185.Xr ip 4 , |
| 186.Xr ipsec 4 , |
|
| 184.Xr netintro 4 , | 187.Xr netintro 4 , |
| 188.Xr ovpn 4 , |
|
| 185.Xr ipf 5 , 186.Xr pf.conf 5 , 187.Xr ifconfig 8 , 188.Xr ipfw 8 , 189.Xr wg 8 190.Rs 191.%T WireGuard whitepaper 192.%U https://www.wireguard.com/papers/wireguard.pdf 193.Re 194.Sh HISTORY 195The 196.Nm 197device driver first appeared in 198.Fx 14.0 . 199.Sh AUTHORS | 189.Xr ipf 5 , 190.Xr pf.conf 5 , 191.Xr ifconfig 8 , 192.Xr ipfw 8 , 193.Xr wg 8 194.Rs 195.%T WireGuard whitepaper 196.%U https://www.wireguard.com/papers/wireguard.pdf 197.Re 198.Sh HISTORY 199The 200.Nm 201device driver first appeared in 202.Fx 14.0 . 203.Sh AUTHORS |
| 204.An -nosplit |
|
| 200The 201.Nm | 205The 206.Nm |
| 202device driver written by | 207device driver was written by |
| 203.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , 204.An Matt Dunwoodie Aq Mt ncon@nconroy.net , 205and 206.An Kyle Evans Aq Mt kevans@FreeBSD.org . 207.Pp 208This manual page was written by 209.An Gordon Bergling Aq Mt gbe@FreeBSD.org 210and is based on the 211.Ox 212manual page written by 213.An David Gwynne Aq Mt dlg@openbsd.org . | 208.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , 209.An Matt Dunwoodie Aq Mt ncon@nconroy.net , 210and 211.An Kyle Evans Aq Mt kevans@FreeBSD.org . 212.Pp 213This manual page was written by 214.An Gordon Bergling Aq Mt gbe@FreeBSD.org 215and is based on the 216.Ox 217manual page written by 218.An David Gwynne Aq Mt dlg@openbsd.org . |