Introducing pinentry-touchid

August 3, 2021 pinentry touchid gpg mac

Last edited on 28 September 2021

secure login image


This post introduces pinentry-touchid, a wrapper of pinentry-mac that uses Touch ID for accessing your PIN/password from the Keychain. It will help you avoid typing your password when interacting with your GPG keys (like when you sign a Git commit).

See it in action

Here is a short clip on how pinentry-touchid works (after configuring the gpg-agent):


It is possible to install pinentry-touchid using Homebrew:

❯ brew tap jorgelbg/tap
❯ brew install pinentry-touchid

You can also download the binaries directly from our releases page.

A bit of history

I use GPG to sign my commits. So far, I’ve been using either pinentry-curses or the pinentry-mac for typing my pin/password, when it is requested.

Since I got a Touch ID capable computer I’ve been enjoying the sweet life of Touch ID. The use of Touch ID has spread on the macOS ecosystem and a lot of popular apps like 1Password support Touch ID. Getting passwords autocompleted with 1Password is a breeze, I have to type 0 passwords, while still getting a confirmation that it is me requesting the password, via Touch ID.

I also use gopass for storing tokens/secrets that I normally need in the shell. The main reason for this is that it integrates nicely with the shell/terminal, even more than 1Password. gopass makes using secrets in environment variables a breeze.

For instance, my environment is full of commands like this:

 export GITHUB_API_TOKEN=$(gopass github/mytoken)

Since gopass uses a GPG key for encrypting the secrets I type my pin/password quite often. As I say to my friends, I am a lazy driven developer 😂:

… the essence is to identify what is painful and then eliminate the pain.

Typing my password all the time falls into the painful/repetitive category for me. Yes, I could increase the amount of time that the gpg-agent caches the password but that would be just a patch. Turns out that this Macbook Pro already has something that would allow me to avoid typing the password every single time: the Touch ID sensor.

It would be awesome if I could use Touch ID for getting the pin/password of my GPG key. Unsurprisingly, I’m not the first person to want this. A simple Google search reveals multiple users requesting this. Sadly, it is not supported yet by pinentry-mac.

pinentry-mac already supports storing the pin/password in the macOS Keychain, but accessing the entry does not use Touch ID. I ended up writing a small wrapper that saves the pin in the macOS Keychain (following the same format as the default pinentry-mac) but guards every access with Touch ID. It is backward compatible with pinentry-mac and calls pinentry-mac for requesting a password from the user when there is no entry in the Keychain for the given GPG key.

This was an interesting project, I learned a bit about Assuan, the IPC protocol used by the gpp-agent to communicate with any pinentry-like program.


The current version does not store the password in the Secure Enclave of your device. This allowed us to reuse the same Keychain entry created by pinentry-mac, if present. At the same time, the entry created by pinentry-touchid can be used by pinentry-mac keeping compatibility between both programs. Also, go-keychain does not offer support for the secure enclave (yet).


Finally, I would like to say thank you to the authors and contributors of go-assuan, go-keychain, gopass and go-touchid.

Touch ID icon made by Freepik from Flaticon.