Last updated: March 16, 2026

Managing PGP keys securely is a critical skill for developers and power users who rely on encryption for communication, code signing, or data protection. Storing your private keys on a hardware security key like YubiKey provides protection against malware, physical theft, and remote attacks that could compromise software-based key storage. This guide covers the complete workflow for setting up GnuPG with a hardware security key.

Table of Contents

Prerequisites

Before you begin, gather the following:

Install GnuPG on macOS:

brew install gnupg

On Ubuntu/Debian:

sudo apt install gnupg

On Windows, download Gpg4win from the official GnuPG website.

Step 2 - Initializing Your Hardware Security Key

The first step involves configuring the OpenPGP application on your YubiKey. This process sets up the card with your preferences and creates three slots for different key types.

Insert your YubiKey and verify it’s detected:

gpg --card-status

If you see card information, GnuPG recognizes your YubiKey. Now configure basic settings. Set the admin PIN (default: 12345678) and user PIN (default: 123456) to strong, unique values:

gpg --card-edit
admin
passwd

Select option 3 to change the Admin PIN, then option 1 to change the User PIN. The User PIN is what you’ll enter daily; the Admin PIN is required for key management tasks.

Configure cardholder information:

gpg --card-edit
name (enter your name)
lang (your language code, e.g., en)

Step 3 - Generate Keys Directly on the YubiKey

For maximum security, generate your encryption and signing keys directly on the hardware device. This ensures the private key material never exists in software memory.

Generate an encryption key:

gpg --card-edit
generate

Choose “Your key does not expire” or set an expiration period (3-5 years is common for encryption keys). Enter your name and email. When asked about backup, choose not to create a backup, Hardware keys cannot be backed up, which is the point.

For the signing key, repeat the process but note that you’ll use this for code signing and git commits.

The YubiKey generates keys using its secure random number generator. This process takes several minutes as the hardware performs cryptographic operations.

Migrating Existing Keys to Hardware

If you already have PGP keys, you can migrate the private key material to your YubiKey while keeping the public key on your system. This preserves your identity while securing the private portion.

Export your existing private key:

gpg --export-secret-keys your@email.com > private.key

Import and move to YubiKey:

gpg --edit-key your@email.com
key 1
keytocard

Repeat for each subkey. After migration, delete the software copy:

gpg --delete-secret-keys your@email.com

Keep a paper backup of your revocation certificate in a secure location before deleting software keys.

Step 4 - Use Your Hardware-Protected Keys

Once your keys are on the YubiKey, using them works similarly to software keys, with one important difference: every operation requires physical touch confirmation.

Encrypt a file:

gpg --encrypt --recipient your@email.com document.txt

Sign a file:

gpg --sign document.txt

For git commit signing with YubiKey:

git config --global user.signingkey YOUR_KEY_ID
git commit -S -m "Your commit message"

When you run these commands, the YubiKey will blink, indicating it needs touch confirmation. Place your finger on the contact or tap the button, depending on your YubiKey model.

Configure touch policies if needed. The YubiKey can require touch for signing, encryption, or authentication:

gpg --card-edit
admin
forcesignature

Step 5 - Manage Multiple Keys and Backups

For professional use, consider a backup strategy. Generate a revocation certificate before transferring keys:

gpg --output revocation_certificate.asc --gen-revoke your@email.com

Store this certificate physically (secure safe or paper) since it revokes your identity if keys are lost.

If you need to use your keys across multiple computers, export only the public key:

gpg --armor --export your@email.com > public_key.asc

Import on other machines:

gpg --import public_key.asc

The private key remains on your YubiKey, portable between any computer with GnuPG installed.

Troubleshooting Common Issues

YubiKey not detected by GnuPG - Ensure the OpenPGP application is enabled. Use YubiKey Manager to check:

ykman openpgp info

PIN blocked - After 3 failed attempts, the User PIN blocks. Use the Admin PIN to unblock:

gpg --card-edit
admin
passwd

Select option 2 to unblock the PIN.

Key operations fail silently - Some YubiKey models require touch policy configuration. Verify:

gpg --card-status

Look for signature key usage flags indicating whether touch is required.

Security Considerations and Best Practices

Hardware security keys provide excellent protection but require proper operational security. Never share your Admin PIN, this allows key deletion and reset. Store your revocation certificate offline in a secure physical location.

Consider a secondary YubiKey for redundancy. Configure the same keys on a backup device using the same key generation process.

For high-threat scenarios, use an air-gapped computer for key generation, then transfer to YubiKey in a controlled environment. This prevents key exposure during the creation process.

Test your setup regularly. Verify you can decrypt messages, sign commits, and access your keys after system reboots. Document your recovery procedures, lost YubiKeys without revocation certificates create permanent identity loss.

Frequently Asked Questions

How long does it take to manage pgp keys securely using hardware security key?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Is this approach secure enough for production?

The patterns shown here follow standard practices, but production deployments need additional hardening. Add rate limiting, input validation, proper secret management, and monitoring before going live. Consider a security review if your application handles sensitive user data.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.

Related Articles