OpenPGP Setup

Posted on 30 2026

GnuPG is installed by default on Kubuntu. The version shipped with Kubuntu 24.04 LTS is GnuPG 2.4.x. The source material this series draws on was written for GnuPG 2.2.x, and there are meaningful differences between the two worth knowing about before you start configuring anything. This page covers the current version throughout.

Verify what you have installed:

gpg --version

The output should confirm GnuPG 2.4.x and list the supported algorithms. If it does not, check that your system is fully updated before continuing.

Directory structure

GnuPG stores its configuration, keyrings, and agent socket in ~/.gnupg. The permissions on this directory are strict by design. If they are wrong, GnuPG will complain loudly. Verify them:

chmod 700 ~/.gnupg

Files inside should be 600:

chmod 600 ~/.gnupg/*

GPG configuration

Create or open ~/.gnupg/gpg.conf. The configuration below reflects current best practice for GnuPG 2.4.x, with annotations explaining the less obvious settings:

#
# Options for gpg (GnuPG) 2.4.x
# See 'man gpg' for full option documentation
#

#--------------------------------------
# Default key
#--------------------------------------

# Set your default signing key. Replace with your actual key ID once generated.
# The 0x prefix tells GnuPG this is a hex key ID.
# default-key 0x0123456789ABCDEF

#--------------------------------------
# Behaviour
#--------------------------------------

# Use the longer, more precise key ID format
keyid-format 0xlong

# Display key fingerprints
with-fingerprint

# Show validity of UIDs in key listings
verify-options show-uid-validity
list-options show-uid-validity

# When making a data signature, prompt for an expiration time
ask-cert-expire
ask-sig-expire

# Disable comment string in clear text signatures and ASCII armored messages
no-comments

# Disable inclusion of the version string in ASCII armored output
no-emit-version

# Display the fingerprint of the signing key when listing signatures
sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g

# Use standard GnuPG compliance mode
compliance gnupg

#--------------------------------------
# Algorithms and ciphers
#--------------------------------------

# Preference list for symmetric ciphers, digests, and compression
# Listed in order of preference; GnuPG will use the first algorithm
# supported by all recipients
personal-cipher-preferences AES256 AES192 AES
personal-digest-preferences SHA512 SHA384 SHA256
personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed

# Default preferences for new keys
default-preference-list SHA512 SHA384 SHA256 AES256 AES192 AES ZLIB BZIP2 ZIP Uncompressed

# Message digest algorithm used for signing keys
cert-digest-algo SHA512

# Disable SHA-1 based signatures (considered weak)
weak-digest SHA1

#--------------------------------------
# Key server
#--------------------------------------

# Key server to use for key lookups and uploads
# keys.openpgp.org is recommended over the old SKS pool
keyserver hkps://keys.openpgp.org

# Key server options
keyserver-options no-honor-keyserver-url
keyserver-options include-revoked

GPG agent configuration

The GPG agent handles passphrase caching and smart card operations. It runs as a background daemon for the duration of your desktop session.

Create or open ~/.gnupg/gpg-agent.conf:

#
# Options for gpg-agent (GnuPG) 2.4.x
# See 'man gpg-agent' for full option documentation
#

#--------------------------------------
# Passphrase caching
#--------------------------------------

# How long a cache entry is valid after last use, in seconds
# Default: 600 (10 minutes)
default-cache-ttl 3600

# Maximum time a cache entry is valid regardless of use, in seconds
# Default: 7200 (2 hours)
max-cache-ttl 86400

# SSH passphrase cache TTL
default-cache-ttl-ssh 3600
max-cache-ttl-ssh 86400

#--------------------------------------
# Pinentry
#--------------------------------------

# Use the Qt pinentry for Kubuntu / KDE Plasma
# This integrates with KWallet and uses native KDE dialogs
pinentry-program /usr/bin/pinentry-qt

#--------------------------------------
# SSH support
#--------------------------------------

# Enable the OpenSSH Agent protocol
# This allows GPG to act as an SSH agent using your authentication subkey
enable-ssh-support

Note the pinentry setting. The source material this series is based on specifies pinentry-gnome3, which is the correct choice for a GNOME desktop. On Kubuntu, pinentry-qt is the right one: it uses native KDE dialogs and integrates properly with KWallet. Install it if not already present:

sudo apt install pinentry-qt

Dirmngr configuration

Dirmngr handles network operations for GnuPG: key server lookups, certificate revocation list downloads, and OCSP checks. It runs as a companion daemon to gpg-agent.

Create or open ~/.gnupg/dirmngr.conf:

#
# Options for dirmngr (GnuPG) 2.4.x
# See 'man dirmngr' for full option documentation
#

# Use the modern HKPS (HTTPS) key server
keyserver hkps://keys.openpgp.org

# Enable OCSP checking for X.509 certificates
enable-ocsp

Shell environment

GnuPG needs to know which terminal or display it is operating from in order to present passphrase prompts correctly. Add the following to your ~/.bashrc:

# Let gpg-agent know which terminal it has been called from
export GPG_TTY=$(tty)

# Set your key ID for use in scripts and commands
# Replace with your actual key ID once generated
# export GPGKEY=0x0123456789ABCDEF

If you are using a different shell, add the same lines to the appropriate configuration file (~/.zshrc for Zsh, etc.).

Reload your shell configuration:

source ~/.bashrc

Starting and reloading the agent

The GPG agent starts automatically when you first use GPG. If you have changed the configuration and need to reload it without restarting your session:

gpgconf --reload gpg-agent

To kill all running GnuPG daemons and force a clean restart:

gpgconf --kill all

The agent will restart automatically on the next GPG operation.

Verifying the configuration

Check that the agent is running and the socket is in the expected location:

gpgconf --list-dirs agent-socket

Check that SSH support is active:

echo $SSH_AUTH_SOCK

If SSH support is enabled in the agent configuration, this should point to a GPG agent socket rather than the default SSH agent socket. If it is empty or points to the wrong socket, check that enable-ssh-support is in gpg-agent.conf and that the agent has been reloaded.

Changes to gpg-agent.conf require a reload or restart of the agent to take effect. Changes to gpg.conf take effect immediately on the next GPG invocation.