Fixed bug 842 (segv in gpgconf)
[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 * Files used by gpgconf:: What files are used by gpgconf.
207 @end menu
208
209 @manpause
210 @node Invoking gpgconf
211 @subsection Invoking gpgconf
212
213 @mansect commands
214 One of the following commands must be given:
215
216 @table @gnupgtabopt
217
218 @item --list-components
219 List all components.  This is the default command used if none is
220 specified.
221
222 @item --check-programs
223 List all available backend programs and test whether they are runnable.
224
225 @item --list-options @var{component}
226 List all options of the component @var{component}.
227
228 @item --change-options @var{component}
229 Change the options of the component @var{component}.
230
231 @item --apply-defaults
232 Update all configuration files with values taken from the global
233 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
234
235 @item --check-config [@var{filename}]
236 Run a syntax check on the global configuration file.  If @var{filename}
237 is given, check that file instead.
238
239 @end table
240
241
242 @mansect options
243
244 The following options may be used:
245
246 @table @gnupgtabopt
247 @c FIXME: Not yet supported.
248 @c @item -o @var{file}
249 @c @itemx --output @var{file}
250 @c Use @var{file} as output file.
251
252 @item -v
253 @itemx --verbose
254 Outputs additional information while running.  Specifically, this
255 extends numerical field values by human-readable descriptions.
256
257 @c FIXME: Not yet supported.
258 @c @item -n
259 @c @itemx --dry-run
260 @c Do not actually change anything.  Useful together with
261 @c @code{--change-options} for testing purposes.
262
263 @item -r
264 @itemx --runtime
265 Only used together with @code{--change-options}.  If one of the
266 modified options can be changed in a running daemon process, signal
267 the running daemon to ask it to reparse its configuration file after
268 changing.
269
270 This means that the changes will take effect at run-time, as far as
271 this is possible.  Otherwise, they will take effect at the next start
272 of the respective backend programs.
273 @manpause
274 @end table
275
276
277 @node Format conventions
278 @subsection Format conventions
279
280 Some lines in the output of @command{gpgconf} contain a list of
281 colon-separated fields.  The following conventions apply:
282
283 @itemize @bullet
284 @item
285 The GUI program is required to strip off trailing newline and/or
286 carriage return characters from the output.
287
288 @item
289 @command{gpgconf} will never leave out fields.  If a certain version
290 provides a certain field, this field will always be present in all
291 @command{gpgconf} versions from that time on.
292
293 @item
294 Future versions of @command{gpgconf} might append fields to the list.
295 New fields will always be separated from the previously last field by
296 a colon separator.  The GUI should be prepared to parse the last field
297 it knows about up until a colon or end of line.
298
299 @item
300 Not all fields are defined under all conditions.  You are required to
301 ignore the content of undefined fields.
302 @end itemize
303
304 There are several standard types for the content of a field:
305
306 @table @asis
307 @item verbatim
308 Some fields contain strings that are not escaped in any way.  Such
309 fields are described to be used @emph{verbatim}.  These fields will
310 never contain a colon character (for obvious reasons).  No de-escaping
311 or other formatting is required to use the field content.  This is for
312 easy parsing of the output, when it is known that the content can
313 never contain any special characters.
314
315 @item percent-escaped
316 Some fields contain strings that are described to be
317 @emph{percent-escaped}.  Such strings need to be de-escaped before
318 their content can be presented to the user.  A percent-escaped string
319 is de-escaped by replacing all occurences of @code{%XY} by the byte
320 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
321 from the set @code{0-9a-f}.
322
323 @item localised
324 Some fields contain strings that are described to be @emph{localised}.
325 Such strings are translated to the active language and formatted in
326 the active character set.
327
328 @item @w{unsigned number}
329 Some fields contain an @emph{unsigned number}.  This number will
330 always fit into a 32-bit unsigned integer variable.  The number may be
331 followed by a space, followed by a human readable description of that
332 value (if the verbose option is used).  You should ignore everything
333 in the field that follows the number.
334
335 @item @w{signed number}
336 Some fields contain a @emph{signed number}.  This number will always
337 fit into a 32-bit signed integer variable.  The number may be followed
338 by a space, followed by a human readable description of that value (if
339 the verbose option is used).  You should ignore everything in the
340 field that follows the number.
341
342 @item @w{boolean value}
343 Some fields contain a @emph{boolean value}.  This is a number with
344 either the value 0 or 1.  The number may be followed by a space,
345 followed by a human readable description of that value (if the verbose
346 option is used).  You should ignore everything in the field that follows
347 the number; checking just the first character is sufficient in this
348 case.
349
350 @item option
351 Some fields contain an @emph{option} argument.  The format of an
352 option argument depends on the type of the option and on some flags:
353
354 @table @asis
355 @item no argument
356 The simplest case is that the option does not take an argument at all
357 (@var{type} @code{0}).  Then the option argument is an unsigned number
358 that specifies how often the option occurs.  If the @code{list} flag
359 is not set, then the only valid number is @code{1}.  Options that do
360 not take an argument never have the @code{default} or @code{optional
361 arg} flag set.
362
363 @item number
364 If the option takes a number argument (@var{alt-type} is @code{2} or
365 @code{3}), and it can only occur once (@code{list} flag is not set),
366 then the option argument is either empty (only allowed if the argument
367 is optional), or it is a number.  A number is a string that begins
368 with an optional minus character, followed by one or more digits.  The
369 number must fit into an integer variable (unsigned or signed,
370 depending on @var{alt-type}).
371
372 @item number list
373 If the option takes a number argument and it can occur more than once,
374 then the option argument is either empty, or it is a comma-separated
375 list of numbers as described above.
376
377 @item string
378 If the option takes a string argument (@var{alt-type} is 1), and it
379 can only occur once (@code{list} flag is not set) then the option
380 argument is either empty (only allowed if the argument is optional),
381 or it starts with a double quote character (@code{"}) followed by a
382 percent-escaped string that is the argument value.  Note that there is
383 only a leading double quote character, no trailing one.  The double
384 quote character is only needed to be able to differentiate between no
385 value and the empty string as value.
386
387 @item string list
388 If the option takes a number argument and it can occur more than once,
389 then the option argument is either empty, or it is a comma-separated
390 list of string arguments as described above.
391 @end table
392 @end table
393
394 The active language and character set are currently determined from
395 the locale environment of the @command{gpgconf} program.
396
397 @c FIXME: Document the active language and active character set.  Allow
398 @c to change it via the command line?
399
400
401 @mansect usage
402 @node Listing components
403 @subsection Listing components
404
405 The command @code{--list-components} will list all components that can
406 be configured with @command{gpgconf}.  Usually, one component will
407 correspond to one GnuPG-related program and contain the options of
408 that programs configuration file that can be modified using
409 @command{gpgconf}.  However, this is not necessarily the case.  A
410 component might also be a group of selected options from several
411 programs, or contain entirely virtual options that have a special
412 effect rather than changing exactly one option in one configuration
413 file.
414
415 A component is a set of configuration options that semantically belong
416 together.  Furthermore, several changes to a component can be made in
417 an atomic way with a single operation.  The GUI could for example
418 provide a menu with one entry for each component, or a window with one
419 tabulator sheet per component.
420
421 The command argument @code{--list-components} lists all available
422 components, one per line.  The format of each line is:
423
424 @code{@var{name}:@var{description}:@var{pgmname}:}
425
426 @table @var
427 @item name
428 This field contains a name tag of the component.  The name tag is used
429 to specify the component in all communication with @command{gpgconf}.
430 The name tag is to be used @emph{verbatim}.  It is thus not in any
431 escaped format.
432
433 @item description
434 The @emph{string} in this field contains a human-readable description
435 of the component.  It can be displayed to the user of the GUI for
436 informational purposes.  It is @emph{percent-escaped} and
437 @emph{localized}.
438
439 @item pgmname
440 The @emph{string} in this field contains the absolute name of the
441 program's file.  It can be used to unambiguously invoke that program.
442 It is @emph{percent-escaped}.
443 @end table
444
445 Example:
446 @example
447 $ gpgconf --list-components
448 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
449 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
450 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
451 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
452 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
453 @end example
454
455
456
457 @node Checking programs
458 @subsection Checking programs
459
460 The command @code{--check-programs} is similar to
461 @code{--list-components} but works on backend programs and not on
462 components.  It runs each program to test wether it is installed and
463 runnable.  This also includes a syntax check of all config file options
464 of the program.
465
466 The command argument @code{--check-programs} lists all available
467 programs, one per line.  The format of each line is:
468
469 @code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
470
471 @table @var
472 @item name
473 This field contains a name tag of the program which is identical to the
474 name of the component.  The name tag is to be used @emph{verbatim}.  It
475 is thus not in any escaped format.  This field may be empty to indicate
476 a continuation of error descriptions for the last name.  The description
477 and pgmname fields are then also empty.
478
479 @item description
480 The @emph{string} in this field contains a human-readable description
481 of the component.  It can be displayed to the user of the GUI for
482 informational purposes.  It is @emph{percent-escaped} and
483 @emph{localized}.
484
485 @item pgmname
486 The @emph{string} in this field contains the absolute name of the
487 program's file.  It can be used to unambiguously invoke that program.
488 It is @emph{percent-escaped}.
489
490 @item avail
491 The @emph{boolean value} in this field indicates whether the program is
492 installed and runnable.
493
494 @item okay
495 The @emph{boolean value} in this field indicates whether the program's
496 config file is syntactically okay.
497
498 @item cfgfile
499 If an error occured in the configuraion file (as indicated by a false
500 value in the field @code{okay}), this field has the name of the failing
501 configuration file.  It is @emph{percent-escaped}.
502
503 @item line
504 If an error occured in the configuration file, this field has the line
505 number of the failing statement in the configuration file.  
506 It is an @emph{unsigned number}.
507
508 @item error
509 If an error occured in the configuration file, this field has the error
510 text of the failing statement in the configuration file.  It is
511 @emph{percent-escaped} and @emph{localized}.
512
513 @end table
514
515 @noindent
516 In the following example the @command{dirmngr} is not runnable and the
517 configuration file of @command{scdaemon} is not okay.
518
519 @example
520 $ gpgconf --check-programs
521 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
522 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
523 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
524 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
525 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
526 @end example
527
528
529 @node Listing options
530 @subsection Listing options
531
532 Every component contains one or more options.  Options may be gathered
533 into option groups to allow the GUI to give visual hints to the user
534 about which options are related.
535
536 The command argument @code{@w{--list-options @var{component}}} lists
537 all options (and the groups they belong to) in the component
538 @var{component}, one per line.  @var{component} must be the string in
539 the field @var{name} in the output of the @code{--list-components}
540 command.
541
542 There is one line for each option and each group.  First come all
543 options that are not in any group.  Then comes a line describing a
544 group.  Then come all options that belong into each group.  Then comes
545 the next group and so on.  There does not need to be any group (and in
546 this case the output will stop after the last non-grouped option).
547
548 The format of each line is:
549
550 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
551
552 @table @var
553 @item name
554 This field contains a name tag for the group or option.  The name tag
555 is used to specify the group or option in all communication with
556 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
557 thus not in any escaped format.
558
559 @item flags
560 The flags field contains an @emph{unsigned number}.  Its value is the
561 OR-wise combination of the following flag values:
562
563 @table @code
564 @item group (1)
565 If this flag is set, this is a line describing a group and not an
566 option.
567 @end table
568
569 The following flag values are only defined for options (that is, if
570 the @code{group} flag is not used).
571
572 @table @code
573 @item optional arg (2)
574 If this flag is set, the argument is optional.  This is never set for
575 @var{type} @code{0} (none) options.
576
577 @item list (4)
578 If this flag is set, the option can be given multiple times.
579
580 @item runtime (8)
581 If this flag is set, the option can be changed at runtime.
582
583 @item default (16)
584 If this flag is set, a default value is available.
585
586 @item default desc (32)
587 If this flag is set, a (runtime) default is available.  This and the
588 @code{default} flag are mutually exclusive.
589
590 @item no arg desc (64)
591 If this flag is set, and the @code{optional arg} flag is set, then the
592 option has a special meaning if no argument is given.
593
594 @item no change (128)
595 If this flag is set, gpgconf ignores requests to change the value.  GUI
596 frontends should grey out this option.  Note, that manual changes of the
597 configuration files are still possible.
598 @end table
599
600 @item level
601 This field is defined for options and for groups.  It contains an
602 @emph{unsigned number} that specifies the expert level under which
603 this group or option should be displayed.  The following expert levels
604 are defined for options (they have analogous meaning for groups):
605
606 @table @code
607 @item basic (0)
608 This option should always be offered to the user.
609
610 @item advanced (1)
611 This option may be offered to advanced users.
612
613 @item expert (2)
614 This option should only be offered to expert users.
615
616 @item invisible (3)
617 This option should normally never be displayed, not even to expert
618 users.
619
620 @item internal (4)
621 This option is for internal use only.  Ignore it.
622 @end table
623
624 The level of a group will always be the lowest level of all options it
625 contains.
626
627 @item description
628 This field is defined for options and groups.  The @emph{string} in
629 this field contains a human-readable description of the option or
630 group.  It can be displayed to the user of the GUI for informational
631 purposes.  It is @emph{percent-escaped} and @emph{localized}.
632
633 @item type
634 This field is only defined for options.  It contains an @emph{unsigned
635 number} that specifies the type of the option's argument, if any.  The
636 following types are defined:
637
638 Basic types:
639
640 @table @code
641 @item none (0)
642 No argument allowed.
643
644 @item string (1)
645 An @emph{unformatted string}.
646
647 @item int32 (2)
648 A @emph{signed number}.
649
650 @item uint32 (3)
651 An @emph{unsigned number}.
652 @end table
653
654 Complex types:
655
656 @table @code
657 @item pathname (32)
658 A @emph{string} that describes the pathname of a file.  The file does
659 not necessarily need to exist.
660
661 @item ldap server (33)
662 A @emph{string} that describes an LDAP server in the format:
663
664 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
665 @end table
666
667 More types will be added in the future.  Please see the @var{alt-type}
668 field for information on how to cope with unknown types.
669
670 @item alt-type
671 This field is identical to @var{type}, except that only the types
672 @code{0} to @code{31} are allowed.  The GUI is expected to present the
673 user the option in the format specified by @var{type}.  But if the
674 argument type @var{type} is not supported by the GUI, it can still
675 display the option in the more generic basic type @var{alt-type}.  The
676 GUI must support all the defined basic types to be able to display all
677 options.  More basic types may be added in future versions.  If the
678 GUI encounters a basic type it doesn't support, it should report an
679 error and abort the operation.
680
681 @item argname
682 This field is only defined for options with an argument type
683 @var{type} that is not @code{0}.  In this case it may contain a
684 @emph{percent-escaped} and @emph{localised string} that gives a short
685 name for the argument.  The field may also be empty, though, in which
686 case a short name is not known.
687
688 @item default
689 This field is defined only for options.  Its format is that of an
690 @emph{option argument} (@xref{Format conventions}, for details).  If
691 the default value is empty, then no default is known.  Otherwise, the
692 value specifies the default value for this option.  Note that this
693 field is also meaningful if the option itself does not take a real
694 argument.
695
696 @item argdef
697 This field is defined only for options for which the @code{optional
698 arg} flag is set.  If the @code{no arg desc} flag is not set, its
699 format is that of an @emph{option argument} (@xref{Format
700 conventions}, for details).  If the default value is empty, then no
701 default is known.  Otherwise, the value specifies the default value
702 for this option.  If the @code{no arg desc} flag is set, the field is
703 either empty or contains a description of the effect of this option if
704 no argument is given.  Note that this field is also meaningful if the
705 option itself does not take a real argument.
706
707 @item value
708 This field is defined only for options.  Its format is that of an
709 @emph{option argument}.  If it is empty, then the option is not
710 explicitely set in the current configuration, and the default applies
711 (if any).  Otherwise, it contains the current value of the option.
712 Note that this field is also meaningful if the option itself does not
713 take a real argument.
714 @end table
715
716
717 @node Changing options
718 @subsection Changing options
719
720 The command @w{@code{--change-options @var{component}}} will attempt
721 to change the options of the component @var{component} to the
722 specified values.  @var{component} must be the string in the field
723 @var{name} in the output of the @code{--list-components} command.  You
724 have to provide the options that shall be changed in the following
725 format on standard input:
726
727 @code{@var{name}:@var{flags}:@var{new-value}}
728
729 @table @var
730 @item name
731 This is the name of the option to change.  @var{name} must be the
732 string in the field @var{name} in the output of the
733 @code{--list-options} command.
734
735 @item flags
736 The flags field contains an @emph{unsigned number}.  Its value is the
737 OR-wise combination of the following flag values:
738
739 @table @code
740 @item default (16)
741 If this flag is set, the option is deleted and the default value is
742 used instead (if applicable).
743 @end table
744
745 @item new-value
746 The new value for the option.  This field is only defined if the
747 @code{default} flag is not set.  The format is that of an @emph{option
748 argument}.  If it is empty (or the field is omitted), the default
749 argument is used (only allowed if the argument is optional for this
750 option).  Otherwise, the option will be set to the specified value.
751 @end table
752
753 Examples:
754
755 To set the force option, which is of basic type @code{none (0)}:
756
757 @example
758 $ echo 'force:0:1' | gpgconf --change-options dirmngr
759 @end example
760
761 To delete the force option:
762
763 @example
764 $ echo 'force:16:' | gpgconf --change-options dirmngr
765 @end example
766
767 The @code{--runtime} option can influence when the changes take
768 effect.
769
770 @mansect files
771 @node Files used by gpgconf
772 @subsection Files used by gpgconf
773
774 @table @file
775
776 @item /etc/gnupg/gpgconf.conf
777 @cindex gpgconf.conf
778   If this file exists, it is processed as a global configuration file.
779   A commented example can be found in the @file{examples} directory of
780   the distribution.
781 @end table
782
783
784 @mansect see also
785 @ifset isman
786 @command{gpg}(1), 
787 @command{gpgsm}(1), 
788 @command{gpg-agent}(1), 
789 @command{scdaemon}(1),
790 @command{dirmngr}(1)
791 @end ifset
792 @include see-also-note.texi
793
794
795
796 @c
797 @c    APPLYGNUPGDEFAULTS
798 @c
799 @manpage applygnupgdefaults.8
800 @node applygnupgdefaults
801 @section Run gpgconf for all users.
802 @ifset manverb
803 .B applygnupgdefaults
804 \- Run gpgconf --apply-defaults for all users.
805 @end ifset
806
807 @mansect synopsis
808 @ifset manverb
809 .B  applygnupgdefaults
810 @end ifset
811
812 @mansect description
813 This script is a wrapper around @command{gpgconf} to run it with the
814 command @code{--apply-defaults} for all real users with an existing
815 GnuPG home directory.  Admins might want to use this script to update he
816 GnuPG configuration files for all users after
817 @file{/etc/gnupg/gpgconf.conf} has been changed.  This allows to enforce
818 certain policies for all users.  Note, that this is not a bulletproof of
819 forcing a user to use certain options.  A user may always directly edit
820 the configuration files and bypass gpgconf.
821
822 @noindent
823 @command{applygnupgdefaults} is invoked by root as:
824
825 @example
826 applygnupgdefaults
827 @end example
828
829
830 @c
831 @c    GPGSM-GENCERT.SH
832 @c
833 @node gpgsm-gencert.sh
834 @section Generate an X.509 certificate request
835 @manpage gpgsm-gencert.sh.1
836 @ifset manverb
837 .B gpgsm-gencert.sh
838 \- Generate an X.509 certificate request
839 @end ifset 
840
841 @mansect synopsis
842 @ifset manverb
843 .B  gpgsm-gencert.sh
844 @end ifset
845
846 @mansect description
847 This is a simple tool to interactivly generate a certificate request
848 which will be printed to stdout.
849
850 @manpause
851 @noindent
852 @command{gpgsm-gencert.sh} is invoked as:
853
854 @samp{gpgsm-cencert.sh}
855
856 @mansect see also
857 @ifset isman
858 @command{gpgsm}(1), 
859 @command{gpg-agent}(1), 
860 @command{scdaemon}(1)
861 @end ifset
862 @include see-also-note.texi
863
864
865
866 @c
867 @c   GPG-PRESET-PASSPHRASE
868 @c
869 @node gpg-preset-passphrase
870 @section Put a passphrase into the cache.
871 @manpage gpg-preset-passphrase.1
872 @ifset manverb
873 .B gpg-preset-passphrase
874 \- Put a passphrase into gpg-agent's cache
875 @end ifset
876
877 @mansect synopsis
878 @ifset manverb
879 .B  gpg-preset-passphrase
880 .RI [ options ]
881 .RI [ command ]
882 .I keygrip
883 @end ifset
884
885 @mansect description
886 The @command{gpg-preset-passphrase} is a utility to seed the internal
887 cache of a running @command{gpg-agent} with passphrases.  It is mainly
888 useful for unattended machines, where the usual @command{pinentry} tool
889 may not be used and the passphrases for the to be used keys are given at
890 machine startup.
891
892 Passphrases set with this utility don't expire unless the
893 @option{--forget} option is used to explicitly clear them from the cache
894 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
895 SIGHUP to it).  It is necessary to allow this passphrase presetting by
896 starting @command{gpg-agent} with the
897 @option{--allow-preset-passphrase}.
898
899 @menu
900 * Invoking gpg-preset-passphrase::   List of all commands and options.
901 @end menu
902
903 @manpause
904 @node Invoking gpg-preset-passphrase
905 @subsection List of all commands and options.
906 @mancont
907
908 @noindent
909 @command{gpg-preset-passphrase} is invoked this way:
910
911 @example
912 gpg-preset-passphrase [options] [command] @var{keygrip}
913 @end example
914
915 @var{keygrip} is a 40 character string of hexadecimal characters
916 identifying the key for which the passphrase should be set or cleared.
917 This keygrip is listed along with the key when running the command:
918 @code{gpgsm --dump-secret-keys}. One of the following command options
919 must be given:
920
921 @table @gnupgtabopt
922 @item --preset
923 @opindex preset
924 Preset a passphrase. This is what you usually will
925 use. @command{gpg-preset-passphrase} will then read the passphrase from
926 @code{stdin}.
927
928 @item --forget
929 @opindex forget
930 Flush the passphrase for the given keygrip from the cache.
931
932 @end table
933
934 @noindent
935 The following additional options may be used:
936
937 @table @gnupgtabopt
938 @item -v
939 @itemx --verbose
940 @opindex verbose
941 Output additional information while running.  
942
943 @item -P @var{string}
944 @itemx --passphrase @var{string}
945 @opindex passphrase
946 Instead of reading the passphrase from @code{stdin}, use the supplied
947 @var{string} as passphrase.  Note that this makes the passphrase visible
948 for other users.
949 @end table
950
951 @mansect see also
952 @ifset isman
953 @command{gpg}(1), 
954 @command{gpgsm}(1), 
955 @command{gpg-agent}(1), 
956 @command{scdaemon}(1)
957 @end ifset
958 @include see-also-note.texi
959
960
961
962
963 @c
964 @c   GPG-CONNECT-AGENT
965 @c
966 @node gpg-connect-agent
967 @section Communicate with a running agent.
968 @manpage gpg-connect-agent.1
969 @ifset manverb
970 .B gpg-connect-agent
971 \- Communicate with a running agent
972 @end ifset
973
974 @mansect synopsis
975 @ifset manverb
976 .B  gpg-connect-agent
977 .RI [ options ]
978 @end ifset
979
980 @mansect description
981 The @command{gpg-connect-agent} is a utility to communicate with a
982 running @command{gpg-agent}.  It is useful to check out the commands
983 gpg-agent provides using the Assuan interface.  It might also be useful
984 for scripting simple applications.  Inputis expected at stdin and out
985 put gets printed to stdout.
986
987 It is very similar to running @command{gpg-agent} in server mode; but
988 here we connect to a running instance.
989
990 @menu
991 * Invoking gpg-connect-agent::       List of all options.
992 * Controlling gpg-connect-agent::    Control commands.
993 @end menu
994
995 @manpause
996 @node Invoking gpg-connect-agent
997 @subsection List of all options.
998
999 @noindent
1000 @command{gpg-connect-agent} is invoked this way:
1001
1002 @example
1003 gpg-connect-agent [options]
1004 @end example
1005 @mancont
1006
1007 @noindent
1008 The following options may be used:
1009
1010 @table @gnupgtabopt
1011 @item -v
1012 @itemx --verbose
1013 @opindex verbose
1014 Output additional information while running.  
1015
1016 @item -q
1017 @item --quiet
1018 @opindex q
1019 @opindex quiet
1020 Try to be as quiet as possible.
1021
1022 @include opt-homedir.texi
1023
1024 @item -S
1025 @itemx --raw-socket @var{name}
1026 @opindex S        
1027 @opindex raw-socket
1028 Connect to socket @var{name} assuming this is an Assuan style server.
1029 Do not run any special initializations or environment checks.  This may
1030 be used to directly connect to any Assuan style socket server.
1031
1032 @item -E
1033 @itemx --exec
1034 @opindex exec
1035 Take the rest of the command line as a program and it's arguments and
1036 execute it as an assuan server. Here is how you would run @command{gpgsm}:
1037 @smallexample
1038  gpg-connect-agent --exec gpgsm --server
1039 @end smallexample
1040
1041
1042 @item --no-ext-connect
1043 @opindex no-ext-connect
1044 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
1045 connects to the assuan server in extended mode to allow descriptor
1046 passing.  This option makes it use the old mode.
1047
1048 @item --hex
1049 @opindex hex
1050 Print data lines in a hex format and the ASCII representation of
1051 non-control characters.
1052
1053 @item --decode
1054 @opindex decode
1055 Decode data lines.  That is to remove percent escapes but make sure that
1056 a new line always starts with a D and a space.
1057
1058 @end table
1059
1060 @mansect control commands
1061 @node Controlling gpg-connect-agent
1062 @subsection Control commands.
1063
1064 While reading Assuan commands, gpg-agent also allows a few special
1065 commands to control its operation.  These control commands all start
1066 with a slash (@code{/}).
1067
1068
1069 @table @code
1070
1071 @item /echo @var{args}
1072 Just print @var{args}.
1073
1074 @item /definqfile @var{name} @var{file}
1075
1076 Use content of @var{file} for inquiries with @var{name}.
1077 @var{name} may be an asterisk (@code{*} to match any inquiry.
1078
1079 @item /definqprog @var{name} @var{prog}
1080 Run @var{prog} for inquiries matching @var{name} and pass the
1081 entire line to it as command line arguments
1082
1083 @item /showdef
1084 Print all definitions
1085
1086 @item /cleardef
1087 Delete all definitions
1088
1089 @item /sendfd @var{file} @var{mode}
1090 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1091 mode string) and send the file descriptor to the server.  This is
1092 usually followed by a command like @code{INPUT FD} to set the
1093 input source for other commands.
1094
1095 @item /recvfd
1096 Not yet implemented.
1097
1098 @item /hex
1099 @itemx /nohex
1100 Same as the command line option @option{--hex}.
1101
1102 @item /decode
1103 @itemx /nodecode
1104 Same as the command line option @option{--decode}.
1105
1106 @item /help
1107 Print a list of available control commands.
1108
1109 @end table
1110
1111
1112 @ifset isman
1113 @mansect see also
1114 @command{gpg-agent}(1), 
1115 @command{scdaemon}(1)
1116 @include see-also-note.texi
1117 @end ifset
1118
1119
1120 @c
1121 @c   GPGPARSEMAIL
1122 @c
1123 @node gpgparsemail
1124 @section Parse a mail message into an annotated format
1125
1126 @manpage gpgparsemail.1
1127 @ifset manverb
1128 .B gpgparsemail
1129 \- Parse a mail message into an annotated format
1130 @end ifset
1131
1132 @mansect synopsis
1133 @ifset manverb
1134 .B  gpgparsemail
1135 .RI [ options ]
1136 .RI [ file ]
1137 @end ifset
1138
1139 @mansect description
1140 The @command{gpgparsemail} is a utility currently only useful for
1141 debugging.  Run it with @code{--help} for usage information.
1142
1143
1144
1145 @c
1146 @c   SYMCRYPTRUN
1147 @c
1148 @node symcryptrun
1149 @section Call a simple symmetric encryption tool.
1150 @manpage symcryptrun.1
1151 @ifset manverb
1152 .B symcryptrun
1153 \- Call a simple symmetric encryption tool
1154 @end ifset
1155
1156 @mansect synopsis
1157 @ifset manverb
1158 .B  symcryptrun
1159 .B \-\-class
1160 .I class
1161 .B \-\-program
1162 .I program
1163 .B \-\-keyfile
1164 .I keyfile
1165 .RB [ --decrypt | --encrypt ]
1166 .RI [ inputfile ]
1167 @end ifset
1168
1169 @mansect description
1170 Sometimes simple encryption tools are already in use for a long time and
1171 there might be a desire to integrate them into the GnuPG framework.  The
1172 protocols and encryption methods might be non-standard or not even
1173 properly documented, so that a full-fledged encryption tool with an
1174 interface like gpg is not doable.  @command{symcryptrun} provides a
1175 solution: It operates by calling the external encryption/decryption
1176 module and provides a passphrase for a key using the standard
1177 @command{pinentry} based mechanism through @command{gpg-agent}.
1178
1179 Note, that @command{symcryptrun} is only available if GnuPG has been
1180 configured with @samp{--enable-symcryptrun} at build time.
1181
1182 @menu
1183 * Invoking symcryptrun::   List of all commands and options.
1184 @end menu
1185
1186 @manpause
1187 @node Invoking symcryptrun
1188 @subsection List of all commands and options.
1189
1190 @noindent
1191 @command{symcryptrun} is invoked this way:
1192
1193 @example
1194 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1195    [--decrypt | --encrypt] [inputfile]
1196 @end example
1197 @mancont
1198
1199 For encryption, the plain text must be provided on STDIN or as the
1200 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1201 For decryption vice versa.
1202
1203 @var{CLASS} describes the calling conventions of the external tool.
1204 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1205 the full filename of that external tool.
1206  
1207 For the class @samp{confucius} the option @option{--keyfile} is
1208 required; @var{keyfile} is the name of a file containing the secret key,
1209 which may be protected by a passphrase.  For detailed calling
1210 conventions, see the source code.
1211  
1212 @noindent
1213 Note, that @command{gpg-agent} must be running before starting
1214 @command{symcryptrun}.
1215
1216 @noindent
1217 The following additional options may be used:
1218
1219 @table @gnupgtabopt
1220 @item -v
1221 @itemx --verbose
1222 @opindex verbose
1223 Output additional information while running.  
1224
1225 @item -q
1226 @item --quiet
1227 @opindex q
1228 @opindex quiet
1229 Try to be as quiet as possible.
1230
1231 @include opt-homedir.texi
1232
1233
1234 @item --log-file @var{file}
1235 @opindex log-file
1236 Append all logging output to @var{file}.  Default is to write logging
1237 informaton to STDERR.
1238
1239 @end table
1240
1241 @noindent
1242 The possible exit status codes of @command{symcryptrun} are:
1243
1244 @table @code
1245 @item 0 
1246         Success.
1247 @item 1 
1248         Some error occured.
1249 @item 2 
1250         No valid passphrase was provided.
1251 @item 3 
1252         The operation was canceled by the user.
1253
1254 @end table
1255
1256 @mansect see also
1257 @ifset isman
1258 @command{gpg}(1), 
1259 @command{gpgsm}(1), 
1260 @command{gpg-agent}(1), 
1261 @end ifset
1262 @include see-also-note.texi
1263