Add a /while loop.
[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 * 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.  Its format is that of an
695 @emph{option argument} (@xref{Format conventions}, for details).  If
696 the default value is empty, then no default is known.  Otherwise, the
697 value specifies the default value for this option.  Note that this
698 field is also meaningful if the option itself does not take a real
699 argument.
700
701 @item argdef
702 This field is defined only for options for which the @code{optional
703 arg} flag is set.  If the @code{no arg desc} flag is not set, its
704 format is that of an @emph{option argument} (@xref{Format
705 conventions}, for details).  If the default value is empty, then no
706 default is known.  Otherwise, the value specifies the default value
707 for this option.  If the @code{no arg desc} flag is set, the field is
708 either empty or contains a description of the effect of this option if
709 no argument is given.  Note that this field is also meaningful if the
710 option itself does not take a real argument.
711
712 @item value
713 This field is defined only for options.  Its format is that of an
714 @emph{option argument}.  If it is empty, then the option is not
715 explicitely set in the current configuration, and the default applies
716 (if any).  Otherwise, it contains the current value of the option.
717 Note that this field is also meaningful if the option itself does not
718 take a real argument.
719 @end table
720
721
722 @node Changing options
723 @subsection Changing options
724
725 The command @w{@code{--change-options @var{component}}} will attempt
726 to change the options of the component @var{component} to the
727 specified values.  @var{component} must be the string in the field
728 @var{name} in the output of the @code{--list-components} command.  You
729 have to provide the options that shall be changed in the following
730 format on standard input:
731
732 @code{@var{name}:@var{flags}:@var{new-value}}
733
734 @table @var
735 @item name
736 This is the name of the option to change.  @var{name} must be the
737 string in the field @var{name} in the output of the
738 @code{--list-options} command.
739
740 @item flags
741 The flags field contains an @emph{unsigned number}.  Its value is the
742 OR-wise combination of the following flag values:
743
744 @table @code
745 @item default (16)
746 If this flag is set, the option is deleted and the default value is
747 used instead (if applicable).
748 @end table
749
750 @item new-value
751 The new value for the option.  This field is only defined if the
752 @code{default} flag is not set.  The format is that of an @emph{option
753 argument}.  If it is empty (or the field is omitted), the default
754 argument is used (only allowed if the argument is optional for this
755 option).  Otherwise, the option will be set to the specified value.
756 @end table
757
758 Examples:
759
760 To set the force option, which is of basic type @code{none (0)}:
761
762 @example
763 $ echo 'force:0:1' | gpgconf --change-options dirmngr
764 @end example
765
766 To delete the force option:
767
768 @example
769 $ echo 'force:16:' | gpgconf --change-options dirmngr
770 @end example
771
772 The @code{--runtime} option can influence when the changes take
773 effect.
774
775
776 @node Listing global options
777 @subsection Listing global options
778
779 Sometimes it is useful for applications to look at the global options
780 file @file{gpgconf.conf}. 
781 The colon separated listing format is record oriented and uses the first
782 field to identify the record type:
783
784 @table @code
785 @item k
786 This describes a key record to start the definition of a new ruleset for
787 a user/group.  The format of a key record is:
788
789   @code{k:@var{user}:@var{group}:}
790
791 @table @var
792 @item user
793 This is the user field of the key.  It is percent escaped.  See the
794 definition of the gpgconf.conf format for details.
795
796 @item group
797 This is the group field of the key.  It is percent escaped.
798 @end table
799
800 @item r
801 This describes a rule record. All rule records up to the next key record
802 make up a rule set for that key.  The format of a rule record is:
803
804   @code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}
805
806 @table @var
807 @item component
808 This is the component part of a rule.  It is a plain string.
809
810 @item option
811 This is the option part of a rule.  It is a plain string.
812
813 @item flag
814 This is the flags part of a rule.  There may be only one flag per rule
815 but by using the same component and option, several flags may be
816 assigned to an option.  It is a plain string.
817
818 @item value
819 This is the optional value for the option.  It is a percent escaped
820 string with a single quotation mark to indicate a string.  The quotation
821 mark is only required to distinguish between no value specified and an
822 empty string.
823 @end table
824
825 @end table
826
827 @noindent
828 Unknown record typs should be ignored.  Note that there is intentionally
829 no feature to change the global option file through @command{gpgconf}.
830
831
832
833 @mansect files
834 @node Files used by gpgconf
835 @subsection Files used by gpgconf
836
837 @table @file
838
839 @item /etc/gnupg/gpgconf.conf
840 @cindex gpgconf.conf
841   If this file exists, it is processed as a global configuration file.
842   A commented example can be found in the @file{examples} directory of
843   the distribution.
844 @end table
845
846
847 @mansect see also
848 @ifset isman
849 @command{gpg}(1), 
850 @command{gpgsm}(1), 
851 @command{gpg-agent}(1), 
852 @command{scdaemon}(1),
853 @command{dirmngr}(1)
854 @end ifset
855 @include see-also-note.texi
856
857
858
859 @c
860 @c    APPLYGNUPGDEFAULTS
861 @c
862 @manpage applygnupgdefaults.8
863 @node applygnupgdefaults
864 @section Run gpgconf for all users.
865 @ifset manverb
866 .B applygnupgdefaults
867 \- Run gpgconf --apply-defaults for all users.
868 @end ifset
869
870 @mansect synopsis
871 @ifset manverb
872 .B  applygnupgdefaults
873 @end ifset
874
875 @mansect description
876 This script is a wrapper around @command{gpgconf} to run it with the
877 command @code{--apply-defaults} for all real users with an existing
878 GnuPG home directory.  Admins might want to use this script to update he
879 GnuPG configuration files for all users after
880 @file{/etc/gnupg/gpgconf.conf} has been changed.  This allows to enforce
881 certain policies for all users.  Note, that this is not a bulletproof of
882 forcing a user to use certain options.  A user may always directly edit
883 the configuration files and bypass gpgconf.
884
885 @noindent
886 @command{applygnupgdefaults} is invoked by root as:
887
888 @example
889 applygnupgdefaults
890 @end example
891
892
893 @c
894 @c    GPGSM-GENCERT.SH
895 @c
896 @node gpgsm-gencert.sh
897 @section Generate an X.509 certificate request
898 @manpage gpgsm-gencert.sh.1
899 @ifset manverb
900 .B gpgsm-gencert.sh
901 \- Generate an X.509 certificate request
902 @end ifset 
903
904 @mansect synopsis
905 @ifset manverb
906 .B  gpgsm-gencert.sh
907 @end ifset
908
909 @mansect description
910 This is a simple tool to interactivly generate a certificate request
911 which will be printed to stdout.
912
913 @manpause
914 @noindent
915 @command{gpgsm-gencert.sh} is invoked as:
916
917 @samp{gpgsm-cencert.sh}
918
919 @mansect see also
920 @ifset isman
921 @command{gpgsm}(1), 
922 @command{gpg-agent}(1), 
923 @command{scdaemon}(1)
924 @end ifset
925 @include see-also-note.texi
926
927
928
929 @c
930 @c   GPG-PRESET-PASSPHRASE
931 @c
932 @node gpg-preset-passphrase
933 @section Put a passphrase into the cache.
934 @manpage gpg-preset-passphrase.1
935 @ifset manverb
936 .B gpg-preset-passphrase
937 \- Put a passphrase into gpg-agent's cache
938 @end ifset
939
940 @mansect synopsis
941 @ifset manverb
942 .B  gpg-preset-passphrase
943 .RI [ options ]
944 .RI [ command ]
945 .I keygrip
946 @end ifset
947
948 @mansect description
949 The @command{gpg-preset-passphrase} is a utility to seed the internal
950 cache of a running @command{gpg-agent} with passphrases.  It is mainly
951 useful for unattended machines, where the usual @command{pinentry} tool
952 may not be used and the passphrases for the to be used keys are given at
953 machine startup.
954
955 Passphrases set with this utility don't expire unless the
956 @option{--forget} option is used to explicitly clear them from the cache
957 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
958 SIGHUP to it).  It is necessary to allow this passphrase presetting by
959 starting @command{gpg-agent} with the
960 @option{--allow-preset-passphrase}.
961
962 @menu
963 * Invoking gpg-preset-passphrase::   List of all commands and options.
964 @end menu
965
966 @manpause
967 @node Invoking gpg-preset-passphrase
968 @subsection List of all commands and options.
969 @mancont
970
971 @noindent
972 @command{gpg-preset-passphrase} is invoked this way:
973
974 @example
975 gpg-preset-passphrase [options] [command] @var{keygrip}
976 @end example
977
978 @var{keygrip} is a 40 character string of hexadecimal characters
979 identifying the key for which the passphrase should be set or cleared.
980 This keygrip is listed along with the key when running the command:
981 @code{gpgsm --dump-secret-keys}. One of the following command options
982 must be given:
983
984 @table @gnupgtabopt
985 @item --preset
986 @opindex preset
987 Preset a passphrase. This is what you usually will
988 use. @command{gpg-preset-passphrase} will then read the passphrase from
989 @code{stdin}.
990
991 @item --forget
992 @opindex forget
993 Flush the passphrase for the given keygrip from the cache.
994
995 @end table
996
997 @noindent
998 The following additional options may be used:
999
1000 @table @gnupgtabopt
1001 @item -v
1002 @itemx --verbose
1003 @opindex verbose
1004 Output additional information while running.  
1005
1006 @item -P @var{string}
1007 @itemx --passphrase @var{string}
1008 @opindex passphrase
1009 Instead of reading the passphrase from @code{stdin}, use the supplied
1010 @var{string} as passphrase.  Note that this makes the passphrase visible
1011 for other users.
1012 @end table
1013
1014 @mansect see also
1015 @ifset isman
1016 @command{gpg}(1), 
1017 @command{gpgsm}(1), 
1018 @command{gpg-agent}(1), 
1019 @command{scdaemon}(1)
1020 @end ifset
1021 @include see-also-note.texi
1022
1023
1024
1025
1026 @c
1027 @c   GPG-CONNECT-AGENT
1028 @c
1029 @node gpg-connect-agent
1030 @section Communicate with a running agent.
1031 @manpage gpg-connect-agent.1
1032 @ifset manverb
1033 .B gpg-connect-agent
1034 \- Communicate with a running agent
1035 @end ifset
1036
1037 @mansect synopsis
1038 @ifset manverb
1039 .B  gpg-connect-agent
1040 .RI [ options ]
1041 @end ifset
1042
1043 @mansect description
1044 The @command{gpg-connect-agent} is a utility to communicate with a
1045 running @command{gpg-agent}.  It is useful to check out the commands
1046 gpg-agent provides using the Assuan interface.  It might also be useful
1047 for scripting simple applications.  Inputis expected at stdin and out
1048 put gets printed to stdout.
1049
1050 It is very similar to running @command{gpg-agent} in server mode; but
1051 here we connect to a running instance.
1052
1053 @menu
1054 * Invoking gpg-connect-agent::       List of all options.
1055 * Controlling gpg-connect-agent::    Control commands.
1056 @end menu
1057
1058 @manpause
1059 @node Invoking gpg-connect-agent
1060 @subsection List of all options.
1061
1062 @noindent
1063 @command{gpg-connect-agent} is invoked this way:
1064
1065 @example
1066 gpg-connect-agent [options]
1067 @end example
1068 @mancont
1069
1070 @noindent
1071 The following options may be used:
1072
1073 @table @gnupgtabopt
1074 @item -v
1075 @itemx --verbose
1076 @opindex verbose
1077 Output additional information while running.  
1078
1079 @item -q
1080 @item --quiet
1081 @opindex q
1082 @opindex quiet
1083 Try to be as quiet as possible.
1084
1085 @include opt-homedir.texi
1086
1087 @item -S
1088 @itemx --raw-socket @var{name}
1089 @opindex S        
1090 @opindex raw-socket
1091 Connect to socket @var{name} assuming this is an Assuan style server.
1092 Do not run any special initializations or environment checks.  This may
1093 be used to directly connect to any Assuan style socket server.
1094
1095 @item -E
1096 @itemx --exec
1097 @opindex exec
1098 Take the rest of the command line as a program and it's arguments and
1099 execute it as an assuan server. Here is how you would run @command{gpgsm}:
1100 @smallexample
1101  gpg-connect-agent --exec gpgsm --server
1102 @end smallexample
1103
1104
1105 @item --no-ext-connect
1106 @opindex no-ext-connect
1107 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
1108 connects to the assuan server in extended mode to allow descriptor
1109 passing.  This option makes it use the old mode.
1110
1111 @item --run @var{file}
1112 @opindex run 
1113 Run the commands from @var{file} at startup and then continue with the
1114 regular input method.
1115
1116 @item -s
1117 @itemx --subst
1118 @opindex subst
1119 Run the command @code{/subst} at startup.
1120
1121 @item --hex
1122 @opindex hex
1123 Print data lines in a hex format and the ASCII representation of
1124 non-control characters.
1125
1126 @item --decode
1127 @opindex decode
1128 Decode data lines.  That is to remove percent escapes but make sure that
1129 a new line always starts with a D and a space.
1130
1131 @end table
1132
1133 @mansect control commands
1134 @node Controlling gpg-connect-agent
1135 @subsection Control commands.
1136
1137 While reading Assuan commands, gpg-agent also allows a few special
1138 commands to control its operation.  These control commands all start
1139 with a slash (@code{/}).
1140
1141 @table @code
1142
1143 @item /echo @var{args}
1144 Just print @var{args}.
1145
1146 @item /let @var{name} @var{value}
1147 Set the variable @var{name} to @var{value}.  Variables are only
1148 substituted on the input if the @command{/subst} has been used.
1149 Variables are referenced by prefixing the name with a dollr sign and
1150 optionally include the name in curly braces.  The rules for a valid name
1151 are idnetically to those of the standard bourne shell.  This is not yet
1152 enforced but may be in the future.  When used with curly braces no
1153 leading or trailing white space is allowed. 
1154
1155 If a variable is not found, it is searched in the environment and if
1156 found copied to the table of variables.
1157
1158 Variable functions are available: The name of the function must be
1159 followed by at least one space and the at least one argument.  The
1160 following functions are available:
1161
1162 @table @code
1163 @item get
1164 Return a value described by the argument.  Available arguments are:
1165
1166 @table @code    
1167 @item cwd
1168 The current working directory.
1169 @item homedir
1170 The gnupg homedir.
1171 @item sysconfdir
1172 GnuPG's system configuration directory.
1173 @item bindir
1174 GnuPG's binary directory.
1175 @item libdir
1176 GnuPG's library directory.
1177 @item libexecdir
1178 GnuPG's library directory for executable files.
1179 @item datadir
1180 GnuPG's data directory.
1181 @item serverpid
1182 The PID of the current server. Command @command{/serverpid} must
1183 have been given to return a useful value.
1184 @end table
1185
1186 @item unescape @var{args}
1187 Remove C-style escapes from @var{args}.  Note that @code{\0} and
1188 @code{\x00} terminate the returned string implictly.  The string to be
1189 converted are the entire arguments right behind the delimiting space of
1190 the function name.
1191
1192 @item unpercent @var{args}
1193 @itemx unpercent+ @var{args}
1194 Remove percent style ecaping from @var{args}.  Note that @code{%00}
1195 terminates the string implicitly.  The string to be converted are the
1196 entire arguments right behind the delimiting space of the function
1197 name. @code{unpercent+} also maps plus signs to a spaces.
1198
1199 @item percent @var{args}
1200 @itemx percent+ @var{args}
1201 Escape the @var{args} using percent style ecaping.  Tabs, formfeeds,
1202 linefeeds, carriage returns and colons are escaped. @code{percent+} also
1203 maps spaces to plus signs.
1204
1205 @item +
1206 @itemx -
1207 @item *
1208 @item /
1209 @item %
1210 Evaluate all arguments as long integers using @code{strtol} and apply
1211 this operator.  A division by zero yields an empty string.
1212
1213
1214 @end table
1215
1216
1217 @item /definq @var{name} @var{var}
1218 Use content of the variable @var{var} for inquiries with @var{name}.
1219 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1220
1221
1222 @item /definqfile @var{name} @var{file}
1223 Use content of @var{file} for inquiries with @var{name}.
1224 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1225
1226 @item /definqprog @var{name} @var{prog}
1227 Run @var{prog} for inquiries matching @var{name} and pass the
1228 entire line to it as command line arguments.
1229
1230 @item /showdef
1231 Print all definitions
1232
1233 @item /cleardef
1234 Delete all definitions
1235
1236 @item /sendfd @var{file} @var{mode}
1237 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1238 mode string) and send the file descriptor to the server.  This is
1239 usually followed by a command like @code{INPUT FD} to set the
1240 input source for other commands.
1241
1242 @item /recvfd
1243 Not yet implemented.
1244
1245 @item /open @var{var} @var{file} [@var{mode}]
1246 Open @var{file} and assign the file descriptor to @var{var}.  Warning:
1247 This command is experimental and might change in future versions.
1248
1249 @item /close @var{fd}
1250 Close the file descriptor @var{fd}.  Warning: This command is
1251 experimental and might change in future versions.
1252
1253 @item /showopen
1254 Show a listy of open files.
1255
1256 @item /serverpid
1257 Send the Assuan command @command{GETINFO pid} to the server and store
1258 the returned PID for internal purposes.
1259
1260 @item /sleep
1261 Sleep for a second.
1262
1263 @item /hex
1264 @itemx /nohex
1265 Same as the command line option @option{--hex}.
1266
1267 @item /decode
1268 @itemx /nodecode
1269 Same as the command line option @option{--decode}.
1270
1271 @item /subst
1272 @itemx /nosubst
1273 Enable and disable variable substitution.  It defaults to disabled
1274 unless the command line option @option{--subst} has been used.
1275 If /subst as been enabled once, leading white spaces are removed from
1276 input lines which makes scripts easier to read.
1277
1278 @item /while @var{condition}
1279 @itemx /end
1280 These commands provide a way for executing loops.  All lines between the
1281 @code{while} and the corresponding @code{end} are executed as long as
1282 the evaluation of @var{condition} yields a non-zero value.  The
1283 evaluation is done by passing @var{condition} to the @code{strtol}
1284 function.  Example:
1285
1286 @smallexample
1287   /subst
1288   /let i 3
1289   /while $i
1290     /echo loop couter is $i
1291     /let i $@{- $i 1@}
1292   /end
1293 @end smallexample
1294
1295
1296 @item /run @var{file}
1297 Run commands from @var{file}.
1298
1299 @item /bye
1300 Terminate the connection and the program
1301
1302 @item /help
1303 Print a list of available control commands.
1304
1305 @end table
1306
1307
1308 @ifset isman
1309 @mansect see also
1310 @command{gpg-agent}(1), 
1311 @command{scdaemon}(1)
1312 @include see-also-note.texi
1313 @end ifset
1314
1315
1316 @c
1317 @c   GPGPARSEMAIL
1318 @c
1319 @node gpgparsemail
1320 @section Parse a mail message into an annotated format
1321
1322 @manpage gpgparsemail.1
1323 @ifset manverb
1324 .B gpgparsemail
1325 \- Parse a mail message into an annotated format
1326 @end ifset
1327
1328 @mansect synopsis
1329 @ifset manverb
1330 .B  gpgparsemail
1331 .RI [ options ]
1332 .RI [ file ]
1333 @end ifset
1334
1335 @mansect description
1336 The @command{gpgparsemail} is a utility currently only useful for
1337 debugging.  Run it with @code{--help} for usage information.
1338
1339
1340
1341 @c
1342 @c   SYMCRYPTRUN
1343 @c
1344 @node symcryptrun
1345 @section Call a simple symmetric encryption tool.
1346 @manpage symcryptrun.1
1347 @ifset manverb
1348 .B symcryptrun
1349 \- Call a simple symmetric encryption tool
1350 @end ifset
1351
1352 @mansect synopsis
1353 @ifset manverb
1354 .B  symcryptrun
1355 .B \-\-class
1356 .I class
1357 .B \-\-program
1358 .I program
1359 .B \-\-keyfile
1360 .I keyfile
1361 .RB [ --decrypt | --encrypt ]
1362 .RI [ inputfile ]
1363 @end ifset
1364
1365 @mansect description
1366 Sometimes simple encryption tools are already in use for a long time and
1367 there might be a desire to integrate them into the GnuPG framework.  The
1368 protocols and encryption methods might be non-standard or not even
1369 properly documented, so that a full-fledged encryption tool with an
1370 interface like gpg is not doable.  @command{symcryptrun} provides a
1371 solution: It operates by calling the external encryption/decryption
1372 module and provides a passphrase for a key using the standard
1373 @command{pinentry} based mechanism through @command{gpg-agent}.
1374
1375 Note, that @command{symcryptrun} is only available if GnuPG has been
1376 configured with @samp{--enable-symcryptrun} at build time.
1377
1378 @menu
1379 * Invoking symcryptrun::   List of all commands and options.
1380 @end menu
1381
1382 @manpause
1383 @node Invoking symcryptrun
1384 @subsection List of all commands and options.
1385
1386 @noindent
1387 @command{symcryptrun} is invoked this way:
1388
1389 @example
1390 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1391    [--decrypt | --encrypt] [inputfile]
1392 @end example
1393 @mancont
1394
1395 For encryption, the plain text must be provided on STDIN or as the
1396 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1397 For decryption vice versa.
1398
1399 @var{CLASS} describes the calling conventions of the external tool.
1400 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1401 the full filename of that external tool.
1402  
1403 For the class @samp{confucius} the option @option{--keyfile} is
1404 required; @var{keyfile} is the name of a file containing the secret key,
1405 which may be protected by a passphrase.  For detailed calling
1406 conventions, see the source code.
1407  
1408 @noindent
1409 Note, that @command{gpg-agent} must be running before starting
1410 @command{symcryptrun}.
1411
1412 @noindent
1413 The following additional options may be used:
1414
1415 @table @gnupgtabopt
1416 @item -v
1417 @itemx --verbose
1418 @opindex verbose
1419 Output additional information while running.  
1420
1421 @item -q
1422 @item --quiet
1423 @opindex q
1424 @opindex quiet
1425 Try to be as quiet as possible.
1426
1427 @include opt-homedir.texi
1428
1429
1430 @item --log-file @var{file}
1431 @opindex log-file
1432 Append all logging output to @var{file}.  Default is to write logging
1433 informaton to STDERR.
1434
1435 @end table
1436
1437 @noindent
1438 The possible exit status codes of @command{symcryptrun} are:
1439
1440 @table @code
1441 @item 0 
1442         Success.
1443 @item 1 
1444         Some error occured.
1445 @item 2 
1446         No valid passphrase was provided.
1447 @item 3 
1448         The operation was canceled by the user.
1449
1450 @end table
1451
1452 @mansect see also
1453 @ifset isman
1454 @command{gpg}(1), 
1455 @command{gpgsm}(1), 
1456 @command{gpg-agent}(1), 
1457 @end ifset
1458 @include see-also-note.texi
1459