pinentry-remote

繁體中文 · Documentation

pinentry-remote lets GnuPG on a remote or headless Linux machine ask for a passphrase or confirmation on another trusted device. The GPG keys stay on the machine running GPG; only the pinentry request and answer travel over an authenticated, encrypted connection. Local and permitted remote prompts race, and the first successful answer wins.

Features

• Authenticated, encrypted device-to-device transport using Noise.
• Interactive pairing with a 12-digit verification code—no public-key copying.
• Independent send and receive permissions for every paired device.
• Local and multiple remote pinentry candidates with cancellation propagation.
• GUI, curses, or TTY pinentry support; Android receiving through Termux:API.
• Configuration hot reload, immediate permission revocation, and JSON audit logs.
• Foreground operation or systemd user socket/service activation.
• Built-in peer inspection, revocation, and connection diagnostics.

Install

Arch Linux

Install pinentry-remote from the Forgejo Arch package registry. Follow Arch package setup to add the registry and signing key.

Debian

Install the .deb from the Forgejo package registry. Follow Debian package setup to add the package source and signing key.

Prebuilt binary

Download the matching Linux binary from the releases page and install it in your user bin directory:

mkdir -p "$HOME/.local/bin"
install -m755 pinentry-remote "$HOME/.local/bin/pinentry-remote"
export PATH="$HOME/.local/bin:$PATH"

go install

Clone the source, then run go install from the repository directory:

git clone https://git.1li.tw/simbafs/pinentry-remote.git
cd pinentry-remote
GOBIN="$HOME/.local/bin" go install .

Ensure ~/.local/bin is in your PATH. See Linux package setup for package details.

Get started

This example uses A and B as two Linux machines that can both run GPG and display each other's prompts. Install pinentry-remote on both machines first. Both also need GnuPG and a pinentry program, and each must be able to reach the other's advertised TCP service address on port 7749.

Initialize the configuration on both A and B:

pinentry-remote init

Pair the devices by running this in an interactive terminal on both:

pinentry-remote pair

On B choose 1 = wait. Answer yes to both permission questions, enable B's receiver, and advertise an address A can reach, such as 192.168.1.20:7749. On A choose 2 = connect, enter B's address, answer yes to both permission questions, enable A's receiver, and advertise an address B can reach. Compare all 12 verification digits and answer yes on both devices only when they match.

The pairing wizard is a convenience for exchanging and verifying public keys without copying them by hand. You can instead exchange public keys through a trusted channel and configure the peer entries manually; see Configuration.

Start the service in a separate terminal on both machines:

pinentry-remote serve

Finally, on A, open ~/.gnupg/gpg-agent.conf in a text editor and add or update the pinentry-program setting to the absolute path of the installed binary, for example:

pinentry-program /home/alice/.local/bin/pinentry-remote

Replace the example path with the actual path on A. Then reload the GnuPG agent and check the connection:

gpgconf --reload gpg-agent
pinentry-remote doctor

The commands above are intentionally minimal. For regular use, install the systemd user units instead of keeping serve terminals open. The generated config contains the device private key and must remain private.

Documentation

• CLI reference — commands, flags, exit behavior, and GnuPG mode.
• Configuration — complete TOML schema and hot reload.
• Pairing and permissions — roles, directions, verification, and recovery.
• Service setup — foreground use, systemd, GUI environments, and custom configs.
• Termux receiver — Android setup and limitations.
• Troubleshooting — diagnostics, common failures, and logs.
• Architecture and security — trust boundaries, protocol, limits, and audit design.
• Development — build, test, source map, and upgrade notes.
• Project status — completed review work and future-work policy.

License

This project is licensed under the MIT License.