3 Ways to Protect WireGuard With YubiKey

WireGuard’s security depends entirely on the secrecy of your private keys (with one exception: for connections that use a preshared key, the connection remains secure even when the private keys are compromised, as long as the preshared key remains secret). If an adversary steals your private keys (plus any preshared keys you use), she can decrypt the contents of your WireGuard connections, and impersonate you to the rest of your WireGuard network.

You usually don’t have to worry too much about your WireGuard keys being stolen — they will be safe as long as an adversary does not get root or physical access to your computer. However, they are vulnerable to being stolen under the following circumstances:

The techniques shown in this article will mitigate the first three issues. The fourth issue is also possible to mitigate, but requires a customized version of the WireGuard client to interface directly with the YubiKey, as mentioned above.

All these techniques involve encrypting your WireGuard private keys with the PGP key stored in your YubiKey. This changes the game for an adversary from stealing your WireGuard private keys to stealing your PGP private keys. And if you generate your PGP keys on the YubiKey itself, this is impossible unless the adversary steals the physical YubiKey device.

So if you generated your PGP keys on the YubiKey itself, and require a YubiKey touch for each decryption attempt, the only way an adversary can access your WireGuard private keys will be one of the following:

A convenient way to encrypt your WireGuard keys is to use the pass password manager (which was also created by the author of WireGuard, Jason A. Donenfeld). If you configure pass to use your YubiKey’s PGP key, each access of any key in pass’s password store will require a decryption operation by your YubiKey (and therefore requires your YubiKey to be physically present, and optionally that you touch it to confirm).

For example, if the key ID for the master PGP key on your YubiKey is 0x1234567890ABCDEF, you would use the following command to initialize your password store with it:

You can then create a new WireGuard private key and store it in your password store with the following command:

Alternately, you can copy a WireGuard key you previously generated and paste it into your password store with the following command:

To derive the public key for a private key stored in your password store, run the following command:

This is the public key you put in the configuration of the remote hosts to which you want to connect from your local computer.

In your local WireGuard config file, replace the PrivateKey line with the following PostUp script (assuming the name of the WireGuard interface is wg0, and your username is justin):

This will configure the WireGuard interface to start up without a private key; and then once the interface is up, set its private key to the wireguard/private-keys/wg0 password from your password store. The scripts in WireGuard config files are run as root, so in order to access your password store and decrypt a password with your YubiKey via your gpg-agent instance, you need to switch to your user account with the sudo command (or a similar command such as su, doas, etc).

Alternately, you can omit the PrivateKey line and the addition of a PostUp script from your WireGuard configuration, and set the private key for the interface manually, as a separate step after you start up the interface. For example, the following two commands start up the WireGuard interface wg0, and then set its private key from your password store:

Doing this in two steps avoids the awkwardness of switching back to your own user account to call the pass command from within the switch to root required to start up the WireGuard interface. The /dev/fd/0 path in the wg set wg0 private-key command above tells the wg utility to read the private key from its stdin stream (into which the key is piped from the stdout stream of the pass program).

If you use preshared keys for certain WireGuard connections, you can also store them in your password store, and decrypt them for use with WireGuard the same way.

For example, you can generate and store a preshared key for the connection to another WireGuard host (“Host B”) with the following command:

To retrieve the preshared key from your password store (so you can share it with Host B), you can run the following command:

In your local WireGuard config file, replace the PresharedKey line for Host B with the following PostUp script (assuming the name of the WireGuard interface is wg0, the public key of the remote peer for Host B is fE/wdxzl0klVp/IR8UcaoGUMjqaWi3jAd7KzHKFS6Ds=, and your username is justin):

Make sure you put the PostUp script in the [Interface] section of the config file, not the [Peer] section. Include a separate PostUp script for each preshared key.

The following example shows how you might set up a config file for a WireGuard interface wg0, where its private key is stored in your password store under wireguard/private-keys/wg0, with a preshared key for its connection to Host B stored in your password store under wireguard/preshared-keys/wg0/host-b, and a preshared key for its connection to Host C stored in your password store under wireguard/preshared-keys/wg0/host-c:

If you don’t want to use the pass program to manage your WireGuard keys, you can simply use regular PGP-encrypted files on disk.

For example, if the key ID for the master PGP key on your YubiKey is 0x1234567890ABCDEF, you would use the following command to create a WireGuard private key, and store it encrypted in some file on your local disk (like ~/.config/wireguard/wg0.key.gpg) with your YubiKey PGP encryption key:

Alternately, you can save a WireGuard key you previously generated, as a single line in a file, and encrypt it like the following (as a file called wg0.key.gpg):

To derive the public key from an encrypted private key, run the following command:

This is the public key you put in the configuration of the remote hosts to which you want to connect from your local computer.

In your local WireGuard config file, replace the PrivateKey line with the following PostUp script (assuming the name of the WireGuard interface is wg0, and your username is justin):

This will configure the WireGuard interface to start up without a private key; and then once the interface is up, set its private key to the decrypted contents of the /home/justin/.config/wireguard/wg0.key.gpg file.

The scripts in WireGuard config files are run as root, so in order to decrypt files with your YubiKey via your gpg-agent instance, you need to switch to your user account with the sudo command (or a similar command such as su, doas, etc). And because the decryption command is run as your user account, make sure you store the encrypted WireGuard private key in a file to which your user account has access. A directory in your home folder (like ~/.config/wireguard) is good for this.

