GPG Setup and Configuration

Note

Throughout this documentation we assume GnuPG version 2.2.x as pre-installed in Ubuntu 20.04.

GnuPG Configuration

The available configuration options can be found on the gpg man page.

Open the file .gnupg/gpg.conf in you home directory and change, add or uncomment as follows:

#
# Options for gpg (GnuPG) 2.2.12
# See the 'OPTIONS' section of 'man gpg'
#   https://manpages.ubuntu.com/manpages/bionic/man1/gpg.1.html#options


#--------------------------------------
# Default Private Key
#--------------------------------------

# Use name as the default key to sign with. If this option is not used, the
# default key is the first key found in the secret keyring. Note that -u or
# --local-user overrides this option. This option may be given multiple times.
# In this case, the last key for which a secret key is available is used. If
# there is no secret key available for any of the specified values, GnuPG will
# not emit an error message but continue as if this option wasn't given.
default-key 0x0123456789ABCDEF

# Use name as default recipient if option --recipient is not used and don't ask
# if this is a valid one. name must be non-empty.
#default-recipient name

# Use the default key as default recipient if option --recipient is not used and
# don't ask if this is a valid one. The default key is the first one from the
# secret keyring or the one set with --default-key.
default-recipient-self

# Reset --default-recipient and --default-recipient-self.
#no-default-recipient


#--------------------------------------
# List Options
#--------------------------------------

# This is a space or comma delimited string that gives options used when listing
# keys and signatures.
#
# That is, --list-keys, --check-signatures, --list-public-keys,
# --list-secret-keys, and the --edit-key functions.
#
# Options can be prepended with a no- (after the two dashes) to give the
# opposite meaning. The options are:
#   show-photos
#       Causes --list-keys, --check-signatures, --list-public-keys, and
#       --list-secret-keys to display any photo IDs attached to the key.
#       Defaults to no. See also --photo-viewer. Does not work with
#       --with-colons: see --attribute-fd for the appropriate way to get photo
#       data for scripts and other frontends.
#   show-usage
#       Show usage information for keys and subkeys in the standard key listing.
#       This is a list of letters indicating the allowed usage for a key
#       (E=encryption, S=signing, C=certification, A=authentication). Defaults
#       to yes.
#   show-policy-urls
#       Show policy URLs in the --check-signatures listings. Defaults to no.
#   show-notations, show-std-notations, show-user-notations
#       Show all, IETF standard, or user-defined signature notations in the
#       --check-signatures listings. Defaults to no.
#   show-keyserver-urls
#       Show any preferred keyserver URL in the --check-signatures listings.
#       Defaults to no.
#   show-uid-validity
#       Display the calculated validity of user IDs during key listings.
#       Defaults to yes.
#   show-unusable-uids
#       Show revoked and expired user IDs in key listings. Defaults to no.
#   show-unusable-subkeys
#       Show revoked and expired subkeys in key listings. Defaults to no.
#   show-keyring
#       Display the keyring photoration dates (if any) during --check-signatures
#       listings. Defaults to no.
#   show-sig-subpackets
#       Include signature subpackets in the key listing. This option can take an
#       optional argument list of the subpackets to list. If no argument is
#       passed, list all subpackets. Defaults to no. This option is only
#       meaningful when using --with-colons along with --check-signatures.
#   show-only-fpr-mbox
#       For each valid user-id which also has a valid mail address print only
#       the fingerprint and the mail address.
#
list-options show-uid-validity


#--------------------------------------
# Verify Options
#--------------------------------------

