1db2d4dce57025a94e41e9a470b79e4b8e7c0abd
[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 @item --enhanced
171 @itemx -e
172 @opindex enhanced
173 @opindex e
174 Ask for timeouts and insurance, too.  Note that this is currently not
175 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-type @var{string}
195 @itemx --lc-messages @var{string}
196 @opindex display 
197 @opindex ttyname 
198 @opindex ttytype 
199 @opindex lc-type 
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
207 @end table
208
209 @c 
210 @c  Assuan Protocol
211 @c
212 @node Protocol
213 @chapter pinentry's Assuan Protocol
214
215 The PIN-Entry should never service more than one connection at once.
216 It is reasonable to exec the PIN-Entry prior to a request.
217
218 The PIN-Entry does not need to stay in memory because the
219 @sc{gpg-agent} has the ability to cache passphrases.  The usual way to
220 run the PIN-Entry is by setting up a pipe (and not a socket) and then
221 fork/exec the PIN-Entry.  The communication is then done by means of
222 the protocol described here until the client is satisfied with the
223 result.
224
225 Although it is called a PIN-Entry, it does allow to enter reasonably
226 long strings (at least 2048 characters are supported by every
227 pinentry).  The client using the PIN-Entry has to check for
228 correctness.
229
230 Note that all strings are expected to be encoded as UTF-8; @pinentry{}
231 takes care of converting it to the locally used codeset.  To include
232 linefeeds or other special characters, you may percent-escape them
233 (i.e. a line feed is encoded as @code{%0A}, the percent sign itself
234 is encoded as @code{%25}).
235
236 Here is the list of supported commands:
237
238 @table @gnupgtabopt
239
240 @item Set the descriptive text to be displayed
241 @example
242   C: SETDESC Enter PIN for Richard Nixon <nobody@@trickydicky.gov>
243   S: OK
244 @end example
245
246 @item Set the prompt to be shown
247 When asking for a PIN, set the text just before the widget for
248 passphrase entry.
249 @example
250   C: SETPROMPT PIN:
251   S: OK
252 @end example
253
254 @item Set the button texts
255 There are two text with can be set to override the English defaults:
256
257 To set the text for the button signaling confirmation (in UTF-8).
258 @example
259   C: SETOK Yes
260   S: OK
261 @end example
262
263 To set the text for the button signaling cancellation or disagreement
264 (in UTF-8).
265 @example
266   C: SETCANCEL No
267   S: OK
268 @end example
269
270 @item Set the Error text
271 This is used by the client to display an error message.  In contrast
272 to the other commands this error message is automatically reset with
273 a GETPIN or CONFIRM, and is only displayed when asking for a PIN.
274 @example
275   C: SETERROR Invalid PIN entered - please try again
276   S: OK
277 @end example
278
279 @item Enable a passphrase quality indicator
280 Adds a quality indicator to the GETPIN window.  This indicator is
281 updated as the passphrase is typed.  The clients needs to implement an
282 inquiry named "QUALITY" which gets passed the current passpharse
283 (percent-plus escaped) and should send back a string with a single
284 numerical vauelue between -100 and 100.  Negative values will be
285 displayed in red.
286 @example
287   C: SETQUALITYBAR
288   S: OK
289 @end example
290
291 If a custom laber for the auality bar is required, just add that label
292 as an argument as precent escaped string.  You will need this feature to
293 translate the label because pinentry has no internal gettext except for
294 stock strings from the toolkit library.
295
296 @item Ask for a PIN
297 The meat of this tool is to ask for a passphrase of PIN, it is done with
298 this command:
299 @example
300   C: GETPIN
301   S: D no more tapes
302   S: OK
303 @end example
304 Note that the passphrase is transmitted in clear using standard data
305 responses.  Expect it to be in UTF-8.
306
307 @item Ask for confirmation
308 To ask for a confirmation (yes or no), you can use this command:
309 @example
310   C: CONFIRM
311   S: OK
312 @end example
313 The client should use SETDESC to set an appropriate text before
314 issuing this command, and may use SETPROMPT to set the button texts.
315 The value returned is either OK for YES or the error code
316 @code{ASSUAN_Not_Confirmed}.
317
318 @item Show a message
319 To show a message, you can use this command:
320 @example
321   C: MESSAGE
322   S: OK
323 @end example
324 alternativly you may add an option to confirm:
325 @example
326   C: CONFIRM --one-button
327   S: OK
328 @end example
329 The client should use SETDESC to set an appropriate text before issuing
330 this command, and may use SETOK to set the text for the dismiss button.
331 The value returned is OK or an error message.
332
333 @item Set the output device
334 When using X, the @pinentry{} program must be invoked with an
335 appropriate @code{DISPLAY} environment variable or the
336 @code{--display} option.
337
338 When using a text terminal:
339 @example
340   C: OPTION ttyname=/dev/tty3
341   S: OK
342   C: OPTION ttytype=vt100
343   S: OK
344   C: OPTION lc-ctype=de_DE.UTF-8
345   S: OK
346 @end example
347 The client should use the @code{ttyname} option to set the output TTY
348 file name, the @code{ttytype} option to the @code{TERM} variable
349 appropriate for this tty and @code{lc-ctype} to the locale which
350 defines the character set to use for this terminal.
351
352 @end table
353
354 @c ---------------------------------------------------------------------
355 @c Legal Blurbs
356 @c ---------------------------------------------------------------------
357
358 @include gpl.texi
359
360 @c ---------------------------------------------------------------------
361 @c Indexes
362 @c ---------------------------------------------------------------------
363
364 @node Option Index
365 @unnumbered Option Index
366
367 @printindex op
368
369 @node Index
370 @unnumbered Index
371
372 @printindex cp
373
374 @c ---------------------------------------------------------------------
375 @c Epilogue
376 @c ---------------------------------------------------------------------
377
378 @bye
379
380