YubiKey Guide is a community-maintained reference for using YubiKey hardware security devices with GnuPG and SSH to protect cryptographic keys.
The guide addresses the problem of securing private keys by leveraging YubiKey's hardware-based cryptography, where private keys are generated and stored on the device and cannot be extracted. The approach involves creating a separate offline "Certify" key to manage key renewal and rotation, while subkeys for signing, encryption, and authentication are transferred to the YubiKey for daily use. This architecture ensures that even if a computer is compromised, the master key remains protected offline and the device itself must be physically present to perform cryptographic operations.
The guide is suited for developers and system administrators who need to secure SSH access, sign code or commits, and manage encrypted communications. It walks through the complete setup process from purchasing a compatible YubiKey model through configuring GnuPG, transferring keys to the device, and integrating with SSH, email clients like Thunderbird and Mutt, and platforms like GitHub. The guide covers both basic usage and advanced topics including agent forwarding over SSH, managing multiple YubiKeys, and optional hardening measures. It explicitly addresses legacy distributions and provides troubleshooting sections for common issues.
The project maintains a structured, comprehensive reference that evolves to address user questions and emerging use cases. Documentation is organized into logical sections covering initial setup, daily usage patterns, key rotation procedures, and security considerations. The guide includes specific configuration examples and step-by-step instructions rather than high-level overviews, making it practical for implementation. Community contributions have expanded coverage to include multiple email clients, SSH agent configurations, and network-specific scenarios like chained agent forwarding.
