wsl_tutorial.md

Yubikey on WSL

This tutorial will guide you to confgure YubiKey so it can be used with SSH under WSL. We will use YubiKey as PIV Compatible Smart Card. Note that YubiKey has also other modes that can be used for secure SHH access like GPG that are not covered in this tutorial.

Prerequisites

• Fresh YubiKey 5
• Yubico software from https://www.yubico.com/products/services-software/download/smart-card-drivers-tools/
  • YubiKey Manager (graphic interface) - it also installs ykman.exe
  • YubiKey Smart Card Minidriver (Windows) - it is required to get ECDSA instead of default RSA
• WinCrypt SSH Agent from https://github.com/buptczq/WinCryptSSHAgent
• Console (ie. cmd.exe or Windows Terminal)

Steps

Insert YubiKey into USB port of your computer

You can check with Device Manager (devmgmt.msc) that system recognized your key. It will be listed under Smart Cards as YubiKey Smart Card Minidriver.

Change default PIN and PUK

Execute following commands, provide new PIN and PUK when prompted:

1. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv set-pin-retries 5 10
2. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv change-pin --pin 123456
3. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv change-puk --puk 12345678
4. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv change-management-key --generate --protect --touch

This will give you a YubiKey with PIN and PUK that is only knwon to you and requires touch to change keys on it.

Generate Keys

1. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv generate-key --algorithm ECCP384 --format PEM --pin-policy ONCE --touch-policy ALWAYS 9a "%UserProfile%\Desktop\%username%_public_key.pem"

   Command generates private key inside of YubiKey. It is not possible to extract it so it is very secure. Also it requires a touch every time it is used for authentication.

2. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv generate-certificate --valid-days 365 --subject "SSH Key" 9a "%UserProfile%\Desktop\%username%_public_key.pem"

   Command generatea certificate from your public key. In brief: Windows needs it when speaking to your YubiKey.

Check Windows Certificate Store

1. Unplug your YubiKey.
2. Plug your YubiKey back.
3. Run Certificate Manager Tool (certmgr.msc) and in Certificates - Current User \ Personal \ Certificates your certificate named SSH key should be visible.

Confiure YubiKey for SSH in WLS and target machine

1. Ensure that WinCryptSSHAgent.exe is running.

2. Right click on WinCrypt SSH Agent's icon in tray and select Show WSL settings then press OK.

   Line like export SSH_AUTH_SOCK=/mnt/c/Users/Jane/wincrypt-wsl.sock will be copeid into your clipboard.

3. Run your WSL console and execute command from previosu step.

4. ssh into your target machine, authenticate with credentials used until now.

5. Right click on WinCrypt SSH Agent's icon in tray and select Show public keys settings then press OK.

   All known keys in SSH format will be copied. You need to locate one named SHA key.

6. Copy line with SSH key into ~\.ssh\authorized_keys on target machine.

7. Disconnect from target machine.

Use YubiKey for SSH

1. ssh into your machine.
2. Provide PIN when Windows asks.
3. Touch YubiKey twice (it should be blinking).
4. You shold eb allowed into yout trget machine. Enjoy! 🚀