DEV Community: Miguel

Getting Started with WireGuard

Miguel — Sun, 05 Apr 2020 20:07:41 +0000

WireGuard is a relatively new VPN tunnel protocol that aims to be very fast and easy to setup. It follows the Unix Philosophy closely in that it only does one thing (creating secured VPN tunnels) and does it well.

If you've ever set up an VPN service such as OpenVPN before then you know that it can get complicated because of all the steps you have to go through such as generating certificate authorities, issuing server and client keys and certificates, setting up multiple configuration files, configuring firewall rules, setting up route traffic forwarding, etc. which can either be dreadful or daunting. WireGuard is changing all that by simplifying the process of getting up and running in no time and allowing for easy configuration to connect multiple clients (peers).

Why use WireGuard?

A VPN helps protect you from man in the middle attacks.
Protect your privacy against ISPs that snoop into your traffic.
Get around internet censorship in countries.

Advantages of WireGuard over other VPNs:

It's kernel-based; improved performance.
Establishes connections in less than 100ms.
Small footprint; can be ran in virtually any device, ie. embedded devices.
Easy to configure and deploy as SSH; reduces attack surface since there's less complexity.
Uses modern and improved cryptographic standards.
Simple handshake occurring every few minutes to ensure connection secrecy.
IP roaming support meaning you can change wifi networks or disconnect from wifi or celluar and the VPN tunnel connection won't be lost. It just works!

What we'll be going over

This post assumes that you've never installed a VPN service before and we'll be using an Ubuntu machine since it's the most popular distro.

This post is pretty verbose! but you can skip to the TLDR; to see the final scripts and configuration files used if you're familiar with the concepts already.

The steps outlined in this post are:

Setting up a server
Installing WireGuard on server
Generating server keys
Creating server configuration file
Enabling IP forwarding on server
Installing WireGuard on client
Generating client keys
Creating client configuration file
Setting client info on server config
Starting WireGuard service on server
Starting WireGuard service on client
Connecting a mobile client to server

Please note that in WireGuard land there is no "server" and "client" in the traditional sense. Rather, computers and devices connected to each other are known as "peers". For simplicity sake, we'll be using "server" to mean the hosted server that will be forwarding all our traffic to, and we'll be using "client" to refer to the home computer that forwards all it's traffic to the server.

Setting up a server

I'll be using a free tier EC2 micro instance from AWS for the example (and tearing down it afterwards). If you have an AWS account you can launch a new instance by going to:

EC2 → Launch Instance → t2.micro with Ubuntu → Review and Launch → Launch

In this example I'm running Ubuntu 18.04 (Bionic Beaver).

Installing WireGuard on server

To install wireguard on Ubuntu <19.04 run the following comands:

sudo add-apt-repository ppa:wireguard/wireguard
sudo apt-get update
sudo apt-get install wireguard

If your server is using a different distro then look at the WireGuard installation instructions.

ubuntu@ip-172-30-0-233:~$ sudo add-apt-repository ppa:wireguard/wireguard
 WireGuard is a novel VPN that runs inside the Linux Kernel. This is the Ubuntu packaging for WireGuard. More info may be found at its website, listed below.

More info: https://www.wireguard.com/
Packages: wireguard wireguard-tools wireguard-dkms

Install with: $ apt install wireguard
 More info: https://launchpad.net/~wireguard/+archive/ubuntu/wireguard
Press [ENTER] to continue or Ctrl-c to cancel adding it.

<truncated>

Fetched 18.5 MB in 4s (4840 kB/s)

ubuntu@ip-172-30-0-233:~$ sudo apt-get update
Hit:1 http://us-east-1.ec2.archive.ubuntu.com/ubuntu bionic InRelease
Hit:2 http://us-east-1.ec2.archive.ubuntu.com/ubuntu bionic-updates InRelease
Hit:3 http://us-east-1.ec2.archive.ubuntu.com/ubuntu bionic-backports InRelease
Hit:4 http://security.ubuntu.com/ubuntu bionic-security InRelease
Hit:5 http://ppa.launchpad.net/wireguard/wireguard/ubuntu bionic InRelease
Reading package lists... Done

ubuntu@ip-172-30-0-233:~$ sudo apt-get install wireguard
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:

<truncated>

update-alternatives: using /usr/bin/g++ to provide /usr/bin/c++ (c++) in auto mode
Setting up build-essential (12.4ubuntu1) ...
Setting up wireguard-dkms (1.0.20200401-1ubuntu1~18.04) ...
Loading new wireguard-1.0.20200401 DKMS files...
Building for 4.15.0-1057-aws
Building initial module for 4.15.0-1057-aws
Done.

wireguard:
Running module version sanity check.
 - Original module
   - No original module exists within this kernel
 - Installation
   - Installing to /lib/modules/4.15.0-1057-aws/updates/dkms/

depmod...

DKMS: install completed.
Setting up wireguard (1.0.20200319-0ppa1~18.04) ...
Processing triggers for libc-bin (2.27-3ubuntu1) ...
Processing triggers for man-db (2.8.3-2ubuntu0.1) ...

Let's launch a shell as root with sudo -s to avoid having to type sudo every time from now on:

ubuntu@ip-172-30-0-233:~$ sudo -s
root@ip-172-30-0-233:~#

Run wg to check if installation was successful which should not output anything if everything is OK:

root@ip-172-30-0-233:/etc/wireguard/keys# wg
root@ip-172-30-0-233:/etc/wireguard/keys#

The two WireGuard commands we'll be using are:

wg for configuring WireGuard interfaces.
wg-quick for starting and stopping WireGuard VPN tunnels.

Generating server keys

WireGuard configuration files will live under /etc/wireguard/ so let's create a directory named keys there to store the keys we'll generate:

root@ip-172-30-0-233:~# mkdir /etc/wireguard/keys

Go into the /etc/wireguard/keys/ directory:

root@ip-172-30-0-233:~# cd /etc/wireguard/keys

Set the directory user mask to 077 by running umask 077. A umask of 077 allows read, write, and execute permissions for the file's owner (root in this case), but prohibits read, write, and execute permissions for everyone else and makes sure credentials don't leak in a race condition:

root@ip-172-30-0-233:/etc/wireguard/keys# umask 077

WireGuard uses asymmetric public/private Curve25519 key pairs for authentication between client and server.

Use the wg genkey command to generate a private key. We can generate both the private and public key at once by piping the private key output to tee to save it to file but also to forward the private key to wg publickey which derived the public key from a private key and the save it to a file.

So the command to run is wg genkey | tee privatekey | wg pubkey > publickey to generate the key pair at once:

root@ip-172-30-0-233:/etc/wireguard/keys# wg genkey | tee privatekey | wg pubkey > publickey

If we do an ls we see there's a privatekey and publickey file:

root@ip-172-30-0-233:/etc/wireguard/keys# ls
privatekey  publickey

Outputting the contents of the private key file shows us the random key it generated in base64 format:

root@ip-172-30-0-233:/etc/wireguard/keys# cat privatekey
wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=

Likewise the public key it derived from the private key is in base64 format:

root@ip-172-30-0-233:/etc/wireguard/keys# cat publickey
H6StMJOYIjfqhDvG9v46DSX9UlQl52hOoUm7F3COxC4=

We'll be needing the private key for the WireGuard server configuration, and the public key for the client configuration.

