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 a PIV Compatible Smart Card. Note that YubiKey also has 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 the 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 access set-retries 5 10
2. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv access change-pin --pin 123456
3. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv access change-puk --puk 12345678
4. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv access change-management-key --generate --protect --touch

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

Generate Keys

1. "C:\Program Files\Yubico\YubiKey Manager\ykman.exe" piv keys generate --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 certificates generate --valid-days 365 --subject "SSH Key" 9a "%UserProfile%\Desktop\%username%_public_key.pem"

   Command generates a 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.

NOTE: Please make sure Allow ECC certificates to be used for logon and authentication in Group Policy Editor (gpedit.msc) > Computer Configuration > Administrative Templates > Windows Components > Smart Card is enabled.

NOTE#2: You should also install the YubiKey Smart Card Minidriver if you want to work with ECC algorithm certificates.

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 previous 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 SSH 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 should be allowed into your target machine. Enjoy! 🚀