GnuPG Cheat Sheet

The gpg command does a few distinct jobs:

manage OpenPGP keys, encrypt data to recipients
decrypt data for key holders, and
create or verify signatures.

Most common use case of GPG includes verifying an companion .asc file of a software release against its develoer’s public key, or signing your Git commits and tags with your secret key.

Installation #

# archlinux
# gnupg and pinentry should already be installed on your system as it is a dependency of pacman.

# debian/ubuntu
sudo apt install gnupg pinentry-curses pinentry-gtk-2

# redhat/fedora/centos
sudo dnf install gnupg2 pinentry  # fedora/rhel 8+
sudo yum install gnupg2 pinentry  # rhel 7

# mac
brew install gnupg pinentry-mac

GPG uses a program called pinentry to prompt for passphrases when unlocking private keys. The key design principle is separation: pinentry runs as a separate process, so the application requesting decryption never sees your passphrase - only the GPG agent does. This provides a trusted path between you and the crypto operations. Multiple variants exist: pinentry-curses (CLI), pinentry-gtk (GTK), pinentry-qt (Qt), pinentry-mac (macOS native), and others. You can configure which one to use in ~/.gnupg/gpg-agent.conf with the pinentry-program directive.

Key management #

“Armor” means base64 version of binary data to make it easy for copy-and-paste.

# Generate a new key 
gpg --full-generate-key

# import a public key so GPG knows who he is
gpg --import public-or-private-key.asc

# export a public key
gpg --export you@example.com            # (binary key to stdout)
gpg --export --armor you@example.com    # (ASCII armor to be copied around)

# Export a secret key (you know the danger)
gpg --export-secret-keys you@example.com            # (binary key to stdout)
gpg --armor --export-secret-keys you@example.com    # (ASCII armor to be copied around)

# List locals keys
gpg --list-keys                             # public
gpg --list-secret-keys --keyid-format=long  # public-secret key pair

# Edit key metadata, expiration, trust, or subkeys
gpg --edit-key alice@example.com

# Delete a public key from your local keyring
gpg --delete-key alice@example.com

# When removing one of your own identities,
# delete the secret key first, then the public key
gpg --delete-secret-key you@example.com
gpg --delete-key you@example.com

# Show the fingerprint of a key
# the short key ID is not enough for identity verification:
gpg --fingerprint alice@example.com

Encryption / Decryption #

# Encrypt a file for one recipient
# writes secret.txt.gpg by default
gpg --encrypt --recipient alice@example.com 

# Encrypt a file for multiple recipients
# every intended reader must be listed
gpg --encrypt \
  --recipient alice@example.com \
  --recipient bob@example.com \
  report.pdf

# Decrypt a file to stdout
gpg --decrypt secret.txt.gpg

# Decrypt to a specific output path
gpg --output secret.txt --decrypt secret.txt.gpg

Sign and Verify #

# Create a detached signature
# use this when the receiver already has the original file
# writes release.tar.gz.asc
gpg --detach-sign --armor release.tar.gz

# Verify a detached signature
gpg --verify release.tar.gz.asc release.tar.gz

# Create a cleartext signature
# useful for text that should remain human-readable
gpg --clearsign notes.txt

# Verify a clearsigned file
gpg --verify notes.txt.asc

Misc maintenance commands #


# Reload the agent after changing configuration
gpgconf --kill gpg-agent

Use with standard input and output #

# Encrypt piped data and emit ASCII armor
printf '%s\n' 'hello' | gpg --armor --encrypt --recipient alice@example.com

# Sign piped data without creating an input file
printf '%s\n' 'release approved' | gpg --clearsign