Creating server configuration file

Go into the /etc/wireguard/ directory and create a new file wg0.conf. WireGuard will create a new network interface named the same as the filename so it's common convention to denote the first WireGuard network interface as wg0 for context:

root@ip-172-30-0-233:/etc/wireguard# touch /etc/wireguard/wg0.conf

Open up the server configuration file /etc/wireguard/wg0.conf in your favorite editor:

root@ip-172-30-0-233:/etc/wireguard# vim /etc/wireguard/wg0.conf

Paste the following configuration into the new config file:

[Interface]
PrivateKey = <server private key>
Address = 10.0.0.1/24
ListenPort = 51820

The config files are in standard INI format.

Replace the PrivateKey value with the private key content you generated earlier:

[Interface]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
Address = 10.0.0.1/24
ListenPort = 51820

The address 10.0.0.1 was chosen because it's an available private subnet on the server. If your server is using that IP range already, then pick a different address like 192.168.2.1 to avoid conflicts.

To summarize, the server [Interface] section is for configuration the new WireGuard interface we are creating.

PrivateKey is your server's private key.
Address is the private network IP address range that we're assigning to for this network interface.
ListenPort is the host port to run the service on. This port will need to be publicly accessible. The port 51820 is the default port.

Make sure to enable the port 51820 for UDP traffic. If using EC2 then you should allow it under the Security Group for the EC2 instance.

EC2 instance → Security groups → Click on security group → Edit inbound rules → Add rules → Custom UDP → Port range: 51820 → Source: Anywhere → Save rules

The rules immediately take effect.

If your server is behind a NAT then all traffic needs to be forwarded from the default interface to the WireGuard interface.

To find out the name of the default interface run ip route:

root@ip-172-30-0-233:/etc/wireguard/keys# ip route | grep default | awk '{print $5}'
eth0

Now add forwarding rules for forwarding in the server configuration file using the PostUp and PostDown config settings where PostUp value command is ran when the WireGuard service starts and PostDown value command runs when the service is shutting down.

[Interface]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

The three iptable rules are:

iptables -A FORWARD -i %i -j ACCEPT for allowing inbound traffic received by the interface.
iptables -A FORWARD -o %i -j ACCEPT for allowing outbound traffic from the interface.
iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE for masking the private IP address of the interface with the external IP address of the default interface.

Enabling IP forwarding on server

By default IP forwarding is disabled meaning that if the interface receives a packet that wasn't intended for it then it'll reject it. Since we need to pass on packets from one interface to another then we need to allow IP forwarding.

Open up the file /etc/sysctl.conf for editing:

root@ip-172-30-0-233:/etc/wireguard# vim /etc/sysctl.conf

Allow forwarding of IP packets by uncommenting out the line net.ipv4.ip_forward=1 near line 28:

# Uncomment the next line to enable packet forwarding for IPv4
net.ipv4.ip_forward=1

Run sysctl -p for the changes to take effect without requiring a reboot:

root@ip-172-30-0-233:/etc/wireguard# sysctl -p
net.ipv4.ip_forward = 1

Confirm that IP forwarding is enabled by outputting the contents of /proc/sys/net/ipv4/ip_forward which should return 1:

root@ip-172-30-0-233:/etc/wireguard# cat /proc/sys/net/ipv4/ip_forward
1

The server is almost fully configured. It's only now missing information about the client so let's set up the client next.

Installing WireGuard on client

Jump back to your client machine and install WireGuard. My client machine is running Arch linux but the process will be the same for most linux distros. If you're running Ubuntu on the client then do the same install steps you did on the server above or look at the official WireGuard installation instructions.

Ubuntu WireGuard install instructions:

$ sudo add-apt-repository ppa:wireguard/wireguard
$ sudo apt-get update
$ sudo apt-get install wireguard

If running Arch like I am, then these are the WireGuard install instructions:

$ sudo pacman -S wireguard-tools wireguard-dkms

Let's launch a shell as root with sudo -s to avoid having to type sudo every time from now on:

$ sudo -s
[root@archlinux ~]#

Generating client keys

The process of generating WireGuard keys on the client is the same as how it's done on the server. Create the directory /etc/wireguard/keys and set the user mask to 077.

[root@archlinux ~]# mkdir /etc/wireguard/keys
[root@archlinux ~]# cd /etc/wireguard/keys
[root@archlinux keys]# umask 077

Generate a private and public key pair for the client using the same command as we did on the server:

[root@archlinux keys]# wg genkey | tee privatekey | wg pubkey > publickey

Output the key contents which we'll be needing soon in our configuration files:

[root@archlinux keys]# cat privatekey
cAqmevIKScn5l4Jg1F69KEIty6gVb8wGNqNlApvzc0c=
[root@archlinux keys]# cat publickey
vi4TCAo8TNRkpf4ZpiMsp3YHaOLrcouSDkrm4wJxezw=

Creating client configuration file

On the client create the configuration /etc/wireguard/wg0.conf:

[root@archlinux keys]# vim /etc/wireguard/wg0.conf

Paste the configuration into your client configuration file:

[Interface]
Address = 10.0.0.2/32
PrivateKey = <client private key>

Replace the PrivateKey value with your client's private key:

[Interface]
Address = 10.0.0.2/32
PrivateKey = cAqmevIKScn5l4Jg1F69KEIty6gVb8wGNqNlApvzc0c=

Optionally, you can set the DNS resolver to use. We'll set the DNS resolver IP to Cloudflare's public DNS resolver 1.1.1.1 which is fast and secure:

[Interface]
Address = 10.0.0.2/32
PrivateKey = cAqmevIKScn5l4Jg1F69KEIty6gVb8wGNqNlApvzc0c=
DNS = 1.1.1.1

To summarize, the client [Interface] section is for configuration the new WireGuard interface we are creating.

Address is the private network IP address range that we're assigning to for this network interface.
PrivateKey is your client's private key.
DNS is the DNS resolve to use.

Setting server peer on client config

The next step is to set information about the server in the client configuration file under the [Peer] section:

[Interface]
Address = 10.0.0.2/32
PrivateKey = cAqmevIKScn5l4Jg1F69KEIty6gVb8wGNqNlApvzc0c=
DNS = 1.1.1.1

[Peer]
PublicKey = <server public key>
Endpoint = <server public ip>:51820
AllowedIPs = 0.0.0.0/0

Replace the PublicKey value to your server's public key and set the Endpoint to be your server's public IP address:

[Interface]
Address = 10.0.0.2/32
PrivateKey = cAqmevIKScn5l4Jg1F69KEIty6gVb8wGNqNlApvzc0c=
DNS = 1.1.1.1

[Peer]
PublicKey = H6StMJOYIjfqhDvG9v46DSX9UlQl52hOoUm7F3COxC4=
Endpoint = 54.225.123.18:51820
AllowedIPs = 0.0.0.0/0

If your server is behind a NAT and not accessible via a public IP, then under the peer section you'll need to set PersistentKeepalive to keep the connection alive. It's important that you only set PersistentKeepalive if your server in an internal server, otherwise you'd be wasting bandwidth and battery life for no good reason.

PersistentKeepalive = 25

To summarize, the client [Peer] section is for configuration information about the peer it's connecting to, which in this case it's the client connection to the server.