Alternately, you can omit the PrivateKey line and the addition of a PostUp script from your WireGuard configuration, and set the private key for the interface manually, as a separate step after you start up the interface. For example, the first of the following two commands starts up the WireGuard interface wg0; and then the second command decrypts the private key for wg0, and updates the interface with it:

Doing this in two steps avoids the awkwardness of switching back to your own user account to call the decryption command from within the switch to root required to start up the WireGuard interface. The /dev/fd/0 path in the wg set wg0 private-key command above tells the wg utility to read the private key from its stdin stream (into which the key is piped from the stdout stream of the GnuPG program).

If you use preshared keys for certain WireGuard connections, you can also encrypt them in the same way.

For example, you can generate and encrypt a preshared key for the connection to another WireGuard host (“Host B”) with the following command:

To decrypt the preshared key (so you can share it with Host B), run the following command:

In your local WireGuard config file, replace the PresharedKey line for Host B with the following PostUp script (assuming the name of the WireGuard interface is wg0, the public key of the remote peer for Host B is fE/wdxzl0klVp/IR8UcaoGUMjqaWi3jAd7KzHKFS6Ds=, and your username is justin):

Make sure you put the PostUp script in the [Interface] section of the config file, not the [Peer] section. Include a separate PostUp script for each preshared key.

The following example shows how you might set up a config file for a WireGuard interface wg0, with its private key and two preshared keys encrypted with your YubiKey PGP key, and stored in your home folder within the ~/.config/wireguard directory:

In addition to functioning as an OpenPGP card, a YubiKey also has the functionality of a US Federal PIV (Personal Identity Verification) card. A bonus feature of this functionality is that the YubiKey offers about 65,000 unused PIV slots in which you can store small blobs of data on the card itself (the PIV card standard uses only about 50 slots). These unused slots can be read without requiring a PIN or touch, and up to 3 KB of data can be stored in each slot.

This allows you to improve a bit on the security of the above Password Store and File on Disk techniques by storing your PGP-encrypted WireGuard keys as opaque blobs in unused PIV slots. This can mitigate the (fairly narrow) scenario where you did not generate your PGP key on the YubiKey device itself, and had a back-up of your PGP keys — along with the contents of your computer’s hard drive — stolen by an adversary.

In that case, if you had stored your WireGuard keys on your hard drive, the adversary would be able to use the stolen PGP key to decrypt them; but if you store your WireGuard keys in the PIV slots of your YubiKey, the adversary would have to mount a targeted attack to gain direct access to your computer and read your WireGuard keys from your YubiKey while it was plugged in (or steal the physical YubiKey device itself).

To create a WireGuard private key and store it in a PIV slot, run the following command, using the YubiKey Manager CLI to interact with the PIV application:

In the above command, change 0x1234567890ABCDEF to the key ID of the master PGP key for your YubiKey, and change 5f0000 to the hex ID of the PIV slot to use. You can use any slot from 5f0000 to 5fffff — except for slots 5fc100 through 5fc12f, which are defined for use by the PIV application itself (and if you write arbitrary data to them, you may brick the PIV application). The PIN you will be prompted for is the PIN for the PIV management key — not the PIN for your PGP key.

Alternately, you can encrypt and store a WireGuard key you previously generated, as a single line in a file, by encrypting and writing it to the PIV 5f0000 slot like the following:

To derive the public key from an encrypted private key stored in PIV slot 5f0000, run the following command:

This is the public key you put in the configuration of the remote hosts to which you want to connect from your local computer.

In your local WireGuard config file, replace the PrivateKey line with the following PostUp script (assuming the name of the WireGuard interface is wg0, you’ve stored the private key in PIV slot 5f0000, and your username is justin):

This will configure the WireGuard interface to start up without a private key; and then once the interface is up, set its private key to the decrypted contents of PIV slot 5f0000. The scripts in WireGuard config files are run as root, so in order to decrypt files with your YubiKey via your gpg-agent instance, you need to switch to your user account with the sudo command (or a similar command such as su, doas, etc).

Alternately, you can omit the PrivateKey line and the addition of a PostUp script from your WireGuard configuration, and set the private key for the interface manually, as a separate step after you start up the interface. For example, the first of the following two commands starts up the WireGuard interface wg0; and then the second command decrypts the private key for wg0, and updates the interface with it:

Doing this in two steps avoids the awkwardness of switching back to your own user account to call the decryption command from within the switch to root required to start up the WireGuard interface. The /dev/fd/0 path in the wg set wg0 private-key command above tells the wg utility to read the private key from its stdin stream (into which the key is piped from the stdout stream of the GnuPG program).

If you use preshared keys for certain WireGuard connections, you can also encrypt them in the same way.

For example, you can generate and encrypt a preshared key for the connection to another WireGuard host (“Host B”) with the following command, storing it in PIV slot 5f0001:

To decrypt the preshared key (so you can share it with Host B), run the following command:

In your local WireGuard config file, replace the PresharedKey line for Host B with the following PostUp script (assuming the name of the WireGuard interface is wg0, the public key of the remote peer for Host B is fE/wdxzl0klVp/IR8UcaoGUMjqaWi3jAd7KzHKFS6Ds=, and your username is justin):

Make sure you put the PostUp script in the [Interface] section of the config file, not the [Peer] section. Include a separate PostUp script for each preshared key.

The following example shows how you might set up a config file for a WireGuard interface wg0, where its private key is stored in PIV slot 5f0000, with a preshared key for its connection to Host B stored in PIV slot 5f0001, and a preshared key for its connection to Host C stored PIV slot 5f0002: