GPG agent

Android · Linux · macOS · Windows
View Markdown

Keyguard can act as a GPG agent for GnuPG on desktop and in Termux, and for OpenPGP apps on Android. The private key never leaves your vault: a program sends Keyguard what it needs signed or decrypted and gets back only the result. GnuPG’s keyring holds only your public key, so no secret key sits on disk for other programs to read or copy.

Keyguard asks you to approve requests and logs every request. Agent approvals covers when Keyguard remembers a desktop approval.

Before you begin

  • A GPG Key item in your vault that holds a private key. The Generator creates one, and GPG keys lists what Keyguard imports.
  • GPG agent turned on in Settings > Developer > GPG agent.
  • On desktop, GnuPG installed. On Windows, where.exe gpg and where.exe gpgconf must show native GnuPG, normally in Program Files\GnuPG\bin. The gpg bundled with Git for Windows doesn’t work.

Set up the agent on desktop

Open Settings > Developer > GPG agent > GPG client setup. Under Automatic configuration, select Configure automatically. Choose your shells, continue to review the files, then select Apply changes. The wizard checks the agent connection after applying. Open a new terminal afterward. Bash, Zsh, Fish, PowerShell 7 and Windows PowerShell 5.1 are supported.

The Flatpak build can’t edit host files, so the wizard shows a command instead. Run it in a host terminal. It shows the file changes and asks before applying them.

Setup selects Keyguard’s separate GnuPG home. It does not copy keyrings or trust settings, import private keys, or change Git signing. Import your public certificates using the steps below. The connection check lists the keys served by the agent; sign a test message to check the complete signing flow.

Setup adds Keyguard’s settings to the end of each shell profile and leaves your lines unchanged. Check these lines lists GNUPGHOME lines that run later and can replace Keyguard’s value. Make sure they don’t select another GnuPG home.

If no files need changes, select Check agent connection. It tests Keyguard’s endpoint; it does not prove which settings your shell loads.

The undo icon in Automatic configuration removes recorded settings while preserving other edits. Existing terminals and graphical applications keep their current environment.

For manual shell configuration:

  1. Add the GNUPGHOME line for your platform, listed below, to your shell profile.
  2. Open a new shell.

Linux

The agent’s home is $XDG_DATA_HOME/keyguard/gnupg, or ~/.local/share/keyguard/gnupg when XDG_DATA_HOME is unset, empty or relative. GnuPG finds the agent by the exact path, so this command also removes repeated slashes:

case "${XDG_DATA_HOME:-}" in
  /*) GNUPGHOME="$XDG_DATA_HOME/keyguard/gnupg" ;;
  *) GNUPGHOME="$HOME/.local/share/keyguard/gnupg" ;;
esac
GNUPGHOME="$(printf '%s' "$GNUPGHOME" | tr -s '/')"
export GNUPGHOME

In the Flatpak build:

export GNUPGHOME="$HOME/.var/app/com.artemchep.keyguard/data/gnupg"

macOS

export GNUPGHOME="$HOME/.keyguard/gnupg"

Windows

Add this line to your PowerShell profile:

$env:GNUPGHOME = "$env:LOCALAPPDATA\ArtemChepurnyi\keyguard\gnupg"

Set up the agent in Termux

Termux reaches Keyguard through a helper package. It serves the GnuPG home ~/.keyguard/gnupg, so GnuPG’s own agent keeps ~/.gnupg.

  1. Install Termux.

  2. In Keyguard, open Settings > Developer > GPG agent > GPG client setup.

  3. In Termux, run the commands under Install package. They add Keyguard’s APT repository and install gnupg and keyguard-android-gpg-agent.

  4. Review and apply startup configuration for your shell:

    keyguard-android-gpg-agent --setup-shells bash

    Choose bash, zsh, fish, or a comma-separated list. The helper asks before editing files. New terminals start the helper and set GNUPGHOME. To review removal, run keyguard-android-gpg-agent --undo-setup.

  5. Open a new Termux session.

Keyguard saves an exported public key to Downloads. To import it in Termux, give Termux storage access once:

termux-setup-storage

Then import the file:

gpg --import ~/storage/downloads/gpg_*.public.asc

Import the public key

GnuPG needs your public key to use the private key in Keyguard. Only the public key leaves your vault.

  1. Export the public key from the GPG Key item. Keyguard saves a .public.asc file.

  2. Import the file into GnuPG:

    gpg --import <PUBLIC_KEY_FILE>

  3. List the secret keys:

    gpg --no-autostart --list-secret-keys --with-keygrip --keyid-format=long

    Your key appears in the list.

Sign a test message

  1. Sign a message with your key’s fingerprint:

    printf "Keyguard GPG agent test\n" | gpg --no-autostart --local-user <KEY_FINGERPRINT> --clearsign

    In PowerShell on Windows:

    "Keyguard GPG agent test" | gpg --no-autostart --local-user <KEY_FINGERPRINT> --clearsign

  2. In Keyguard, approve the request. gpg prints the signed message.

To sign commits with this key, see Sign Git commits.

Use the agent from Android apps

Apps that support the OpenKeychain API can select Keyguard as their OpenPGP provider. They see Keyguard only while GPG agent is on.

  1. In the other app’s OpenPGP settings, select Keyguard as the OpenPGP provider. The setting’s name depends on the app.
  2. In Keyguard, approve the registration request.

Later requests can ask you to choose keys, unlock the vault or authenticate. Apps can select recipients and signing keys, read public keys, sign, verify, encrypt and decrypt. They never get the private key.

Apps with this integration include Thunderbird for Android and K-9 Mail and FairEmail. Support varies between app versions.

To revoke an app, select it in Settings > Developer > Connected apps, then select Revoke. If an app’s signing certificate changes, the app loses access until you revoke its old registration.

Review request history

In Settings > Developer > GPG agent, select Request log. It lists requests from desktop tools, Termux and Android apps, with the caller, the key, the operation and the result.

Troubleshooting

”Failed to start the GPG agent”

Keyguard can’t find GnuPG or prepare its socket directory. The GPG agent status shows Failed.

Install GnuPG. Keyguard looks for gpgconf on your PATH, and on macOS and Windows also in the usual install folders. If GnuPG is elsewhere on macOS or Windows, set the KEYGUARD_GPG_BIN_DIR environment variable to its bin folder, then restart Keyguard.

gpg reports “No secret key”

GnuPG doesn’t reach Keyguard, or Keyguard doesn’t serve the key.

Check that the program running GnuPG uses Keyguard’s GnuPG home and GPG agent is on. Check that the GPG Key item holds a private key and that GPG agent filters include it.

If Git signing works in your terminal but fails in a Git client, follow Configure Git for a GPG key.

To list the keys that Keyguard serves, run:

GPG_AGENT_SOCKET="$(gpgconf --homedir "$GNUPGHOME" --list-dirs agent-socket)"
gpg-connect-agent --raw-socket "$GPG_AGENT_SOCKET" "KEYINFO --list" /bye

In PowerShell on Windows:

$env:GPG_AGENT_SOCKET = & gpgconf --homedir "$env:GNUPGHOME" --list-dirs agent-socket
gpg-connect-agent --raw-socket "$env:GPG_AGENT_SOCKET" "KEYINFO --list" /bye