f62d726bb737b3e959d6920b8372726b3d765d5b
[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 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 Free Documentation License, Version 1.1 or
13 any later version published by the Free Software Foundation; with no
14 Invariant Sections, with no Front-Cover texts, and with no Back-Cover
15 Texts.  A copy of the license is included in the section entitled ``GNU
16 Free Documentation License''.
17 @end macro
18
19
20 @settitle Using the PINEntry
21
22 @c Create a separate index for command line options.
23 @defcodeindex op
24 @c Merge the standard indexes into a single one.
25 @syncodeindex fn cp
26 @syncodeindex vr cp
27 @syncodeindex ky cp
28 @syncodeindex pg cp
29 @syncodeindex tp cp
30
31 @c printing stuff taken from gcc.
32 @macro gnupgtabopt{body}
33 @code{\body\}
34 @end macro
35 @macro gnupgoptlist{body}
36 @smallexample
37 \body\
38 @end smallexample
39 @end macro
40 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
41 @c they get lost at some point in handling the macro.  But if @macro is
42 @c used here rather than @alias, it produces double line breaks.
43 @iftex
44 @alias gol = *
45 @end iftex
46 @ifnottex
47 @macro gol
48 @end macro
49 @end ifnottex
50
51
52 @c Change the font used for @def... commands, since the default
53 @c proportional one used is bad for names starting __.
54 @tex
55 \global\setfont\defbf\ttbshape{10}{\magstep1}
56 @end tex
57
58 @c %**end of header
59
60 @ifnottex
61 @dircategory GNU Utilities
62 @direntry
63 * gpg: (gnupg).            OpenPGP encryption and signing tool.
64 * gpgsm: (gnupg).          S/MIME encryption and signing tool.
65 @end direntry
66 This file documents the use and the internals of the PINEnrty.
67
68 This is edition @value{EDITION}, last updated @value{UPDATED}, of
69 @cite{The `PINEnrty' Manual}, for version @value{VERSION}.
70 @sp 1
71 Published by g10 Code GmbH@*
72 Remscheider Str. 22@*
73 40215 Düsseldorf, Germany
74 @sp 1
75 @copyrightnotice{}
76 @sp 1
77 @permissionnotice{}
78 @end ifnottex
79
80 @setchapternewpage odd
81
82 @titlepage
83 @title Using the PINEntry
84 @subtitle Version @value{VERSION}
85 @subtitle @value{UPDATED}
86 @author Werner Koch @code{(wk@@gnupg.org)}
87
88 @page
89 @vskip 0pt plus 1filll
90 @copyrightnotice{}
91 @sp 2
92 @permissionnotice{}
93 @end titlepage
94 @summarycontents
95 @contents
96 @page
97
98
99 @node Top
100 @top Introduction
101 @cindex introduction
102
103 This manual documents how to use the PINEntry and the protocol implemented.
104
105 The @sc{pinentry} is a small GUI application used to enter PINs or
106 Passphrases. It is usually invoked by @sc{gpg-agent}
107 (@pxref{Invoking GPG-AGENT, ,Invoking the gpg-agent, gnupg,
108     The `GNU Privacy Guard' Manual}, for details).       
109
110 @sc{pinentry} comes in 3 flavors to fit the look and feel of the used
111 GUI toolkit:  A @sc{GTK+} based one named @code{pinentry-gtk}, a
112 @sc{Qt} based one named @code{pinentry-qt} and a non-graphical one based
113 on curser and named @code{pinentry-curses}.  Not all of them might be
114 available on your installation.  If curses is supported on your system,
115 the GUI based flavors fall back to curses when the @code{DISPLAY}
116 variable is not set.
117
118
119 @menu
120 * Using pinentry::      How to use the beast.
121
122 Developer information
123
124 * Protocol::            The Assuan protocol description.
125
126 Miscellaneous
127
128 * Copying::             GNU General Public License says
129                         how you can copy and share GnuPG
130 * GNU Free Documentation License:: How you can copy and share this manual.
131
132 Indices
133
134 * Option Index::        Index to command line options.
135 * Index::               Index of concepts and symbol names.
136 @end menu
137
138 @node Using pinentry
139 @chapter How to use the pinentry
140
141 @c man begin DESCRIPTION
142
143 You may run it directly from the commandline and pass the commands
144 according to the Assuan protocol via stdin/stdout.
145
146
147 @c man end
148
149 @c man begin OPTIONS
150
151 Here is a list of options supported by all 3 flavors of pinentry
152
153 @table @gnupgtabopt
154 @item --version
155 @opindex version
156 Print the program version and licensing information. 
157
158 @item --help
159 @opindex help
160 Print a usage message summarizing the most usefule command-line options.
161
162 @item --debug
163 @itemx -d
164 @opindex debug
165 @opindex d
166 Trun on some debugging.  Mostly useful for the mainatiners.  Note that
167 this may reveal sensitive information like the entered passphrase.
168
169 @item --enhanced
170 @itemx -x
171 @opindex enhanced
172 @opindex e
173 Ask for timeouts and insurance, too.
174
175
176 @item --no-global-grab
177 @itemx -g
178 @opindex no-global-grab
179 @opindex g
180 Grab the keyboard only when the window is focused.
181
182
183
184 @end table
185
186 @c 
187 @c  Assuan Protocol
188 @c
189 @node Protocol
190 @chapter pinentry's Assuan Protocol
191
192 The PIN-Entry should never service more than one connection at once.
193 It is reasonable to exec the PIN-Entry prior to a request.
194
195 The PIN-Entry does not need to stay in memory because the gpg-agent has
196 the ability to cache passphrases.  The usual way to run the PIN-Entry is
197 by setting up a pipe (and not a socket) and then fork/exec the
198 PIN-Entry.  The communication is then done by means of the protocol
199 described here until the client is satisfied with the result.
200
201 Although it is called a PIN-Entry, it does allow to enter reasonably
202 long strings (at least 2048 characters are supported by every
203 pinentry).  The client using the PIN-Entry has to check for
204 correctness.
205
206 Here is the list of supported commands:
207
208 @table @gnupgtabopt
209
210 @item Set the descriptive text to be displayed
211 @example
212   C: SETDESC Enter PIN for Richard Nixon <nobody@@trickydicky.gov>
213   S: OK
214 @end example
215
216 @item Set the prompt to be shown
217 When asking for a PIN, set the text just before the widget for
218 passphrase entry.
219 @example
220   C: SETPROMPT PIN:
221   S: OK
222 @end example
223
224 @item Set the button texts
225 There are two text with can be set to overide the English defaults:
226
227 To set the text for the button signalling confirmation (in UTF-8).
228 @example
229   C: SETOK Yes
230   S: OK
231 @end example
232
233 To set the text for the button signalling cancellation or disagreement
234 (in UTF-8).
235 @example
236   C: SETCANCEL No
237   S: OK
238 @end example
239
240 @item Set the Error text
241 This is used by the client to display an error message.  In contrast
242 to the other commands this error message is automatically reset with
243 a GETPIN or CONFIRM, and is only displayed when asking for a PIN.
244 @example
245   C: SETERROR Invalid PIN entered - please try again
246   S: OK
247 @end example
248
249 @item Ask for a PIN
250 The meat of this tool is to ask for a passphrase of PIN, it is done with
251 this command:
252 @example
253   C: GETPIN
254   S: D no more tapes
255   S: OK
256 @end example
257 Note that the passphrase is transmitted in clear using standard data
258 responses.  Expect it to be in utf-8.
259
260 @item Ask for confirmation
261 To ask for a confirmation (yes or no), you can use this command:
262 @example
263   C: CONFIRM
264   S: OK
265 @end example
266 The client should use SETDESC to set an appropriate text before
267 issuing this command, and may use SETPROMPT to set the button texts.
268 The value returned is either OK for YES or the error code
269 @code{ASSUAN_Not_Confirmed}.
270
271 @item Set the output device
272 When using X, the pinentry program must be invoked with an
273 appropriate DISPLAY environment variable or --display option.
274
275 When using a text terminal:
276 @example
277   C: OPTION ttyname=/dev/tty3
278   S: OK
279   C: OPTION ttytype=vt100
280   S: OK
281   C: OPTION lc-ctype=de_DE.UTF-8
282   S: OK
283 @end example
284 The client should set the ttyname option to set the output tty file
285 name, the ttytype option to the TERM variable appropriate for this
286 tty and lc-ctype to the locale which defines the character set to
287 use for this terminal.
288
289 @end table
290
291 @c ---------------------------------------------------------------------
292 @c Legal Blurbs
293 @c ---------------------------------------------------------------------
294
295 @include gpl.texi
296 @include fdl.texi
297
298 @c ---------------------------------------------------------------------
299 @c Indexes
300 @c ---------------------------------------------------------------------
301
302 @node Option Index
303 @unnumbered Option Index
304
305 @printindex op
306
307 @node Index
308 @unnumbered Index
309
310 @printindex cp
311
312 @c ---------------------------------------------------------------------
313 @c Epilogue
314 @c ---------------------------------------------------------------------
315
316 @bye
317
318