Quantum-resistant tunnels with WireGuard

Other VPN software WireGuard Connectivity Windows Linux macOS Feature

Last updated: November 1, 2024

This guide shows how to use the mullvad-upgrade-tunnel utility to create a quantum-resistant tunnel with wg-quick (WireGuard) on Linux and macOS, and the WireGuard app on Windows.

Note: If you use the Mullvad VPN app then you can just enable Quantum-resistant tunnel in the Mullvad app settings > VPN settings > WireGuard settings.

What this guide covers

Option 1: Download a pre-built copy of mullvad-upgrade-tunnel
Option 2: Build mullvad-upgrade-tunnel from source
Modify your WireGuard configuration file
Notes

Option 1: Download a pre-built copy of mullvad-upgrade-tunnel

1. Download the files for your platform

Go to the wgephemeralpeer repository in the Mullvad Github and download the version for your platform. Note about macOS: If you have a Mac with an Apple Silicon processor then download the "darwin_arm64" files. If you have an older Mac with an Intel CPU then download the "darwin_amd64" files.

If you are using a platform that there is no pre-built binary for, then see Option 2: Build mullvad-upgrade-tunnel from source.

2. Verify the signature

To make sure that the mullvad-upgrade-tunnel binary is authentic you can verify the signature. The signature file has the same name as the Zip file with the binary, but it ends with ".asc". It too can be downloaded from our repository above.

1. Install GPG:

Linux: install the gnupg2 package
macOS (using Homebrew): brew install gnupg
Windows: Install GPG4win.

2. Import the signing key

First download the signing key. To import it, use the following command in the Terminal (Linux, macOS) or Command Prompt (Windows):

gpg --import mullvad-rsw.asc

Another way to import it is to use the following command in the Terminal (Linux, macOS) or Command Prompt (Windows):

gpg --import

Then copy the key in the text block below (including the BEGIN and END lines) and do this:

Linux/macOS: paste it in the Terminal, press Enter and then Ctrl+D on the keyboard.
Windows: paste it in the Command Prompt, press Enter and then Ctrl+z and then Enter again on the keyboard.

The response should include this:

gpg: key 35332B90D3936CAE: public key "Mullvad RSW <admin@mullvad.net>" imported

3. Sign the key

Signing the key is optional. If you don't do it then you will see a warning when you verify the file that says that the key is not certified. If you want to certify it by signing it yourself then you can find instructions in our Verifying signatures guide (this signs a different key so the response is different).

4. Unzip the downloaded binary file

The zipped file contains mullvad-upgrade-tunnel.

5. Verify mullvad-upgrade-tunnel

Use the command below for the platform that you downloaded. This guide uses "v1.0.0" but if a newer version is available after this guide is published then replace "v1.0.0" with the newer version number.

macOS (Intel):
gpg --verify mullvad-upgrade-tunnel_v1.0.0_darwin_amd64.zip.asc mullvad-upgrade-tunnel

macOS (Apple Silicon):
gpg --verify mullvad-upgrade-tunnel_v1.0.0_darwin_arm64.zip.asc mullvad-upgrade-tunnel

Linux (amd64):
gpg --verify mullvad-upgrade-tunnel_v1.0.0_linux_amd64.zip.asc mullvad-upgrade-tunnel

Windows (amd64):
gpg --verify mullvad-upgrade-tunnel_v1.0.0_windows_amd64.zip.asc mullvad-upgrade-tunnel.exe

The response should include this:

gpg: Signature made Fri Mar 22 16:48:## 2024 CET
gpg:                using EDDSA key 10241484929EEC4248D6F68035332B90D3936CAE
gpg: Good signature from "Mullvad RSW <admin@mullvad.net>" [unknown]

6. Move the mullvad-upgrade-tunnel file

Place the mullvad-upgrade-tunnel file in a system directory for binaries, for example:

Linux: /usr/local/sbin
macOS: /usr/local/bin
Windows: C:\Program Files\WireGuard

7. Use mullvad-upgrade-tunnel with WireGuard

Continue reading Modify your WireGuard configuration file below.

Option 2: Build mullvad-upgrade-tunnel from source

This section contains instructions for building the mullvad-upgrade-tunnel utility for Windows, Linux and macOS. If you need help to build it for another platform such as a router, then write to support@mullvadvpn.net and include the model and processor architecture.

Prerequisites

Windows

It is possible to build mullvad-upgrade-tunnel natively on Windows if you use MinGW, however it is probably a better experience to use cross-compilation under Ubuntu in Windows. This requires that you do the following:

Install Ubuntu on WSL2
Download the Linux kernel update package
Set WSL 2 as your default version (in the Command Prompt):
wsl --set-version Ubuntu-22.04 2
wsl -l --verbose

