Implement a default-prompt option.
[pinentry.git] / doc / pinentry.texi
1 \input texinfo                      @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename pinentry.info
4
5 @include version.texi
6
7 @macro copyrightnotice
8 Copyright @copyright{} 2002, 2005 g10 Code GmbH
9 @end macro
10 @macro permissionnotice
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU General Public License as published by the
13 Free Software Foundation; either version 2 of the License, or (at your
14 option) any later version. The text of the license can be found in the
15 section entitled ``Copying''.
16 @end macro
17
18 @macro pinentry
19 @sc{pinentry}
20 @end macro
21
22 @settitle Using the PIN-Entry
23
24 @c Create a separate index for command line options.
25 @defcodeindex op
26 @c Merge the standard indexes into a single one.
27 @syncodeindex fn cp
28 @syncodeindex vr cp
29 @syncodeindex ky cp
30 @syncodeindex pg cp
31 @syncodeindex tp cp
32
33 @c printing stuff taken from gcc.
34 @macro gnupgtabopt{body}
35 @code{\body\}
36 @end macro
37 @macro gnupgoptlist{body}
38 @smallexample
39 \body\
40 @end smallexample
41 @end macro
42 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
43 @c they get lost at some point in handling the macro.  But if @macro is
44 @c used here rather than @alias, it produces double line breaks.
45 @iftex
46 @alias gol = *
47 @end iftex
48 @ifnottex
49 @macro gol
50 @end macro
51 @end ifnottex
52
53
54 @c Change the font used for @def... commands, since the default
55 @c proportional one used is bad for names starting __.
56 @tex
57 \global\setfont\defbf\ttbshape{10}{\magstep1}
58 @end tex
59
60 @c %**end of header
61
62 @ifnottex
63 @dircategory GNU Utilities
64 @direntry
65 * pinentry: (pinentry).    Ask securely for a passphrase or PIN.
66 @end direntry
67 This file documents the use and the internals of the @pinentry{}.
68
69 This is edition @value{EDITION}, last updated @value{UPDATED}, of
70 @cite{The `PINEntry' Manual}, for version @value{VERSION}.
71 @sp 1
72 Published by g10 Code GmbH@*
73 Hüttenstr. 61@*
74 40699 Erkrath, Germany
75 @sp 1
76 @copyrightnotice{}
77 @sp 1
78 @permissionnotice{}
79 @end ifnottex
80
81 @setchapternewpage odd
82
83 @titlepage
84 @title Using the PIN-Entry
85 @subtitle Version @value{VERSION}
86 @subtitle @value{UPDATED}
87 @author Werner Koch @code{(wk@@gnupg.org)}
88
89 @page
90 @vskip 0pt plus 1filll
91 @copyrightnotice{}
92 @sp 2
93 @permissionnotice{}
94 @end titlepage
95 @summarycontents
96 @contents
97 @page
98
99
100 @node Top
101 @top Introduction
102 @cindex introduction
103
104 This manual documents how to use the @pinentry{} and its protocol.
105
106 The @pinentry{} is a small GUI application used to enter PINs or
107 passphrases. It is usually invoked by @sc{gpg-agent}
108 (@pxref{Invoking GPG-AGENT, ,Invoking the gpg-agent, gnupg,
109     The `GNU Privacy Guard' Manual}, for details).       
110
111 @pinentry{} comes in 3 flavors to fit the look and feel of the used
112 GUI toolkit:  A @sc{GTK+} based one named @code{pinentry-gtk}, a
113 @sc{Qt} based one named @code{pinentry-qt} and a non-graphical one based
114 on curses and named @code{pinentry-curses}.  Not all of them might be
115 available on your installation.  If curses is supported on your system,
116 the GUI based flavors fall back to curses when the @code{DISPLAY}
117 variable is not set.
118
119
120 @menu
121 * Using pinentry::      How to use the beast.
122
123 Developer information
124
125 * Protocol::            The Assuan protocol description.
126
127 Miscellaneous
128
129 * Copying::             GNU General Public License says
130                         how you can copy and share PIN-Entry
131                         as well as this manual.
132
133 Indices
134
135 * Option Index::        Index to command line options.
136 * Index::               Index of concepts and symbol names.
137 @end menu
138
139 @node Using pinentry
140 @chapter How to use the @pinentry{}
141
142 @c man begin DESCRIPTION
143
144 You may run @pinentry{} directly from the command line and pass the
145 commands according to the Assuan protocol via stdin/stdout.
146
147
148 @c man end
149
150 @c man begin OPTIONS
151
152 Here is a list of options supported by all 3 flavors of pinentry
153
154 @table @gnupgtabopt
155 @item --version
156 @opindex version
157 Print the program version and licensing information. 
158
159 @item --help
160 @opindex help
161 Print a usage message summarizing the most useful command line options.
162
163 @item --debug
164 @itemx -d
165 @opindex debug
166 @opindex d
167 Turn on some debugging.  Mostly useful for the maintainers.  Note that
168 this may reveal sensitive information like the entered passphrase.
169
170 @c @item --enhanced
171 @c @itemx -e
172 @c @opindex enhanced
173 @c @opindex e
174 @c Ask for timeouts and insurance, too.  Note that this is currently not
175 @c fully supported.
176
177 @item --no-global-grab
178 @itemx -g
179 @opindex no-global-grab
180 @opindex g
181 Grab the keyboard only when the window is focused.  Use this option if
182 you are debugging software using the @pinentry{}; otherwise you may
183 not be able to to access your X session anymore (unless you have other
184 means to connect to the machine to kill the @pinentry{}).
185
186 @item --parent-wid @var{n}
187 @opindex parent-wid
188 Use window ID @var{n} as the parent window for positioning the window.
189 Note, that this is not fully supported by all flavors of @pinentry{}.
190
191 @item --display @var{string}
192 @itemx --ttyname @var{string}
193 @itemx --ttytype @var{string}
194 @itemx --lc-ctype @var{string}
195 @itemx --lc-messages @var{string}
196 @opindex display 
197 @opindex ttyname 
198 @opindex ttytype 
199 @opindex lc-ctype 
200 @opindex lc-messa
201 These options are used to pass localization information to
202 @pinentry{}.  They are required because @pinentry{} is usually called
203 by some background process which does not have any information on the
204 locale and terminal to use.  Assuan protocol options are an
205 alternative way to pass these information.
206 @end table
207
208 @c 
209 @c  Assuan Protocol
210 @c
211 @node Protocol
212 @chapter pinentry's Assuan Protocol
213
214 The PIN-Entry should never service more than one connection at once.
215 It is reasonable to exec the PIN-Entry prior to a request.
216
217 The PIN-Entry does not need to stay in memory because the
218 @sc{gpg-agent} has the ability to cache passphrases.  The usual way to
219 run the PIN-Entry is by setting up a pipe (and not a socket) and then
220 fork/exec the PIN-Entry.  The communication is then done by means of
221 the protocol described here until the client is satisfied with the
222 result.
223
224 Although it is called a PIN-Entry, it does allow to enter reasonably
225 long strings (at least 2048 characters are supported by every
226 pinentry).  The client using the PIN-Entry has to check for
227 correctness.
228
229 Note that all strings are expected to be encoded as UTF-8; @pinentry{}
230 takes care of converting it to the locally used codeset.  To include
231 linefeeds or other special characters, you may percent-escape them
232 (i.e. a line feed is encoded as @code{%0A}, the percent sign itself
233 is encoded as @code{%25}).
234
235 Here is the list of supported commands:
236
237 @table @gnupgtabopt
238
239 @item Set the descriptive text to be displayed
240 @example
241   C: SETDESC Enter PIN for Richard Nixon <nobody@@trickydicky.gov>
242   S: OK
243 @end example
244
245 @item Set the prompt to be shown
246 When asking for a PIN, set the text just before the widget for
247 passphrase entry.
248 @example
249   C: SETPROMPT PIN:
250   S: OK
251 @end example
252
253 You should use an underscore in the text only if you known that a modern
254 version of pinentry is used.  Modern versions underline the next
255 character after the underscore and use the first such underlined
256 character as a keyboard accelerator.  Use a double underscore to escape
257 an underscore.
258
259 @item Set the window title
260 This command may be used to change the default window title.  When
261 using this feature you should take care that the window is still
262 identifiable as the pinentry.
263 @example
264   C: SETTITLE Tape Recorder Room
265   S: OK
266 @end example
267
268 @item Set the button texts
269 There are three texts which should be used to override the English
270 defaults:
271
272 To set the text for the button signaling confirmation (in UTF-8).
273 See SETPROMPT on how to use an keyboard accelerator.
274 @example
275   C: SETOK Yes
276   S: OK
277 @end example
278
279
280 To set the text for the button signaling cancellation or disagreement
281 (in UTF-8).  See SETPROMPT on how to use an keyboard accelerator.
282 @example
283   C: SETCANCEL No
284   S: OK
285 @end example
286
287
288 In case tree buttons are required, use the follwing command to set the
289 text (UTF-8) for the non-affirmative response button.  The affirmative button
290 text is still set using SETOK and the CANCEL button text with SETCANCEL.
291 See SETPROMPT on how to use an keyboard accelerator.
292 @example
293   C: SETNOTOK Do not do this
294   S: OK
295 @end example
296
297
298
299 @item Set the Error text
300 This is used by the client to display an error message.  In contrast
301 to the other commands this error message is automatically reset with
302 a GETPIN or CONFIRM, and is only displayed when asking for a PIN.
303 @example
304   C: SETERROR Invalid PIN entered - please try again
305   S: OK
306 @end example
307
308 @item Enable a passphrase quality indicator
309 Adds a quality indicator to the GETPIN window.  This indicator is
310 updated as the passphrase is typed.  The clients needs to implement an
311 inquiry named "QUALITY" which gets passed the current passpharse
312 (percent-plus escaped) and should send back a string with a single
313 numerical vauelue between -100 and 100.  Negative values will be
314 displayed in red.
315 @example
316   C: SETQUALITYBAR
317   S: OK
318 @end example
319
320 If a custom label for the quality bar is required, just add that label
321 as an argument as percent escaped string.  You will need this feature to
322 translate the label because pinentry has no internal gettext except for
323 stock strings from the toolkit library.
324
325 If you want to show a tooltip for the quality bar, you may use
326 @example
327   C: SETQUALITYBAR_TT string
328   S: OK
329 @end example
330
331 @noindent
332 With STRING being a percent escaped string shown as the tooltip.
333
334
335 @item Ask for a PIN
336 The meat of this tool is to ask for a passphrase of PIN, it is done with
337 this command:
338 @example
339   C: GETPIN
340   S: D no more tapes
341   S: OK
342 @end example
343 Note that the passphrase is transmitted in clear using standard data
344 responses.  Expect it to be in UTF-8.
345
346 @item Ask for confirmation
347 To ask for a confirmation (yes or no), you can use this command:
348 @example
349   C: CONFIRM
350   S: OK
351 @end example
352 The client should use SETDESC to set an appropriate text before
353 issuing this command, and may use SETPROMPT to set the button texts.
354 The value returned is either OK for YES or the error code
355 @code{ASSUAN_Not_Confirmed}.
356
357 @item Show a message
358 To show a message, you can use this command:
359 @example
360   C: MESSAGE
361   S: OK
362 @end example
363 alternativly you may add an option to confirm:
364 @example
365   C: CONFIRM --one-button
366   S: OK
367 @end example
368 The client should use SETDESC to set an appropriate text before issuing
369 this command, and may use SETOK to set the text for the dismiss button.
370 The value returned is OK or an error message.
371
372 @item Set the output device
373 When using X, the @pinentry{} program must be invoked with an
374 appropriate @code{DISPLAY} environment variable or the
375 @code{--display} option.
376
377 When using a text terminal:
378 @example
379   C: OPTION ttyname=/dev/tty3
380   S: OK
381   C: OPTION ttytype=vt100
382   S: OK
383   C: OPTION lc-ctype=de_DE.UTF-8
384   S: OK
385 @end example
386 The client should use the @code{ttyname} option to set the output TTY
387 file name, the @code{ttytype} option to the @code{TERM} variable
388 appropriate for this tty and @code{lc-ctype} to the locale which
389 defines the character set to use for this terminal.
390
391 @item Set the default strings
392 To avoid having transaltions in Pinentry proper, the caller may set
393 certain translated strings which are used by Pinentry as default
394 strings.
395
396 @example
397   C: OPTION default-ok=_Korrekt
398   S: OK
399   C: OPTION default-cancel=Abbruch
400   S: OK
401   C: OPTION default-prompt=PIN eingeben:
402   S: OK
403 @end example
404 The strings are subject to accelerator marking, see SETPROMPT for
405 details.
406
407 @end table
408
409 @c ---------------------------------------------------------------------
410 @c Legal Blurbs
411 @c ---------------------------------------------------------------------
412
413 @include gpl.texi
414
415 @c ---------------------------------------------------------------------
416 @c Indexes
417 @c ---------------------------------------------------------------------
418
419 @node Option Index
420 @unnumbered Option Index
421
422 @printindex op
423
424 @node Index
425 @unnumbered Index
426
427 @printindex cp
428
429 @c ---------------------------------------------------------------------
430 @c Epilogue
431 @c ---------------------------------------------------------------------
432
433 @bye
434
435