PublicKey is the public key of the server.
Endpoint is your server's public IP and port the server's interface is listening, configured with ListenPort in the server's config.
AllowedIPs is the IP range to allow forwarding from. Setting it to 0.0.0.0/0 will forward all traffic over the tunnel.
PersistentKeepalive is the interval to periodically send keepalive packets to the server.

If you're not sure what your server's public address is, you can do an IP lookup by doing a DNS query request to myip.opendns.com:

root@ip-172-30-0-233:/etc/wireguard# dig +short myip.opendns.com @resolver1.opendns.com
54.225.123.18

If your server is an EC2 instance, you get query the metadata endpoint to get the public IP address:

root@ip-172-30-0-233:/etc/wireguard# curl http://169.254.169.254/latest/meta-data/public-ipv4
54.225.123.18

Setting client peer on server config

Go back into the server and edit the config. We're going to add information about the client so that the server and client can authenticate with each other.

root@ip-172-30-0-233:/etc/wireguard/keys# vim /etc/wireguard/wg0.conf

Add the [Peer] section to the server config:

[Interface]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = <client public key>
AllowedIPs = 10.0.0.2/32

Replace the PublicKey value with your client's public key:

[Interface]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = vi4TCAo8TNRkpf4ZpiMsp3YHaOLrcouSDkrm4wJxezw=
AllowedIPs = 10.0.0.2/32

To summarize, the server [Peer] section is for configuration information about the peer it's connecting to, which in this case it's the servers connection to the client.

PublicKey is the client's public key.
AllowedIPs are allowed client IP addresses.

Starting WireGuard service on server

Now that the server has the client peer information we can start the WireGuard service with wg-quick up wg0 on the server:

