pinentry: Protocol
3 PINENTRY's Assuan Protocol
****************************
The PINENTRY should never service more than one connection at once. It
is reasonable to exec the PINENTRY prior to a request.
The PINENTRY does not need to stay in memory because the GPG-AGENT
has the ability to cache passphrases. The usual way to run the PINENTRY
is by setting up a pipe (not a socket) and then fork/exec the PINENTRY.
The communication is then done by means of the protocol described here
until the client is satisfied with the result.
Although it is called a PINENTRY, it allows entering reasonably long
strings (strings that are up to 2048 characters long are supported by
every pinentry). The client using the PINENTRY has to check for
correctness.
Note that all strings are expected to be encoded as UTF-8; PINENTRY
takes care of converting it to the locally used codeset. To include
linefeeds or other special characters, you may percent-escape them
(e.g., a line feed is encoded as '%0A', the percent sign itself is
encoded as '%25', etc.).
The following is a list of supported commands:
'Set the timeout before returning an error'
C: SETTIMEOUT 30
S: OK
'Set the descriptive text to display'
C: SETDESC Enter PIN for Richard Nixon <nobody@trickydicky.gov>
S: OK
'Set the prompt to show'
When asking for a PIN, set the text just before the widget for
passphrase entry.
C: SETPROMPT PIN:
S: OK
You should use an underscore in the text only if you know that a
modern version of pinentry is used. Modern versions underline the
next character after the underscore and use the first such
underlined character as a keyboard accelerator. Use a double
underscore to escape an underscore.
'Set the window title'
This command may be used to change the default window title. When
using this feature you should take care that the window is still
identifiable as the pinentry.
C: SETTITLE Tape Recorder Room
S: OK
'Set the button texts'
There are three texts which should be used to override the English
defaults:
To set the text for the button signaling confirmation (in UTF-8).
See SETPROMPT on how to use an keyboard accelerator.
C: SETOK Yes
S: OK
To set the text for the button signaling cancellation or
disagreement (in UTF-8). See SETPROMPT on how to use an keyboard
accelerator.
C: SETCANCEL No
S: OK
In case three buttons are required, use the following command to
set the text (UTF-8) for the non-affirmative response button. The
affirmative button text is still set using SETOK and the CANCEL
button text with SETCANCEL. See SETPROMPT on how to use an keyboard
accelerator.
C: SETNOTOK Do not do this
S: OK
'Set the Error text'
This is used by the client to display an error message. In
contrast to the other commands, the error message is automatically
reset with a GETPIN or CONFIRM, and is only displayed when asking
for a PIN.
C: SETERROR Invalid PIN entered - please try again
S: OK
'Enable a passphrase quality indicator'
Adds a quality indicator to the GETPIN window. This indicator is
updated as the passphrase is typed. The clients needs to implement
an inquiry named "QUALITY" which gets passed the current passphrase
(percent-plus escaped) and should send back a string with a single
numerical value between -100 and 100. Negative values will be
displayed in red.
C: SETQUALITYBAR
S: OK
If a custom label for the quality bar is required, just add that
label as an argument as a percent-escaped string. You will need
this feature to translate the label because PINENTRY has no
internal gettext except for stock strings from the toolkit library.
If you want to show a tooltip for the quality bar, you may use
C: SETQUALITYBAR_TT string
S: OK
With STRING being a percent escaped string shown as the tooltip.
'Ask for a PIN'
The meat of this tool is to ask for a passphrase of PIN, it is done
with this command:
C: GETPIN
S: D no more tapes
S: OK
Note that the passphrase is transmitted in clear using standard
data responses. Expect it to be in UTF-8.
'Ask for confirmation'
To ask for a confirmation (yes or no), you can use this command:
C: CONFIRM
S: OK
The client should use SETDESC to set an appropriate text before
issuing this command, and may use SETPROMPT to set the button
texts. The value returned is either OK for YES or the error code
'ASSUAN_Not_Confirmed'.
'Show a message'
To show a message, you can use this command:
C: MESSAGE
S: OK
alternatively you may add an option to confirm:
C: CONFIRM --one-button
S: OK
The client should use SETDESC to set an appropriate text before
issuing this command, and may use SETOK to set the text for the
dismiss button. The value returned is OK or an error message.
'Set the output device'
When using X, the PINENTRY program must be invoked with an
appropriate 'DISPLAY' environment variable or the '--display'
option.
When using a text terminal:
C: OPTION ttyname=/dev/tty3
S: OK
C: OPTION ttytype=vt100
S: OK
C: OPTION lc-ctype=de_DE.UTF-8
S: OK
The client should use the 'ttyname' option to set the output TTY
file name, the 'ttytype' option to the 'TERM' variable appropriate
for this tty and 'lc-ctype' to the locale which defines the
character set to use for this terminal.
'Set the default strings'
To avoid having translations in Pinentry proper, the caller may set
certain translated strings which are used by PINENTRY as default
strings.
C: OPTION default-ok=_Korrekt
S: OK
C: OPTION default-cancel=Abbruch
S: OK
C: OPTION default-prompt=PIN eingeben:
S: OK
The strings are subject to accelerator marking, see SETPROMPT for
details.
'Passphrase caching'
Some environments, such as GNOME, cache passwords and passphrases.
The PINENTRY should only use an external cache if the
'allow-external-password-cache' option was set and a stable key
identifier (using SETKEYINFO) was provided. In this case, if the
passphrase was read from the cache, the PINENTRY should send the
'PASSWORD_FROM_CACHE' status message before returning the
passphrase. This indicates to GPG Agent that it should not
increment the passphrase retry counter.
C: OPTION allow-external-password-cache
S: OK
C: SETKEYINFO key-grip
S: OK
C: getpin
S: S PASSWORD_FROM_CACHE
S: D 1234
C: OK
Note: if 'allow-external-password-cache' is not specified, an
external password cache must not be used: this can lead to subtle
bugs. In particular, if this option is not specified, then GPG
Agent does not recognize the 'PASSWORD_FROM_CACHE' status message
and will count trying a cached password against the password retry
count. If the password retry count is 1, then the user will never
have the opportunity to correct the cached password.
Note: it is strongly recommended that a pinentry supporting this
feature provide the user an option to enable it manually. That is,
saving a passphrase in an external password manager should be
opt-in.
The key identifier provided SETKEYINFO must be considered opaque
and may change in the future. It currently has the form
'X/HEXSTRING' where 'X' is either 'n', 's', or 'u'. In the former
two cases, the HEXSTRING corresponds to the key grip. The key grip
is not the OpenPGP Key ID, but it can be mapped to the key using
the following:
# gpg2 --with-keygrip --list-secret-keys
and searching the output for the key grip. The same command-line
options can also be used with gpgsm.
Info Catalog
pinentry: Front ends
pinentry: Top
pinentry: Implementation Details