Skip to content

Latest commit

 

History

History
90 lines (57 loc) · 4.73 KB

wsl_tutorial.md

File metadata and controls

90 lines (57 loc) · 4.73 KB
Raw

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

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 WSL and target machine

  1. Ensure that WinCryptSSHAgent.exe is running.

  2. Run your WSL console and execute the command which socat to check if socat is present.

    Some WSL Linux distros don't include socat by default, such as Ubuntu 20.04

    a) If socat is not installed, install it before continuing. (Debian/Ubuntu example: sudo apt install -y socat)

  3. Right click on WinCrypt SSH Agent's icon in tray and select Show WSL settings (or Show WSL2 / Linux On Hyper-V Settings if using WSL2 and/or Hyper-V) then press OK.

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

    For WSL2 / Hyper-V, lines like this will be copied into your clipboard:

    export SSH_AUTH_SOCK=/tmp/wincrypt-hv.sock
ss -lnx | grep -q $SSH_AUTH_SOCK
if [ $? -ne 0 ]; then
 rm -f $SSH_AUTH_SOCK
  (setsid nohup socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork SOCKET-CONNECT:40:0:x0000x33332222x02000000x00000000 >/dev/null 2>&1)
fi

  4. Run your WSL console and execute command from previous step.

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

  6. 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.

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

  8. 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! 🚀