An excerpt from the repository, fetched Nov 13, 2026.
Read the project’s introduction
This guide demonstrates how to store credentials on a YubiKey. The private keys cannot be copied back out of the device. Keys are first generated on an offline computer, then exported to encrypted offline backups, and then transferred to YubiKey for daily use. If the YubiKey is lost, stolen, or destroyed, keys can be restored from an encrypted backup to a new device.
Purchase YubiKey
Prepare setup environment
Download and verify Debian
Create bootable USB device
Prepare hardware
Install software
Prepare GnuPG
Configuration
Identity
Key algorithm
Expiration
Passphrase
Create Certify key
Create Subkeys
Verify keys
Backup keys
Export public key
Configure YubiKey
Change PIN
Set attributes
Transfer Subkeys
Signature key
Encryption key
Authentication key
Verify transfer
Finish setup
Using YubiKey
Encryption
Signature
Configure touch
SSH
Replace agents
Copy public key
Import SSH keys
SSH agent forwarding
Use ssh-agent
Use S.gpg-agent.ssh
Chained forwarding
GitHub
GnuPG agent forwarding
Legacy distributions
Chained GnuPG agent forwarding
Using multiple YubiKeys
Email
Thunderbird
Mailvelope
Mutt
Keyserver
Updating keys
Renew Subkeys
Rotate Subkeys
Reset YubiKey
Optional hardening
Improving entropy
Enable KDF
Network considerations
Notes
Troubleshooting
Alternative solutions
Additional resources
Purchase YubiKey
Choose a YubiKey model that includes the OpenPGP application. YubiKey Security Key and YubiKey Bio models do not include OpenPGP support and cannot be used with this guide.
Verify the YubiKey at yubico.com/genuine. Select Verify Device, touch the key when prompted, and allow the site to identify the device model. This can help detect some supply chain tampering.
Have at least two USB drives or microSD cards for storing encrypted offline backups in different physical locations.
Prepare setup environment
Use a dedicated, hardened environment to generate the keys and backups.
The following environments are ordered from least to most secure for this task:
Public, shared or other computer owned by someone else
Daily-use personal operating system with unrestricted network access
Virtualized system with limited capabilities (using virt-manager, VirtualBox or VMware, for example)
Dedicated and hardened Debian or OpenBSD installation
Ephemeral Debian Live or Tails booted without primary storage attached
Hardened hardware and firmware (e.g., Coreboot, Intel ME removed)
Air-gapped system without network capabilities, preferably ARM-based Raspberry Pi or other architecturally diverse equivalent
Network isolation and dedicated hardware generally provide stronger protection than a daily-use online system. For most people, booting Debian Live from USB on a personal computer is a practical baseline.
Download and verify Debian
Download the latest Debian Live image and signature files. These commands download the checksum file, its signature, and the current 64-bit XFCE Live ISO:
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)"
Download the Debian signing public key:
gpg --keyserver hkps://keyring.debian.org \
--recv DF9B9C49EAA9298432589D76DA87E80D6294BE9B
If the public key cannot be received, use a different keyserver or DNS server:
gpg --keyserver hkps://keyserver.ubuntu.com:443 \
--recv DF9B9C49EAA9298432589D76DA87E80D6294BE9B
The Debian Live signing public key is also available for import in pubkeys:
gpg --import pubkeys/debian-DA87E80D6294BE9B.asc
Verify the signature:
gpg --verify SHA512SUMS.sign SHA512SUMS
Confirm the fingerprint matches Debian's published fingerprint:
gpg: Good signature from "Debian CD signing key <debian-cd@lists.debian.org>"
Verify the image hash matches the signed sums file:
grep $(sha512sum debian-live-*-amd64-xfce.iso) SHA512SUMS
See Verifying authenticity of Debian CDs for more information.
Create bootable USB device
Connect a storage device and identify the device path. This guide uses /dev/sdc throughout, but this value may differ on your system.
WarningThe following dd commands erase and overwrite the selected device. Check the device path before continuing!
Linux
$ sudo dmesg | tail
usb-storage 3-2:1.0: USB Mass Storage device detected
sd 2:0:0:0: [sdc] Attached SCSI removable disk
Copy the Debian image to the device:
sudo dd if=debian-live-*-amd64-xfce.iso of=/dev/sdc bs=4M status=progress ; sync
OpenBSD
$ dmesg | tail -n2
sd2 at scsibus4 targ 1 lun 0: <TS-RDF5, SD Transcend, TS3A> SCSI4 0/direct removable serial.0000000000000
sd2: 15193MB, 512 bytes/sector, 31116288 sectors
$ doas dd if=debian-live-*-amd64-xfce.iso of=/dev/rsd2c bs=4m
465+1 records in
465+1 records out
1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec)
Prepare hardware
Shut down the computer that will be used to generate keys.
Disconnect internal storage and unnecessary peripherals, such as the wireless card.
Install software
Boot the computer from the Debian Live USB drive.
Configure networking to install the required software; see Network considerations for optional restrictions.
TipIf the screen locks on Debian Live, unlock with user / live
Open a terminal and install the required software.
Debian/Ubuntu
sudo apt update
sudo apt -y upgrade
sudo apt -y install \
wget gnupg2 gnupg-agent dirmngr \
cryptsetup scdaemon pcscd \
yubikey-personalization yubikey-manager
OpenBSD
doas pkg_add gnupg pcsc-tools
macOS
Download and install Homebrew and the following packages:
brew install gnupg yubikey-personalization ykman pinentry-mac wget
Or using MacPorts, install the following packages:
sudo port install gnupg2 yubikey-manager pinentry wget
NixOS
Use this repository's purpose-built live ISO instead of Debian Live. Copy the resulting ISO to a USB drive, boot from it, and keep the system offline while generating keys.
ref=$(git ls-remote https://github.com/drduh/Yubikey-Guide refs
Read the full README on GitHub