root@ip-172-30-0-233:/etc/wireguard/keys# wg-quick up wg0
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.0.0.1/24 dev wg0
[#] ip link set mtu 8921 up dev wg0
[#] iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

To start WireGuard across reboots you'll need to enable the service to add it to the systemd init system by running systemctl enable wg-quick@wg0.service:

root@ip-172-30-0-233:/etc/wireguard/keys# systemctl enable wg-quick@wg0.service
Created symlink /etc/systemd/system/multi-user.target.wants/wg-quick@wg0.service → /lib/systemd/system/wg-quick@.service.

Check the status by running systemctl status wg-quick@wg0.service and if you see Active: active (exited) then if everything is good so far:

root@ip-172-30-0-233:/etc/wireguard/keys# systemctl status wg-quick@wg0.service
● wg-quick@wg0.service - WireGuard via wg-quick(8) for wg0
   Loaded: loaded (/lib/systemd/system/wg-quick@.service; indirect; vendor preset: enabled)
   Active: active (exited) since Thu 2020-04-02 06:35:22 UTC; 1s ago
     Docs: man:wg-quick(8)
           man:wg(8)
           https://www.wireguard.com/
           https://www.wireguard.com/quickstart/
           https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8
           https://git.zx2c4.com/wireguard-tools/about/src/man/wg.8
  Process: 10730 ExecStart=/usr/bin/wg-quick up wg0 (code=exited, status=0/SUCCESS)
 Main PID: 10730 (code=exited, status=0/SUCCESS)

Apr 02 06:35:21 ip-172-30-0-233 systemd[1]: Starting WireGuard via wg-quick(8) for wg0...
Apr 02 06:35:22 ip-172-30-0-233 wg-quick[10730]: [#] ip link add wg0 type wireguard
Apr 02 06:35:22 ip-172-30-0-233 wg-quick[10730]: [#] wg setconf wg0 /dev/fd/63
Apr 02 06:35:22 ip-172-30-0-233 wg-quick[10730]: [#] ip -4 address add 10.0.0.1/24 dev wg0
Apr 02 06:35:22 ip-172-30-0-233 wg-quick[10730]: [#] ip link set mtu 8921 up dev wg0
Apr 02 06:35:22 ip-172-30-0-233 wg-quick[10730]: [#] iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; ipt
Apr 02 06:35:22 ip-172-30-0-233 systemd[1]: Started WireGuard via wg-quick(8) for wg0.

Verify that new iproute rules have been applied with iptables -L -n:

root@ip-172-30-0-233:/etc/wireguard# iptables -L -n
Chain INPUT (policy ACCEPT)
target     prot opt source               destination

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination
ACCEPT     all  --  0.0.0.0/0            0.0.0.0/0
ACCEPT     all  --  0.0.0.0/0            0.0.0.0/0

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination

Running the command ifconfig shows the new network interface wg0 with the internal IP address we specified 10.0.0.1:

root@ip-172-30-0-233:/etc/wireguard# ifconfig
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 9001
        inet 172.30.0.233  netmask 255.255.255.0  broadcast 172.30.0.255
        inet6 fe80::1097:5bff:fe30:d57  prefixlen 64  scopeid 0x20<link>
        ether 12:97:5b:30:0d:57  txqueuelen 1000  (Ethernet)
        RX packets 1151269  bytes 524679242 (524.6 MB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 1022229  bytes 345390292 (345.3 MB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
        inet 127.0.0.1  netmask 255.0.0.0
        inet6 ::1  prefixlen 128  scopeid 0x10<host>
        loop  txqueuelen 1000  (Local Loopback)
        RX packets 526  bytes 48787 (48.7 KB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 526  bytes 48787 (48.7 KB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

wg0: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 8921
        inet 10.0.0.1  netmask 255.255.255.0  destination 10.0.0.1
        unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 1000  (UNSPEC)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 0  bytes 0 (0.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Starting WireGuard service on client

First take note of your current public IP address on the client machine:

[root@archlinux wireguard]# dig +short myip.opendns.com @resolver1.opendns.com
65.88.88.4

After we start the WireGuard service on the client then the public IP address will be resolved to the server's public IP address.

Start the WireGuard service using wg-quick just like we did previously on the server:

[root@archlinux wireguard]# wg-quick up wg0

Now that WireGuard is running, check the public IP address again of the client and it should now be the public IP address of the server:

[root@archlinux wireguard]# dig +short myip.opendns.com @resolver1.opendns.com
54.225.123.18

Success! WireGuard is correctly configured and the peers are connected.

Connecting a mobile client to server

Download the WireGuard app for iOS or Android on your device.

For this example we'll create a second client (an iPhone) to connect to the WireGuard server. The same steps will need to be followed from when we setup the first client.

We can generate keys directly on the device and set up the configuration manually but that's not quick and ideal. Instead we can generate the keys and configuration on the server and then securely transfer the information into the WireGuard app.

Run wg genkey but specify different filenames this time to distinguish them from the server keys:

root@ip-172-30-0-233:/etc/wireguard# cd /etc/wireguard/keys
root@ip-172-30-0-233:/etc/wireguard/keys# wg genkey | tee iphone_privatekey | wg pubkey > iphone_publickey
root@ip-172-30-0-233:/etc/wireguard/keys# cat iphone_privatekey
kFnMqMSiAluwb/xWgemXhjLh/II/sb92OoYCbh7yaWw=
root@ip-172-30-0-233:/etc/wireguard/keys# cat iphone_publickey
cKIxzfp5ESpdM34vT2Qk/S7yvprOff6Le4YnyOTI4B8=

Open up the server config /etc/wireguard/wg0.conf in your favorite editor:

root@ip-172-30-0-233:/etc/wireguard/keys# vim /etc/wireguard/wg0.conf

Add the second peer section and include the client's public key and IP address:

[Interface]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PrivateKey = wIObajifv6U2emcZsAGNZbbWzkyrs84EEyr+bgmlB3M=
AllowedIPs = 10.0.0.2/32

[Peer]
PublicKey = cKIxzfp5ESpdM34vT2Qk/S7yvprOff6Le4YnyOTI4B8=
AllowedIPs = 10.0.0.3/32

Create a new configuration file for the iPhone client on the server. We'll name it wgo-iphone.conf:

root@ip-172-30-0-233:/etc/wireguard/keys# vim /etc/wireguard/wg0-iphone.conf

Paste client configuration but remember to use a different private IP that differs from the first client.

[Interface]
PrivateKey = kFnMqMSiAluwb/xWgemXhjLh/II/sb92OoYCbh7yaWw=
Address = 10.0.0.3/32
DNS = 1.1.1.1

[Peer]
PublicKey = H6StMJOYIjfqhDvG9v46DSX9UlQl52hOoUm7F3COxC4=
Endpoint = 54.225.123.18:51820
AllowedIPs = 0.0.0.0/0

Install qrencode on the server to generate a QRCode from the configuration file.

You'll be scanning this qrcode in the WireGuard app to download the configuration. This is a safer way to transport credentials since the keys and configuration files don't need to be zipped and moved.

Generate the text based qrcode image in your terminal with qrencode -t ansiutf8 < wg0-iphone.conf

root@ip-172-30-0-233:/etc/wireguard# qrencode -t ansiutf8 < wg0-iphone.conf
<qrcode image>

In the WireGuard app go to: Add a tunnel → Create from QRCode

Scan the qrcode code generated in the terminal and make sure to Allow the VPN configuration in the settings popup.

Enable the VPN by toggling on the switch.

Visit ipchicken.com in the browser to verify the public iP address has changed.

Generating vanity addresses

It's easy to lose track of which keys belong to which devices since they all look like random strings. To make it easier to associate keys to devices you can use this vanity address generator to generate public keys that contain a custom array of characters.

For example, we'll generate a key pair where the public key starts with "iPho" to denote that it's a key pair to be used on the iPhone client.

First install the vanity address generator with cargo:

$ cargo install wireguard-vanity-address

Now just specify the list of characters that you want in the public key base64 output:

$ wireguard-vanity-address ipho
searching for 'ipho' in pubkey[0..10], one of every 149796 keys should match
one trial takes 83.6 us, CPU cores available: 8
est yield: 1.6 seconds per key, 638.83e-3 keys/s
hit Ctrl-C to stop
private YPpudjAoVCnaPUJdcEVhj5Ttedq7WP1ozL+ZdtuTC1g=  public cHklbipHoMS9CA8XlRdKMBOOIfQC28Ut8SVyYsqmox0=
private kD6FSIZehv1DKJ28MKJQcmSDdd69U3s4s11ymtP1Ekc=  public iPHoaaQye7+OJNq/TfOvXjMr99pq9ADDDlGynRQ6KQ8=
private aEJ33LXCeipouhiAoQjfMjtwrHPfZDvKLguE8XlawnY=  public iPHoEoUy4WgkUXr4e47IkA06IZqVI/AqHNS2RZlGhHM=
^C

It'll keep generating until you manually stop it when you see a key pair that you like.

Automation

A nice tool to automate the process of setting up a WireGuard VPN is Algo.

Algo is a set of Ansible scripts to help you set up and configure WireGuard on the remote server from your local machine.

To get started, clone the algo repository and install the python dependencies:

~$ git clone https://github.com/trailofbits/algo.git
~$ cd algo/
~/algo$ pip install virtualenv
~/algo$ python3 -m virtualenv --python="$(command -v python3)" .env && source .env/bin/activate && python3 -m pip install -U pip virtualenv && python3 -m pip install -r requirements.txt

Now run the algo executable file to start the walkthough of deploying an Algo server to the cloud:

(.env) ~/algo$ ./algo
[Cloud prompt]
What provider would you like to use?
    1. DigitalOcean
    2. Amazon Lightsail
    3. Amazon EC2
    4. Microsoft Azure
    5. Google Compute Engine
    6. Hetzner Cloud
    7. Vultr
    8. Scaleway
    9. OpenStack (DreamCompute optimised)
    10. CloudStack (Exoscale optimised)
    11. Install to existing Ubuntu 18.04 or 19.10 server (for more advanced users)

Enter the number of your desired provider
:
<truncated>

Troubleshooting

The following are additional steps users reported they needed to take after getting the following errors.

If you tried wg-quick up wg0 and received the following:

root@ubuntu:/etc/wireguard# wg-quick up wg0
[#] ip link add wg0 type wireguard
RTNETLINK answers: Operation not supported
Unable to access interface: Protocol not supported
[#] ip link delete dev wg0
Cannot find device "wg0"

The error "RNETLINK answers: Operation not supported" when trying to start the wg0 interface could mean that you need install you install additional kernel modules that are required.

To install the required wireguard kernel modules on Ubuntu, run:

root@ubuntu:/etc/wireguard# apt-get install wireguard-dkms wireguard-tools linux-headers-$(uname -r)

Running modprobe wireguard should not output anything if the kernel modules were installed successful:

root@ubuntu:/etc/wireguard# modprobe wireguard

If you're seeing errors then there's a chance that the Secure Boot feature is blocking the unsigned WireGuard kernel module. To fix this you'll need to disable Secure Boot or sign the WireGuard module for the kernel to trust it. See this answer for instructions.

After rebooting try loading the interface with the ip link command:

root@ubuntu:/etc/wireguard# ip link add dev wg0 type wireguard

There should be no output if successful.

If you tried wg-quick up wg0 and received the following:

root@ubuntu:/etc/wireguard# wg-quick up wg0
[#] ip link add configfile type wireguard
[#] wg setconf configfile /dev/fd/63
[#] ip address add 10.0.0.1/24 dev configfile
[#] ip link set mtu 1420 dev configfile
[#] ip link set configfile up
[#] resolvconf -a configfile -m 0 -x
/usr/bin/wg-quick: line 31: resolvconf: command not found
[#] ip link delete dev configfile

it could mean that resolveconf is not installed on your machine, so you'll need to install the openresolv package:

root@ubuntu:/etc/wireguard# apt-get install openresolv

See this Github issue thread for more context.

TLDR;

Here's a summary of the server and client configuration and commands used in this post:

Server

Server commands:

sudo -s
apt-get install wireguard
mkdir -p /etc/wireguard/keys
cd /etc/wireguard/keys
umask 077
wg genkey | tee privatekey | wg pubkey > publickey
vim /etc/wireguard/wg0.conf # see server config below
vim /etc/sysctl.conf # uncomment line "net.ipv4.ip_forward=1"
sysctl -p
wg-quick up wg0
systemctl enable wg-quick@wg0.service

Server config /etc/wireguard/wg0.conf:

[Interface]
PrivateKey = <server private key>
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = <client public key>
AllowedIPs = 10.0.0.2/32

Client

Client commands:

sudo -s
apt-get install wireguard
mkdir -p /etc/wireguard/keys
cd /etc/wireguard/keys
umask 077
wg genkey | tee privatekey | wg pubkey > publickey
vim /etc/wireguard/wg0.conf # see client config below
wg-quick up wg0

Client config /etc/wireguard/wg0.conf:

[Interface]
PrivateKey = <client private key>
Address = 10.0.0.2/32
DNS = 1.1.1.1

[Peer]
PublicKey = <server public key>
Endpoint = <server public ip>:51820
AllowedIPs = 0.0.0.0/0

Resources

Understanding Cross-Origin Resource Sharing (CORS)

Miguel — Fri, 20 Sep 2019 07:42:24 +0000

Cross-Origin Resource Sharing (CORS) is a way of making HTTP requests from one place to another. Historically browsers have only allowed requests in JavaScript to be made from the same domain enforced by the same-origin policy which prevents cross-origin type of requests.

CORS gives the server authority of who can make requests and what type of requests are allowed. Browsers are the clients that enforce CORS policies.

The server can configure:

Which domains are allowed to make the HTTP request
Which HTTP methods are allowed (GET, POST, PUT, DELETE, etc).
Which headers are allowed on the request.
Whether or not requests may include cookie information.
Which response headers the client can read.

Intro TLDR;

CORS allows for restricted resources on a server to be accessed by a client on a different host.

We'll be covering all that things that you need to know about CORS beyond `Access-Control-Allow-Origin: *` in this tutorial. Yes there's a lot to learn!

Same-Origin vs Cross-Origin

For simplification purposes, a same-origin request is like 2 people in a house communicating.

There's no communication barrier between the Alice and Bob since they are in the same house (the same origin).

A cross-origin request is like having 2 different houses and a person from one house communicating from a person on the other house.

Since Bob wants to communicate with Charlie who lives in a different house then it's considered cross-origin communication because the homes live in different origins. And since Bob is initiating the call then the house Charlie is in needs to approve Bobs call.

TLDR;

A same-origin request is when the request is made from a host to the same host while a cross-origin request is when the request is made from a host to a different host.

Same-origin request

As an example, let's first make a same-origin request. We'll create a simple server offering an endpoint for the client and serving an HTML page. Throughout this this tutorial we'll be using Node.js and the express server for simplicity sake.

File server.js



const express = require('express')
const app = express()
const port = 8000

app.use(express.static(__dirname))
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

File index.html




<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts')

      console.log(await res.json())
    })()
  </script>
</body>
</html>



$ node server.js
listening on port 8000

If you visit http://localhost:8000/ you can see the request was successful. Nothing crazy and expected because it's from the same origin.

Cross-origin request

Now to show a cross-origin request let's spin up a new server to server the HTML file listening on a different port.

File server2.js



const express = require('express')
const app = express()
const port = 9000

app.use(express.static(__dirname))
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Let's see what happens when we visit the second server's webpage at http://localhost:9000/

The browser threw the error:



Access to fetch at 'http://localhost:8000/api/posts' from origin 'http://localhost:9000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

To demonstrate why this happened, let's see how the browser and server communicate with a simple chat example.

Browser: "hello server http://127.0.0.1:8000 please give me the data at /api/posts and let me know if the client at http://localhost:9000 can access it. Here's the HTTP message:"



Get /api/posts HTTTP1.1
User-Agent: Chrome
Host: 127.0.0.1:8000
Accept: */*
Origin: http://localhost:9000

Server: "here is the data, and the client cannot have access because I don't have the origin http://localhost:9000 as an allowed origin to access the data."



HTTP/1.1 200 OK

The server responds with the data but the browser will not give it to the JavaScript client unless the server says that the client is allowed based on their origin.

What server has to do to allow cross-origin requests is set the Access-Control-Allow-Origin response header.

So let's try again by setting up CORS on the server now by adding a new header to every request. We'll be adding the Access-Control-Allow-Origin with a wildcard * value which tells the browser that any origin can access the resource.

File server.js



const express = require('express')
const app = express()
const port = 8000

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')
  next()
})
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Side note: server2.js will not be changing throughout this tutorial so you can leave it running. We'll only be changing server.js from now on.

Ok, now let's see what happens when we visit the second server's webpage at http://localhost:9000/

To demonstrate why it works now, let's see how the browser and server communicate with a simple chat example again.

Browser: "hello server http://127.0.0.1:8000 please give me the data at /api/posts and let me know if the client at http://localhost:9000 can access it. Here's the HTTP message:"



Get /api/posts HTTTP1.1
User-Agent: Chrome
Host: 127.0.0.1:8000
Accept: */*
Origin: http://localhost:9000

Server: "here is the data, and yes any client can have access:"



HTTP/1.1 200 OK
Access-Control-Allow-Origin: *

Access-Control-Allow-Origin

The most important CORS headers are:

The Origin request header
TheAccess-Control-Allow-Origin response header

The origin is the host which is composed of the protocol, hostname, and port:



Origin = protocol + hostname + port

Example protocols:

http
https

Example hostnames:

localhost
example.com
foo.example.com

Example ports:

80
443
8000

Example origins:

The value null can be used a valid value for Origin when the browser origin can't be determined such as when using an absolute file path like file:///Users/alice/wwww/index.html

Browsers don't allow changing the origin header otherwise the client can pretend to be someone else.

The value of the Access-Control-Allow-Origin header can either be a wildcard or an origin value.

Example of valid headers:



Access-Control-Allow-Origin: *
Access-Control-Allow-Origin: http://localhost:8000
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Origin: null

You can only have one value so having multiple values like this is not valid:



# Not valid values, can't have multiple!
Access-Control-Allow-Origin: http://localhost:8000, http://example.com

To support multiple origins, you'll have to replace the header value dynamically with the current origin who's making the request.

For example, you would first check if the origin is whitelisted and then set the header:



if (whitelist.contains(req.get('origin')) {
  res.set('Access-Control-Allow-Origin', req.get('origin'))
}

For localhost entries you can use a regular expression to match all port numbers, for example

The regex /^http://\/\/localhost(:\d+)?$/i matches



http://localhost
http://localhost:1
http://localhost:10
http://localhost:100
http://localhost:1000 
http://localhost:2000 etc

You can use a hardcoded whitelist, regular expressions, or database query. A blacklist is better than nothing but not recommended.

Steps for origin validation:

Read value from Origin header
Validate origin using whitelist
Set origin to value of Access-Control-Allow-Origin

You can add null to your whitelist if you don't care that the origin is not set.



Access-Control-Allow-Origin: null

TLDR;

Use the Access-Control-Allow-Origin header to tell the browser which origins are allowed to access the data.

Preflight requests

For certain HTTP methods, the browser asks for permissions by doing what is known as a preflight request. If the browser approves the response from the preflight request then the actual request is made. If the browser doesn't approve the response from the preflight request then the actual request is never made.

HTTP methods that trigger a preflight request are:

PUT
PATCH
DELETE
TRACE

HTTP methods that don't trigger a preflight request are known as simple requests which are:

HEAD
GET
POST

A preflight request is a small request to the server from the browser before the main request and contains information such as which HTTP method is used and if any http headers are present. The server determines if the browser should send the actual request by returning a 2xx HTTP status code or return an error indicating that the client should not send the actual request.

The preflight request protects servers from receiving cross-origin requests they may not want. If a server is CORS-enabled it will know how to handle a preflight request and can respond accordingly. If the server doesn't understand or care about CORS then the server won't send the correct preflight response.

The preflight request uses the OPTIONS HTTP method.

A preflight is triggered when:

The client request is using a method other than GET, POST or HEAD (which are known as simple methods)
Client sets the Content-Type request header with values other than:
- application/x-www-form-urencoded
- multipart/form-data
- text/plain
Client sets additional request headers that are not:
- Accept
- Accept-Language
- Content-Language

Preflight responses should be in the 200 range (HTTP code 204 is standard) and contain no body. Containing a body can also confuse developers.

Let make a DELETE request to demonstrate a preflight request. First we'll check if the request is a preflight request. And if it is then return the HTTP 204 No Content status code.

File server.js



const express = require('express')
const app = express()
const port = 8000

const isPreflight = (req) => {
  return (
    req.method === 'OPTIONS' &&
    req.headers['origin'] &&
    req.headers['access-control-request-method']
  )
}

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.status(204).end()
    return
  }

  next()
})
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.delete('/api/posts', (req, res) => {
  res.json({success: true})
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

File index.html



<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts', {
        method: 'DELETE'
      })

      console.log(await res.json())
    })()
  </script>
</body>
</html>

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

We can see the error saying that the method DELETE is not allowed by CORS:



Access to fetch at 'http://localhost:8000/api/posts' from origin 'http://localhost:9000' has been blocked by CORS policy: Method DELETE is not allowed by Access-Control-Allow-Methods in preflight response.

Remember, that simple requests such as GET, POST, or HEAD don't initiate a preflight request and they are automatically allowed methods by CORS but methods such as DELETE or PUT need to be explicit allowed by the server.

To allow the DELETE method to be performed by the client we'll need to add the response header Access-Control-Allow-Methods in the preflight request.

File server.js



app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE') // Add this!
    res.status(204).end()
    return
  }

  next()
})

And now the the DELETE request works as expected:

Notice the different number of requests made in the two screenshots.

In the first screenshot, the preflight request failed so the actual DELETE request was never made, creating only 1 request.

In the second screenshot, the preflight request succeeded so the actual DELETE request was made, creating 2 requests.

To reject a preflight request:

Leave out the Access-Control-Allow-Origin header.
Return a value in Access-Control-Allow-Methods that doesn't match Access-Control-Request-Method header.
If preflight request has an Access-Control-Request-Header
- Leave out the Access-Control-Allow-Headers header.
- Return a value in the Access-Control-Allow-Headers header that doesn't match the Access-Control-Request-Headers header.

Both preflight response and actual response need the Access-Control-Allow-Origin header.

The browser may cache the preflight response from the first request to a resource from that origin to avoid sending additional queries all the time.

Preflights are stateless, meaning that the actual request doesn't contain any information connecting it to the preflight request.

Preflight requests will never follow redirects. If trying to make a preflight request but server tries to redirect then the preflight request will fail. You can manually inspect the Location header to see where the server is trying to redirect you to. Only simple CORS requests (GET, POST, HEAD) will follow redirects.

If redirect is the same server, then the Origin header will stay the same, otherwise it will be set to null.

TLDR;

A preflight request determines if the client is allowed to make the actual request based on what the server allows. The request must be an OPTIONS method, have the Access-Control-Request-Method header (such as DELETE or PUT), and contain the Origin header to be considered a preflight request.

Access-Control-Request-Method

The Access-Control-Request-Method is a single request header value that asks permission to use a specific HTTP method. This header is set by the browser when the client sends a non-simple method request.

The Access-Control-Request-Method is only sent in the preflight request.

The screenshot below shows the Access-Control-Request-Method request header in the preflight request and shows the response header Access-Control-Allow-Methods in the preflight response from when we did the DELETE request earlier.

Use accurate preflight headers to protect your server from unexpected requests. If your server only allows GET requests then don't put other headers in the Access-Control-Allow-Methods header.

TLDR;

The browser will send the Access-Control-Request-Method request header in the preflight request to let the server know it's intending to use the requested method in the actual request. If the server allows that method, then the browser will make the actual request.

Access-Control-Allow-Methods

The Access-Control-Allow-Methods is used in preflight requests to tell the client which methods are allowed with CORS.

For example, having the Access-Control-Allow-Methods: DELETE header indicates the server allows the client to make DELETE requests to the URL.

The Access-Control-Allow-Methods request header can have multiple values, for example:



Access-Control-Allow-Methods: HEAD, GET, POST, PUT, PATCH, DELETE

Remember that GET, POST, and HEAD are simple methods and always allowed so having them in the header is redundant and unnecessary, but some people like having them in the header because it's more to clear to them and avoids confusion.

Example showing PUT and DELETE (in addition to simple methods) as allowed:

TLDR;

The server should respond with the Access-Control-Allow-Methods response header to let the browser know which HTTP methods the client is allowed to make.

Access-Control-Request-Headers

The Access-Control-Request-Headers request header is sent in the preflight request to let the server know which headers the client will be sending in the actual response.

Let's try to send a custom header to the server.

File index.html



<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts', {
        headers: new Headers({
          'My-Custom-Header': 'hello world'
        })
      })

      console.log(await res.json())
    })()
  </script>
</body>
</html>

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

The browser responds with the error:



Access to fetch at 'http://localhost:8000/api/posts' from origin 'http://localhost:9000' has been blocked by CORS policy: Request header field my-custom-header is not allowed by Access-Control-Allow-Headers in preflight response.

Since browsers enforce CORS policies, the headers that cannot be set by JavaScript are:

Accept-Charset
Accept-Encoding
Access-Control-Request-Headers
Access-Control-Request-Method
Connection
Content-Length
Cookie
Cookie2
Date
DNT
Expect
Host
Keep-Alive
Origin
Referer
TE
Trailer
Transfer-Encoding
Upgrade
User-Agent
Via
headers starting with Proxy- or Sec-

These headers can only be set by the browser because they have special meaning. The browser will simply ignore the value that you set for those headers.

For other headers, the server will have to give permission to the client to include custom request headers on the cross-origin request.

We can see that the browser asked permission to access the custom header in the preflight request with the header Access-Control-Request-Headers:

The server needs to whitelist approved custom request headers and if doesn't whitelist the request headers then the request will fail.

If doing a same-origin request, then the request can include any custom request header since the origin is trusted.

By default CORS only allows the client to read these response headers:

Cache-Control
Content-Language
Content-Type
Expires
Last-Modified
Pragma

If the server sets additional response headers then the client won't be able to see them. In order for the client to see additional response headers then the server to expose those headers which we'll go over in a bit.

So to have the server be able to accept the client's custom header, it needs to explicitly allow that header by setting the response header Access-Control-Allow-Headers in the preflight response.

File server.js



const express = require('express')
const app = express()
const port = 8000

const isPreflight = (req) => {
  return (
    req.method === 'OPTIONS' &&
    req.headers['origin'] &&
    req.headers['access-control-request-method']
  )
}

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header') // Add this!
    res.status(204).end()
    return
  }

  next()
})
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.delete('/api/posts', (req, res) => {
  res.json({success: true})
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

The preflight responds with the allowed headers so the browser proceeds to make the actual request sending the custom request header.

Remember that headers starting with Access-Control-Request- are request headers by the browser asking for permission by the server and headers starting with Access-Control-Allow- are response headers sent by the server granting permissions to the browser.

Access-Control-Allow-Headers only needs to be present on preflight responses.

TLDR;

The browser sends a Access-Control-Request-Headers request header in the preflight request to let the server know that the actual request will request the specified headers. If the server denies those headers to be requested, then the actual request will not be sent.

Access-Control-Expose-Headers

The Access-Control-Allow-Headers header is used by the preflight to indicate which headers are allowed on the request while the Access-Control-Expose-Headers header is used by the actual response to indicate which response headers are visible to the client.

The client won't be able to read a a response header if the server doesn't set in the expose header.

Headers that are always exposed to the client are simple headers which are:

Cache-Control
Content-Language
Content-Type
Expires
Last-Modified
Pragma

As an example let's try to read all the response headers on the client:

File index.html



<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts')

      console.log(Array.from(await res.headers.entries()))
    })()
  </script>
</body>
</html>

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

Nothing surprising yet, we get back standard headers.

Let's set a custom response header on the server side.



const express = require('express')
const app = express()
const port = 8000

const isPreflight = (req) => {
  return (
    req.method === 'OPTIONS' &&
    req.headers['origin'] &&
    req.headers['access-control-request-method']
  )
}

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.status(204).end()
    return
  } else {
    res.set('Timezone-Offset', '240') // Add this!
  }

  next()
})
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.delete('/api/posts', (req, res) => {
  res.json({success: true})
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

Wait, we just see the same headers. The new header wasn't provided. Well this is because the server needs to set which headers are allowed to be read by the client with the Access-Control-Expose-Headers response header.

Let's add Access-Control-Expose-Headers as a regular response header to tell the browser that the client is allowed to read the custom header:

File server.js



const express = require('express')
const app = express()
const port = 8000

const isPreflight = (req) => {
  return (
    req.method === 'OPTIONS' &&
    req.headers['origin'] &&
    req.headers['access-control-request-method']
  )
}

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.status(204).end()
    return
  } else {
    res.set('Access-Control-Expose-Headers', 'Timezone-Offset') // Add this!
    res.set('Timezone-Offset', '240')
  }

  next()
})
app.get('/api/posts', (req, res) => {
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.delete('/api/posts', (req, res) => {
  res.json({success: true})
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

We can now read the custom header the server sent to the browser in the client.

TLDR;

Use Access-Control-Expose-Headers to allow the client to read additional non-simple headers.

Access-Control-Max-Age

The Access-Control-Max-Age header indicates how long in seconds a preflight response should stay cached. Let's tell the browser to cache preflight response for 2 minutes (120 seconds) by setting the header Access-Control-Max-Age in the preflight response.

File server.js



app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*')

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.set('Access-Control-Max-Age', '120') // Add this!
    res.status(204).end() 
    return
  } else {
    res.set('Access-Control-Expose-Headers', 'Timezone-Offset')
    res.set('Timezone-Offset', '240')
  }

  next()
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

We can see the Access-Control-Max-Age header in the preflight response header:

Firefox doesn't allow items to be cached longer than 24 hours while Chrome, Opera, and Safari cache items for a maximum of 5 minutes. If the Access-Control-Max-Age isn't specified then Firefox doesn't cache the preflight while Chrome, Opera, and Safari cache the preflight for 5 seconds.

Maximize the Access-Control-Max-Age header for a better mobile experience by reducing number of network requests.

To prevent proxy servers from caching responses from one client and sending them to a different client, use the Vary: Origin response header to indicate that the Access-Control-Allow-Origin will differ and should not be cached



Vary: Origin

For example:



if (isPreflight(req)) {
  if (whitelist.contains(req.get('origin'))) {
    res.set('Access-Control-Allow-Origin', req.get('origin'))
  }

  res.set('Vary', 'Origin')
} else {
  res.set('Access-Control-Allow-Origin', '*')
}

TDLR;

The Access-Control-Max-Age tells the browser how long in seconds to cache preflight responses for.

Access-Control-Allow-Credentials

The Access-Control-Allow-Credentials header is used to allow the client to send sensitive information like cookies in cross-origin requests.

Cookies require additional configuration for security and safety reason because they contain sensitive information. It would be dangerous to accidentally send personal information to a website on a different origin if opt-in was enabled all the time.

The JavaScript document.cookie API cannot read or write the value from another origin. Calling document.cookie only returns the clients own cookies and not the cross-origin cookies. Cookies themselves use the same-origin policy and each cookie has a path and a domain and only pages that match the path and domain can read the cookie.

Cookies work best in situations where:

You want to authorize users within your own ecosystem of clients and servers.
You know exactly which clients will be accessing your server.

Websites identify users through user credentials, with the most popular form being the cookie. Servers use cookies to store a unique identifier that identifies the use such as a session ID tied to a user ID.

The same-origin HTTP request will always contain the cookie but cross-origin doesn't contain cookie by default.

Enable the credentials option in the client side to send:

Cookies
Basic authentication
Client-side SSL certs

Let's set a cookie on the server and read the cookie on the client. For this example let's do it on the GET request for the posts. The response header for the cookie will be a simple key/value that can be read from any path.



Set-Cookie: username=alice; Path=/

File server.js



const express = require('express')
const app = express()
const port = 8000

const isPreflight = (req) => {
  return (
    req.method === 'OPTIONS' &&
    req.headers['origin'] &&
    req.headers['access-control-request-method']
  )
}

app.use(express.static(__dirname))
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', '*') 

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.set('Access-Control-Max-Age', '120')
    res.status(204).end()
    return
  } else {
    res.set('Access-Control-Expose-Headers', 'Timezone-Offset')
    res.set('Timezone-Offset', '240')
  }

  next()
})
app.get('/api/posts', (req, res) => {
  res.set('Set-Cookie', 'username=alice; Path=/') // Add this!
  res.json([
    {id: 1, content: 'foo'},
    {id: 1, content: 'bar'},
  ])
})
app.delete('/api/posts', (req, res) => {
  res.json({success: true})
})
app.listen(port, () => {
  console.log(`listening on port ${port}`)
})

File index.html



<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts')

      console.log(document.cookie)
    })()
  </script>
