explaingit

drduh/yubikey-guide

★ 12,308HTMLAudience · ops devopsComplexity · 4/5Setup · hard

TLDR

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.

Mindmap

mindmap
  root((yubikey-guide))
    Key Generation
      Air-gapped Linux
      GnuPG setup
      Offline only
    YubiKey Setup
      Key transfer
      Never exported
      Hardware auth
    Use Cases
      SSH login
      Git signing
      File encryption
      Email signing
    Audience
      Developers
      Security-focused
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Set up a YubiKey to authenticate SSH connections instead of storing private keys on your laptop.

USE CASE 2

Sign Git commits with a hardware key so your identity cannot be spoofed even if your computer is compromised.

USE CASE 3

Generate and store GPG encryption keys on a YubiKey for encrypting sensitive files and emails.

USE CASE 4

Chain SSH agent forwarding through multiple remote servers using a YubiKey as the authenticator.

Tech stack

GnuPGLinuxSSH

Getting it running

Difficulty · hard Time to first run · 1day+

Requires a YubiKey hardware device and booting a temporary air-gapped Linux environment for secure key generation.

In plain English

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.

Copy-paste prompts

Prompt 1
Walk me through setting up a YubiKey for SSH authentication on macOS following the drduh yubikey-guide approach.
Prompt 2
How do I configure Git to sign commits using a GPG key stored on a YubiKey?
Prompt 3
Help me set up GPG key generation on an air-gapped Debian Live USB, then transfer the keys to my YubiKey.
Prompt 4
I want to use my YubiKey to sign emails in Thunderbird, what GPG setup steps do I need from the yubikey-guide?
Open on GitHub → Explain another repo

← drduh on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.