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