# This is a space or comma delimited string that gives options used when
# verifying signatures. Options can be prepended with a `no-' to give the
# opposite meaning. The options are:
#   show-photos
#       Display any photo IDs present on the key that issued the signature.
#       Defaults to no. See also --photo-viewer.
#   show-policy-urls
#       Show policy URLs in the signature being verified. Defaults to yes.
#   show-notations, show-std-notations, show-user-notations
#       Show all, IETF standard, or user-defined signature notations in the
#       signature being verified. Defaults to IETF standard.
#   show-keyserver-urls
#       Show any preferred keyserver URL in the signature being verified.
#       Defaults to yes.
#   show-uid-validity
#       Display the calculated validity of the user IDs on the key that issued
#       the signature. Defaults to yes.
#   show-unusable-uids
#       Show revoked and expired user IDs during signature verification.
#       Defaults to no.
#   show-primary-uid-only
#       Show only the primary user ID during signature verification. That is all
#       the AKA lines as well as photo Ids are not shown with the signature
#       verification status.
#   pka-lookups
#       Enable PKA lookups to verify sender addresses. Note that PKA is based on
#       DNS, and so enabling this option may disclose information on when and
#       what signatures are verified or to whom data is encrypted. This is
#       similar to the "web bug" described for the --auto-key-retrieve option.
#   pka-trust-increase
#       Raise the trust in a signature to full if the signature passes PKA
#       validation. This option is only meaningful if pka-lookups is set.
verify-options show-policy-urls show-std-notations show-keyserver-urls show-uid-validity show-primary-uid-only pka-lookups pka-trust-increase

# Use this program to display photo user IDs
#photo-viewer xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN


#--------------------------------------
# Charset Options
#--------------------------------------

# Display output UTF-8 encoded
display-charset utf-8

# Assume that command line arguments are given as UTF-8 strings.
utf8-strings


#--------------------------------------
# Certification Level
#--------------------------------------

# When making a key signature, prompt for a certification level. If this option
# is not specified, the certification level used is set via
# --default-cert-level. See --default-cert-level for information on the specific
# levels and how they are used. --no-ask-cert-level disables this option.
# This option defaults to no.
ask-cert-level
#no-ask-cert-level

# The default to use for the check level when signing a key:
#
#   0 means you make no particular claim as to how carefully you verified the
#   key.
#   1 means you believe the key is owned by the person who claims to own it but
#   you could not, or did not verify the key at all. This is useful for a
#   "persona" verification, where you sign the key of a pseudonymous user.
#   2 means you did casual verification of the key. For example, this could mean
#   that you verified the key fingerprint and checked the user ID on the key
#   against a photo ID.
#   3 means you did extensive verification of the key. For example, this could
#   mean that you verified the key fingerprint with the owner of the key in
#   person, and that you checked, by means of a hard to forge document with a
#   photo ID (such as a passport) that the name of the key owner matches the
#   name in the user ID on the key, and finally that you verified (by exchange
#   of email) that the email address on the key belongs to the key owner.
#
# Note that the examples given above for levels 2 and 3 are just that: examples.
# In the end, it is up to you to decide just what "casual" and "extensive" mean
# to you.
# This option defaults to 0 (no particular claim).
#default-cert-level 0

# When building the trust database, treat any signatures with a certification
# level below this as invalid. Defaults to 2, which disregards level 1
# signatures. Note that level 0 "no particular claim" signatures are always
# accepted.
#min-cert-level 2

# Assume that the specified key (which must be given as a full 8 byte key ID) is
# as trustworthy as one of your own secret keys. This option is useful if you
# don't want to keep your secret keys (or one of them) online but still want to
# be able to check the validity of a given recipient's or signator's key.
#trusted-key long key ID


#--------------------------------------
# Trust model
#--------------------------------------

# Set what trust model GnuPG should follow.
trust-model tofu+pgp

# Number of completely trusted users to introduce a new key signer.
# Defaults is: 1
#completes-needed 1

# Number of marginally trusted users to introduce a new key signer.
# Defaults in: 3
#marginals-needed 3

# The default TOFU policy. For more information about the meaning of this
# option, see: trust-model-tofu.
# Defaults is: auto
tofu-default-policy unknown


#--------------------------------------
# Key retrieval and methods
#--------------------------------------

# Automatically locate and retrieve keys as needed.
# The default is "local,wkd".