</body>
</html>

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

Nothing was logged! That's because cookies are allowed to be read by default on cross-origin requests. We can tell the server that we wish to read the cookies by setting credentials: 'include' on the fetch request options.

In the JavaScript fetch call you'll need to set credentials: 'include' to send cookies on cross-origin requests. If using XMLHttpRequest then you need to set withCredentials: true.

File index.html



<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <script>
    (async () => {
      const res = await fetch('http://localhost:8000/api/posts', {
        credentials: 'include'
      })

      console.log(document.cookie)
    })()
  </script>
</body>
</html>

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

We get the error:



Access to fetch at 'http://localhost:8000/api/posts' from origin 'http://localhost:9000' has been blocked by CORS policy: The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'.

Which means that in order for the client to read cookies, the Access-Control-Allow-Origin cannot be a wildcard * and it has to be explicitly set to the origin that's allowed to read the cookies.

Easy enough we can dynamically set the allowed origin to be the origin in the request header. In real world application you would be more secure and set to a whitelist of origins allowed to read cookies.

File server.js



app.use((req, res, next) => {
  // res.set('Access-Control-Allow-Origin', '*') // remove this!
  res.set('Access-Control-Allow-Origin', req.get('origin')) // Add this!

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.set('Access-Control-Max-Age', '120')
    res.status(204).end()
    return
  } else {
    res.set('Access-Control-Expose-Headers', 'Timezone-Offset')
    res.set('Timezone-Offset', '240')
  }

  next()
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

We get the following error:



Access to fetch at 'http://localhost:8000/api/posts' from origin 'http://localhost:9000' has been blocked by CORS policy: The value of the 'Access-Control-Allow-Credentials' header in the response is '' which must be 'true' when the request's credentials mode is 'include'.

This is because the browser needs to know that the server allows cookies to be read from cross-origin requests.

To enable cookie support the server must have the Access-Control-Allow-Credentials header set to true in order to indicate that the client is allowed to read cookies as well as that the server allows to receive cookies.

The only only value that the header Access-Control-Allow-Credentials can have is true.



Access-Control-Allow-Credentials: true

File server.js



app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', req.get('origin'))

  if (isPreflight(req)) {
    res.set('Access-Control-Allow-Methods', 'DELETE')
    res.set('Access-Control-Allow-Headers', 'My-Custom-Header')
    res.set('Access-Control-Max-Age', '120')
    res.status(204).end()
    return
  } else {
    res.set('Access-Control-Expose-Headers', 'Timezone-Offset')
    res.set('Access-Control-Allow-Credentials', 'true') // Add this!
    res.set('Timezone-Offset', '240')
  }

  next()
})

