drduh/YubiKey-Guide: GnuPG and SSH Key Storage on YubiKey

What This Guide Covers and Who It Is For

The drduh/YubiKey-Guide is a detailed community reference that documents how to use a YubiKey as a hardware token for storing GnuPG private keys. The central security property it describes is straightforward: once subkeys are transferred to the YubiKey, the private key material cannot be copied back out of the device. All cryptographic operations using those keys require the physical YubiKey to be present.

The guide covers the full workflow: choosing the right YubiKey model, preparing a secure environment for key generation, creating a root Certify key and three subkeys for signing, encryption, and authentication, backing up key material to offline storage, configuring the YubiKey, transferring the subkeys, and then using the configured key for SSH connections, GitHub commit signing, and email encryption in clients including Thunderbird, Mailvelope, and Mutt.

The intended audience is developers and security-conscious individuals who use SSH heavily, sign git commits, or send encrypted email and want the private key to be protected by hardware rather than stored on disk. It is not a general introduction to GnuPG: readers who are unfamiliar with public key cryptography will find the early sections on key algorithms, expiration, and passphrases require additional background reading.

The Key Architecture: Certify Key and Three Subkeys

The guide distinguishes between the Certify key and the three subkeys (signing, encryption, and authentication) because they have different security roles and different storage requirements.

The Certify key is the root of the identity. It is used only to create and sign the subkeys and to replace them when they expire or are compromised. The guide instructs that the Certify key must be retained offline and must never be transferred to the YubiKey. It should remain on an encrypted USB drive or microSD card stored separately from the YubiKey itself. The guide recommends at least two such backup copies stored in different physical locations.

The three subkeys are the ones used day-to-day: the signing subkey for signing git commits and documents, the encryption subkey for encrypting and decrypting files and email, and the authentication subkey for SSH. Only these three are transferred to the YubiKey. When any of them expires or needs to be rotated, the Certify key is retrieved from offline storage, new subkeys are generated and signed, and the new subkeys replace the old ones on the device.

This architecture limits the blast radius of a compromised or lost YubiKey. The subkeys can be revoked and replaced using the Certify key, and the Certify key was never on the YubiKey to begin with.

Preparing a Secure Environment for Key Generation

The guide is explicit that key material should not be generated on a daily-use, network-connected operating system. It orders possible environments from least to most secure, with a daily-use personal operating system with unrestricted network access ranked second-least secure, just above a public or shared computer.

The practical recommendation for most users is to boot Debian Live from USB on a personal computer without attaching the primary storage device. Debian Live runs from RAM and leaves no persistent state on the computer. Tails is listed as a more hardened alternative. An air-gapped system without network capabilities, preferably ARM-based like a Raspberry Pi, is described as the most secure option.

To obtain a verified Debian Live image, the guide provides commands for downloading the image and its signature, importing the Debian signing key, and verifying both the signature and the image hash:

imageUrl="https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/"
curl -sfL -O "$imageUrl/SHA512SUMS" -O "$imageUrl/SHA512SUMS.sign"
curl -sfLO "$imageUrl/$(awk '/xfce\.iso$/ {print $NF}' SHA512SUMS)"

gpg --keyserver hkps://keyring.debian.org \
    --recv DF9B9C49EAA9298432589D76DA87E80D6294BE9B

gpg --verify SHA512SUMS.sign SHA512SUMS

Once the signature is verified, the image can be written to a USB drive with dd. The guide provides the command for both Linux and OpenBSD environments:

sudo dd if=debian-live-*-amd64-xfce.iso of=/dev/sdc bs=4M status=progress ; sync

The guide warns explicitly to confirm the device path before running dd, as it overwrites the target device completely.

YubiKey Model Selection and Verification

Not all YubiKey models support the OpenPGP application that this guide relies on. The guide states clearly that YubiKey Security Key models and YubiKey Bio models do not include OpenPGP support. Any YubiKey used with this guide must include the OpenPGP application, which is available in the YubiKey 5 series and other models with the full application set.

