wireguard.md - www.codemadness.org - www.codemadness.org saait content files
HTML git clone git://git.codemadness.org/www.codemadness.org
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
wireguard.md (8280B)
---
1 Wireguard is a fast, modern and secure VPN tunnel.
2
3 Below is a guide to setup [Wireguard](https://www.wireguard.com/) on the OpenBSD
4 operating system intended for use as a mobile VPN.
5
6 It describes using the OpenBSD Wireguard wg(4) kernel driver using ifconfig,
7 not the userland application, and will focus on setting up a IPv4 tunnel.
8
9 It is however recommended to install wireguard-tools, because it contains
10 useful tools to generate a private and public key (wg genkey, wg pubkey).
11
12 To install the wireguard-tools package on OpenBSD:
13
14 # pkg_add wireguard-tools
15
16
17 ## Enable IPv4 traffic forwarding
18
19 To enable traffic forwarding for IPv4 run:
20
21 # sysctl net.inet.ip.forwarding=1
22
23 To make it persistent add the above lines to the file /etc/sysctl.conf. These
24 sysctl lines are loaded on boot time.
25
26
27 ## Server config: /etc/hostname.wg0
28
29 This is an example config for the wg0 network interface. It is stored at
30 /etc/hostname.wg0:
31
32 wgport 51820 wgkey 'private_key_here'
33 inet 10.1.2.1/24
34 up
35
36 # peer: phone
37 wgpeer 'pubkey' wgaip 10.1.2.2/32 wgdescr 'phone' wgpsk 'psk_here'
38
39
40 ## Generating a private key
41
42 Using wireguard-tools wg command:
43
44 $ wg genkey
45
46 Replace private\_key\_here with the generated text.
47
48 To generate both a private and public key to the files private.key and
49 public.key:
50
51 $ wg genkey | tee private.key | wg pubkey > public.key
52
53 **!!! Keep the private key secure. Do not share it with anyone!!!**
54
55
56 ## Generate a separate preshared key (PSK).
57
58 Using a preshared key (PSK) is optional, but recommended. This is used in the
59 handshake to guard against future compromise of the peers' encrypted tunnel if
60 a quantum-computational attack on their Diffie-Hellman exchange becomes
61 feasible.
62
63 Using wireguard-tools wg command:
64
65 $ wg genpsk
66
67 The PSK can be shared with a known client when configuring the clients. **Make sure
68 to share it via a safe channel**.
69
70 To configure or restart the wg0 interface using the configuration in
71 /etc/hostname.wg0:
72
73 # sh /etc/netstart wg0
74
75 To show general info of the interface run the command (requires root
76 permissions to view all information):
77
78 # ifconfig wg0
79
80 In the ifconfig wg0 output it should list the server public key as:
81
82 wgpubkey server_pubkey_here
83
84
85 ## Full example of a client config: wg-client.conf
86
87 [Interface]
88 Address = 10.1.2.2/32
89 DNS = 10.1.2.1
90 PrivateKey = CHBzstIHCi7+YOOa2MN0RXhkPAmJwIXQW0e6/n6+Pno=
91
92 [Peer]
93 AllowedIPs = 0.0.0.0/0
94 Endpoint = example.org:51820
95 PreSharedKey = 8ao/EMExyPAHrT3ShX+lnA0u7jUmo7MhrT0GjDcrIJA=
96 PublicKey = Rny+AW4EPqPPxfO+8O+QdlkIrWbZRGQ6u6Fje5pUOFM=
97
98 **Of course do not copy-paste this private key and PSK. Generate your own ;)**
99
100
101 ## pf(4) firewall rules
102
103 Below is a fragment of the firewall rules required for Wireguard.
104 These rules assume a simple VPS with a vio network interface connected to the
105 interwebs (no double NAT or other weird complex things ;)).
106
107 pf.conf:
108
109 # wireguard
110 pass out quick on egress inet from (wg0:network) nat-to (vio0:0)
111 pass in quick on wg0 from any to any
112 pass in quick on wg0 proto udp from any to any port 51820
113 # allow all on wireguard
114 pass quick on wg0
115
116
117 ## Mobile VPN application
118
119 For Android download the APK from <https://www.wireguard.com/install/>.
120 There are also other versions available on the page.
121
122 ## Android Wireguard settings
123
124 ## Adding a tunnel
125
126 In the Wireguard application press the plus (+) button in the bottom left of
127 the screen to add a tunnel.
128
129
130 ## Option: "Scan from QR code"
131
132 ### Generate a QR code image from a client config
133
134 Install the libqrencode package for the qrencode program:
135
136 # pkg_add libqrencode
137
138 Generate a QR code PNG image from a client config:
139
140 $ qrencode -o qr.png < wg-client.conf
141
142 This QR code simply contains the full text from the wg-client.conf. It can be
143 scanned from the Android Wireguard application. If it contains sensitive
144 information such as the private key make sure to share the image in a safe way
145 and/or destroy it immediately.
146
147 
148
149 If the QR code contains a private key, make sure to destroy it "Inspector Gadget"-style.
150
151 
152
153 [Inspector Gadget, self-destruct video clip](https://codemadness.org/downloads/openbsd-wg/inspector_gadget.webm)
154
155 Now scan the generated image to import the config.
156
157
158 ### Option: "Import from file or archive"
159
160 Import a text .conf file or archive (ZIP) file containing one or more configs.
161
162 Example conf file: [client-example.conf](https://codemadness.org/downloads/openbsd-wg/client-example.conf).
163 Example ZIP file: [client-example.zip](https://codemadness.org/downloads/openbsd-wg/client-example.zip).
164
165
166 ### Option: "Create from scratch"
167
168 Generating the private key on the device itself and sharing the **public** key
169 and PSK is probably the safest option. Although sharing the public key text
170 from a mobile device can be a bit annoying.
171
172
173 ## Android settings
174
175 Only allow connections and DNS using VPN:
176
177 * Settings -> VPN -> Network & Internet:
178 Make sure Wireguard is set and enabled under VPN.
179
180 VPN settings, open Wireguard cogwheel:
181 * Enable: Always on VPN option, with the description: "Stay connected to VPN at all times".
182 * Enable: Block connections without VPN.
183
184 Other recommendations:
185
186 * Under Wi-Fi -> Privacy.
187 * Use randomized MAC.
188 * Disable "Send device name".
189 * Set a secure and privacy-respecting DNS server.
190
191
192 ## Wireguard persistent keepalive setting
193
194 If the interface very rarely sends traffic, but it might at anytime receive
195 traffic from a peer, and it is behind NAT, the interface might benefit from
196 having a persistent keepalive interval of 25 seconds.
197
198 If it is not needed, then it is recommended to not enable it, which is the
199 default.
200
201 This option is called PersistentKeepalive in Wireguard conf and is called
202 wgpka for OpenBSD ifconfig, see the ifconfig(8) man page WIREGUARD section.
203
204
205 ## Debugging tips
206
207 For the Wireguard Android application you can find a textual log:
208
209 * Open the Wireguard application.
210 * At the top right select the 3 dots settings thingy.
211 * Select the menu labeled "View application log".
212
213 On the OpenBSD server you can run enable run-time debugging on the wg0 interface:
214
215 # ifconfig wg0 debug
216
217
218 ## Bonus: example using wg-quick from wg-tools
219
220 Using the wg-quick program from wg-tools you can also quickly setup a client.
221 This will setup the DNS, routing and interface. It can setup and restore the
222 DNS and routing settings easily.
223
224 As root, to setup the interface:
225
226 # wg-quick up absolute/path/to/config/wg-client.conf
227
228 As root, to restore the interface:
229
230 # wg-quick down absolute/path/to/config/wg-client.conf
231
232
233 ## Bonus: generating a private key using only OpenSSL commands
234
235 Generate a private key:
236
237 $ openssl genpkey -algorithm X25519 -outform DER -out private.der
238
239 Now extract the last 32 bytes which has part of the actual private key (the
240 first ASN.1 DER encoded bytes contain metadata information). Convert the actual
241 key data to base64.
242
243 Run:
244
245 $ tail -c 32 private.der | openssl enc -a -A > private.key
246
247 Derive public key:
248
249 $ openssl pkey -inform DER -in private.der -pubout -outform DER -out public.der
250
251 Convert public key to Wireguard format:
252
253 $ tail -c 32 public.der | openssl enc -a -A > public.key
254
255 Or even the magical voodoo commands:
256
257 $ openssl rand -base64 32 > private.key
258 $ (printf '\060\056\002\001\000\060\005\006\003\053\145\156\004\042\004\040';openssl enc -d -a -A < private.key) | \
259 openssl pkey -inform DER -pubout -outform DER | \
260 tail -c 32 | \
261 openssl enc -a -A > public.key
262
263
264 ## References
265
266 * [Wireguard](https://www.wireguard.com/):
267 * [Wireguard quickstart page](https://www.wireguard.com/quickstart/):
268 This uses the userland Wireguard programs and config. But it contains
269 helpful information.
270 * [wg(8) man page](https://www.man7.org/linux/man-pages/man8/wg.8.html).
271 * [wg-quick(8) man page](https://www.man7.org/linux/man-pages/man8/wg-quick.8.html).
272 * [OpenBSD operating system](https://www.openbsd.org/):
273 * [wg(4) driver man page](https://man.openbsd.org/wg).
274 * [ifconfig(8) man page WIREGUARD section](https://man.openbsd.org/ifconfig.8#WIREGUARD).
275 * [pf.conf(5) file format](https://man.openbsd.org/pf.conf.5).