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