# Locate the key using the local keyrings. This mechanism allows the user to
# select the order a local key lookup is done. Thus using '--auto-key-locate
# local' is identical to --no-auto-key-locate.
auto-key-locate local

# Locate a key using the Web Key Directory protocol.
# Available since GnuPG 2.1.12
auto-key-locate wkd

# Locate a key using DNS PKA.
auto-key-locate pka

# Locate a key using DANE, as specified in draft-ietf-dane-openpgpkey-05.txt.
# Available since GnuPG 2.2.1
auto-key-locate dane

# Locate a key using DNS CERT, as specified in RFC-4398.
auto-key-locate cert

# Locate a key using whatever keyserver is defined using the --keyserver option.
auto-key-locate keyserver

# Using DNS Service Discovery, check the domain in question for any LDAP
# keyservers to use. If this fails, attempt to locate the key using the PGP
# Universal method of checking 'ldap://keys.(thedomain)'.
auto-key-locate ldap

# The option --no-auto-key-locate or the mechanism "clear" resets the list.
#no-auto-key-locate
#auto-key-locate clear

# Enable automatic retrieving of unknown keys when verifying signatures.
auto-key-retrieve


#--------------------------------------
# Key-ID Display Option
#--------------------------------------

# Always display long key IDs. Short key IDs can be spoofed.
# Default: short
keyid-format 0xlong


#--------------------------------------
# Key Server Options
#--------------------------------------

# This is a space or comma delimited string that gives options for the
# keyserver. Options can be prefixed with a `no-' to give the opposite meaning.
# Valid import-options or export-options may be used here as well to apply to
# importing (--recv-key) or exporting (--send-key) a key from a keyserver. While
# not all options are available for all keyserver types, some common options
# are:
#   include-revoked
#       When searching for a key with --search-keys, include keys that are
#       marked on the keyserver as revoked. Note that not all keyservers
#       differentiate between revoked and unrevoked keys, and for such
#       keyservers this option is meaningless. Note also that most keyservers do
#       not have cryptographic verification of key revocations, and so turning
#       this option off may result in skipping keys that are incorrectly marked
#       as revoked.
#   include-disabled
#       When searching for a key with --search-keys, include keys that are
#       marked on the keyserver as disabled. Note that this option is not used
#       with HKP keyservers.
#   honor-keyserver-url
#       When using --refresh-keys, if the key in question has a preferred
#       keyserver URL, then use that preferred keyserver to refresh the key
#       from. In addition, if auto-key-retrieve is set, and the signature being
#       verified has a preferred keyserver URL, then use that preferred
#       keyserver to fetch the key from. Note that this option introduces a "web
#       bug": The creator of the key can see when the keys is refreshed. Thus
#       this option is not enabled by default.
#   honor-pka-record
#       If --auto-key-retrieve is used, and the signature being verified has a
#       PKA record, then use the PKA information to fetch the key. Defaults to
#       "yes".
#   include-subkeys
#      When receiving a key, include subkeys as potential targets. Note that
#      this option is not used with HKP keyservers, as they do not support
#      retrieving keys by subkey id.
#   timeout
#       Tell the keyserver helper program how long (in seconds) to try and
#       perform a keyserver action before giving up. Note that performing
#       multiple actions at the same time uses this timeout value per action.
#       For example, when retrieving multiple keys via --receive-keys, the
#       timeout applies separately to each key retrieval, and not to the
#       --receive-keys command as a whole. Defaults to 30 seconds.
keyserver-options honor-keyserver-url honor-pka-record include-subkeys


#--------------------------------------
# Output Display Options
#--------------------------------------

# Suppress the initial copyright message.
no-greeting


#--------------------------------------
# Key related options
#--------------------------------------

# Encrypt for user id name. Same as --recipient but this one is intended for use
# in the options file and may be used with your own user-id as an
# "encrypt-to-self". These keys are only used when there are other recipients
# given either by use of --recipient or by the asked user id. No trust checking
# is performed for these user ids and even disabled keys can be used.
#encrypt-to name