Before starting the key generation process, the guide instructs users to verify the YubiKey's authenticity at yubico.com/genuine. This involves selecting the Verify Device option on that page, touching the key when prompted, and allowing the site to identify the device model. The purpose is to detect potential supply chain tampering, which is a documented risk for hardware security tokens.

The physical form factor of the YubiKey (USB-A, USB-C, NFC variants) does not affect compatibility with the guide. What matters is the presence of the OpenPGP application. A YubiKey purchased without confirming OpenPGP support cannot be used with this guide regardless of its other capabilities.

Transferring Subkeys and Configuring Touch

After the Certify key and three subkeys are created and backed up offline, the guide covers configuring the YubiKey before transferring the subkeys. The configuration steps include changing the default PIN (123456) and admin PIN (12345678) to user-chosen values, and setting key attributes such as the card holder name and preferred public key URL.

The subkey transfer moves each of the three subkeys to the corresponding slot on the YubiKey: the signing key to the signature slot, the encryption key to the encryption slot, and the authentication key to the authentication slot. After transfer, the private key material is no longer on the local filesystem; GnuPG operations that require a private key will invoke the YubiKey's hardware.

The guide also covers configuring touch requirements. Touch protection requires a physical tap on the YubiKey for each cryptographic operation, adding a layer of protection against malware that might attempt to silently use the stored key. The guide describes how to enable this setting on a per-key basis.

Using the YubiKey for SSH and GitHub

Once the authentication subkey is on the YubiKey, it can be used for SSH. The guide covers two agent setups: using GnuPG's gpg-agent as an SSH agent (via the S.gpg-agent.ssh socket), and using the system's ssh-agent with the gpg-agent in passthrough mode. Both approaches expose the YubiKey's authentication key as an SSH identity without requiring a separate SSH private key file on disk.

The guide also covers SSH agent forwarding in two configurations: using ssh-agent for forwarding and using S.gpg-agent.ssh for chained forwarding to remote hosts. It notes that chained GnuPG agent forwarding requires additional socket configuration on intermediate hosts.

For GitHub, the public key derived from the authentication subkey can be added to a GitHub account for SSH authentication, and the public key from the signing subkey can be registered with GitHub for commit signing verification. Both workflows require exporting the public key and uploading it to the relevant GitHub settings page.

Email encryption is covered for Thunderbird (using the native OpenPGP support or Enigmail), Mailvelope (a browser extension), and Mutt. In all three cases, the YubiKey serves as the hardware token that holds the decryption and signing keys, and the email client communicates with gpg-agent to perform cryptographic operations.

Updating Keys and Resetting the YubiKey

Subkeys on a YubiKey have an expiration date set during the key creation process. When subkeys expire, the guide covers two paths: renewing the subkeys (extending the expiration without replacing the key material) and rotating the subkeys (generating new key material and transferring the new subkeys to the YubiKey). Both operations require retrieving the Certify key from offline storage, which is why the offline backup is critical.

The guide also documents how to reset the YubiKey completely. This wipes the OpenPGP applet on the device, removing all stored key material and resetting the PIN and admin PIN to factory defaults. This is relevant when a YubiKey is to be repurposed or when PINs have been locked after too many incorrect attempts.

Optional hardening steps in the guide include improving entropy during key generation, enabling the Key Derived Function (KDF) feature which stores a hash of the PIN on the YubiKey rather than comparing PINs directly, and network isolation considerations during the setup process.

The repository's last push was on 2026-09-21. The MIT licence covers the guide text. The repository is the primary place to file issues and suggests alternative tools in an Alternative solutions section for users whose requirements the YubiKey/GnuPG approach does not cover.

Editorial conclusion

Developers who want hardware-backed GPG keys for SSH authentication, commit signing, and encrypted email will find this guide the most complete community resource available for YubiKey specifically. The guide is not appropriate for YubiKey Security Key or YubiKey Bio models, which do not include the OpenPGP application. The most important step to verify before starting is that your YubiKey model appears on the comparison table at yubico.com/store/compare with OpenPGP listed as a supported application. If that step passes, the guide provides every command needed for the complete setup.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository