* gpg-agent.c (handle_connections): Need to check for events if
[gnupg.git] / doc / tools.texi
1 @c Copyright (C) 2004 Free Software Foundation, Inc.
2 @c This is part of the GnuPG manual.
3 @c For copying conditions, see the file GnuPG.texi.
4
5 @node Helper Tools
6 @chapter Helper Tools
7
8 GnuPG comes with a couple of smaller tools:
9
10 @menu
11 * watchgnupg::            Read logs from a socket.
12 * addgnupghome::          Create .gnupg home directories.
13 * gpgconf::               Modify .gnupg home directories.
14 * gpgsm-gencert.sh::      Generate an X.509 certificate request.
15 * gpg-preset-passphrase:: Put a passphrase into the cache.
16 * gpg-connect-agent::     Communicate with a running agent.
17 @end menu
18
19 @c
20 @c  WATCHGNUPG
21 @c
22 @node watchgnupg
23 @section Read logs from a socket
24
25 Most of the main utilities are able to write there log files to a
26 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
27 listener for such a socket.  It ameliorates the output with a time
28 stamp and makes sure that long lines are not interspersed with log
29 output from other utilities.
30
31 @noindent
32 @command{watchgnupg} is commonly invoked as
33
34 @samp{watchgnupg --force ~/.gnupg/S.log}
35
36 @noindent
37 This starts it on the current terminal for listening on the socket
38 @file{~/.gnupg/S.log}.  
39
40 @noindent
41 @command{watchgnupg} understands these options:
42
43 @table @gnupgtabopt
44
45 @item --force 
46 @opindex force
47 Delete an already existing socket file.
48
49 @item --verbose
50 @opindex verbose
51 Enable extra informational output.
52
53 @item --version
54 @opindex version
55 print version of the program and exit
56
57 @item --help
58 @opindex help
59 Display a brief help page and exit
60
61 @end table
62
63
64 @c
65 @c    ADDGNUPGHOME
66 @c
67 @node addgnupghome
68 @section Create .gnupg home directories.
69
70 If GnuPG is installed on a system with existing user accounts, it is
71 sometimes required to populate the GnuPG home directory with existing
72 files.  Especially a @file{trustlist.txt} and a keybox with some
73 initial certificates are often desired.  This scripts help to do this
74 by copying all files from @file{/etc/skel/.gnupg} to the home
75 directories of the accounts given on the command line.  It takes care
76 not to overwrite existing GnuPG home directories.
77
78 @noindent
79 @command{addgnupghome} is invoked by root as:
80
81 @samp{addgnupghome account1 account2 ... accountn}
82
83
84 @c
85 @c   GPGCONF
86 @c
87 @node gpgconf
88 @section Modify .gnupg home directories.
89
90 The @command{gpgconf} is a utility to automatically and reasonable
91 safely query and modify configuration files in the @file{.gnupg} home
92 directory.  It is designed not to be invoked manually by the user, but
93 automatically by graphical user interfaces (GUI).@footnote{Please note
94 that currently no locking is done, so concurrent access should be
95 avoided.  There are some precautions to avoid corruption with
96 concurrent usage, but results may be inconsistent and some changes may
97 get lost.  The stateless design makes it difficult to provide more
98 guarantees.}
99
100 @command{gpgconf} provides access to the configuration of one or more
101 components of the GnuPG system.  These components correspond more or
102 less to the programs that exist in the GnuPG framework, like GnuPG,
103 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
104 relationship.  Not all configuration options are available through
105 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
106 method to access the most important configuration options that can
107 feasibly be controlled via such a mechanism.
108
109 @command{gpgconf} can be used to gather and change the options
110 available in each component, and can also provide their default
111 values.  @command{gpgconf} will give detailed type information that
112 can be used to restrict the user's input without making an attempt to
113 commit the changes.
114
115 @command{gpgconf} provides the backend of a configuration editor.  The
116 configuration editor would usually be a graphical user interface
117 program, that allows to display the current options, their default
118 values, and allows the user to make changes to the options.  These
119 changes can then be made active with @command{gpgconf} again.  Such a
120 program that uses @command{gpgconf} in this way will be called GUI
121 throughout this section.
122
123 @menu
124 * Invoking gpgconf::      List of all commands and options.
125 * Format conventions::    Formatting conventions relevant for all commands.
126 * Listing components::    List all gpgconf components.
127 * Listing options::       List all options of a component.
128 * Changing options::      Changing options of a component.
129 @end menu
130
131
132 @node Invoking gpgconf
133 @subsection Invoking gpgconf
134
135 One of the following commands must be given:
136
137 @table @gnupgtabopt
138 @item --list-components
139 List all components.  This is the default command used if none is
140 specified.
141
142 @item --list-options @var{component}
143 List all options of the component @var{component}.
144
145 @item --change-options @var{component}
146 Change the options of the component @var{component}.
147 @end table
148
149 The following options may be used:
150
151 @table @gnupgtabopt
152 @c FIXME: Not yet supported.
153 @c @item -o @var{file}
154 @c @itemx --output @var{file}
155 @c Use @var{file} as output file.
156
157 @item -v
158 @itemx --verbose
159 Outputs additional information while running.  Specifically, this
160 extends numerical field values by human-readable descriptions.
161
162 @c FIXME: Not yet supported.
163 @c @item -n
164 @c @itemx --dry-run
165 @c Do not actually change anything.  Useful together with
166 @c @code{--change-options} for testing purposes.
167
168 @item -r
169 @itemx --runtime
170 Only used together with @code{--change-options}.  If one of the
171 modified options can be changed in a running daemon process, signal
172 the running daemon to ask it to reparse its configuration file after
173 changing.
174
175 This means that the changes will take effect at run-time, as far as
176 this is possible.  Otherwise, they will take effect at the next start
177 of the respective backend programs.
178 @end table
179
180
181 @node Format conventions
182 @subsection Format conventions
183
184 Some lines in the output of @command{gpgconf} contain a list of
185 colon-separated fields.  The following conventions apply:
186
187 @itemize @bullet
188 @item
189 The GUI program is required to strip off trailing newline and/or
190 carriage return characters from the output.
191
192 @item
193 @command{gpgconf} will never leave out fields.  If a certain version
194 provides a certain field, this field will always be present in all
195 @command{gpgconf} versions from that time on.
196
197 @item
198 Future versions of @command{gpgconf} might append fields to the list.
199 New fields will always be separated from the previously last field by
200 a colon separator.  The GUI should be prepared to parse the last field
201 it knows about up until a colon or end of line.
202
203 @item
204 Not all fields are defined under all conditions.  You are required to
205 ignore the content of undefined fields.
206 @end itemize
207
208 There are several standard types for the content of a field:
209
210 @table @asis
211 @item verbatim
212 Some fields contain strings that are not escaped in any way.  Such
213 fields are described to be used @emph{verbatim}.  These fields will
214 never contain a colon character (for obvious reasons).  No de-escaping
215 or other formatting is required to use the field content.  This is for
216 easy parsing of the output, when it is known that the content can
217 never contain any special characters.
218
219 @item percent-escaped
220 Some fields contain strings that are described to be
221 @emph{percent-escaped}.  Such strings need to be de-escaped before
222 their content can be presented to the user.  A percent-escaped string
223 is de-escaped by replacing all occurences of @code{%XY} by the byte
224 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
225 from the set @code{0-9a-f}.
226
227 @item localised
228 Some fields contain strings that are described to be @emph{localised}.
229 Such strings are translated to the active language and formatted in
230 the active character set.
231
232 @item @w{unsigned number}
233 Some fields contain an @emph{unsigned number}.  This number will
234 always fit into a 32-bit unsigned integer variable.  The number may be
235 followed by a space, followed by a human readable description of that
236 value (if the verbose option is used).  You should ignore everything
237 in the field that follows the number.
238
239 @item @w{signed number}
240 Some fields contain a @emph{signed number}.  This number will always
241 fit into a 32-bit signed integer variable.  The number may be followed
242 by a space, followed by a human readable description of that value (if
243 the verbose option is used).  You should ignore everything in the
244 field that follows the number.
245
246 @item option
247 Some fields contain an @emph{option} argument.  The format of an
248 option argument depends on the type of the option and on some flags:
249
250 @table @asis
251 @item no argument
252 The simplest case is that the option does not take an argument at all
253 (@var{type} @code{0}).  Then the option argument is an unsigned number
254 that specifies how often the option occurs.  If the @code{list} flag
255 is not set, then the only valid number is @code{1}.  Options that do
256 not take an argument never have the @code{default} or @code{optional
257 arg} flag set.
258
259 @item number
260 If the option takes a number argument (@var{alt-type} is @code{2} or
261 @code{3}), and it can only occur once (@code{list} flag is not set),
262 then the option argument is either empty (only allowed if the argument
263 is optional), or it is a number.  A number is a string that begins
264 with an optional minus character, followed by one or more digits.  The
265 number must fit into an integer variable (unsigned or signed,
266 depending on @var{alt-type}).
267
268 @item number list
269 If the option takes a number argument and it can occur more than once,
270 then the option argument is either empty, or it is a comma-separated
271 list of numbers as described above.
272
273 @item string
274 If the option takes a string argument (@var{alt-type} is 1), and it
275 can only occur once (@code{list} flag is not set) then the option
276 argument is either empty (only allowed if the argument is optional),
277 or it starts with a double quote character (@code{"}) followed by a
278 percent-escaped string that is the argument value.  Note that there is
279 only a leading double quote character, no trailing one.  The double
280 quote character is only needed to be able to differentiate between no
281 value and the empty string as value.
282
283 @item string list
284 If the option takes a number argument and it can occur more than once,
285 then the option argument is either empty, or it is a comma-separated
286 list of string arguments as described above.
287 @end table
288 @end table
289
290 The active language and character set are currently determined from
291 the locale environment of the @command{gpgconf} program.
292
293 @c FIXME: Document the active language and active character set.  Allow
294 @c to change it via the command line?
295
296
297 @node Listing components
298 @subsection Listing components
299
300 The command @code{--list-components} will list all components that can
301 be configured with @command{gpgconf}.  Usually, one component will
302 correspond to one GnuPG-related program and contain the options of
303 that programs configuration file that can be modified using
304 @command{gpgconf}.  However, this is not necessarily the case.  A
305 component might also be a group of selected options from several
306 programs, or contain entirely virtual options that have a special
307 effect rather than changing exactly one option in one configuration
308 file.
309
310 A component is a set of configuration options that semantically belong
311 together.  Furthermore, several changes to a component can be made in
312 an atomic way with a single operation.  The GUI could for example
313 provide a menu with one entry for each component, or a window with one
314 tabulator sheet per component.
315
316 The command argument @code{--list-components} lists all available
317 components, one per line.  The format of each line is:
318
319 @code{@var{name}:@var{description}}
320
321 @table @var
322 @item name
323 This field contains a name tag of the component.  The name tag is used
324 to specify the component in all communication with @command{gpgconf}.
325 The name tag is to be used @emph{verbatim}.  It is thus not in any
326 escaped format.
327
328 @item description
329 The @emph{string} in this field contains a human-readable description
330 of the component.  It can be displayed to the user of the GUI for
331 informational purposes.  It is @emph{percent-escaped} and
332 @emph{localized}.
333 @end table
334
335 Example:
336 @example
337 $ gpgconf --list-components
338 gpg:GPG for OpenPGP
339 gpg-agent:GPG Agent
340 scdaemon:Smartcard Daemon
341 gpgsm:GPG for S/MIME
342 dirmngr:Directory Manager
343 @end example
344
345
346 @node Listing options
347 @subsection Listing options
348
349 Every component contains one or more options.  Options may be gathered
350 into option groups to allow the GUI to give visual hints to the user
351 about which options are related.
352
353 The command argument @code{@w{--list-options @var{component}}} lists
354 all options (and the groups they belong to) in the component
355 @var{component}, one per line.  @var{component} must be the string in
356 the field @var{name} in the output of the @code{--list-components}
357 command.
358
359 There is one line for each option and each group.  First come all
360 options that are not in any group.  Then comes a line describing a
361 group.  Then come all options that belong into each group.  Then comes
362 the next group and so on.  There does not need to be any group (and in
363 this case the output will stop after the last non-grouped option).
364
365 The format of each line is:
366
367 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
368
369 @table @var
370 @item name
371 This field contains a name tag for the group or option.  The name tag
372 is used to specify the group or option in all communication with
373 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
374 thus not in any escaped format.
375
376 @item flags
377 The flags field contains an @emph{unsigned number}.  Its value is the
378 OR-wise combination of the following flag values:
379
380 @table @code
381 @item group (1)
382 If this flag is set, this is a line describing a group and not an
383 option.
384 @end table
385
386 The following flag values are only defined for options (that is, if
387 the @code{group} flag is not used).
388
389 @table @code
390 @item optional arg (2)
391 If this flag is set, the argument is optional.  This is never set for
392 @var{type} @code{0} (none) options.
393
394 @item list (4)
395 If this flag is set, the option can be given multiple times.
396
397 @item runtime (8)
398 If this flag is set, the option can be changed at runtime.
399
400 @item default (16)
401 If this flag is set, a default value is available.
402
403 @item default desc (32)
404 If this flag is set, a (runtime) default is available.  This and the
405 @code{default} flag are mutually exclusive.
406
407 @item no arg desc (64)
408 If this flag is set, and the @code{optional arg} flag is set, then the
409 option has a special meaning if no argument is given.
410 @end table
411
412 @item level
413 This field is defined for options and for groups.  It contains an
414 @emph{unsigned number} that specifies the expert level under which
415 this group or option should be displayed.  The following expert levels
416 are defined for options (they have analogous meaning for groups):
417
418 @table @code
419 @item basic (0)
420 This option should always be offered to the user.
421
422 @item advanced (1)
423 This option may be offered to advanced users.
424
425 @item expert (2)
426 This option should only be offered to expert users.
427
428 @item invisible (3)
429 This option should normally never be displayed, not even to expert
430 users.
431
432 @item internal (4)
433 This option is for internal use only.  Ignore it.
434 @end table
435
436 The level of a group will always be the lowest level of all options it
437 contains.
438
439 @item description
440 This field is defined for options and groups.  The @emph{string} in
441 this field contains a human-readable description of the option or
442 group.  It can be displayed to the user of the GUI for informational
443 purposes.  It is @emph{percent-escaped} and @emph{localized}.
444
445 @item type
446 This field is only defined for options.  It contains an @emph{unsigned
447 number} that specifies the type of the option's argument, if any.  The
448 following types are defined:
449
450 Basic types:
451
452 @table @code
453 @item none (0)
454 No argument allowed.
455
456 @item string (1)
457 An @emph{unformatted string}.
458
459 @item int32 (2)
460 A @emph{signed number}.
461
462 @item uint32 (3)
463 An @emph{unsigned number}.
464 @end table
465
466 Complex types:
467
468 @table @code
469 @item pathname (32)
470 A @emph{string} that describes the pathname of a file.  The file does
471 not necessarily need to exist.
472
473 @item ldap server (33)
474 A @emph{string} that describes an LDAP server in the format:
475
476 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
477 @end table
478
479 More types will be added in the future.  Please see the @var{alt-type}
480 field for information on how to cope with unknown types.
481
482 @item alt-type
483 This field is identical to @var{type}, except that only the types
484 @code{0} to @code{31} are allowed.  The GUI is expected to present the
485 user the option in the format specified by @var{type}.  But if the
486 argument type @var{type} is not supported by the GUI, it can still
487 display the option in the more generic basic type @var{alt-type}.  The
488 GUI must support all the defined basic types to be able to display all
489 options.  More basic types may be added in future versions.  If the
490 GUI encounters a basic type it doesn't support, it should report an
491 error and abort the operation.
492
493 @item argname
494 This field is only defined for options with an argument type
495 @var{type} that is not @code{0}.  In this case it may contain a
496 @emph{percent-escaped} and @emph{localised string} that gives a short
497 name for the argument.  The field may also be empty, though, in which
498 case a short name is not known.
499
500 @item default
501 This field is defined only for options.  Its format is that of an
502 @emph{option argument} (@xref{Format conventions}, for details).  If
503 the default value is empty, then no default is known.  Otherwise, the
504 value specifies the default value for this option.  Note that this
505 field is also meaningful if the option itself does not take a real
506 argument.
507
508 @item argdef
509 This field is defined only for options for which the @code{optional
510 arg} flag is set.  If the @code{no arg desc} flag is not set, its
511 format is that of an @emph{option argument} (@xref{Format
512 conventions}, for details).  If the default value is empty, then no
513 default is known.  Otherwise, the value specifies the default value
514 for this option.  If the @code{no arg desc} flag is set, the field is
515 either empty or contains a description of the effect of this option if
516 no argument is given.  Note that this field is also meaningful if the
517 option itself does not take a real argument.
518
519 @item value
520 This field is defined only for options.  Its format is that of an
521 @emph{option argument}.  If it is empty, then the option is not
522 explicitely set in the current configuration, and the default applies
523 (if any).  Otherwise, it contains the current value of the option.
524 Note that this field is also meaningful if the option itself does not
525 take a real argument.
526 @end table
527
528
529 @node Changing options
530 @subsection Changing options
531
532 The command @w{@code{--change-options @var{component}}} will attempt
533 to change the options of the component @var{component} to the
534 specified values.  @var{component} must be the string in the field
535 @var{name} in the output of the @code{--list-components} command.  You
536 have to provide the options that shall be changed in the following
537 format on standard input:
538
539 @code{@var{name}:@var{flags}:@var{new-value}}
540
541 @table @var
542 @item name
543 This is the name of the option to change.  @var{name} must be the
544 string in the field @var{name} in the output of the
545 @code{--list-options} command.
546
547 @item flags
548 The flags field contains an @emph{unsigned number}.  Its value is the
549 OR-wise combination of the following flag values:
550
551 @table @code
552 @item default (16)
553 If this flag is set, the option is deleted and the default value is
554 used instead (if applicable).
555 @end table
556
557 @item new-value
558 The new value for the option.  This field is only defined if the
559 @code{default} flag is not set.  The format is that of an @emph{option
560 argument}.  If it is empty (or the field is omitted), the default
561 argument is used (only allowed if the argument is optional for this
562 option).  Otherwise, the option will be set to the specified value.
563 @end table
564
565 Examples:
566
567 To set the force option, which is of basic type @code{none (0)}:
568
569 @example
570 $ echo 'force:0:1' | gpgconf --change-options dirmngr
571 @end example
572
573 To delete the force option:
574
575 @example
576 $ echo 'force:16:' | gpgconf --change-options dirmngr
577 @end example
578
579 The @code{--runtime} option can influence when the changes take
580 effect.
581
582 @c
583 @c    GPGSM-GENCERT.SH
584 @c
585 @node gpgsm-gencert.sh
586 @section Generate an X.509 certificate request
587
588 This is a simple tool to interactivly generate a certificate request
589 whicl will be printed to stdout.
590
591 @noindent
592 @command{gpgsm-gencert.sh} is invoked as:
593
594 @samp{gpgsm-cencert.sh}
595
596
597
598 @c
599 @c   GPG-PRESET-PASSPHRASE
600 @c
601 @node gpg-preset-passphrase
602 @section Put a passphrase into the cache.
603
604 The @command{gpg-preset-passphrase} is a utility to seed the internal
605 cache of a running @command{gpg-agent} with passphrases.  It is mainly
606 useful for unattended machines, where the usual @command{pinentry} tool
607 may not be used and the passphrases for the to be used keys are given at
608 machine startup.
609
610 Passphrases set with this utility don't expire unless the
611 @option{--forget} option is used to explicitly clear them from the cache
612 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
613 SIGHUP to it).  It is necessary to allow this passphrase presetting by
614 starting @command{gpg-agent} with the
615 @option{--allow-preset-passphrase}.
616
617 @menu
618 * Invoking gpg-preset-passphrase::   List of all commands and options.
619 @end menu
620
621
622 @node Invoking gpg-preset-passphrase
623 @subsection List of all commands and options.
624
625 @noindent
626 @command{gpg-preset-passphrase} is invoked this way:
627
628 @example
629 gpg-preset-passphrase [options] [command] @var{keygrip}
630 @end example
631
632 @var{keygrip} is a 40 character string of hexadecimal characters
633 identifying the key for which the passphrase should be set or cleared.
634 This keygrip is listed along with the key when running the command:
635 @code{gpgsm --dump-secret-keys}. One of the following command options
636 must be given:
637
638 @table @gnupgtabopt
639 @item --preset
640 Preset a passphrase. This is what you usually will
641 use. @command{gpg-preset-passphrase} will then read the passphrase from
642 @code{stdin}.
643
644 @item --forget
645 Flush the passphrase for the given keygrip from the cache.
646
647 @end table
648
649 @noindent
650 The following additional options may be used:
651
652 @table @gnupgtabopt
653 @item -v
654 @itemx --verbose
655 @opindex verbose
656 Output additional information while running.  
657
658 @item -P @var{string}
659 @itemx --passphrase @var{string}
660 @opindex passphrase
661 Instead of reading the passphrase from @code{stdin}, use the supplied
662 @var{string} as passphrase.  Note that this makes the passphrase visible
663 for other users.
664 @end table
665
666
667
668
669
670 @c
671 @c   GPG-CONNECT-AGENT
672 @c
673 @node gpg-connect-agent
674 @section Communicate with a runnig agent.
675
676 The @command{gpg-connect-agent} is a utility to communicate with a
677 running @command{gpg-agent}.  It is useful to check out the commands
678 gpg-agent provides using the Assuan interface.  It might also be useful
679 for scripting simple applications.  Inputis expected at stdin and out
680 put gets printed to stdout.
681
682 It is very similar to running @command{gpg-agent} in server mode; but
683 here we connect to a running instance.
684
685 @menu
686 * Invoking gpg-connect-agent::   List of all commands and options.
687 @end menu
688
689
690 @node Invoking gpg-connect-agent
691 @subsection List of all commands and options.
692
693 @noindent
694 @command{gpg-connect-agent} is invoked this way:
695
696 @example
697 gpg-connect-agent [options]
698 @end example
699
700 @noindent
701 The following options may be used:
702
703 @table @gnupgtabopt
704 @item -v
705 @itemx --verbose
706 @opindex verbose
707 Output additional information while running.  
708
709 @item -q
710 @item --quiet
711 @opindex q
712 @opindex quiet
713 Try to be as quiet as possible.
714
715 @item --homedir @var{dir}
716 @opindex homedir
717 Set the name of the home directory to @var{dir}. If his option is not
718 used, the home directory defaults to @file{~/.gnupg}.  It is only
719 recognized when given on the command line.  It also overrides any home
720 directory stated through the environment variable @env{GNUPGHOME} or
721 (on W32 systems) by means on the Registry entry
722 @var{HKCU\Software\GNU\GnuPG:HomeDir}.
723
724
725 @end table
726
727
728
729