# Encrypt for user ID name, but hide the key ID of this user's key. Same as
# --hidden-recipient but this one is intended for use in the options file and
# may be used with your own user-id as a hidden "encrypt-to-self". These keys
# are only used when there are other recipients given either by use of
# --recipient or by the asked user id. No trust checking is performed for these
# user ids and even disabled keys can be used.
#hidden-encrypt-to name

# For hidden recipients GPG needs to know the keys to use for trial decryption.
# The key set with --default-key is always tried first, but this is often not
# sufficient. This option allows setting more keys to be used for trial
# decryption. Although any valid user-id specification may be used for name it
# makes sense to use at least the long keyid to avoid ambiguities. Note that
# gpg-agent might pop up a pinentry for a lot keys to do the trial decryption.
# If you want to stop all further trial decryption you may use close-window
# button instead of the cancel button.
try-secret-key 0x0123456789ABCDEF


#--------------------------------------
# Input and Output
#--------------------------------------

# This filter drops the selected key signatures on user ids. Self-signatures are
# not considered. Currently only implemented for --import-filter.
import-filter drop-sig="expired=true"

# PGP Global Directory Verification Key <do-not-reply@keyserver.pgp.com>
import-filter drop-sig="uid=0x9710B89BCA57AD7C"

# Include the fingerprint when listing keys
# Same as the command --fingerprint but changes only the format of the output
# and may be used together with another command.
with-fingerprint

# If a fingerprint is printed for the primary key, this option forces printing
# of the fingerprint for all subkeys. This could also be achieved by using the
# --with-fingerprint twice but by using this option along with keyid-format
# "none" a compact fingerprint is printed.
#with-subkey-fingerprint


#--------------------------------------
# OpenPGP protocol specific options
#--------------------------------------

# List of personal ciphers algorithms
# Set the list of personal cipher preferences to string. Use gpg --version to
# get a list of available algorithms, and use none to set no preference at all.
# This allows the user to safely override the algorithm chosen by the recipient
# key preferences, as GPG will only select an algorithm that is usable by all
# recipients. The most highly ranked cipher in this list is also used for the
# --symmetric encryption command.
personal-cipher-preferences AES256 AES192 AES CAST5

# List of personal digest algorithms
# Set the list of personal digest preferences to string. Use gpg --version to
# get a list of available algorithms, and use none to set no preference at all.
# This allows the user to safely override the algorithm chosen by the recipient
# key preferences, as GPG will only select an algorithm that is usable by all
# recipients. The most highly ranked digest algorithm in this list is also used
# when signing without encryption (e.g. --clear-sign or --sign).
personal-digest-preferences SHA512 SHA384 SHA256 SHA224

# List of personal compression algorithms
# Set the list of personal compression preferences to string. Use gpg --version
# to get a list of available algorithms, and use none to set no preference at
# all. This allows the user to safely override the algorithm chosen by the
# recipient key preferences, as GPG will only select an algorithm that is usable
# by all recipients. The most highly ranked compression algorithm in this list
# is also used when there are no recipient keys to consider (e.g. --symmetric).
personal-compress-preferences BZIP2 ZLIB ZIP Uncompressed

# Use name as the cipher algorithm for symmetric encryption with a passphrase if
# --personal-cipher-preferences and --cipher-algo are not given.
# The default is AES-128
s2k-cipher-algo AES256

# Use name as the digest algorithm used to mangle the passphrases for symmetric
# encryption.
# The default is SHA-1
s2k-digest-algo SHA256


#--------------------------------------
# Compliance options
#--------------------------------------

# These options control what GnuPG is compliant to. Only one of these options
# may be active at a time. Note that the default setting of this is nearly
# always the correct one. See the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
# section below before using one of these options.

