2008-01-10 Marcus Brinkmann <marcus@g10code.de>
[gnupg.git] / doc / tools.texi
1 @c Copyright (C) 2004, 2008 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 * gpgv::                  Verify OpenPGP signatures.
13 * addgnupghome::          Create .gnupg home directories.
14 * gpgconf::               Modify .gnupg home directories.
15 * applygnupgdefaults::    Run gpgconf for all users.
16 * gpgsm-gencert.sh::      Generate an X.509 certificate request.
17 * gpg-preset-passphrase:: Put a passphrase into the cache.
18 * gpg-connect-agent::     Communicate with a running agent.
19 * gpgparsemail::          Parse a mail message into an annotated format
20 * symcryptrun::           Call a simple symmetric encryption tool.
21 @end menu
22
23 @c
24 @c  WATCHGNUPG
25 @c
26 @manpage watchgnupg.1
27 @node watchgnupg
28 @section Read logs from a socket
29 @ifset manverb
30 .B watchgnupg
31 \- Read and print logs from a socket
32 @end ifset
33
34 @mansect synopsis
35 @ifset manverb
36 .B  watchgnupg
37 .RB [ \-\-force ]
38 .RB [ \-\-verbose ]
39 .I socketname
40 @end ifset
41
42 @mansect description
43 Most of the main utilities are able to write there log files to a
44 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
45 listener for such a socket.  It ameliorates the output with a time
46 stamp and makes sure that long lines are not interspersed with log
47 output from other utilities.
48
49 @noindent
50 @command{watchgnupg} is commonly invoked as
51
52 @example
53 watchgnupg --force ~/.gnupg/S.log
54 @end example
55 @manpause
56
57 @noindent
58 This starts it on the current terminal for listening on the socket
59 @file{~/.gnupg/S.log}.  
60
61 @mansect options
62 @noindent
63 @command{watchgnupg} understands these options:
64
65 @table @gnupgtabopt
66
67 @item --force 
68 @opindex force
69 Delete an already existing socket file.
70
71 @item --verbose
72 @opindex verbose
73 Enable extra informational output.
74
75 @item --version
76 @opindex version
77 print version of the program and exit
78
79 @item --help
80 @opindex help
81 Display a brief help page and exit
82
83 @end table
84
85 @mansect see also
86 @ifset isman
87 @command{gpg}(1), 
88 @command{gpgsm}(1), 
89 @command{gpg-agent}(1), 
90 @command{scdaemon}(1)
91 @end ifset
92 @include see-also-note.texi
93
94
95 @c
96 @c  GPGV
97 @c
98 @include gpgv.texi
99
100
101 @c
102 @c    ADDGNUPGHOME
103 @c
104 @manpage addgnupghome.8
105 @node addgnupghome
106 @section Create .gnupg home directories.
107 @ifset manverb
108 .B addgnupghome 
109 \- Create .gnupg home directories
110 @end ifset
111
112 @mansect synopsis
113 @ifset manverb
114 .B  addgnupghome
115 .I account_1
116 .IR account_2 ... account_n
117 @end ifset
118
119 @mansect description
120 If GnuPG is installed on a system with existing user accounts, it is
121 sometimes required to populate the GnuPG home directory with existing
122 files.  Especially a @file{trustlist.txt} and a keybox with some
123 initial certificates are often desired.  This scripts help to do this
124 by copying all files from @file{/etc/skel/.gnupg} to the home
125 directories of the accounts given on the command line.  It takes care
126 not to overwrite existing GnuPG home directories.
127
128 @noindent
129 @command{addgnupghome} is invoked by root as:
130
131 @example
132 addgnupghome account1 account2 ... accountn
133 @end example
134
135
136 @c
137 @c   GPGCONF
138 @c
139 @manpage gpgconf.1
140 @node gpgconf
141 @section Modify .gnupg home directories.
142 @ifset manverb
143 .B gpgconf
144 \- Modify .gnupg home directories
145 @end ifset
146
147 @mansect synopsis
148 @ifset manverb
149 .B gpgconf
150 .RI [ options ]
151 .B \-\-list-components
152 .br
153 .B gpgconf
154 .RI [ options ]
155 .B \-\-list-options 
156 .I component
157 .br
158 .B gpgconf
159 .RI [ options ]
160 .B \-\-change-options
161 .I component
162 @end ifset
163
164
165 @mansect description
166 The @command{gpgconf} is a utility to automatically and reasonable
167 safely query and modify configuration files in the @file{.gnupg} home
168 directory.  It is designed not to be invoked manually by the user, but
169 automatically by graphical user interfaces (GUI).@footnote{Please note
170 that currently no locking is done, so concurrent access should be
171 avoided.  There are some precautions to avoid corruption with
172 concurrent usage, but results may be inconsistent and some changes may
173 get lost.  The stateless design makes it difficult to provide more
174 guarantees.}
175
176 @command{gpgconf} provides access to the configuration of one or more
177 components of the GnuPG system.  These components correspond more or
178 less to the programs that exist in the GnuPG framework, like GnuPG,
179 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
180 relationship.  Not all configuration options are available through
181 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
182 method to access the most important configuration options that can
183 feasibly be controlled via such a mechanism.
184
185 @command{gpgconf} can be used to gather and change the options
186 available in each component, and can also provide their default
187 values.  @command{gpgconf} will give detailed type information that
188 can be used to restrict the user's input without making an attempt to
189 commit the changes.
190
191 @command{gpgconf} provides the backend of a configuration editor.  The
192 configuration editor would usually be a graphical user interface
193 program, that allows to display the current options, their default
194 values, and allows the user to make changes to the options.  These
195 changes can then be made active with @command{gpgconf} again.  Such a
196 program that uses @command{gpgconf} in this way will be called GUI
197 throughout this section.
198
199 @menu
200 * Invoking gpgconf::       List of all commands and options.
201 * Format conventions::     Formatting conventions relevant for all commands.
202 * Listing components::     List all gpgconf components.
203 * Checking programs::      Check all programs know to gpgconf.
204 * Listing options::        List all options of a component.
205 * Changing options::       Changing options of a component.
206 * Listing global options:: List all global options.
207 * Files used by gpgconf::  What files are used by gpgconf.
208 @end menu
209
210 @manpause
211 @node Invoking gpgconf
212 @subsection Invoking gpgconf
213
214 @mansect commands
215 One of the following commands must be given:
216
217 @table @gnupgtabopt
218
219 @item --list-components
220 List all components.  This is the default command used if none is
221 specified.
222
223 @item --check-programs
224 List all available backend programs and test whether they are runnable.
225
226 @item --list-options @var{component}
227 List all options of the component @var{component}.
228
229 @item --change-options @var{component}
230 Change the options of the component @var{component}.
231
232 @item --apply-defaults
233 Update all configuration files with values taken from the global
234 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
235
236 @item --list-config [@var{filename}]
237 List the global configuration file in a colon separated format.  If
238 @var{filename} is given, check that file instead.
239
240 @item --check-config [@var{filename}]
241 Run a syntax check on the global configuration file.  If @var{filename}
242 is given, check that file instead.
243
244 @end table
245
246
247 @mansect options
248
249 The following options may be used:
250
251 @table @gnupgtabopt
252 @c FIXME: Not yet supported.
253 @c @item -o @var{file}
254 @c @itemx --output @var{file}
255 @c Use @var{file} as output file.
256
257 @item -v
258 @itemx --verbose
259 Outputs additional information while running.  Specifically, this
260 extends numerical field values by human-readable descriptions.
261
262 @c FIXME: Not yet supported.
263 @c @item -n
264 @c @itemx --dry-run
265 @c Do not actually change anything.  Useful together with
266 @c @code{--change-options} for testing purposes.
267
268 @item -r
269 @itemx --runtime
270 Only used together with @code{--change-options}.  If one of the
271 modified options can be changed in a running daemon process, signal
272 the running daemon to ask it to reparse its configuration file after
273 changing.
274
275 This means that the changes will take effect at run-time, as far as
276 this is possible.  Otherwise, they will take effect at the next start
277 of the respective backend programs.
278 @manpause
279 @end table
280
281
282 @node Format conventions
283 @subsection Format conventions
284
285 Some lines in the output of @command{gpgconf} contain a list of
286 colon-separated fields.  The following conventions apply:
287
288 @itemize @bullet
289 @item
290 The GUI program is required to strip off trailing newline and/or
291 carriage return characters from the output.
292
293 @item
294 @command{gpgconf} will never leave out fields.  If a certain version
295 provides a certain field, this field will always be present in all
296 @command{gpgconf} versions from that time on.
297
298 @item
299 Future versions of @command{gpgconf} might append fields to the list.
300 New fields will always be separated from the previously last field by
301 a colon separator.  The GUI should be prepared to parse the last field
302 it knows about up until a colon or end of line.
303
304 @item
305 Not all fields are defined under all conditions.  You are required to
306 ignore the content of undefined fields.
307 @end itemize
308
309 There are several standard types for the content of a field:
310
311 @table @asis
312 @item verbatim
313 Some fields contain strings that are not escaped in any way.  Such
314 fields are described to be used @emph{verbatim}.  These fields will
315 never contain a colon character (for obvious reasons).  No de-escaping
316 or other formatting is required to use the field content.  This is for
317 easy parsing of the output, when it is known that the content can
318 never contain any special characters.
319
320 @item percent-escaped
321 Some fields contain strings that are described to be
322 @emph{percent-escaped}.  Such strings need to be de-escaped before
323 their content can be presented to the user.  A percent-escaped string
324 is de-escaped by replacing all occurences of @code{%XY} by the byte
325 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
326 from the set @code{0-9a-f}.
327
328 @item localised
329 Some fields contain strings that are described to be @emph{localised}.
330 Such strings are translated to the active language and formatted in
331 the active character set.
332
333 @item @w{unsigned number}
334 Some fields contain an @emph{unsigned number}.  This number will
335 always fit into a 32-bit unsigned integer variable.  The number may be
336 followed by a space, followed by a human readable description of that
337 value (if the verbose option is used).  You should ignore everything
338 in the field that follows the number.
339
340 @item @w{signed number}
341 Some fields contain a @emph{signed number}.  This number will always
342 fit into a 32-bit signed integer variable.  The number may be followed
343 by a space, followed by a human readable description of that value (if
344 the verbose option is used).  You should ignore everything in the
345 field that follows the number.
346
347 @item @w{boolean value}
348 Some fields contain a @emph{boolean value}.  This is a number with
349 either the value 0 or 1.  The number may be followed by a space,
350 followed by a human readable description of that value (if the verbose
351 option is used).  You should ignore everything in the field that follows
352 the number; checking just the first character is sufficient in this
353 case.
354
355 @item option
356 Some fields contain an @emph{option} argument.  The format of an
357 option argument depends on the type of the option and on some flags:
358
359 @table @asis
360 @item no argument
361 The simplest case is that the option does not take an argument at all
362 (@var{type} @code{0}).  Then the option argument is an unsigned number
363 that specifies how often the option occurs.  If the @code{list} flag
364 is not set, then the only valid number is @code{1}.  Options that do
365 not take an argument never have the @code{default} or @code{optional
366 arg} flag set.
367
368 @item number
369 If the option takes a number argument (@var{alt-type} is @code{2} or
370 @code{3}), and it can only occur once (@code{list} flag is not set),
371 then the option argument is either empty (only allowed if the argument
372 is optional), or it is a number.  A number is a string that begins
373 with an optional minus character, followed by one or more digits.  The
374 number must fit into an integer variable (unsigned or signed,
375 depending on @var{alt-type}).
376
377 @item number list
378 If the option takes a number argument and it can occur more than once,
379 then the option argument is either empty, or it is a comma-separated
380 list of numbers as described above.
381
382 @item string
383 If the option takes a string argument (@var{alt-type} is 1), and it
384 can only occur once (@code{list} flag is not set) then the option
385 argument is either empty (only allowed if the argument is optional),
386 or it starts with a double quote character (@code{"}) followed by a
387 percent-escaped string that is the argument value.  Note that there is
388 only a leading double quote character, no trailing one.  The double
389 quote character is only needed to be able to differentiate between no
390 value and the empty string as value.
391
392 @item string list
393 If the option takes a number argument and it can occur more than once,
394 then the option argument is either empty, or it is a comma-separated
395 list of string arguments as described above.
396 @end table
397 @end table
398
399 The active language and character set are currently determined from
400 the locale environment of the @command{gpgconf} program.
401
402 @c FIXME: Document the active language and active character set.  Allow
403 @c to change it via the command line?
404
405
406 @mansect usage
407 @node Listing components
408 @subsection Listing components
409
410 The command @code{--list-components} will list all components that can
411 be configured with @command{gpgconf}.  Usually, one component will
412 correspond to one GnuPG-related program and contain the options of
413 that programs configuration file that can be modified using
414 @command{gpgconf}.  However, this is not necessarily the case.  A
415 component might also be a group of selected options from several
416 programs, or contain entirely virtual options that have a special
417 effect rather than changing exactly one option in one configuration
418 file.
419
420 A component is a set of configuration options that semantically belong
421 together.  Furthermore, several changes to a component can be made in
422 an atomic way with a single operation.  The GUI could for example
423 provide a menu with one entry for each component, or a window with one
424 tabulator sheet per component.
425
426 The command argument @code{--list-components} lists all available
427 components, one per line.  The format of each line is:
428
429 @code{@var{name}:@var{description}:@var{pgmname}:}
430
431 @table @var
432 @item name
433 This field contains a name tag of the component.  The name tag is used
434 to specify the component in all communication with @command{gpgconf}.
435 The name tag is to be used @emph{verbatim}.  It is thus not in any
436 escaped format.
437
438 @item description
439 The @emph{string} in this field contains a human-readable description
440 of the component.  It can be displayed to the user of the GUI for
441 informational purposes.  It is @emph{percent-escaped} and
442 @emph{localized}.
443
444 @item pgmname
445 The @emph{string} in this field contains the absolute name of the
446 program's file.  It can be used to unambiguously invoke that program.
447 It is @emph{percent-escaped}.
448 @end table
449
450 Example:
451 @example
452 $ gpgconf --list-components
453 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
454 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
455 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
456 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
457 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
458 @end example
459
460
461
462 @node Checking programs
463 @subsection Checking programs
464
465 The command @code{--check-programs} is similar to
466 @code{--list-components} but works on backend programs and not on
467 components.  It runs each program to test wether it is installed and
468 runnable.  This also includes a syntax check of all config file options
469 of the program.
470
471 The command argument @code{--check-programs} lists all available
472 programs, one per line.  The format of each line is:
473
474 @code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
475
476 @table @var
477 @item name
478 This field contains a name tag of the program which is identical to the
479 name of the component.  The name tag is to be used @emph{verbatim}.  It
480 is thus not in any escaped format.  This field may be empty to indicate
481 a continuation of error descriptions for the last name.  The description
482 and pgmname fields are then also empty.
483
484 @item description
485 The @emph{string} in this field contains a human-readable description
486 of the component.  It can be displayed to the user of the GUI for
487 informational purposes.  It is @emph{percent-escaped} and
488 @emph{localized}.
489
490 @item pgmname
491 The @emph{string} in this field contains the absolute name of the
492 program's file.  It can be used to unambiguously invoke that program.
493 It is @emph{percent-escaped}.
494
495 @item avail
496 The @emph{boolean value} in this field indicates whether the program is
497 installed and runnable.
498
499 @item okay
500 The @emph{boolean value} in this field indicates whether the program's
501 config file is syntactically okay.
502
503 @item cfgfile
504 If an error occured in the configuraion file (as indicated by a false
505 value in the field @code{okay}), this field has the name of the failing
506 configuration file.  It is @emph{percent-escaped}.
507
508 @item line
509 If an error occured in the configuration file, this field has the line
510 number of the failing statement in the configuration file.  
511 It is an @emph{unsigned number}.
512
513 @item error
514 If an error occured in the configuration file, this field has the error
515 text of the failing statement in the configuration file.  It is
516 @emph{percent-escaped} and @emph{localized}.
517
518 @end table
519
520 @noindent
521 In the following example the @command{dirmngr} is not runnable and the
522 configuration file of @command{scdaemon} is not okay.
523
524 @example
525 $ gpgconf --check-programs
526 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
527 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
528 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
529 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
530 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
531 @end example
532
533
534 @node Listing options
535 @subsection Listing options
536
537 Every component contains one or more options.  Options may be gathered
538 into option groups to allow the GUI to give visual hints to the user
539 about which options are related.
540
541 The command argument @code{@w{--list-options @var{component}}} lists
542 all options (and the groups they belong to) in the component
543 @var{component}, one per line.  @var{component} must be the string in
544 the field @var{name} in the output of the @code{--list-components}
545 command.
546
547 There is one line for each option and each group.  First come all
548 options that are not in any group.  Then comes a line describing a
549 group.  Then come all options that belong into each group.  Then comes
550 the next group and so on.  There does not need to be any group (and in
551 this case the output will stop after the last non-grouped option).
552
553 The format of each line is:
554
555 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
556
557 @table @var
558 @item name
559 This field contains a name tag for the group or option.  The name tag
560 is used to specify the group or option in all communication with
561 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
562 thus not in any escaped format.
563
564 @item flags
565 The flags field contains an @emph{unsigned number}.  Its value is the
566 OR-wise combination of the following flag values:
567
568 @table @code
569 @item group (1)
570 If this flag is set, this is a line describing a group and not an
571 option.
572 @end table
573
574 The following flag values are only defined for options (that is, if
575 the @code{group} flag is not used).
576
577 @table @code
578 @item optional arg (2)
579 If this flag is set, the argument is optional.  This is never set for
580 @var{type} @code{0} (none) options.
581
582 @item list (4)
583 If this flag is set, the option can be given multiple times.
584
585 @item runtime (8)
586 If this flag is set, the option can be changed at runtime.
587
588 @item default (16)
589 If this flag is set, a default value is available.
590
591 @item default desc (32)
592 If this flag is set, a (runtime) default is available.  This and the
593 @code{default} flag are mutually exclusive.
594
595 @item no arg desc (64)
596 If this flag is set, and the @code{optional arg} flag is set, then the
597 option has a special meaning if no argument is given.
598
599 @item no change (128)
600 If this flag is set, gpgconf ignores requests to change the value.  GUI
601 frontends should grey out this option.  Note, that manual changes of the
602 configuration files are still possible.
603 @end table
604
605 @item level
606 This field is defined for options and for groups.  It contains an
607 @emph{unsigned number} that specifies the expert level under which
608 this group or option should be displayed.  The following expert levels
609 are defined for options (they have analogous meaning for groups):
610
611 @table @code
612 @item basic (0)
613 This option should always be offered to the user.
614
615 @item advanced (1)
616 This option may be offered to advanced users.
617
618 @item expert (2)
619 This option should only be offered to expert users.
620
621 @item invisible (3)
622 This option should normally never be displayed, not even to expert
623 users.
624
625 @item internal (4)
626 This option is for internal use only.  Ignore it.
627 @end table
628
629 The level of a group will always be the lowest level of all options it
630 contains.
631
632 @item description
633 This field is defined for options and groups.  The @emph{string} in
634 this field contains a human-readable description of the option or
635 group.  It can be displayed to the user of the GUI for informational
636 purposes.  It is @emph{percent-escaped} and @emph{localized}.
637
638 @item type
639 This field is only defined for options.  It contains an @emph{unsigned
640 number} that specifies the type of the option's argument, if any.  The
641 following types are defined:
642
643 Basic types:
644
645 @table @code
646 @item none (0)
647 No argument allowed.
648
649 @item string (1)
650 An @emph{unformatted string}.
651
652 @item int32 (2)
653 A @emph{signed number}.
654
655 @item uint32 (3)
656 An @emph{unsigned number}.
657 @end table
658
659 Complex types:
660
661 @table @code
662 @item pathname (32)
663 A @emph{string} that describes the pathname of a file.  The file does
664 not necessarily need to exist.
665
666 @item ldap server (33)
667 A @emph{string} that describes an LDAP server in the format:
668
669 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
670 @end table
671
672 More types will be added in the future.  Please see the @var{alt-type}
673 field for information on how to cope with unknown types.
674
675 @item alt-type
676 This field is identical to @var{type}, except that only the types
677 @code{0} to @code{31} are allowed.  The GUI is expected to present the
678 user the option in the format specified by @var{type}.  But if the
679 argument type @var{type} is not supported by the GUI, it can still
680 display the option in the more generic basic type @var{alt-type}.  The
681 GUI must support all the defined basic types to be able to display all
682 options.  More basic types may be added in future versions.  If the
683 GUI encounters a basic type it doesn't support, it should report an
684 error and abort the operation.
685
686 @item argname
687 This field is only defined for options with an argument type
688 @var{type} that is not @code{0}.  In this case it may contain a
689 @emph{percent-escaped} and @emph{localised string} that gives a short
690 name for the argument.  The field may also be empty, though, in which
691 case a short name is not known.
692
693 @item default
694 This field is defined only for options for which the @code{default} or
695 @code{default desc} flag is set.  If the @code{default} flag is set,
696 its format is that of an @emph{option argument} (@xref{Format
697 conventions}, for details).  If the default value is empty, then no
698 default is known.  Otherwise, the value specifies the default value
699 for this option.  If the @code{default desc} flag is set, the field is
700 either empty or contains a description of the effect if the option is
701 not given.
702
703 @item argdef
704 This field is defined only for options for which the @code{optional
705 arg} flag is set.  If the @code{no arg desc} flag is not set, its
706 format is that of an @emph{option argument} (@xref{Format
707 conventions}, for details).  If the default value is empty, then no
708 default is known.  Otherwise, the value specifies the default argument
709 for this option.  If the @code{no arg desc} flag is set, the field is
710 either empty or contains a description of the effect of this option if
711 no argument is given.
712
713 @item value
714 This field is defined only for options.  Its format is that of an
715 @emph{option argument}.  If it is empty, then the option is not
716 explicitely set in the current configuration, and the default applies
717 (if any).  Otherwise, it contains the current value of the option.
718 Note that this field is also meaningful if the option itself does not
719 take a real argument (in this case, it contains the number of times
720 the option appears).
721 @end table
722
723
724 @node Changing options
725 @subsection Changing options
726
727 The command @w{@code{--change-options @var{component}}} will attempt
728 to change the options of the component @var{component} to the
729 specified values.  @var{component} must be the string in the field
730 @var{name} in the output of the @code{--list-components} command.  You
731 have to provide the options that shall be changed in the following
732 format on standard input:
733
734 @code{@var{name}:@var{flags}:@var{new-value}}
735
736 @table @var
737 @item name
738 This is the name of the option to change.  @var{name} must be the
739 string in the field @var{name} in the output of the
740 @code{--list-options} command.
741
742 @item flags
743 The flags field contains an @emph{unsigned number}.  Its value is the
744 OR-wise combination of the following flag values:
745
746 @table @code
747 @item default (16)
748 If this flag is set, the option is deleted and the default value is
749 used instead (if applicable).
750 @end table
751
752 @item new-value
753 The new value for the option.  This field is only defined if the
754 @code{default} flag is not set.  The format is that of an @emph{option
755 argument}.  If it is empty (or the field is omitted), the default
756 argument is used (only allowed if the argument is optional for this
757 option).  Otherwise, the option will be set to the specified value.
758 @end table
759
760 Examples:
761
762 To set the force option, which is of basic type @code{none (0)}:
763
764 @example
765 $ echo 'force:0:1' | gpgconf --change-options dirmngr
766 @end example
767
768 To delete the force option:
769
770 @example
771 $ echo 'force:16:' | gpgconf --change-options dirmngr
772 @end example
773
774 The @code{--runtime} option can influence when the changes take
775 effect.
776
777
778 @node Listing global options
779 @subsection Listing global options
780
781 Sometimes it is useful for applications to look at the global options
782 file @file{gpgconf.conf}. 
783 The colon separated listing format is record oriented and uses the first
784 field to identify the record type:
785
786 @table @code
787 @item k
788 This describes a key record to start the definition of a new ruleset for
789 a user/group.  The format of a key record is:
790
791   @code{k:@var{user}:@var{group}:}
792
793 @table @var
794 @item user
795 This is the user field of the key.  It is percent escaped.  See the
796 definition of the gpgconf.conf format for details.
797
798 @item group
799 This is the group field of the key.  It is percent escaped.
800 @end table
801
802 @item r
803 This describes a rule record. All rule records up to the next key record
804 make up a rule set for that key.  The format of a rule record is:
805
806   @code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}
807
808 @table @var
809 @item component
810 This is the component part of a rule.  It is a plain string.
811
812 @item option
813 This is the option part of a rule.  It is a plain string.
814
815 @item flag
816 This is the flags part of a rule.  There may be only one flag per rule
817 but by using the same component and option, several flags may be
818 assigned to an option.  It is a plain string.
819
820 @item value
821 This is the optional value for the option.  It is a percent escaped
822 string with a single quotation mark to indicate a string.  The quotation
823 mark is only required to distinguish between no value specified and an
824 empty string.
825 @end table
826
827 @end table
828
829 @noindent
830 Unknown record typs should be ignored.  Note that there is intentionally
831 no feature to change the global option file through @command{gpgconf}.
832
833
834
835 @mansect files
836 @node Files used by gpgconf
837 @subsection Files used by gpgconf
838
839 @table @file
840
841 @item /etc/gnupg/gpgconf.conf
842 @cindex gpgconf.conf
843   If this file exists, it is processed as a global configuration file.
844   A commented example can be found in the @file{examples} directory of
845   the distribution.
846 @end table
847
848
849 @mansect see also
850 @ifset isman
851 @command{gpg}(1), 
852 @command{gpgsm}(1), 
853 @command{gpg-agent}(1), 
854 @command{scdaemon}(1),
855 @command{dirmngr}(1)
856 @end ifset
857 @include see-also-note.texi
858
859
860
861 @c
862 @c    APPLYGNUPGDEFAULTS
863 @c
864 @manpage applygnupgdefaults.8
865 @node applygnupgdefaults
866 @section Run gpgconf for all users.
867 @ifset manverb
868 .B applygnupgdefaults
869 \- Run gpgconf --apply-defaults for all users.
870 @end ifset
871
872 @mansect synopsis
873 @ifset manverb
874 .B  applygnupgdefaults
875 @end ifset
876
877 @mansect description
878 This script is a wrapper around @command{gpgconf} to run it with the
879 command @code{--apply-defaults} for all real users with an existing
880 GnuPG home directory.  Admins might want to use this script to update he
881 GnuPG configuration files for all users after
882 @file{/etc/gnupg/gpgconf.conf} has been changed.  This allows to enforce
883 certain policies for all users.  Note, that this is not a bulletproof of
884 forcing a user to use certain options.  A user may always directly edit
885 the configuration files and bypass gpgconf.
886
887 @noindent
888 @command{applygnupgdefaults} is invoked by root as:
889
890 @example
891 applygnupgdefaults
892 @end example
893
894
895 @c
896 @c    GPGSM-GENCERT.SH
897 @c
898 @node gpgsm-gencert.sh
899 @section Generate an X.509 certificate request
900 @manpage gpgsm-gencert.sh.1
901 @ifset manverb
902 .B gpgsm-gencert.sh
903 \- Generate an X.509 certificate request
904 @end ifset 
905
906 @mansect synopsis
907 @ifset manverb
908 .B  gpgsm-gencert.sh
909 @end ifset
910
911 @mansect description
912 This is a simple tool to interactivly generate a certificate request
913 which will be printed to stdout.
914
915 @manpause
916 @noindent
917 @command{gpgsm-gencert.sh} is invoked as:
918
919 @samp{gpgsm-cencert.sh}
920
921 @mansect see also
922 @ifset isman
923 @command{gpgsm}(1), 
924 @command{gpg-agent}(1), 
925 @command{scdaemon}(1)
926 @end ifset
927 @include see-also-note.texi
928
929
930
931 @c
932 @c   GPG-PRESET-PASSPHRASE
933 @c
934 @node gpg-preset-passphrase
935 @section Put a passphrase into the cache.
936 @manpage gpg-preset-passphrase.1
937 @ifset manverb
938 .B gpg-preset-passphrase
939 \- Put a passphrase into gpg-agent's cache
940 @end ifset
941
942 @mansect synopsis
943 @ifset manverb
944 .B  gpg-preset-passphrase
945 .RI [ options ]
946 .RI [ command ]
947 .I keygrip
948 @end ifset
949
950 @mansect description
951 The @command{gpg-preset-passphrase} is a utility to seed the internal
952 cache of a running @command{gpg-agent} with passphrases.  It is mainly
953 useful for unattended machines, where the usual @command{pinentry} tool
954 may not be used and the passphrases for the to be used keys are given at
955 machine startup.
956
957 Passphrases set with this utility don't expire unless the
958 @option{--forget} option is used to explicitly clear them from the cache
959 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
960 SIGHUP to it).  It is necessary to allow this passphrase presetting by
961 starting @command{gpg-agent} with the
962 @option{--allow-preset-passphrase}.
963
964 @menu
965 * Invoking gpg-preset-passphrase::   List of all commands and options.
966 @end menu
967
968 @manpause
969 @node Invoking gpg-preset-passphrase
970 @subsection List of all commands and options.
971 @mancont
972
973 @noindent
974 @command{gpg-preset-passphrase} is invoked this way:
975
976 @example
977 gpg-preset-passphrase [options] [command] @var{keygrip}
978 @end example
979
980 @var{keygrip} is a 40 character string of hexadecimal characters
981 identifying the key for which the passphrase should be set or cleared.
982 This keygrip is listed along with the key when running the command:
983 @code{gpgsm --dump-secret-keys}. One of the following command options
984 must be given:
985
986 @table @gnupgtabopt
987 @item --preset
988 @opindex preset
989 Preset a passphrase. This is what you usually will
990 use. @command{gpg-preset-passphrase} will then read the passphrase from
991 @code{stdin}.
992
993 @item --forget
994 @opindex forget
995 Flush the passphrase for the given keygrip from the cache.
996
997 @end table
998
999 @noindent
1000 The following additional options may be used:
1001
1002 @table @gnupgtabopt
1003 @item -v
1004 @itemx --verbose
1005 @opindex verbose
1006 Output additional information while running.  
1007
1008 @item -P @var{string}
1009 @itemx --passphrase @var{string}
1010 @opindex passphrase
1011 Instead of reading the passphrase from @code{stdin}, use the supplied
1012 @var{string} as passphrase.  Note that this makes the passphrase visible
1013 for other users.
1014 @end table
1015
1016 @mansect see also
1017 @ifset isman
1018 @command{gpg}(1), 
1019 @command{gpgsm}(1), 
1020 @command{gpg-agent}(1), 
1021 @command{scdaemon}(1)
1022 @end ifset
1023 @include see-also-note.texi
1024
1025
1026
1027
1028 @c
1029 @c   GPG-CONNECT-AGENT
1030 @c
1031 @node gpg-connect-agent
1032 @section Communicate with a running agent.
1033 @manpage gpg-connect-agent.1
1034 @ifset manverb
1035 .B gpg-connect-agent
1036 \- Communicate with a running agent
1037 @end ifset
1038
1039 @mansect synopsis
1040 @ifset manverb
1041 .B  gpg-connect-agent
1042 .RI [ options ]
1043 @end ifset
1044
1045 @mansect description
1046 The @command{gpg-connect-agent} is a utility to communicate with a
1047 running @command{gpg-agent}.  It is useful to check out the commands
1048 gpg-agent provides using the Assuan interface.  It might also be useful
1049 for scripting simple applications.  Inputis expected at stdin and out
1050 put gets printed to stdout.
1051
1052 It is very similar to running @command{gpg-agent} in server mode; but
1053 here we connect to a running instance.
1054
1055 @menu
1056 * Invoking gpg-connect-agent::       List of all options.
1057 * Controlling gpg-connect-agent::    Control commands.
1058 @end menu
1059
1060 @manpause
1061 @node Invoking gpg-connect-agent
1062 @subsection List of all options.
1063
1064 @noindent
1065 @command{gpg-connect-agent} is invoked this way:
1066
1067 @example
1068 gpg-connect-agent [options]
1069 @end example
1070 @mancont
1071
1072 @noindent
1073 The following options may be used:
1074
1075 @table @gnupgtabopt
1076 @item -v
1077 @itemx --verbose
1078 @opindex verbose
1079 Output additional information while running.  
1080
1081 @item -q
1082 @item --quiet
1083 @opindex q
1084 @opindex quiet
1085 Try to be as quiet as possible.
1086
1087 @include opt-homedir.texi
1088
1089 @item -S
1090 @itemx --raw-socket @var{name}
1091 @opindex S        
1092 @opindex raw-socket
1093 Connect to socket @var{name} assuming this is an Assuan style server.
1094 Do not run any special initializations or environment checks.  This may
1095 be used to directly connect to any Assuan style socket server.
1096
1097 @item -E
1098 @itemx --exec
1099 @opindex exec
1100 Take the rest of the command line as a program and it's arguments and
1101 execute it as an assuan server. Here is how you would run @command{gpgsm}:
1102 @smallexample
1103  gpg-connect-agent --exec gpgsm --server
1104 @end smallexample
1105
1106
1107 @item --no-ext-connect
1108 @opindex no-ext-connect
1109 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
1110 connects to the assuan server in extended mode to allow descriptor
1111 passing.  This option makes it use the old mode.
1112
1113 @item --run @var{file}
1114 @opindex run 
1115 Run the commands from @var{file} at startup and then continue with the
1116 regular input method.
1117
1118 @item -s
1119 @itemx --subst
1120 @opindex subst
1121 Run the command @code{/subst} at startup.
1122
1123 @item --hex
1124 @opindex hex
1125 Print data lines in a hex format and the ASCII representation of
1126 non-control characters.
1127
1128 @item --decode
1129 @opindex decode
1130 Decode data lines.  That is to remove percent escapes but make sure that
1131 a new line always starts with a D and a space.
1132
1133 @end table
1134
1135 @mansect control commands
1136 @node Controlling gpg-connect-agent
1137 @subsection Control commands.
1138
1139 While reading Assuan commands, gpg-agent also allows a few special
1140 commands to control its operation.  These control commands all start
1141 with a slash (@code{/}).
1142
1143 @table @code
1144
1145 @item /echo @var{args}
1146 Just print @var{args}.
1147
1148 @item /let @var{name} @var{value}
1149 Set the variable @var{name} to @var{value}.  Variables are only
1150 substituted on the input if the @command{/subst} has been used.
1151 Variables are referenced by prefixing the name with a dollr sign and
1152 optionally include the name in curly braces.  The rules for a valid name
1153 are idnetically to those of the standard bourne shell.  This is not yet
1154 enforced but may be in the future.  When used with curly braces no
1155 leading or trailing white space is allowed. 
1156
1157 If a variable is not found, it is searched in the environment and if
1158 found copied to the table of variables.
1159
1160 Variable functions are available: The name of the function must be
1161 followed by at least one space and the at least one argument.  The
1162 following functions are available:
1163
1164 @table @code
1165 @item get
1166 Return a value described by the argument.  Available arguments are:
1167
1168 @table @code    
1169 @item cwd
1170 The current working directory.
1171 @item homedir
1172 The gnupg homedir.
1173 @item sysconfdir
1174 GnuPG's system configuration directory.
1175 @item bindir
1176 GnuPG's binary directory.
1177 @item libdir
1178 GnuPG's library directory.
1179 @item libexecdir
1180 GnuPG's library directory for executable files.
1181 @item datadir
1182 GnuPG's data directory.
1183 @item serverpid
1184 The PID of the current server. Command @command{/serverpid} must
1185 have been given to return a useful value.
1186 @end table
1187
1188 @item unescape @var{args}
1189 Remove C-style escapes from @var{args}.  Note that @code{\0} and
1190 @code{\x00} terminate the returned string implictly.  The string to be
1191 converted are the entire arguments right behind the delimiting space of
1192 the function name.
1193
1194 @item unpercent @var{args}
1195 @itemx unpercent+ @var{args}
1196 Remove percent style ecaping from @var{args}.  Note that @code{%00}
1197 terminates the string implicitly.  The string to be converted are the
1198 entire arguments right behind the delimiting space of the function
1199 name. @code{unpercent+} also maps plus signs to a spaces.
1200
1201 @item percent @var{args}
1202 @itemx percent+ @var{args}
1203 Escape the @var{args} using percent style ecaping.  Tabs, formfeeds,
1204 linefeeds, carriage returns and colons are escaped. @code{percent+} also
1205 maps spaces to plus signs.
1206
1207 @item +
1208 @itemx -
1209 @item *
1210 @item /
1211 @item %
1212 Evaluate all arguments as long integers using @code{strtol} and apply
1213 this operator.  A division by zero yields an empty string.
1214
1215
1216 @end table
1217
1218
1219 @item /definq @var{name} @var{var}
1220 Use content of the variable @var{var} for inquiries with @var{name}.
1221 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1222
1223
1224 @item /definqfile @var{name} @var{file}
1225 Use content of @var{file} for inquiries with @var{name}.
1226 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1227
1228 @item /definqprog @var{name} @var{prog}
1229 Run @var{prog} for inquiries matching @var{name} and pass the
1230 entire line to it as command line arguments.
1231
1232 @item /showdef
1233 Print all definitions
1234
1235 @item /cleardef
1236 Delete all definitions
1237
1238 @item /sendfd @var{file} @var{mode}
1239 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1240 mode string) and send the file descriptor to the server.  This is
1241 usually followed by a command like @code{INPUT FD} to set the
1242 input source for other commands.
1243
1244 @item /recvfd
1245 Not yet implemented.
1246
1247 @item /open @var{var} @var{file} [@var{mode}]
1248 Open @var{file} and assign the file descriptor to @var{var}.  Warning:
1249 This command is experimental and might change in future versions.
1250
1251 @item /close @var{fd}
1252 Close the file descriptor @var{fd}.  Warning: This command is
1253 experimental and might change in future versions.
1254
1255 @item /showopen
1256 Show a listy of open files.
1257
1258 @item /serverpid
1259 Send the Assuan command @command{GETINFO pid} to the server and store
1260 the returned PID for internal purposes.
1261
1262 @item /sleep
1263 Sleep for a second.
1264
1265 @item /hex
1266 @itemx /nohex
1267 Same as the command line option @option{--hex}.
1268
1269 @item /decode
1270 @itemx /nodecode
1271 Same as the command line option @option{--decode}.
1272
1273 @item /subst
1274 @itemx /nosubst
1275 Enable and disable variable substitution.  It defaults to disabled
1276 unless the command line option @option{--subst} has been used.
1277 If /subst as been enabled once, leading white spaces are removed from
1278 input lines which makes scripts easier to read.
1279
1280 @item /while @var{condition}
1281 @itemx /end
1282 These commands provide a way for executing loops.  All lines between the
1283 @code{while} and the corresponding @code{end} are executed as long as
1284 the evaluation of @var{condition} yields a non-zero value.  The
1285 evaluation is done by passing @var{condition} to the @code{strtol}
1286 function.  Example:
1287
1288 @smallexample
1289   /subst
1290   /let i 3
1291   /while $i
1292     /echo loop couter is $i
1293     /let i $@{- $i 1@}
1294   /end
1295 @end smallexample
1296
1297
1298 @item /run @var{file}
1299 Run commands from @var{file}.
1300
1301 @item /bye
1302 Terminate the connection and the program
1303
1304 @item /help
1305 Print a list of available control commands.
1306
1307 @end table
1308
1309
1310 @ifset isman
1311 @mansect see also
1312 @command{gpg-agent}(1), 
1313 @command{scdaemon}(1)
1314 @include see-also-note.texi
1315 @end ifset
1316
1317
1318 @c
1319 @c   GPGPARSEMAIL
1320 @c
1321 @node gpgparsemail
1322 @section Parse a mail message into an annotated format
1323
1324 @manpage gpgparsemail.1
1325 @ifset manverb
1326 .B gpgparsemail
1327 \- Parse a mail message into an annotated format
1328 @end ifset
1329
1330 @mansect synopsis
1331 @ifset manverb
1332 .B  gpgparsemail
1333 .RI [ options ]
1334 .RI [ file ]
1335 @end ifset
1336
1337 @mansect description
1338 The @command{gpgparsemail} is a utility currently only useful for
1339 debugging.  Run it with @code{--help} for usage information.
1340
1341
1342
1343 @c
1344 @c   SYMCRYPTRUN
1345 @c
1346 @node symcryptrun
1347 @section Call a simple symmetric encryption tool.
1348 @manpage symcryptrun.1
1349 @ifset manverb
1350 .B symcryptrun
1351 \- Call a simple symmetric encryption tool
1352 @end ifset
1353
1354 @mansect synopsis
1355 @ifset manverb
1356 .B  symcryptrun
1357 .B \-\-class
1358 .I class
1359 .B \-\-program
1360 .I program
1361 .B \-\-keyfile
1362 .I keyfile
1363 .RB [ --decrypt | --encrypt ]
1364 .RI [ inputfile ]
1365 @end ifset
1366
1367 @mansect description
1368 Sometimes simple encryption tools are already in use for a long time and
1369 there might be a desire to integrate them into the GnuPG framework.  The
1370 protocols and encryption methods might be non-standard or not even
1371 properly documented, so that a full-fledged encryption tool with an
1372 interface like gpg is not doable.  @command{symcryptrun} provides a
1373 solution: It operates by calling the external encryption/decryption
1374 module and provides a passphrase for a key using the standard
1375 @command{pinentry} based mechanism through @command{gpg-agent}.
1376
1377 Note, that @command{symcryptrun} is only available if GnuPG has been
1378 configured with @samp{--enable-symcryptrun} at build time.
1379
1380 @menu
1381 * Invoking symcryptrun::   List of all commands and options.
1382 @end menu
1383
1384 @manpause
1385 @node Invoking symcryptrun
1386 @subsection List of all commands and options.
1387
1388 @noindent
1389 @command{symcryptrun} is invoked this way:
1390
1391 @example
1392 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1393    [--decrypt | --encrypt] [inputfile]
1394 @end example
1395 @mancont
1396
1397 For encryption, the plain text must be provided on STDIN or as the
1398 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1399 For decryption vice versa.
1400
1401 @var{CLASS} describes the calling conventions of the external tool.
1402 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1403 the full filename of that external tool.
1404  
1405 For the class @samp{confucius} the option @option{--keyfile} is
1406 required; @var{keyfile} is the name of a file containing the secret key,
1407 which may be protected by a passphrase.  For detailed calling
1408 conventions, see the source code.
1409  
1410 @noindent
1411 Note, that @command{gpg-agent} must be running before starting
1412 @command{symcryptrun}.
1413
1414 @noindent
1415 The following additional options may be used:
1416
1417 @table @gnupgtabopt
1418 @item -v
1419 @itemx --verbose
1420 @opindex verbose
1421 Output additional information while running.  
1422
1423 @item -q
1424 @item --quiet
1425 @opindex q
1426 @opindex quiet
1427 Try to be as quiet as possible.
1428
1429 @include opt-homedir.texi
1430
1431
1432 @item --log-file @var{file}
1433 @opindex log-file
1434 Append all logging output to @var{file}.  Default is to write logging
1435 informaton to STDERR.
1436
1437 @end table
1438
1439 @noindent
1440 The possible exit status codes of @command{symcryptrun} are:
1441
1442 @table @code
1443 @item 0 
1444         Success.
1445 @item 1 
1446         Some error occured.
1447 @item 2 
1448         No valid passphrase was provided.
1449 @item 3 
1450         The operation was canceled by the user.
1451
1452 @end table
1453
1454 @mansect see also
1455 @ifset isman
1456 @command{gpg}(1), 
1457 @command{gpgsm}(1), 
1458 @command{gpg-agent}(1), 
1459 @end ifset
1460 @include see-also-note.texi
1461