diff options
Diffstat (limited to 'debian/pinentry-tqt/pinentry-tqt-1.1.0/doc/pinentry.texi')
| -rw-r--r-- | debian/pinentry-tqt/pinentry-tqt-1.1.0/doc/pinentry.texi | 755 |
1 files changed, 755 insertions, 0 deletions
diff --git a/debian/pinentry-tqt/pinentry-tqt-1.1.0/doc/pinentry.texi b/debian/pinentry-tqt/pinentry-tqt-1.1.0/doc/pinentry.texi new file mode 100644 index 00000000..44e2eb1f --- /dev/null +++ b/debian/pinentry-tqt/pinentry-tqt-1.1.0/doc/pinentry.texi @@ -0,0 +1,755 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename pinentry.info + +@include version.texi + +@macro copyrightnotice +Copyright @copyright{} 2002, 2005, 2015 g10 Code GmbH +@end macro +@macro permissionnotice +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2 of the License, or (at your +option) any later version. The text of the license can be found in the +section entitled ``Copying''. +@end macro + +@macro pinentry +@sc{pinentry} +@end macro + +@settitle Using the PIN-Entry + +@c Create a separate index for command line options. +@defcodeindex op +@c Merge the standard indexes into a single one. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@c printing stuff taken from gcc. +@macro gnupgtabopt{body} +@code{\body\} +@end macro +@macro gnupgoptlist{body} +@smallexample +\body\ +@end smallexample +@end macro +@c Makeinfo handles the above macro OK, TeX needs manual line breaks; +@c they get lost at some point in handling the macro. But if @macro is +@c used here rather than @alias, it produces double line breaks. +@iftex +@alias gol = * +@end iftex +@ifnottex +@macro gol +@end macro +@end ifnottex + + +@c %**end of header + +@ifnottex +@dircategory GNU Utilities +@direntry +* pinentry: (pinentry). Securely ask for a passphrase or PIN. +@end direntry +This file documents the use and the internals of the @pinentry{}. + +This is edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The `PINEntry' Manual}, for version @value{VERSION}. +@sp 1 +Published by g10 Code GmbH@* +Hüttenstr. 61@* +40699 Erkrath, Germany +@sp 1 +@copyrightnotice{} +@sp 1 +@permissionnotice{} +@end ifnottex + +@setchapternewpage odd + +@titlepage +@title Using the PIN-Entry +@subtitle Version @value{VERSION} +@subtitle @value{UPDATED} +@author Werner Koch @code{(wk@@gnupg.org)} + +@page +@vskip 0pt plus 1filll +@copyrightnotice{} +@sp 2 +@permissionnotice{} +@end titlepage +@summarycontents +@contents +@page + + +@node Top +@top Introduction +@cindex introduction + +This manual documents how to use the @pinentry{} and its protocol. + +The @pinentry{} is a small GUI application used to enter PINs or +passphrases. It is usually invoked by @sc{gpg-agent} +(@pxref{Invoking GPG-AGENT, ,Invoking the gpg-agent, gnupg, + The `GNU Privacy Guard' Manual}, for details). + +@pinentry{} comes in several flavors to fit the look and feel of the +used GUI toolkit: A @sc{GTK+} based one named @code{pinentry-gtk}; a +@sc{Qt} based one named @code{pinentry-qt}; and, two non-graphical +ones @code{pinentry-curses}, which uses curses, and +@code{pinentry-tty}, which doesn't require anything more than a simple +terminal. Not all of them are necessarily available on your +installation. If curses is supported on your system, the GUI-based +flavors fall back to curses when the @code{DISPLAY} variable is not +set. + + +@menu +* Using pinentry:: How to use the beast. +* Front ends:: Description and comparison of the front ends + +Developer information + +* Protocol:: The Assuan protocol description. +* Implementation Details:: For those extending or writing a new pinentry. + +Miscellaneous + +* Copying:: GNU General Public License says + how you can copy and share PIN-Entry + as well as this manual. + +Indices + +* Option Index:: Index to command line options. +* Index:: Index of concepts and symbol names. +@end menu + +@node Using pinentry +@chapter How to use the @pinentry{} + +@c man begin DESCRIPTION + +You may run @pinentry{} directly from the command line and pass the +commands according to the Assuan protocol via stdin/stdout. + + +@c man end + +@c man begin OPTIONS + +Here is a list of options supported by all flavors of pinentry: + +@table @gnupgtabopt +@item --version +@opindex version +Print the program version and licensing information. + +@item --help +@opindex help +Print a usage message summarizing the most useful command line options. + +@item --debug +@itemx -d +@opindex debug +@opindex d +Turn on some debugging. Mostly useful for the maintainers. Note that +this may reveal sensitive information like the entered passphrase. + +@c @item --enhanced +@c @itemx -e +@c @opindex enhanced +@c @opindex e +@c Ask for timeouts and insurance, too. Note that this is currently not +@c fully supported. + +@item --no-global-grab +@itemx -g +@opindex no-global-grab +@opindex g +Grab the keyboard only when the window is focused. Use this option if +you are debugging software using the @pinentry{}; otherwise you may +not be able to to access your X session anymore (unless you have other +means to connect to the machine to kill the @pinentry{}). + +@item --parent-wid @var{n} +@opindex parent-wid +Use window ID @var{n} as the parent window for positioning the window. +Note, that this is not fully supported by all flavors of @pinentry{}. + +@item --timeout @var{seconds} +@opindex timeout +Give up waiting for input from the user after the specified number of +seconds and return an error. The error returned is the same as if the +Cancel button was selected. To disable the timeout and wait +indefinitely, set this to 0, which is the default. + +@item --display @var{string} +@itemx --ttyname @var{string} +@itemx --ttytype @var{string} +@itemx --lc-ctype @var{string} +@itemx --lc-messages @var{string} +@opindex display +@opindex ttyname +@opindex ttytype +@opindex lc-ctype +@opindex lc-messa +These options are used to pass localization information to +@pinentry{}. They are required because @pinentry{} is usually called +by some background process which does not have any information about +the locale and terminal to use. It is also possible to pass these +options using Assuan protocol options. +@end table + +@node Front ends +@chapter Front Ends + +There are several different flavors of @pinentry{}. Concretely, there +are Gtk+2, Qt@tie{}4, Gnome@tie{}3, Emacs, curses and tty variants. +These different implementations provide higher levels of integration +with a specific environment. For instance, the Gnome@tie{}3 +@pinentry{} uses Gnome@tie{}3 widgets to display the prompts. For +Gnome@tie{}3 users, this higher level of integration provides a more +consistent aesthetic. However, this comes at a cost. Because this +@pinentry{} uses so many components, there is a larger chance of a +failure. In particular, there is a larger chance that the passphrase +is saved in memory and that memory is exposed to an attacker (consider +the OpenSSL Heartbeat vulnerability). + +To understand how many components touch the passphrase, consider again +the Gnome@tie{}3 implementation. When a user presses a button on the +keyboard, the key is passed from the kernel to the X@tie{}server to +the toolkit (Gtk+) and to the actual text entry widget. Along the +way, the key is saved in memory and processed. In fact, the key +presses are probably read using standard C library functions, which +buffer the input. None of this code is careful to make sure the +contents of the memory are not leaked by keeping the data in unpagable +memory and wiping it when the buffer is freed. However, even if they +did, there is still the problem that when a computer hibernates, the +system writes unpagable memory to disk anyway. Further, many +installations are virtualized (e.g., running on Xen) and have little +control over their actual environment. + +The curses variant uses a significant smaller software stack and the +tty variant uses an even smaller one. However, if they are run in an +X@tie{}terminal, then a similar number of components are handling the +passphrase as in the Gnome@tie{}3 case! Thus, to be most secure, you +need to direct GPG@tie{}Agent to use a fixed virtual console. Since +you need to remain logged in for GPG@tie{}Agent to use that console, +you should run there and have @code{screen} or @code{tmux} lock the +tty. + +The Emacs pinentry implementation interacts with a running Emacs +session and directs the Emacs instance to display the passphrase +prompt. Since this doesn't work very well if there is no Emacs +running, the generic @pinentry{} backend checks if a +@pinentry{}-enabled Emacs should be used. Specifically, it looks to +see if the @code{INSIDE_EMACS} variable is set and then attempts to +establish a connection to the specified address. If this is the case, +then instead of, e.g., @code{pinentry-gtk2} displaying a Gtk+2 +pinentry, it interacts with the Emacs session. This functionality can +be explicitly disabled by passing @code{--disable-inside-emacs} to +@code{configure} when building @pinentry{}. + +Having Emacs get the passphrase is convenient, however, it is a +significant security risk. Emacs is a huge program, which doesn't +provide any process isolation to speak of. As such, having it handle +the passphrase adds a huge chunk of code to the user's trusted computing +base. Because of this concern, Emacs doesn't enable this by default, +unless the @code{allow-emacs-pinentry} option is explicitly set in his +or her @code{.gnupg/gpg-agent.conf} file. + +Similar to the inside-emacs check, the @pinentry{} frontends check +whether the @code{DISPLAY} variable is set and a working X server is +available. If this is not the case, then they fallback to the curses +front end. This can also be disabled by passing +@code{--disable-fallback-curses} to @code{configure} at build time. + +@c +@c Assuan Protocol +@c +@node Protocol +@chapter @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 +@sc{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 @code{%0A}, the percent sign itself +is encoded as @code{%25}, etc.). + +The following is a list of supported commands: + +@table @gnupgtabopt + +@item Set the timeout before returning an error +@example + C: SETTIMEOUT 30 + S: OK +@end example + +@item Set the descriptive text to display +@example + C: SETDESC Enter PIN for Richard Nixon <nobody@@trickydicky.gov> + S: OK +@end example + +@item Set the prompt to show +When asking for a PIN, set the text just before the widget for +passphrase entry. +@example + C: SETPROMPT PIN: + S: OK +@end example + +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. + +@item 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. +@example + C: SETTITLE Tape Recorder Room + S: OK +@end example + +@item 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. +@example + C: SETOK Yes + S: OK +@end example + + +To set the text for the button signaling cancellation or disagreement +(in UTF-8). See SETPROMPT on how to use an keyboard accelerator. +@example + C: SETCANCEL No + S: OK +@end example + + +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. +@example + C: SETNOTOK Do not do this + S: OK +@end example + + + +@item 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. +@example + C: SETERROR Invalid PIN entered - please try again + S: OK +@end example + +@item 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. +@example + C: SETQUALITYBAR + S: OK +@end example + +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 +@example + C: SETQUALITYBAR_TT string + S: OK +@end example + +@noindent +With STRING being a percent escaped string shown as the tooltip. + + +@item Ask for a PIN +The meat of this tool is to ask for a passphrase of PIN, it is done with +this command: +@example + C: GETPIN + S: D no more tapes + S: OK +@end example +Note that the passphrase is transmitted in clear using standard data +responses. Expect it to be in UTF-8. + +@item Ask for confirmation +To ask for a confirmation (yes or no), you can use this command: +@example + C: CONFIRM + S: OK +@end example +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 +@code{ASSUAN_Not_Confirmed}. + +@item Show a message +To show a message, you can use this command: +@example + C: MESSAGE + S: OK +@end example +alternatively you may add an option to confirm: +@example + C: CONFIRM --one-button + S: OK +@end example +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. + +@item Set the output device +When using X, the @pinentry{} program must be invoked with an +appropriate @code{DISPLAY} environment variable or the +@code{--display} option. + +When using a text terminal: +@example + C: OPTION ttyname=/dev/tty3 + S: OK + C: OPTION ttytype=vt100 + S: OK + C: OPTION lc-ctype=de_DE.UTF-8 + S: OK +@end example +The client should use the @code{ttyname} option to set the output TTY +file name, the @code{ttytype} option to the @code{TERM} variable +appropriate for this tty and @code{lc-ctype} to the locale which +defines the character set to use for this terminal. + +@item 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. + +@example + C: OPTION default-ok=_Korrekt + S: OK + C: OPTION default-cancel=Abbruch + S: OK + C: OPTION default-prompt=PIN eingeben: + S: OK +@end example +The strings are subject to accelerator marking, see SETPROMPT for +details. + +@item Passphrase caching + +Some environments, such as GNOME, cache passwords and passphrases. +The @pinentry{} should only use an external cache if the +@code{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 +@code{PASSWORD_FROM_CACHE} status message before returning the +passphrase. This indicates to GPG Agent that it should not increment +the passphrase retry counter. + +@example + 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 +@end example + +Note: if @code{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 @code{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 +@code{X/HEXSTRING} where @code{X} is either @code{n}, @code{s}, or +@code{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: + +@example + # gpg2 --with-keygrip --list-secret-keys +@end example + +@noindent +and searching the output for the key grip. The same command-line +options can also be used with gpgsm. + +@end table + +@node Implementation Details +@chapter Implementation Details + +The pinentry source code can be divided into three categories. There +is a backend module, which lives in @code{pinentry/}, there are +utility functions, e.g., in @code{secmem/}, and there are various +frontends. + +All of the low-level logic lives in the backend. This frees the +frontends from having to implement, e.g., the Assuan protocol. When +the backend receives an option, it updates the state in a +@code{pinentry_t} struct. The frontend is called when the client +either calls @code{GETPIN}, @code{CONFIRM} or @code{MESSAGE}. In +these cases, the backend invokes the @code{pinentry_cmd_handler}, +which is passed the @code{pinentry_t} struct. + +When the callback is invoked, the frontend should create a window +based on the state in the @code{pinentry_t} struct. For instance, the +title to use for the dialog's window (if any) is stored in the +@code{title} field. If the is @code{NULL}, the frontend should choose +a reasonable default value. (Default is not always provided, because +different tool kits and environments have different reasonable +defaults.) + +The widget needs to support a number of different interactions with +the user. Each of them is described below. + +@table @gnupgtabopt +@item Passphrase Confirmation + +When creating a new key, the passphrase should be entered twice. The +client (typically GPG Agent) indicates this to the @pinentry{} by +invoking @code{SETREPEAT}. In this case, the backend sets the +@code{repeat_passphrase} field to a copy of the passed string. The +value of this field should be used to label a second text input. + +It is the frontend's responsibility to check that the passwords match. +If they don't match, the frontend should display an error message and +continue to prompt the user. + +If the passwords do match, then, when the user presses the okay +button, the @code{repeat_okay} field should be set to @code{1} (this +causes the backend to emit the @code{S PIN_REPEATED} status message). + +@item Message Box + +Sometimes GPG Agent needs to display a message. In this case, the +@code{pin} variable is @code{NULL}. + +At the Assuan level, this mode is selected by using either the +@code{MESSAGE} or the @code{CONFIRM} command instead of the +@code{GETPIN} command. The @code{MESSAGE} command never shows the +cancel or an other button. The same holds for @code{CONFIRM} if it +was passed the ``--one-button'' argument. If @code{CONFIRM} was not +passed this argument, the dialog for @code{CONFIRM} should show both +the @code{ok} and the @code{cancel} buttons and optionally the +@code{notok} button. The frontend can determine whether the dialog is +a one-button dialog by inspecting the @code{one_button} variable. + +@item Passphrase Entry + +If neither of the above cases holds, then GPG Agent is simply +requesting the passphrase. In this case, the @code{ok} and +@code{cancel} buttons should be displayed. + +@end table + +The layout of the three variants is quite similar. Here are the +relevant elements that describe the layout: + +@table @gnupgtabopt +@item @code{title} +The window's title. + +@item @code{description} +The reason for the dialog. When requesting a passphrase, this +describes the key. When showing a message box, this is the message to +show. + +@item @code{error} +If GPG Agent determines that the passphrase was incorrect, it will +call @code{GETPIN} again (up to a configurable number of times) to +again prompt the user. In this case, this variable contains a +description of the error message. This text should typically be +highlighted in someway. + +@item @code{prompt}, @code{default-prompt} +The string to associate with the passphrase entry box. + +There is a subtle difference between @code{prompt} and +@code{default-prompt}. @code{default-prompt} means that a stylized +prompt (e.g., an icon suggesting a prompt) may be used. @code{prompt} +means that the entry's meaning is not consistent with such a style +and, as such, no icon should be used. + +If both variables are set, the @code{prompt} variant takes precedence. + +@item @code{repeat_passphrase} +The string to associate with the second passphrase entry box. The +second passphrase entry box should only be shown if this is not +@code{NULL}. + +@item @code{ok}, @code{default-ok} +The string to show in the @code{ok} button. + +If there are any @code{_} characters, the following character should +be used as an accelerator. (A double underscore means a plain +underscore should be shown.) If the frontend does not support +accelerators, then the underscores should be removed manually. + +There is a subtle difference between @code{ok} and @code{default-ok}. +@code{default-ok} means that a stylized OK button should be used. For +instance, it could include a check mark. @code{ok} means that the +button's meaning is not consistent with such an icon and, as such, no +icon should be used. Thus, if the @code{ok} button should have the +text ``No password required'' then @code{ok} should be used because a +check mark icon doesn't make sense. + +If this variable is @code{NULL}, the frontend should choose a +reasonable default. + +If both variables are set, the @code{ok} variant takes precedence. + +@item @code{cancel}, @code{default-cancel} +Like the @code{ok} and @code{default-ok} buttons except these strings +are used for the cancel button. + +This button should not be shown if @code{one_button} is set. + +@code{default-notok} +Like the @code{default-ok} button except this string is used for the +other button. + +This button should only be displayed when showing a message box. If +these variables are @code{NULL} or @code{one_button} is set, this +button should not be displayed. + +@item @code{quality_bar} +If this is set, a widget should be used to show the password's +quality. The value of this field is a label for the widget. + +Note: to update the password quality, whenever the password changes, +call the @code{pinentry_inq_quality} function and then update the +password quality widget correspondingly. + +@item @code{quality_bar_tt} +A tooltip for the quality bar. + +@item @code{default_pwmngr} +If @code{may_cache_password} and @code{keyinfo} are set and the user +consents, then the @pinentry{} may cache the password with an external +manager. Note: getting the user's consent is essential, because +password managers often provide a different level of security. If the +above condition is true and @code{tried_password_cache} is false, then +a check box with the specified string should be displayed. The check +box must default to off. + +@item @code{default-cf-visi} +The string to show with a question if you want to confirm that +the user wants to change the visibility of the password. + +@item @code{default-tt-visi} +Tooltip for an action that would reveal the entered password. + +@item @code{default-tt-hide} +Tooltip for an action that would hide the password revealed +by the action labeld with @code{default-tt-visi} + +@end table + +When the handler is done, it should store the passphrase in +@code{pin}, if appropriate. This variable is allocated in secure +memory. Use @code{pinentry_setbufferlen} to size the buffer. + +The actual return code is dependent on whether the dialog is in +message mode or in passphrase mode. + +If the dialog is in message mode and the user pressed ok, return 1. +Otherwise, return 0. If an error occurred, indicate this by setting it +in @code{specific_err} or setting @code{locale_err} to @code{1} (for +locale specific errors). If the dialog was canceled, then the handler +should set the @code{canceled} variable to @code{1}. If the not ok +button was pressed, don't do anything else. + +If the dialog is in passphrase mode return @code{1} if the user +entered a password and pressed ok. If an error occurred, return +@code{-1} and set @code{specific_err} or @code{locale_err}, as above. +If the user canceled the dialog box, return @code{-1}. + +If the window was closed, then the handler should set the +@code{close_button} variable and otherwise act as if the cancel button +was pressed. + + + +@c --------------------------------------------------------------------- +@c Legal Blurbs +@c --------------------------------------------------------------------- + +@include gpl.texi + +@c --------------------------------------------------------------------- +@c Indexes +@c --------------------------------------------------------------------- + +@node Option Index +@unnumbered Option Index + +@printindex op + +@node Index +@unnumbered Index + +@printindex cp + +@c --------------------------------------------------------------------- +@c Epilogue +@c --------------------------------------------------------------------- + +@bye + + |