Seed the gpg-agent Passphrase Cache Safely

You will finish with a repeatable way to place a passphrase in a running gpg-agent cache, verify that the installed utility is the one you expect, and clear the entry again. The examples use GnuPG 2.4.4 from Ubuntu package gpg-agent 2.4.4-2ubuntu17.6.

Allow about fifteen minutes. You need a shell, a user account that owns the relevant GnuPG home, and a keygrip or application cache ID. This is a security-sensitive operation: the passphrase is deliberately held in the agent's memory, so use it only for an unattended workflow you already understand. Ordinary commands in this guide do not need sudo.

1. Confirm the installed utility

The manpage is installed with the package, but this binary is not on this machine's normal PATH. Check both the package version and the executable before copying a command into a service or script:

$ dpkg-query -W -f='${Package} ${Version}\n' gpg-agent
gpg-agent 2.4.4-2ubuntu17.6
$ /usr/lib/gnupg/gpg-preset-passphrase --version
gpg-preset-passphrase (GnuPG) 2.4.4

On another distribution the executable may be in a different directory. Use command -v gpg-preset-passphrase first, then substitute that path in the examples. The installed help also exposes --restricted, an option not described by this local manpage. This guide sticks to the documented --preset and --forget operations.

2. Allow presetting in gpg-agent

gpg-preset-passphrase cannot seed an agent unless the agent was started with presetting allowed. For a per-user setup, put the following line in ~/.gnupg/gpg-agent.conf:

allow-preset-passphrase

Do not use sudo to edit this file. It belongs to the user whose agent will receive the passphrase. If the directory does not exist, create it as that user with mkdir -m 700 -p ~/.gnupg.

Reload the agent after changing its configuration:

$ gpgconf --reload gpg-agent

A reload sends a signal to the user's running agent and can clear existing cached passphrases. Warn anyone relying on that agent before doing this on a shared workstation. If the agent still rejects presetting, inspect the account's GnuPG home and restart the agent in a planned maintenance window. Do not keep retrying with a passphrase on the command line.

3. Find the correct cache ID

The safest cache ID for a key is its 40-character hexadecimal keygrip. The local manual points to gpgsm --with-keygrip --list-secret-keys; the keygrip is printed alongside the secret key. For scripts, request machine-readable output and use the value on the grp line:

$ gpgsm --with-keygrip --with-colons --list-secret-keys
sec:::<key data>::::<key data>:::
grp:::::::::0123456789abcdef0123456789abcdef01234567:
# record the 40-character value after grp:::::::::

The displayed key material is host-specific. Do not guess a keygrip from a fingerprint or paste a real secret into a tutorial. If your application needs a passphrase that is not tied to a key, the utility also accepts an arbitrary string. Prefix it with the application name, for example backup-agent:2026, so unrelated jobs cannot collide.

4. Preset the passphrase without exposing it in history

Read the value silently, then pipe it on standard input. Replace KEYGRIP_OR_CACHE_ID with the exact value from the previous step:

$ read -r -s PASSPHRASE
$ printf '%s\n' "$PASSPHRASE" | /usr/lib/gnupg/gpg-preset-passphrase --preset KEYGRIP_OR_CACHE_ID
$ unset PASSPHRASE

The command normally prints nothing and returns status 0. Check the status immediately if you are putting it in a script:

$ printf 'preset status: %s\n' "$?"
preset status: 0

Do not replace the pipe with --passphrase SECRET unless you have a specific reason. The manpage warns that --passphrase makes the value visible to other users, for example through process inspection. Do not put a real passphrase in shell history, a unit file, a world-readable environment file or a command-line argument.

5. Understand how long the entry stays cached

A preset entry does not use the ordinary idle expiry described for a normal interactive prompt. The manpage says preset values remain until you explicitly forget them, restart or reload gpg-agent, or reach the agent's maximum cache time. The upstream agent documentation gives a default --max-cache-ttl of 7200 seconds, but an administrator may have changed it. Check the active agent configuration before treating the cache as permanent or temporary.

This is why presetting is unsuitable for a general login shortcut. Anyone who can use the relevant agent socket may be able to make the agent perform operations that use the cached value. Keep the GnuPG home and agent socket under the intended account, and limit the service that depends on them.

6. Forget the entry when the job ends

Clear the same cache ID with --forget:

$ /usr/lib/gnupg/gpg-preset-passphrase --forget KEYGRIP_OR_CACHE_ID
$ printf 'forget status: %s\n' "$?"
forget status: 0

This removes the preset value from the cache; it does not revoke a key or delete any key material. If the installed Ubuntu 2.4.4 build reports No inquire callback in IPC while forgetting an entry, check the exact utility path and agent version first. As a broader recovery, reload the agent:

$ gpgconf --reload gpg-agent

That also clears cached passphrases and may interrupt other GnuPG operations for the account. If you need to remove a value immediately, stop the dependent job before reloading, then rerun the job only after confirming its cache policy.

7. Diagnose the common failures

An error about the cache or an unavailable agent usually means the agent was not started with allow-preset-passphrase, the command is running as a different user, or GNUPGHOME points at a different configuration. Compare these values without printing any secret:

$ id -un
operator
$ printf 'GNUPGHOME=%s\n' "${GNUPGHOME:-$HOME/.gnupg}"
GNUPGHOME=/home/operator/.gnupg
$ gpgconf --list-options gpg-agent | grep allow-preset-passphrase

If the cache ID is wrong, the agent cannot associate the passphrase with the intended key. Re-run the keygrip listing and copy the complete 40-character value. A successful preset only says that the agent accepted a cache entry; it does not prove that a later signing, decryption or service action selected the same ID.