# Use standard GnuPG behavior. This is essentially OpenPGP behavior (see
# --openpgp), but with some additional workarounds for common compatibility
# problems in different versions of PGP. This is the default option, so it is
# not generally needed, but it may be useful to override a different compliance
# option in the gpg.conf file.
compliance gnupg

# 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 mail address of the signing key when listing signatures
sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g

# When making a data signature, prompt for an expiration time. If this option is
# not specified, the expiration time set via --default-sig-expire is used.
# --no-ask-sig-expire disables this option.
#no-ask-sig-expire

# The default expiration time to use for signature expiration. Valid values are
# "0" for no expiration, a number followed by the letter d (for days), w (for
# weeks), m (for months), or y (for years) (for example "2m" for two months, or
# "5y" for five years), or an absolute date in the form YYYY-MM-DD. Defaults to
# "0".
#default-sig-expire 0

# When making a key signature, prompt for an expiration time. If this option is
# not specified, the expiration time set via --default-cert-expire is used.
# --no-ask-cert-expire disables this option.
ask-cert-expire

# The default expiration time to use for key signature expiration. Valid values
# are "0" for no expiration, a number followed by the letter d (for days), w
# (for weeks), m (for months), or y (for years) (for example "2m" for two
# months, or "5y" for five years), or an absolute date in the form YYYY-MM-DD.
# Defaults to "0".
default-cert-expire 2y

# This option can be used to change the default algorithms for key generation.
# The string is similar to the arguments required for the command
# --quick-add-key but slightly different. For example the current default of
# "rsa2048/cert,sign+rsa2048/encr" (or "rsa3072") can be changed to the value of
# what we currently call future default, which is
# "ed25519/cert,sign+cv25519/encr".
# You need to consult the source code to learn the details.
# Note that the advanced key generation commands can always be used to specify a
# key algorithm directly.
#default-new-key-algo string

# List of default ciphers when creating new keys
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed

# Set the default keyserver URL to name. This keyserver will be used as the
# keyserver URL when writing a new self-signature on a key, which includes key
# generation and changing preferences.
default-keyserver-url hkps://keys.openpgp.org

# -*- mode: ini; tab-width: 4; indent-tabs-mode: nil -*-

GnuPG Agent Configuration

The “Gnu Privacy Guard Agent” is a service which safely manages your private-keys in the background. Any application (e.g. the mail-client signing a message with your key) don’t need direct access to your key or your passphrase. Instead they go trough the agent, which eventually will ask the user for the key passphrase in a protected environment.

Additionally GnuPG-Agent also will manage your SSH keys, thus replacing the SSH- Agent.

The available configuration options can be found on the gpg-agent man page.

Open the file .gnupg/gpg-agent.conf and change, add or uncomment as follows:

#
# Options for gpg-agent (GnuPG) 2.2.19
#
# See the 'OPTIONS' section of 'man gpg-agent'
# https://manpages.ubuntu.com/manpages/focal/en/man1/gpg-agent.1.html#options

# Time in seconds, since last use of a GPG key, after which you will be asked to
# provide your passhprase again.
# Default: 600 (10 minutes)
default-cache-ttl 7200 # 2 hours

# Time in seconds after which you will be asked to provide your GPG key
# passhprase again, regardless of the time since that GPG key has been used.
# Default: 7200 (2 hours)
max-cache-ttl 86400 # 24 hours

# Time in seconds, since last use of an SSH key, after which you will be asked
# to provide your passhprase again.
# Default: 1800 (30 minutes)
default-cache-ttl-ssh 21600 # 6 hours

# Time in seconds after which you will be asked to provide your SSH key
# passhprase again, regardless of the time since that SSH key has been used.
# Default: 7200 (2 hours)
max-cache-ttl-ssh 86400 # 24 hours

# Use program filename as the PIN entry. The default is installation dependent.
# With the default configuration the name of the default pinentry is `pinentry';
# if that file does not exist but a `pinentry-basic' exist the latter is used.
pinentry-program /usr/bin/pinentry-gnome3

