The ultimate guide to Yubikey on WSL2 [Part 1]
Tags: yubikey, wsl, git, gpg
Published: 2021-02-16 10:08:51

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:**
- Setup OpenGPG with Yubikey
- [Access your YubiKey in WSL2](https://dev.to/dzerycz/the-ultimate-guide-to-yubikey-on-wsl2-part-2-kli)
- [Authenticate against Git server via GPG & Signing git commits with GPG](https://dev.to/dzerycz/the-ultimate-guide-to-yubikey-on-wsl2-part-3-2d8d)

*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](https://gpg4win.org/index.html)
[Putty](https://www.putty.org/)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/946kfcaptejudj5mzbme.PNG)![Outout of gpg - cart-status](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j9rjljlm536yhcywp6b3.png)

### 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 forgot 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](https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html#:~:text=Technical%20details%20about%20the%20YubiKey,default%20PUK%20code%20is%2012345678.).

#### 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n0y2kgp33pucmhq5md5r.png)

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](https://support.yubico.com/hc/en-us/articles/360013761339-Resetting-the-OpenPGP-Applet-on-the-YubiKey). At the end enter password for the GPG key.

> In case you're more comfortable with terminal interface, [please use this official tutorial](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP). 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wy3hc8odowoh8o7qy6wm.png)

#### 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](https://keys.openpgp.org/upload), choose your public key and click Upload.

![Uploading Public key to keys.openpgp.org](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eqdcpuukqk4r3wt84jqi.png)

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](https://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.](https://dev.to/dzerycz/the-ultimate-guide-to-yubikey-on-wsl2-part-2-kli)