Skip to content
Get packs

Guide · Open source

How to use YubiKey-Guide: GnuPG and SSH setup steps

Updated · written with AI from the project's own documentation and checked against our catalogue data

YubiKey-Guide is an MIT-licensed, HTML community guide from drduh that walks you through storing GnuPG (OpenPGP) keys on a YubiKey hardware security key. It covers keys used for signing, encryption and SSH logins. After following it, you will have generated keys on an offline machine, made encrypted backups, and moved the keys onto your YubiKey for daily use.

YubiKey Guidedrduh/YubiKey-Guide · ★ 13.1k · MIT

Quick start

  1. 1Check your YubiKey. Confirm the model includes OpenPGP. YubiKey Security Key and YubiKey Bio models are not supported by this guide.
  2. 2Prepare the environment. Boot a hardened or ephemeral system, such as Debian Live from USB, with internal storage disconnected.
  3. 3Install software. Install GnuPG, scdaemon, pcscd and yubikey-manager using the command for your platform.
  4. 4Generate keys offline. Create the Certify key and Subkeys, then verify them.
  5. 5Make encrypted backups. Export keys to at least two encrypted offline backups stored in different physical locations.
  6. 6Transfer Subkeys. Configure the PIN and attributes on the YubiKey, then move the signature, encryption and authentication Subkeys onto it.
  7. 7Use and verify. Verify the transfer and then configure encryption, signing and SSH use.

Check that your YubiKey supports OpenPGP

The guide requires 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.

The guide also suggests verifying the key at yubico.com/genuine by selecting Verify Device, touching the key when prompted, and letting the site identify the model.

  • Have at least two USB drives or microSD cards for encrypted offline backups stored in different physical locations.
  • Plan for a bootable USB drive as well.

Choose a secure environment and boot Debian Live

The guide asks you to generate keys in a dedicated, hardened environment. It lists options from least to most secure, including a Debian or OpenBSD install, Debian Live or Tails booted without primary storage, and an air-gapped system.

For most people, the guide says booting Debian Live from USB on a personal computer is a practical baseline. Disconnect internal storage and unnecessary peripherals such as the wireless card before booting.

  • Download the Debian Live image and its SHA512SUMS and SHA512SUMS.sign files.
  • Verify the signature with gpg --verify SHA512SUMS.sign SHA512SUMS, then check the image hash against the signed sums file.
  • Write the image to USB with dd, after confirming the device path, because the command erases the selected device.
gpg --verify SHA512SUMS.sign SHA512SUMS

Install the required software

Install the packages for your platform. On Debian or Ubuntu the guide installs GnuPG tools, cryptsetup, scdaemon, pcscd, yubikey-personalization and yubikey-manager. On macOS it uses Homebrew, and the guide also offers MacPorts and NixOS options.

  • Debian/Ubuntu: sudo apt -y install with wget, gnupg2, gnupg-agent, dirmngr, cryptsetup, scdaemon, pcscd, yubikey-personalization and yubikey-manager.
  • macOS: brew install gnupg yubikey-personalization ykman pinentry-mac wget.
  • OpenBSD: doas pkg_add gnupg pcsc-tools.
brew install gnupg yubikey-personalization ykman pinentry-mac wget

Generate keys, back them up and move them to the YubiKey

The guide prepares GnuPG, then creates a Certify key and Subkeys. Before transferring anything, it has you verify the keys and back them up to encrypted offline media. You export the public key, change the YubiKey PIN, set attributes, and then transfer the Subkeys for signature, encryption and authentication.

The private keys cannot be copied back out of the device. That is the main protection the guide offers: keys stay protected even if the computer is compromised. If the YubiKey is lost, stolen or destroyed, the keys can be restored from an encrypted backup to a new device.

  • Create the Certify key, then the Subkeys.
  • Verify keys and make encrypted backups.
  • Configure the YubiKey: change PIN, set attributes.
  • Transfer Subkeys, then verify the transfer.

Use the YubiKey for signing, encryption and SSH

Once keys are on the YubiKey, the guide covers day-to-day use: encryption, signatures, and configuring touch. For SSH, it explains replacing agents, copying the public key, importing SSH keys and agent forwarding. It also covers GitHub, email clients such as Thunderbird, Mailvelope and Mutt, and the keyserver.

  • Sign commits and use GitHub with the signing key.
  • Log in over SSH using the authentication key.
  • Use multiple YubiKeys with the same workflow, per the guide's section on that topic.

Renew or rotate keys and reset when needed

The guide has separate sections for renewing Subkeys, rotating Subkeys and resetting the YubiKey. Optional hardening topics include improving entropy, enabling KDF and network considerations. Read the Notes and Troubleshooting sections of the guide before you begin.

What people use it for

  • Signing Git commits with a hardware-backed GnuPG key.
  • Logging in to servers over SSH with a key that stays on the YubiKey.
  • Encrypting and signing email in Thunderbird, Mailvelope or Mutt.
  • Restoring keys from an encrypted backup onto a new YubiKey after loss or damage.

Frequently asked questions

Is YubiKey-Guide free to use?

The repository is released under the MIT licence, which the project lists in its metadata. The guide itself is a free community resource, but you still need to buy a YubiKey that supports OpenPGP.

Which YubiKey models work with this guide?

Models that include the OpenPGP application work. The guide states that YubiKey Security Key and YubiKey Bio models do not support OpenPGP and cannot be used with it.

Can I copy my keys off the YubiKey later?

No. The guide says private keys cannot be copied back out of the device. If the YubiKey is lost, stolen or destroyed, you restore keys from an encrypted backup to a new device.

What do I need before starting?

You need a YubiKey with OpenPGP, a bootable USB drive, at least two USB drives or microSD cards for backups, and GnuPG with related tools such as scdaemon, pcscd and yubikey-manager.

Is there an alternative to GnuPG on a YubiKey?

The guide lists comparable projects including FIDO2 security keys with ssh-keygen, age and Keybase. FIDO2 keys may be simpler for SSH, but this guide covers OpenPGP keys for signing, encryption and SSH.

Why does the process take so many steps?

The guide relies on generating keys on an offline machine, making encrypted backups and then transferring keys. That is what protects the private keys, but it means manual work and careful handling of backup media.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

YubiKey-Guide suits developers and GnuPG users who want hardware-backed keys for signing and SSH and are comfortable in a terminal with offline backups. If you want a quick one-click setup, or you own a YubiKey Security Key or Bio, pick a different approach such as FIDO2 keys with ssh-keygen.

Install options & downloads