YubiKey-Guide
Community guide to using YubiKey for GnuPG and SSH - protect secrets with hardware crypto.
A step-by-step guide for setting up a YubiKey hardware security key to handle SSH login, signed Git commits, and encrypted files, with keys generated offline so they never touch your main computer.
A YubiKey is a small USB hardware device that stores cryptographic keys in a way that makes them impossible to export or copy. This repository is a detailed community guide for setting up a YubiKey to handle secure operations like encrypting files, signing emails and commits, and authenticating into SSH servers.
The guide starts with key generation: rather than doing this on your regular computer, it recommends creating the keys on a temporary system with no network connection, booted from a live Linux USB drive. This reduces the chance that software on your main machine could observe or capture the keys during creation. The guide walks through downloading and verifying a Debian Live image, preparing a USB drive to boot from, and installing the required software.
After generating the keys using GnuPG (a standard open-source cryptography tool), the guide covers transferring them onto the YubiKey. Once the keys are on the device, they never leave it. When you sign a document or log in via SSH, the YubiKey performs the cryptographic operation internally and sends only the result back to the computer, so the private key itself never passes through software.
The SSH section covers how to configure your system to use the YubiKey as an SSH authentication agent, how to forward that capability to remote machines you connect to, and how to chain that forwarding across multiple hops. There are also sections on signing Git commits for GitHub, using the YubiKey with email clients like Thunderbird and Mutt, keeping a backup YubiKey, and optional hardening steps.
This is a documentation guide, not a software package. It contains step-by-step instructions with shell commands rather than code to install or run.
The full README is longer than what was shown.
Where it fits
- Set up a YubiKey to authenticate SSH connections instead of storing private keys on your laptop.
- Sign Git commits with a hardware key so your identity cannot be spoofed even if your computer is compromised.
- Generate and store GPG encryption keys on a YubiKey for encrypting sensitive files and emails.
- Chain SSH agent forwarding through multiple remote servers using a YubiKey as the authenticator.