Page MenuHome GnuPG

clarify need of --batch and/or --pinentry-mode looback with --passphrase-* options
Open, LowPublic



As of 2.2.35 the manpage claims the following for --passphrase, --passphrase-file and --passphrase-fd:

Note that since Version 2.0 this passphrase is only used if the option --batch has also been given. Since Version 2.1 the --pinentry-mode also needs to be set to loopback.

Which I'd interpret as: as of 2.1, one needs both --batch and --pinentry-mode looback for the --passphrase-* options to work.

However, either of them seems to be already enough.

Apparently, this is a common question/problem for people (see e.g. or or ).

So could you perhaps clarify what's actually needed for which purpose?

My understanding was that --batch primarily causes no questions being asked interactively (not sure what this has to directly do with reading passphrases from arguments/FD/files and why --batch alone makes it already work).

The description of --pinentry-mode looback:

Redirect Pinentry queries to the caller. Note that in contrast to Pinentry the user is not prompted again if he enters a bad password.

is also not really clear IMO for an end-user. What exactly does it and why is it needed for the --passphrase-* options?

One difference:
When using --passphrase-* with --batch (alone), it won’t e.g. ask for confirmation about overwriting an output file. Whereas when using it with --pinentry-mode looback (alone), it would ask for such confirmation.


Event Timeline

I admit that documentation for users should be updated and/or semantics of options could be improved.

That's being said...

either of them seems to be already enough

It's true for key generation, but not for all cases.

For loopback mode, you wrote:

What exactly does it

Let me explain (from developer's viewpoint).

There are three programs: gpg, gpg-agent, and pinentry.

Normal case, it works like:

       <--> [pinentry] <--\
[user]                    V
       <--> [gpg] <--> [gpg-agent]
        (public key)   (private key)

That is: private keys are under control of gpg-agent, and when gpg-agent asks passphrase/confirmation to users, it invokes pinentry to reach a user. Please note that gpg is not involved in this user interaction for private keys.

When "loopback" mode is specified, the pinentry program is not used. Instead, when needed, gpg-agent asks back to gpg to reach a user. Like that:

              /-----------\  <== we call this "loopback"
              V           V
[user] <--> [gpg] <--> [gpg-agent]
        (public key)   (private key)

In this case, it is the gpg program to handle user interaction.

With --passphrase* option, it should be the gpg program to handle the passphrase interaction, so, loopback should be enabled (except key generation).

It's true for key generation, but not for all cases.

I guess encryption and decryption are also cases where it's true.

Thanks for your explanations.

So I guess one could say, then when using --passphrase*-options one would actually want --pinentry-mode looback (alone) ... and --batch should only be used in addition, when no interactive questions (the passphrase from argument/fd/file is not really such an interactive question) should be asked (like "Do you wanna overwrite that file?")?

However --batch seems to imply --pinentry-mode looback, which is why --batch alone works, too, right?

Had there been any versions (2.0?) where only --batchexisted (and therefore needed to be used) but --pinentry-mode looback didn't exist? Cause that would then explain how this unclear sentence came into the docs.

If the above is all true, then why not simply writing:

The the --pinentry-mode also needs to be set to loopback.

And nothing more. There's IMO no need to explain what needed to be done from 2.0 to 2.1 or what was the case before 2.0 ... because that particular manpage will anyway accompany a current version, where --pinentry-mode looback.
If someone uses an older version of gpg, the manpage of that would contain the information valid for that version.

And if you really want to have the history of what needed to be done previously in the current manpage, then why not writing something like:

The the --pinentry-mode also needs to be set to loopback. From 2.0 to 2.1 --batch needed to be used instead, and before 2.0 no additional options needed to be used.

In addition, with respect to (seemingly) --batch implying --pinentry-mode looback one could write exactly that at the --batch option description, e.g. something like:

Specifying this option implies --pinentry-mode looback.

Perhaps adding that "only when --passphrase* is used, if so.

Or - which might perhaps be better - really properly splitting up that semantics and not have --batch imply --pinentry-mode looback in any case.

werner edited projects, added Documentation, gnupg; removed Bug Report.
werner added a subscriber: werner.

There won't be any semantic changes for obvious reasons.