How do I set up YubiKey for SSH on Windows?

The guide includes Windows-specific instructions using GnuPG and PuTTY: install required software, configure scdaemon.conf and gpg-agent.conf, and export the SSH public key from GnuPG. It notes that WSL requires additional setup with tools like weasel-pageant for agent forwarding.

YubiKey vs software keys for Git commit signing?

YubiKey provides hardware-backed security where keys are non-exportable, reducing theft risk, but requires physical touch and PIN entry. Software keys are easier to set up and manage but are vulnerable to extraction from filesystems. The guide details Git integration with YubiKey for signing commits and tags.

How to backup YubiKey keys securely?

Backup involves encrypting the Certify key and subkeys using LUKS on portable storage, with step-by-step commands for Linux and OpenBSD. The guide recommends multiple backups on separate devices and using Paperkey for physical copies to prevent data loss.

Why is my YubiKey not detected by GnuPG?

Common issues include missing pcscd service, incorrect scdaemon.conf settings, or driver problems. The troubleshooting section advises checking gpg --card-status, ensuring proper software installation, and adjusting configuration files like disabling CCID if needed.

How to use YubiKey for email encryption in Thunderbird?

Configure Thunderbird with Enigmail or Mailvelope, import the public key from YubiKey, and set up GnuPG integration. The guide provides specific steps for Thunderbird, Mutt, and Mailvelope, including agent forwarding for remote decryption.

Can I use multiple YubiKeys with the same identity?

Yes, the guide covers using multiple YubiKeys by managing key stubs in GnuPG. It explains how to transfer subkeys to additional YubiKeys and use scripts to handle serial number conflicts, but notes that each YubiKey can only hold one set of subkeys per identity.

Open-Awesome

YubiKey Guide

MITHTML

A community guide to using YubiKey as a smart card for GnuPG and SSH with hardware-secured cryptographic keys.

Visit Website GitHub

12.4k stars1.2k forks0 contributors

What is YubiKey Guide?

YubiKey-Guide is a comprehensive community-driven tutorial for configuring YubiKey hardware security keys for use with GnuPG and SSH. It provides step-by-step instructions to generate and store cryptographic keys on YubiKey, enabling hardware-backed encryption, signing, and authentication. The guide solves the problem of securing sensitive keys by moving them to a non-exportable hardware device, reducing the risk of key theft or compromise.

Target Audience

Security-conscious developers, system administrators, and privacy advocates who want to enhance their cryptographic key security using hardware tokens. It's particularly useful for those managing SSH access, signing Git commits, or using encrypted email.

Value Proposition

Developers choose this guide because it offers a meticulously detailed, platform-agnostic approach to YubiKey setup with an emphasis on security best practices. Unlike fragmented online resources, it provides a complete, reproducible workflow from key generation to daily usage, including advanced topics like agent forwarding and multi-key management.

Overview

Community guide to using YubiKey for GnuPG and SSH - protect secrets with hardware crypto.

Use Cases

Best For

Securing SSH authentication with hardware-backed keys
Signing Git commits and tags with a YubiKey
Encrypting and decrypting sensitive files using GnuPG
Setting up hardware-based email encryption and signing
Managing cryptographic keys across multiple operating systems
Implementing a hardware security token for developer workflows

Not Ideal For

Users seeking a quick, one-click setup for hardware token integration
Environments where offline key management and air-gapped systems are impractical
Teams without dedicated resources for ongoing key expiration and backup maintenance
Projects requiring support for non-YubiKey hardware security tokens

Pros & Cons

Pros

Hardware-Backed Security

Stores encryption, signature, and authentication keys on YubiKey, making them non-exportable and resistant to software-based extraction, as emphasized in the guide's security-first philosophy.

Cross-Platform Compatibility

Provides detailed setup instructions for Linux, macOS, OpenBSD, Windows, and NixOS, including environment preparation and software installation steps for each.

Comprehensive Workflow Coverage

Guides users from key generation and backup to daily use with SSH, Git signing, and email encryption, including advanced topics like agent forwarding and multi-key management.

Security Best Practices

Recommends air-gapped or hardened environments for key generation, promotes key expiration, and includes secure backup methods using LUKS encryption, reducing risk exposure.

Cons

Complex and Manual Setup

Requires creating ephemeral environments, managing multiple passphrases and PINs, and executing numerous command-line steps, which increases the risk of user error and is time-consuming.

Dependence on Offline Management

The Certify key must be kept offline and accessed only in secure environments for key updates, adding operational overhead and potential recovery challenges if backups are lost.

Limited Hardware Flexibility

Exclusively tailored for YubiKey devices (excluding FIDO-only models), so it doesn't support alternative hardware tokens, locking users into a specific vendor ecosystem.

Configuration Fragility

Agent forwarding and multi-platform setup involve intricate configuration files (e.g., gpg-agent.conf, SSH config), with noted troubleshooting issues like socket errors and compatibility quirks across OS versions.

Frequently Asked Questions

Related Projects

OpenSK

OpenSK is an open-source implementation for security keys written in Rust that supports both FIDO U2F and FIDO2 standards.

Stars3,385

Forks331

Last commit1 month ago

Getting started with security keys

A practical guide to stay safe online and prevent phishing with FIDO2, WebAuthn and security keys

Stars0

Forks0

Last commit

Webauthn and security keys

Describe how authentication works with security keys, details the protocols, and how they articulates with WebAuthn. Key takeaway: “There is no way to create a U2F key with webauthn however. (…) So complete the transition to webauthn of your login process first, then transition registration.”