# The OpenSSH Agent protocol is always enabled, but gpg-agent will only set the
# SSH_AUTH_SOCK variable if this flag is given.
enable-ssh-support

Terminal Session Environment

Since the GnuPG agent is a long-running background process (daemon), it is not attached to a particular terminal session or display.

In order to answer requests, the agent needs to know from which terminal or display that request came from. We can tell him that, trough the environment variable GPG_TTY.

Add the following lines added to your shell configuration file ~/.bashrc:

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

Directory Manager Configuration

dirmngr takes care of retrieving PGP public keys of from various sources (i.e. key-servers). It is also used as a server for managing and downloading certificate revocation lists (CRL) for X.509 certificates, downloading X.509 certificates, and providing access to OCSP providers. dirmngr is invoked internally by gpg, gpgsm, or via the gpg-connect-agent tool.

The available configuration options can be found on the dirmngr man page.

Open the file .gnupg/dirmngr.conf and change, add or uncomment as follows:

#
# Options for dirmngr (GnuPG) 2.2.19
#
# See the 'OPTIONS' section of 'man dirmngr'
# https://manpages.ubuntu.com/manpages/focal/en/man8/dirmngr.8.html#options

# The option --use-tor switches Dirmngr and thus GnuPG into ``Tor mode'' to
# route all network access via Tor (an anonymity network). Certain other
# features are disabled in this mode. The effect of --use-tor cannot be
# overridden by any other command or even be reloading gpg-agent. The use of
# --no-use-tor disables the use of Tor.
# The default is to use Tor if it is available on startup or after reloading
# dirmngr.
use-tor

# Use name as your keyserver. This are the servers that gpg communicates with to
# receive keys, send keys, and search for keys.
#pgp
# The format of the name is a URI: `scheme:[//]keyservername[:port]' The scheme
# is the type of keyserver: "hkp" for the HTTP (or compatible) keyservers,
# "ldap" for the LDAP keyservers, or "mailto" for the Graff email keyserver.
#
# Note that your particular installation of GnuPG may have other keyserver types
# available as well.
#
# Keyserver schemes are case-insensitive.
#
# After the keyserver name, optional keyserver configuration options may be
# provided. These are the same as the --keyserver-options of gpg, but apply only
# to this particular keyserver.
#
# Most keyservers synchronize with each other, so there is generally no need to
# send keys to more than one server. The keyserver hkp://keys.gnupg.net uses
# round robin DNS to give a different keyserver each time you use it.
# keys.gnupg.net is an alias for hkps.pool.sks-keyservers.net.
#
# If exactly two keyservers are configured and only one is a Tor hidden service
# (.onion), Dirmngr selects the keyserver to use depending on whether Tor is
# locally running or not. The check for a running Tor is done for each new
# connection.
#
# Debian and Ubuntu related Linux distributions use hkps://keys.openpgp.org as
# built-in default, which is automatically used, when no other key-server has
# been set. Others may use hkps://hkps.pool.sks-keyservers.net as their default.

# Onion Service for keys.openpgp.org
keyserver hkp://zkaan2xfbuxia2wpf7ofnkbz6r5zdbbvxbunvp5g2iebopbfc4iqmbad.onion

# Onion Service for pool.sks-keyservers.net
keyserver hkp://jirk5u4osbsr34t5.onion

# Others
keyserver hkps://keys.openpgp.org
keyserver hkps://keys.mailvelope.com
keyserver hkps://pgp.mailbox.org
keyserver hkps://keyserver.ubuntu.com/
keyserver hkps://hkps.pool.sks-keyservers.net

PIN Entry

“PIN Entry” is used by “GnuPG Agent” and others to safely ask the user for a passphrase in a secure manner. It works on various graphical desktop environments, text-only consoles and terminal sessions.

“GPG Agent” and “PIN Entry” will not only make the handling of your keys more secure, but also easier to use. You can set a time, during which you keys will stay unlocked so you are not required to enter your passphrase again every time they key is needed.