Post release version number bump
[pinentry.git] / README
1 PIN Entry
2 ---------
3
4 This is a collection of simple PIN or passphrase entry dialogs which
5 utilize the Assuan protocol as described by the aegypten project; see
6 http://www.gnupg.org/aegypten/ for details.
7
8 There are programs for different toolkits available.  For all GUIs it
9 is automatically detected which modules can be built, but it can also
10 be requested explicitely.
11
12 GUI             OPTION                   DEPENDENCIES
13 Curses          --enable-pinentry-curses Curses library, for example ncurses
14 GTK+ V1.2       --enable-pinentry-gtk    Gimp Toolkit Library Version 1.2
15                                          eg. libgtk-1.2 and libglib-1.2
16 GTK+ V2.0       --enable-pinentry-gtk2   Gimp Toolkit Library, Version 2.0
17                                          eg. libgtk-x11-2.0 and libglib-2.0
18 Qt              --enable-pinentry-qt     Qt, eg. libqt or libqt-mt
19 Qt4             --enable-pinentry-qt4    Qt4
20
21 The GTK+ and Qt pinentries can fall back to the curses mode.  The
22 option to enable this is --enable-fallback-curses, but this is also
23 detected automatically in the same way --enable-pinentry-curses is.
24 The fallback to curses also works if --disable-pinentry-curses is
25 specified.  So to disable linking to curses completely you have to
26 pass --disable-fallback-curses to the configure script as well.
27
28 Examples:
29 * To only build the GTK+ 1.2 pinentry with curses support:
30 ./configure --enable-pinentry-gtk --enable-fallback-curses \
31         --disable-pinentry-curses --disable-pinentry-qt
32
33 * To build the Qt pinentry, and the other pinentries if they are
34   supported:
35 ./configure --enable-pinentry-qt
36
37 * To build everything that is supported (complete auto-detection):
38 ./configure
39
40 Some of the code is taken from Robert Bihlmeyer's Quintuple-Agent.
41 For security reasons, all internationalization has been removed.  The
42 client is expected to tell the PIN entry the text strings to be
43 displayed.
44
45
46 Curses Pinentry
47 ---------------
48
49 The curses pinentry supports colors if the terminal does.  The colors
50 can be specified by the --colors=FG,BG,SO option, which sets the
51 foreground, background and standout colors respectively.  The standout
52 color is used for error messages.  Colors can be named by any of
53 "black", "red", "green", "yellow", "blue", "magenta", "cyan" and
54 "white".  The foreground and standout color can be prefixed by
55 "bright-", "bright", "bold-" and "bold", and any of these prefixes has
56 the same effect of making the color bolder or brighter.  Two special
57 color names are defined as well: "default" chooses the default color,
58 and "none" disables use of colors.  The name "none" is only meaningful
59 for the standout color and in this case a reversed effect is used for
60 error messages.  For the other colors, disabling colors means the same
61 as using the defaults.  The default colors are as follows:
62
63         Foreground:     Terminal default
64         Background:     Terminal default
65         Standout:       Bright red
66
67 Note that color support is limited by the capabilities of the display
68 terminal.  Some color combinations can be very difficult to read, and
69 please know that colors are perceived differently by different people.