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