YubiKey Guide
A community guide for storing GnuPG keys on a YubiKey so private keys stay on the hardware.
- Stars
- 13.1k
- Forks
- 1.3k
- Licence
- MIT
- Language
- HTML
- Last update
- 4 days ago
- Type
- Learning resource
What it is
This is a step-by-step guide for using a YubiKey hardware security key to hold GnuPG (OpenPGP) keys for signing, encryption, and SSH logins. The guide says private keys cannot be copied back out of the device, so they stay protected even if the computer is compromised. It walks through generating keys on an offline machine, making encrypted backups, and then moving the keys onto the YubiKey for daily use.
- Generate a GnuPG certify key and subkeys on an offline computer and move them to a YubiKey
- Use the YubiKey to sign Git commits and GPG-encrypted email
- Use the YubiKey for SSH authentication through gpg-agent
- Restore keys from an encrypted backup onto a replacement YubiKey after loss or damage
Great for
- Developers who want to sign commits and log in over SSH with a hardware-backed key
- People who already use GnuPG and want to protect their private keys with a YubiKey
- Users comfortable working in a terminal and following detailed setup steps
- Anyone willing to prepare offline backup media in separate physical locations
Not ideal for
- People who want a quick, one-click setup; the process involves many manual steps and an offline environment
- Owners of YubiKey Security Key or YubiKey Bio models, which the guide says do not support OpenPGP
- People who do not want to manage encrypted offline backups, since losing both the key and backups means losing access
How to get it
- 1
See the README
You'll need: A YubiKey model with OpenPGP support · A bootable USB drive and at least two USB drives or microSD cards for backups · GnuPG and related tools (installed per platform, e.g. gnupg, scdaemon, pcscd, yubikey-manager)
Clone the guide repository
git clone https://github.com/drduh/YubiKey-GuideInstall required software on Debian/Ubuntu
sudo apt -y install wget gnupg2 gnupg-agent dirmngr cryptsetup scdaemon pcscd yubikey-personalization yubikey-managerInstall required software on macOS with Homebrew
brew install gnupg yubikey-personalization ykman pinentry-mac wget - 2
Run it
- Prepare an offline environment, such as a Debian Live USB, and verify the Debian image signature
- Install the required GnuPG and YubiKey tools in that environment
- Generate the Certify key and subkeys, then create encrypted backups
- Transfer the subkeys to the YubiKey and verify it works for encryption, signing, or SSH
- 3
Get the most out of it
- Keep at least two encrypted backups in different physical locations, as the guide recommends
- Enable touch confirmation for keys so each use requires physical presence
- Configure gpg-agent to serve as your SSH agent for seamless SSH logins
- Set key expiration and plan for renewing or rotating subkeys
Downloads
Strengths
- Explains the security reasoning behind each step, including why an offline environment is recommended
- Covers many setups, including Debian, OpenBSD, macOS, and NixOS
- Widely used community resource with a large following and an MIT license
Trade-offs
- Requires a fair amount of GnuPG and command-line knowledge to follow safely
- Setup takes significant time and careful handling of backups and passphrases
- Parts of the guide reference specific OS images and tools that may change over time
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| YubiKey-Guide (this) | 13.1k | Learning resource | advanced | 4 days ago | Developers who want to sign commits and log in over SSH with a hardware-backed key |
| macOS-Security-and-Privacy-Guide | 22.6k | Learning resource | intermediate | 4 days ago | Mac owners who want a checklist of security and privacy settings to work through |
| the-practical-linux-hardening-guide | 10.9k | Learning resource | intermediate | 2.0 years ago | System administrators hardening a Linux server who want a readable checklist |
| PayloadsAllTheThings | 82.3k | Curated list | beginner | 6 days ago | Penetration testers who want a quick reference of payload variations for a known vulnerability class |
| linux-command | 37.2k | Learning resource | beginner | 6 days ago | People learning the Linux command line who want quick, readable command explanations |
| API-Security-Checklist | 23.3k | Learning resource | beginner | 4 months ago | Developers reviewing an API design before launch |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.