KBI0012: Annex encryption: fix passphrase prompt (GPG pinentry) not showing#

authors:: Michał Szczepanik <m.szczepanik@fz-juelich.de>
discussion:: https://github.com/psychoinformatics-de/knowledge-base/pull/44
keywords:: gnupg, gpg, encryption
software-versions:: datalad_0.18.1, gnupg_2.2.12

This technical note describes a solution to a specific issue related to encrypted git annex special remotes that can be seen in certain configurations (for example on a GNU/Linux machine with CLI access only, or on a MacOS machine with fresh GnuPG installation from Homebrew). For a use-case-style introduction to annex encryption with DataLad, see Encrypted data storage and transport in the DataLad Handbook.

Users who:

use an encrypted git-annex special remote
have no gpg-agent configuration
use a passphrase-protected gpg key
use a terminal-based pinentry program

may observe the following error when getting a file from an annex remote that has encryption enabled:

$ datalad get foo.txt
get(error): foo.txt (file) [user error (gpg ["--quiet","--trust-model","always","--batch","--decrypt"] exited 2)
user error (gpg ["--quiet","--trust-model","always","--batch","--decrypt"] exited 2)

This happens because the gpg-agent called (by either DataLad or git-annex) in a subprocess does not have a connection to the terminal from which the get command was issued, and can not ask the user for their GPG key passphrase. The problem does not occur if the passphrase had been cached by gpg-agent.

It can be remedied by setting the GPG_TTY environment variable, as explained by man gpg-agent:

You should always add the following lines to your .bashrc or whatever initialization file is used for all shell invocations:
GPG_TTY=$(tty)
export GPG_TTY

For an alternative solution (that wasn’t tested), it is likely sufficient to have a graphical pinentry program (e.g. pinentry-mac on MacOS, which can be installed with brew), and a pinentry program option configured in ~/.gnupg/gpg-agent.conf:

pinentry-program $HOMEBREW_PREFIX/bin/pinentry-mac