The ultimate guide to Yubikey on WSL2 [Part 1]

There are already a few tutorials on the Internet with topic “how to make Yubikey work on WSL”. But when I followed them I had to do a lot of troubleshooting anyway. Therefore I decided to write down a complete guide to the setup (up to date in 2021).

We are going to go through a couple of use cases:

1. Setup OpenGPG with Yubikey
2. Access your YubiKey in WSL2
3. Authenticate against Git server via GPG & Signing git commits with GPG
4. Managing secrets in WSL with Yubikey

Other parts will be added in the future

Setup of Yubikey and connect it with WSL2

In this part we are going to take a look on how to get Yubikey connected to WSL2. Because WSL does not have access to USB devices, we have to make it connect to our Windows host and then forward the connection to WSL.

First, we are going to need a YubiKey that supports OpenPGP (Security Key Series or YubiKey FIPS Series are not sufficient)

Prerequisites

To make our Smart key work with windows we are going to need GnuPG and Putty. You can either download it here:

• GnuPG install it with Kleopatra
• Putty

or get it via chocolate:

# CMD
choco install gnupg putty.install

Configure GnuPG

# CMD
mkdir %HOMEPATH%\AppData\Roaming\gnupg
echo enable-putty-support◙enable-ssh-support > %HOMEPATH%\AppData\Roaming\gnupg\gpg-agent.conf

You can connect your Yubikey now. Open Kleopatra (you have to open it from system tray) and go to Smartcards.

If you don’t see your Yubikey go to Settings -> Configure Kleopatra -> GnuPG System -> Smartcards and set Connect to reader at port N to Yubico YubiKey OTP+FIDO+CCID 0. Save it, reconnect Yubikey and restart Kleopatra. Now you should be able to see it.
You can also verify it in CMD via: gpg --card-status

A Brand new or Wiped out Yubi key should show up like this

Output of gpg — cart-status

Setting up a new YubiKey

In case you already have an OpenPGP key on your YubiKey, please skip this part and go directly to part 2.

I personaly found generating the keys in Kleipatra GUI the most straightforward. Although it doesn’t give you that many configuration possibilities.

If you’re setting up Your Yubikey for the first time, don’t forget to change your PIN and Admin PIN. Both operations can be done in Kleopatra -> Smartcards -> Change PIN and Change Admin PIN. Default PINs can be found here.

1. Generate GPG keys

In Kleopatra -> Smartcards click at Generate New Keys. A dialog will pop up. Enter your name, email and as algorithm choose the highest available.

Generating Your GPG Keys

Now enter your PIN, then your Admin PIN (pay attention to what the modal window wants) — it’s going to need your PIN several times. In case you encounter with an issue, you can always reset your YubiKey. At the end enter password for the GPG key.

In case you’re more comfortable with terminal interface, please use this official tutorial. Just make sure, you are generating keys and/or subkeys for Signing, Encryption and Authorization.

Now you should be able to see your keys.

Generated Keys

2. Export your public key

In Kleopatra go to Cartificates -> Right click at your newly created certificate and choose Export. This will save your public key to an asc file

3. Publish your public key

This step is not necessary, but I found it helpful when using GPG key in real life.

Go to keys.openpgp.org, choose your public key and click Upload.

Uploading Public key to keys.openpgp.org

Click Send Verification Email, check your e-mail Inbox (or Spam) folder and click the verification link.

To get link to your published Public key go to keys.openpgp.org, search for your email and copy the URL it shows.

YubiKey has a nice handy space for storing this URL. Go to Kleopatra -> Smartkeys -> Publickey URL and edit it.

In case you don’t see your keys or card in WSL after restart of your PC. Please start Kleopatra first and then restart wsl via wsl — shutdown

Additional Tips

Autostart Kleopatra on Windows Logon

The easiest way to achieve it is via “Task Schduler”
- Action -> Create a Basic Task
- Trigger: “When I log on”
- Action: Start a program
- Program/Script: Path to kleopatra.exe (should be `”C:\Program Files (x86)\Gpg4win\bin\kleopatra.exe”`)

Import Yubikey to a new machine

When you insert your Yubikey it should be visible in “Smartcards” section. If you don’t see it follow `Configure GnuPG` section.

- Click the Publickey URL — this will download your public key
- Click Import in kleopatra menu and point to the downloaded file

After that you should be able to continue to part 2 of this tutorial

—

We’ll continue in the part 2.