Skip to content

GPG & Hardware Security Keys Guide

GPG Overview

GNU Privacy Guard (GPG) is a free implementation of the OpenPGP standard for encrypting and signing data. It provides cryptographic privacy and authentication for data communication and is widely used for email encryption, file signing, and SSH authentication.

Hardware Security Keys

This guide includes specific instructions for Nitrokey and other OpenPGP smart cards, which provide enhanced security by storing private keys in hardware.

Basic GPG Operations

Smart Card Management

Smart Card Operations
gpg --card-status  #(1)!
gpg --export-ssh-key keyID  #(2)!
gpg --armor --export keyID > pubkey.asc  #(3)!
  1. Display information about connected OpenPGP smart card (Nitrokey, YubiKey, etc.)
  2. Export SSH public key from GPG key for SSH authentication
  3. Export public key in ASCII-armored format for sharing

Hardware Keys

Smart cards like Nitrokey or YubiKey provide enhanced security by storing private keys in tamper-resistant hardware.

Setting up on New System

When moving to a new system with your hardware key:

Import and Setup
gpg --import pubkey.asc  #(1)!
gpg --card-status  #(2)!
  1. Import your public key from the exported file
  2. Verify the smart card is detected and shows your key information

Key Import

You only need to import the public key - the private key remains secure on your hardware device.

GPG Agent as SSH Agent

Configure GPG to handle SSH authentication using your hardware key:

GPG Agent Configuration
vim .gnupg/gpg-agent.conf

Add these lines to the configuration file:

gpg-agent.conf Content
enable-ssh-support
pinentry-program /usr/bin/pinentry-qt

Configuration Options

  • enable-ssh-support - Enables SSH support in GPG agent
  • pinentry-program - Sets GUI pinentry program for password prompts
Enable Services and Environment
systemctl --user enable --now /usr/lib/systemd/user/gpg-agent*  #(1)!
  1. Enables and starts GPG agent services

Add to your shell configuration (.bashrc, .zshrc):

Shell Environment
export SSH_AUTH_SOCK="/run/user/$(id -u)/gnupg/S.gpg-agent.ssh"  #(1)!

  1. Sets SSH authentication socket to use GPG agent

Result

After configuration, SSH will use your GPG key for authentication, leveraging your hardware security key.

Web Key Directory (WKD)

Publish Your Key

Make your public key discoverable via your domain:

Prepare WKD Structure
mkdir openpgpkey  #(1)!
gpg --list-options show-only-fpr-mbox -k keyID | /usr/lib/gnupg/gpg-wks-client -v --install-key  #(2)!
  1. Creates directory for OpenPGP key structure
  2. Generates the proper WKD directory structure and key file

WKD Structure

Publish the generated structure to: https://yourdomain.com/.well-known/openpgpkey/yourdomain.com/hu/

Learn More About WKD

  • Web Key Directory Info

    Comprehensive information about OpenPGP Web Key Directory

    MetaCode WKD Guide

Retrieving Public Keys

From Web Key Directory

WKD Key Lookup
gpg --locate-key user@example.com  #(1)!
  1. Automatically discovers and imports public key via WKD

Automatic Discovery

WKD allows automatic key discovery based on email addresses, making key exchange seamless.

From Key Servers

Modern Key Server
echo "keyserver hkps://keys.openpgp.org" >> ~/.gnupg/gpg.conf  #(1)!
gpg --auto-key-locate keyserver --locate-keys user@example.com  #(2)!
  1. Sets modern, privacy-respecting keyserver as default
  2. Locates and imports key from keyserver
Legacy SKS Network
gpg --keyserver pool.sks-keyservers.net --recv-keys keyID  #(1)!
  1. Retrieves key from legacy SKS keyserver network

SKS Network Deprecated

The SKS keyserver network has security issues and is largely deprecated. Use keys.openpgp.org instead.

Security Best Practices

Key Management Best Practices

  • Always backup your keys securely before hardware setup
  • Use strong passphrases for key protection
  • Verify fingerprints when importing keys from others
  • Use hardware security keys for enhanced protection

Troubleshooting

Useful Diagnostic Commands
gpg --version          # Check GPG version
gpg --list-keys        # List all public keys
gpg --list-secret-keys # List private keys
gpgconf --list-dirs    # Show GPG directories