Restart the server:



$ node server.js
listening on port 8000



$ node server2.js
listening on port 9000

Now let's see what happens when we visit the second server's webpage at http://localhost:9000/

The client can now read the cookies!

We can see Access-Control-Allow-Credentials set to true and Access-Control-Allow-Origin set to the actual origin instead of the wildcard which both headers are required for cookies to be allowed on the client.

The Access-Control-Allow-Credentials header can be present on both the preflight and actual request but the cookie will only be sent on the actual request. The header is only needed on the non-preflight response.

TLDR;

Set the response header Access-Control-Allow-Credentials: true to allow the client to read sensitive information like cookies. Use credentials: 'include' if using the fetch API or usewithCredentials: trueif using the XMLHttpRequest API.Access-Control-Allow-Origin` can't be a wildcard when requesting credentials.

CSRF

CSRF tokens are an unguessable token shared between the client and the server to protect against cross-site request forgery (CSRF) attacks. The server serves the page to the client with the token as a header and the client sends the CSRF token on each request. If the server can't validate the token then the request is invalidated an rejected CSRf protection is needed when the client is requesting protected data using a cookie.

Spoofing Origin with cURL is possible and easy but spoofing with a cookie is harder because cURL doesn't have access to the browser cookie directly or remotely.

Where possible, consider same-origin requests instead of using CSRF since it's safer.

Use something other than a cookie to validate user if building a public API, such as using Oauth2 instead.

Browser support

CORS is fully supported on:

Chrome 3+
Firefox 3.5+
Safari 4+
IE 10+
Opera 12+
iOS 3.2+
Android 2.1+

Conclusion

We covered a variety of headers around CORS, including:

Questions to ask when adding CORS support:

Why does the server need to support cross-origin requests?
Is CORS being added to new service or existing?
Which client should have access to the site?
What browsers and devices will users be accessing the site from?
Which HTTP methods and headers is the server supporting?
Should the API support user-specific data?
Will cookies be used to authenticate the user?

TLDR;

Only allow cross-origin requests if you must absolutely have to and be very explicit about which origins, methods, headers, and credentials are allowed.

Resources:

How Unix programmers at restaurants search menus for their favorite plate

Miguel — Thu, 13 Dec 2018 10:41:49 +0000

A Unix programmer heads over to the local diner to get something to eat for lunch. He, or Bob as he prefers, knows better than to manually scan the entire menu with his eyeballs because it's inefficient. Bob knows that there's a better way to automate the process in searching for what he wants to eat.

Last time he was here he had a pretty good pasta-and-shrimp plate for under 10 bucks.

Bob wonder's if this same dish is still available. He pops open his laptop running Linux and scrapes the restaurant website menu table into a plain text file.

menu.txt

the menu

steak burrito $11.95
pasta and shrimp $9.75
caesar salad $6.50

Now that Bob has the menu, he does a grep search for the pasta-and-shrimp plate:

$ cat menu.txt | grep shrimp

pasta and shrimp $9.75

So far so good. He filters for the price column by using awk and the NF variable (which is the number of columns fields available) in order to get the last column containing the prices:

$ cat menu.txt | grep shrimp | awk '{print $NF}'

$9.75

The starvation is kicking in and he's typing furiously by now. Bob proceeds with sed to turn the dollar amount into an integer by replacing everything except for what's inbetween the dollar symbol and decimal period. He'll use a capturing group and replace the contents with the first capture group \1:

$ cat menu.txt | grep shrimp | awk '{print $NF}' | sed -E 's/\$([0-9]+)\..*/\1/g'

9

Finally, using the handy test command and the less-than flag -lt, Bob can check whether the price is less than 10 with the help of xargs to pipe the value as the first argument to test:

$ cat menu.txt | grep shrimp | awk '{print $NF}' | sed -E 's/\$([0-9]+)\..*/\1/g' | xargs -I {} test {} -lt 10

But wait there's no output! Actually, test returns an exit status code of 0 if the condition passes or 1 if no match.

Bob simply echo's Available if the previous command was successful by using &&, otherwise he'll echo :( by using the double pipe || if it was not successful:

$ cat menu.txt | grep shrimp | awk '{print $NF}' | sed -E 's/\$([0-9]+)\..*/\1/g' | xargs -I {} test {} -lt 10 && echo 'Available!' || echo ':('

Available!

Voila! there it is, the desired pasta-and-shrimp plate is still the under ten bucks. Bob is happy and proceeds to order his favorite dish.

(hope you liked this intro post to unix pipes and bash commands!)

DEV Community: Miguel

Getting Started with WireGuard

Why use WireGuard?

What we'll be going over

Setting up a server

Installing WireGuard on server

Generating server keys

Creating server configuration file

Enabling IP forwarding on server

Installing WireGuard on client

Generating client keys

Creating client configuration file

Setting server peer on client config

Setting client peer on server config

Starting WireGuard service on server

Starting WireGuard service on client

Connecting a mobile client to server

Generating vanity addresses

Automation

Troubleshooting

TLDR;

Server

Client

Resources

Understanding Cross-Origin Resource Sharing (CORS)

We'll be covering all that things that you need to know about CORS beyond Access-Control-Allow-Origin: * in this tutorial. Yes there's a lot to learn!

Same-Origin vs Cross-Origin

Same-origin request

Cross-origin request

Access-Control-Allow-Origin

Preflight requests

Access-Control-Request-Method

Access-Control-Allow-Methods

Access-Control-Request-Headers

Access-Control-Expose-Headers

Access-Control-Max-Age

Access-Control-Allow-Credentials

CSRF

Browser support

Conclusion

How Unix programmers at restaurants search menus for their favorite plate

We'll be covering all that things that you need to know about CORS beyond `Access-Control-Allow-Origin: *` in this tutorial. Yes there's a lot to learn!