ephemere/bash/yubikey/README.md

YubiKey Scripts

Shell scripts for managing YubiKey hardware security keys on WSL (Windows Subsystem for Linux). Covers SSH key extraction, Git signing key configuration, and fixing USB permission issues that commonly arise in WSL environments.

All scripts require a YubiKey to be attached and forwarded to WSL via usbipd. The ykman and yubico-piv-tool packages must be installed.

Getting Started

Run scripts via the interactive runner from the project root:

make run
# Select: Bash → yubikey → <script>

Or run directly:

bash bash/yubikey/<script-name>.sh

Table of Contents

• add-keys-to-git.sh
• fix-yubikey-perms.sh
• list-yubikey-ssh-keys.sh

---

add-keys-to-git.sh

Extracts the SSH public keys from three YubiKey PIV slots and writes them as Git commit signing keys to the corresponding per-context Git config files. Run this after replacing or re-provisioning a YubiKey.

Slot	Context	Config file
9a	Personal	~/.git-naomi
9c	Deepgram	~/.git-dg
9e	FreeCodeCamp	~/.git-fcc

Usage

bash bash/yubikey/add-keys-to-git.sh

Environment Variables

None.

Data Files

None.

Notes

• After running, you must upload the new public keys to GitHub (and any other services that verify commit signatures) manually.
• Requires ykman and ssh-keygen to be available in your PATH.

---

fix-yubikey-perms.sh

Repairs YubiKey connectivity in WSL by fixing USB device permissions, restarting smart card services, and applying a polkit policy override that allows smart card access in WSL's "inactive" session context.

Usage

bash bash/yubikey/fix-yubikey-perms.sh

Environment Variables

None.

Data Files

None.

Notes

• Run this script when ykman or yubico-piv-tool fail with "Failed to connect" or similar errors after attaching the YubiKey via usbipd.
• The polkit fix modifies /usr/share/polkit-1/actions/org.debian.pcsc-lite.policy (a backup is created automatically on first run).
• Requires sudo access. Several steps use sudo to modify system files and restart services.
• Requires lsusb, yubico-piv-tool, systemctl, and gpgconf to be available.

---

list-yubikey-ssh-keys.sh

Scans PIV slots 9a, 9c, 9d, and 9e on the connected YubiKey and prints any SSH public keys found, along with the certificate subject label if one is present.

Usage

bash bash/yubikey/list-yubikey-ssh-keys.sh

Environment Variables

None.

Data Files

None.

Notes

• Requires ykman, ssh-keygen, and openssl to be available.
• Writes a temporary file to /tmp/yubi_tmp.pem during execution; it is cleaned up automatically after each slot is processed.