Install Make, Go, Git (and for Windows: Podman)

Windows (using Ubuntu on WSL2): sudo apt install make golang git podman
Fedora: sudo dnf install make go git
Debian/Ubuntu: sudo apt install make golang git
macOS (using Homebrew): brew install make go git

Build and install mullvad-upgrade-tunnel

1. Download the source code using the following command:

git clone https://github.com/mullvad/wgephemeralpeer.git

2. Navigate into the downloaded directory and then build the mullvad-upgrade-tunnel utility:

Linux/macOS: make
Windows (using Ubuntu on WSL2): make release-windows-amd64

3. Move the mullvad-upgrade-tunnel file to a system directory for binaries:

Linux: sudo mv mullvad-upgrade-tunnel /usr/local/sbin
macOS: mv mullvad-upgrade-tunnel /usr/local/bin
Windows (using Ubuntu on WSL2):
mv mullvad-upgrade-tunnel-windows_amd64.exe /mnt/c/Users/USERNAME/Downloads/
Then rename the file in the Windows Explorer to mullvad-upgrade-tunnel.exe and move it to
C:\Program Files\WireGuard.

Modify your WireGuard configuration file

In your web browser, go to our WireGuard configuration file generator and download a WireGuard configuration file.
Open the configuration file in a text editor and locate the [Interface] section. Add the following at the end of the section:
For Linux and macOS:
PostUp = mullvad-upgrade-tunnel -wg-interface %i
For Windows:
PostUp = mullvad-upgrade-tunnel -wg-interface %WIREGUARD_TUNNEL_NAME%

Your configuration file for Linux or macOS should now look something like this:

[Interface]
# Device: Mellow Merlin
PrivateKey = <redacted>
Address = 10.64.37.199/32,fc00:bbbb:bbbb:bb01::1:25c6/128
DNS = 10.64.0.1
PostUp = mullvad-upgrade-tunnel -wg-interface %i

[Peer]
PublicKey = 5JMPeO7gXIbR5CnUa/NPNK4L5GqUnreF0/Bozai4pl4=
AllowedIPs = 0.0.0.0/0,::0/0
Endpoint = 185.213.154.66:51820

Linux

You can now use wg-quick to start and stop your tunnel as usual by running wg-quick up <config> and wg-quick down <config> respectively.

When executing wg, you should be able to see a preshared key: (hidden) line underneath the peer section, indicating that a PSK (preshared key) has been successfully configured for your tunnel.

macOS

The WireGuard client available in the Mac App Store unfortunately does not support the PostUp option in the WireGuard configuration file. If you would like to use mullvad-upgrade-tunnel, you can instead install WireGuard with Homebrew. Then use wg-quick similar to the Linux instructions above.

Windows

The PostUp option in the WireGuard configuration file is disabled by default in Windows for security reasons. To enable PostUp, you need to modify the registry using the following command in an elevated Command Prompt (Run as administrator):

reg add HKLM\Software\WireGuard /v DangerousScriptExecution /t REG_DWORD /d 1 /f

For more information about the security risk, see the wireguard-windows website.

To connect, use the WireGuard app for Windows.

When WireGuard is activated, you should be able to see a Preshared key: enabled line in the Peer section, indicating that a PSK (preshared key) has been successfully configured for your tunnel.

Notes

wg-quick SaveConfig

wg-quick offers a SaveConfig option. If set to true, the configuration is saved from the current state of the interface upon shutdown. However, please note that this option cannot be used in conjunction with mullvad-upgrade-tunnel. When negotiating a PSK, you will use an ephemeral peer that is only temporarily valid and accepted on the VPN relay. Thus, using SaveConfig will replace your regular configuration with the ephemeral peer, and subsequent attempts to establish a tunnel will fail.

Key Encapsulation Methods

By setting the -kem <kem> flag for mullvad-upgrade-tunnel, you can use one of the following key encapsulation methods when negotiating the preshared key. The default value is cme-mlkem.

cme (Classic McEliece 460896 Round3)
mlkem (ML-KEM-1024)
cme-mlkem (Classic McEliece 460896 Round3 + ML-KEM-1024)
mlkem-cme (ML-KEM-1024 + Classic McEliece 460896 Round3)

For Linux and macOS:

PostUp = mullvad-upgrade-tunnel -kem kyber-cme -wg-interface %i

For Windows:

PostUp = mullvad-upgrade-tunnel -kem kyber-cme -wg-interface %WIREGUARD_TUNNEL_NAME%

"WireGuard" is a registered trademark of Jason A. Donenfeld.