Support for a global gpgconf configuration file.
[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 * gpgsm-gencert.sh::      Generate an X.509 certificate request.
16 * gpg-preset-passphrase:: Put a passphrase into the cache.
17 * gpg-connect-agent::     Communicate with a running agent.
18 * gpgparsemail::          Parse a mail message into an annotated format
19 * symcryptrun::           Call a simple symmetric encryption tool.
20 @end menu
21
22 @c
23 @c  WATCHGNUPG
24 @c
25 @manpage watchgnupg.1
26 @node watchgnupg
27 @section Read logs from a socket
28 @ifset manverb
29 .B watchgnupg
30 \- Read and print logs from a socket
31 @end ifset
32
33 @mansect synopsis
34 @ifset manverb
35 .B  watchgnupg
36 .RB [ \-\-force ]
37 .RB [ \-\-verbose ]
38 .I socketname
39 @end ifset
40
41 @mansect description
42 Most of the main utilities are able to write there log files to a
43 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
44 listener for such a socket.  It ameliorates the output with a time
45 stamp and makes sure that long lines are not interspersed with log
46 output from other utilities.
47
48 @noindent
49 @command{watchgnupg} is commonly invoked as
50
51 @example
52 watchgnupg --force ~/.gnupg/S.log
53 @end example
54 @manpause
55
56 @noindent
57 This starts it on the current terminal for listening on the socket
58 @file{~/.gnupg/S.log}.  
59
60 @mansect options
61 @noindent
62 @command{watchgnupg} understands these options:
63
64 @table @gnupgtabopt
65
66 @item --force 
67 @opindex force
68 Delete an already existing socket file.
69
70 @item --verbose
71 @opindex verbose
72 Enable extra informational output.
73
74 @item --version
75 @opindex version
76 print version of the program and exit
77
78 @item --help
79 @opindex help
80 Display a brief help page and exit
81
82 @end table
83
84 @mansect see also
85 @command{gpg}(1), 
86 @command{gpgsm}(1), 
87 @command{gpg-agent}(1), 
88 @command{scdaemon}(1)
89 @include see-also-note.texi
90
91
92 @c
93 @c  GPGV
94 @c
95 @include gpgv.texi
96
97
98 @c
99 @c    ADDGNUPGHOME
100 @c
101 @manpage addgnupghome.8
102 @node addgnupghome
103 @section Create .gnupg home directories.
104 @ifset manverb
105 .B addgnupghome 
106 \- Create .gnupg home directories
107 @end ifset
108
109 @mansect synopsis
110 @ifset manverb
111 .B  addgnupghome
112 .I account_1
113 .IR account_2 ... account_n
114 @end ifset
115
116 @mansect description
117 If GnuPG is installed on a system with existing user accounts, it is
118 sometimes required to populate the GnuPG home directory with existing
119 files.  Especially a @file{trustlist.txt} and a keybox with some
120 initial certificates are often desired.  This scripts help to do this
121 by copying all files from @file{/etc/skel/.gnupg} to the home
122 directories of the accounts given on the command line.  It takes care
123 not to overwrite existing GnuPG home directories.
124
125 @noindent
126 @command{addgnupghome} is invoked by root as:
127
128 @example
129 addgnupghome account1 account2 ... accountn
130 @end example
131
132
133 @c
134 @c   GPGCONF
135 @c
136 @manpage gpgconf.1
137 @node gpgconf
138 @section Modify .gnupg home directories.
139 @ifset manverb
140 .B gpgconf
141 \- Modify .gnupg home directories
142 @end ifset
143
144 @mansect synopsis
145 @ifset manverb
146 .B gpgconf
147 .RI [ options ]
148 .B \-\-list-components
149 .br
150 .B gpgconf
151 .RI [ options ]
152 .B \-\-list-options 
153 .I component
154 .br
155 .B gpgconf
156 .RI [ options ]
157 .B \-\-change-options
158 .I component
159 @end ifset
160
161
162 @mansect description
163 The @command{gpgconf} is a utility to automatically and reasonable
164 safely query and modify configuration files in the @file{.gnupg} home
165 directory.  It is designed not to be invoked manually by the user, but
166 automatically by graphical user interfaces (GUI).@footnote{Please note
167 that currently no locking is done, so concurrent access should be
168 avoided.  There are some precautions to avoid corruption with
169 concurrent usage, but results may be inconsistent and some changes may
170 get lost.  The stateless design makes it difficult to provide more
171 guarantees.}
172
173 @command{gpgconf} provides access to the configuration of one or more
174 components of the GnuPG system.  These components correspond more or
175 less to the programs that exist in the GnuPG framework, like GnuPG,
176 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
177 relationship.  Not all configuration options are available through
178 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
179 method to access the most important configuration options that can
180 feasibly be controlled via such a mechanism.
181
182 @command{gpgconf} can be used to gather and change the options
183 available in each component, and can also provide their default
184 values.  @command{gpgconf} will give detailed type information that
185 can be used to restrict the user's input without making an attempt to
186 commit the changes.
187
188 @command{gpgconf} provides the backend of a configuration editor.  The
189 configuration editor would usually be a graphical user interface
190 program, that allows to display the current options, their default
191 values, and allows the user to make changes to the options.  These
192 changes can then be made active with @command{gpgconf} again.  Such a
193 program that uses @command{gpgconf} in this way will be called GUI
194 throughout this section.
195
196 @menu
197 * Invoking gpgconf::      List of all commands and options.
198 * Format conventions::    Formatting conventions relevant for all commands.
199 * Listing components::    List all gpgconf components.
200 * Listing options::       List all options of a component.
201 * Changing options::      Changing options of a component.
202 * Files used by gpgconf:: What files are used by gpgconf.
203 @end menu
204
205 @manpause
206 @node Invoking gpgconf
207 @subsection Invoking gpgconf
208
209 @mansect commands
210 One of the following commands must be given:
211
212 @table @gnupgtabopt
213
214 @item --list-components
215 List all components.  This is the default command used if none is
216 specified.
217
218 @item --list-options @var{component}
219 List all options of the component @var{component}.
220
221 @item --change-options @var{component}
222 Change the options of the component @var{component}.
223
224 @item --apply-defaults
225 Update all configuration files with values taken from the global
226 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
227
228 @item --check-config [@var{filename}]
229 Run a syntax check ion the global configuration file.  If @var{filename}
230 is given, check that file instead.
231
232 @end table
233
234
235 @mansect options
236
237 The following options may be used:
238
239 @table @gnupgtabopt
240 @c FIXME: Not yet supported.
241 @c @item -o @var{file}
242 @c @itemx --output @var{file}
243 @c Use @var{file} as output file.
244
245 @item -v
246 @itemx --verbose
247 Outputs additional information while running.  Specifically, this
248 extends numerical field values by human-readable descriptions.
249
250 @c FIXME: Not yet supported.
251 @c @item -n
252 @c @itemx --dry-run
253 @c Do not actually change anything.  Useful together with
254 @c @code{--change-options} for testing purposes.
255
256 @item -r
257 @itemx --runtime
258 Only used together with @code{--change-options}.  If one of the
259 modified options can be changed in a running daemon process, signal
260 the running daemon to ask it to reparse its configuration file after
261 changing.
262
263 This means that the changes will take effect at run-time, as far as
264 this is possible.  Otherwise, they will take effect at the next start
265 of the respective backend programs.
266 @manpause
267 @end table
268
269
270 @node Format conventions
271 @subsection Format conventions
272
273 Some lines in the output of @command{gpgconf} contain a list of
274 colon-separated fields.  The following conventions apply:
275
276 @itemize @bullet
277 @item
278 The GUI program is required to strip off trailing newline and/or
279 carriage return characters from the output.
280
281 @item
282 @command{gpgconf} will never leave out fields.  If a certain version
283 provides a certain field, this field will always be present in all
284 @command{gpgconf} versions from that time on.
285
286 @item
287 Future versions of @command{gpgconf} might append fields to the list.
288 New fields will always be separated from the previously last field by
289 a colon separator.  The GUI should be prepared to parse the last field
290 it knows about up until a colon or end of line.
291
292 @item
293 Not all fields are defined under all conditions.  You are required to
294 ignore the content of undefined fields.
295 @end itemize
296
297 There are several standard types for the content of a field:
298
299 @table @asis
300 @item verbatim
301 Some fields contain strings that are not escaped in any way.  Such
302 fields are described to be used @emph{verbatim}.  These fields will
303 never contain a colon character (for obvious reasons).  No de-escaping
304 or other formatting is required to use the field content.  This is for
305 easy parsing of the output, when it is known that the content can
306 never contain any special characters.
307
308 @item percent-escaped
309 Some fields contain strings that are described to be
310 @emph{percent-escaped}.  Such strings need to be de-escaped before
311 their content can be presented to the user.  A percent-escaped string
312 is de-escaped by replacing all occurences of @code{%XY} by the byte
313 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
314 from the set @code{0-9a-f}.
315
316 @item localised
317 Some fields contain strings that are described to be @emph{localised}.
318 Such strings are translated to the active language and formatted in
319 the active character set.
320
321 @item @w{unsigned number}
322 Some fields contain an @emph{unsigned number}.  This number will
323 always fit into a 32-bit unsigned integer variable.  The number may be
324 followed by a space, followed by a human readable description of that
325 value (if the verbose option is used).  You should ignore everything
326 in the field that follows the number.
327
328 @item @w{signed number}
329 Some fields contain a @emph{signed number}.  This number will always
330 fit into a 32-bit signed integer variable.  The number may be followed
331 by a space, followed by a human readable description of that value (if
332 the verbose option is used).  You should ignore everything in the
333 field that follows the number.
334
335 @item option
336 Some fields contain an @emph{option} argument.  The format of an
337 option argument depends on the type of the option and on some flags:
338
339 @table @asis
340 @item no argument
341 The simplest case is that the option does not take an argument at all
342 (@var{type} @code{0}).  Then the option argument is an unsigned number
343 that specifies how often the option occurs.  If the @code{list} flag
344 is not set, then the only valid number is @code{1}.  Options that do
345 not take an argument never have the @code{default} or @code{optional
346 arg} flag set.
347
348 @item number
349 If the option takes a number argument (@var{alt-type} is @code{2} or
350 @code{3}), and it can only occur once (@code{list} flag is not set),
351 then the option argument is either empty (only allowed if the argument
352 is optional), or it is a number.  A number is a string that begins
353 with an optional minus character, followed by one or more digits.  The
354 number must fit into an integer variable (unsigned or signed,
355 depending on @var{alt-type}).
356
357 @item number list
358 If the option takes a number argument and it can occur more than once,
359 then the option argument is either empty, or it is a comma-separated
360 list of numbers as described above.
361
362 @item string
363 If the option takes a string argument (@var{alt-type} is 1), and it
364 can only occur once (@code{list} flag is not set) then the option
365 argument is either empty (only allowed if the argument is optional),
366 or it starts with a double quote character (@code{"}) followed by a
367 percent-escaped string that is the argument value.  Note that there is
368 only a leading double quote character, no trailing one.  The double
369 quote character is only needed to be able to differentiate between no
370 value and the empty string as value.
371
372 @item string 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 string arguments as described above.
376 @end table
377 @end table
378
379 The active language and character set are currently determined from
380 the locale environment of the @command{gpgconf} program.
381
382 @c FIXME: Document the active language and active character set.  Allow
383 @c to change it via the command line?
384
385
386 @mansect usage
387 @node Listing components
388 @subsection Listing components
389
390 The command @code{--list-components} will list all components that can
391 be configured with @command{gpgconf}.  Usually, one component will
392 correspond to one GnuPG-related program and contain the options of
393 that programs configuration file that can be modified using
394 @command{gpgconf}.  However, this is not necessarily the case.  A
395 component might also be a group of selected options from several
396 programs, or contain entirely virtual options that have a special
397 effect rather than changing exactly one option in one configuration
398 file.
399
400 A component is a set of configuration options that semantically belong
401 together.  Furthermore, several changes to a component can be made in
402 an atomic way with a single operation.  The GUI could for example
403 provide a menu with one entry for each component, or a window with one
404 tabulator sheet per component.
405
406 The command argument @code{--list-components} lists all available
407 components, one per line.  The format of each line is:
408
409 @code{@var{name}:@var{description}}
410
411 @table @var
412 @item name
413 This field contains a name tag of the component.  The name tag is used
414 to specify the component in all communication with @command{gpgconf}.
415 The name tag is to be used @emph{verbatim}.  It is thus not in any
416 escaped format.
417
418 @item description
419 The @emph{string} in this field contains a human-readable description
420 of the component.  It can be displayed to the user of the GUI for
421 informational purposes.  It is @emph{percent-escaped} and
422 @emph{localized}.
423 @end table
424
425 Example:
426 @example
427 $ gpgconf --list-components
428 gpg:GPG for OpenPGP
429 gpg-agent:GPG Agent
430 scdaemon:Smartcard Daemon
431 gpgsm:GPG for S/MIME
432 dirmngr:Directory Manager
433 @end example
434
435
436 @node Listing options
437 @subsection Listing options
438
439 Every component contains one or more options.  Options may be gathered
440 into option groups to allow the GUI to give visual hints to the user
441 about which options are related.
442
443 The command argument @code{@w{--list-options @var{component}}} lists
444 all options (and the groups they belong to) in the component
445 @var{component}, one per line.  @var{component} must be the string in
446 the field @var{name} in the output of the @code{--list-components}
447 command.
448
449 There is one line for each option and each group.  First come all
450 options that are not in any group.  Then comes a line describing a
451 group.  Then come all options that belong into each group.  Then comes
452 the next group and so on.  There does not need to be any group (and in
453 this case the output will stop after the last non-grouped option).
454
455 The format of each line is:
456
457 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
458
459 @table @var
460 @item name
461 This field contains a name tag for the group or option.  The name tag
462 is used to specify the group or option in all communication with
463 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
464 thus not in any escaped format.
465
466 @item flags
467 The flags field contains an @emph{unsigned number}.  Its value is the
468 OR-wise combination of the following flag values:
469
470 @table @code
471 @item group (1)
472 If this flag is set, this is a line describing a group and not an
473 option.
474 @end table
475
476 The following flag values are only defined for options (that is, if
477 the @code{group} flag is not used).
478
479 @table @code
480 @item optional arg (2)
481 If this flag is set, the argument is optional.  This is never set for
482 @var{type} @code{0} (none) options.
483
484 @item list (4)
485 If this flag is set, the option can be given multiple times.
486
487 @item runtime (8)
488 If this flag is set, the option can be changed at runtime.
489
490 @item default (16)
491 If this flag is set, a default value is available.
492
493 @item default desc (32)
494 If this flag is set, a (runtime) default is available.  This and the
495 @code{default} flag are mutually exclusive.
496
497 @item no arg desc (64)
498 If this flag is set, and the @code{optional arg} flag is set, then the
499 option has a special meaning if no argument is given.
500
501 @item no change (128)
502 If this flag is set, gpgconf ignores requests to change the value.  GUI
503 frontends should grey out this option.  Note, that manual changes of the
504 configuration files are still possible.
505 @end table
506
507 @item level
508 This field is defined for options and for groups.  It contains an
509 @emph{unsigned number} that specifies the expert level under which
510 this group or option should be displayed.  The following expert levels
511 are defined for options (they have analogous meaning for groups):
512
513 @table @code
514 @item basic (0)
515 This option should always be offered to the user.
516
517 @item advanced (1)
518 This option may be offered to advanced users.
519
520 @item expert (2)
521 This option should only be offered to expert users.
522
523 @item invisible (3)
524 This option should normally never be displayed, not even to expert
525 users.
526
527 @item internal (4)
528 This option is for internal use only.  Ignore it.
529 @end table
530
531 The level of a group will always be the lowest level of all options it
532 contains.
533
534 @item description
535 This field is defined for options and groups.  The @emph{string} in
536 this field contains a human-readable description of the option or
537 group.  It can be displayed to the user of the GUI for informational
538 purposes.  It is @emph{percent-escaped} and @emph{localized}.
539
540 @item type
541 This field is only defined for options.  It contains an @emph{unsigned
542 number} that specifies the type of the option's argument, if any.  The
543 following types are defined:
544
545 Basic types:
546
547 @table @code
548 @item none (0)
549 No argument allowed.
550
551 @item string (1)
552 An @emph{unformatted string}.
553
554 @item int32 (2)
555 A @emph{signed number}.
556
557 @item uint32 (3)
558 An @emph{unsigned number}.
559 @end table
560
561 Complex types:
562
563 @table @code
564 @item pathname (32)
565 A @emph{string} that describes the pathname of a file.  The file does
566 not necessarily need to exist.
567
568 @item ldap server (33)
569 A @emph{string} that describes an LDAP server in the format:
570
571 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
572 @end table
573
574 More types will be added in the future.  Please see the @var{alt-type}
575 field for information on how to cope with unknown types.
576
577 @item alt-type
578 This field is identical to @var{type}, except that only the types
579 @code{0} to @code{31} are allowed.  The GUI is expected to present the
580 user the option in the format specified by @var{type}.  But if the
581 argument type @var{type} is not supported by the GUI, it can still
582 display the option in the more generic basic type @var{alt-type}.  The
583 GUI must support all the defined basic types to be able to display all
584 options.  More basic types may be added in future versions.  If the
585 GUI encounters a basic type it doesn't support, it should report an
586 error and abort the operation.
587
588 @item argname
589 This field is only defined for options with an argument type
590 @var{type} that is not @code{0}.  In this case it may contain a
591 @emph{percent-escaped} and @emph{localised string} that gives a short
592 name for the argument.  The field may also be empty, though, in which
593 case a short name is not known.
594
595 @item default
596 This field is defined only for options.  Its format is that of an
597 @emph{option argument} (@xref{Format conventions}, for details).  If
598 the default value is empty, then no default is known.  Otherwise, the
599 value specifies the default value for this option.  Note that this
600 field is also meaningful if the option itself does not take a real
601 argument.
602
603 @item argdef
604 This field is defined only for options for which the @code{optional
605 arg} flag is set.  If the @code{no arg desc} flag is not set, its
606 format is that of an @emph{option argument} (@xref{Format
607 conventions}, for details).  If the default value is empty, then no
608 default is known.  Otherwise, the value specifies the default value
609 for this option.  If the @code{no arg desc} flag is set, the field is
610 either empty or contains a description of the effect of this option if
611 no argument is given.  Note that this field is also meaningful if the
612 option itself does not take a real argument.
613
614 @item value
615 This field is defined only for options.  Its format is that of an
616 @emph{option argument}.  If it is empty, then the option is not
617 explicitely set in the current configuration, and the default applies
618 (if any).  Otherwise, it contains the current value of the option.
619 Note that this field is also meaningful if the option itself does not
620 take a real argument.
621 @end table
622
623
624 @node Changing options
625 @subsection Changing options
626
627 The command @w{@code{--change-options @var{component}}} will attempt
628 to change the options of the component @var{component} to the
629 specified values.  @var{component} must be the string in the field
630 @var{name} in the output of the @code{--list-components} command.  You
631 have to provide the options that shall be changed in the following
632 format on standard input:
633
634 @code{@var{name}:@var{flags}:@var{new-value}}
635
636 @table @var
637 @item name
638 This is the name of the option to change.  @var{name} must be the
639 string in the field @var{name} in the output of the
640 @code{--list-options} command.
641
642 @item flags
643 The flags field contains an @emph{unsigned number}.  Its value is the
644 OR-wise combination of the following flag values:
645
646 @table @code
647 @item default (16)
648 If this flag is set, the option is deleted and the default value is
649 used instead (if applicable).
650 @end table
651
652 @item new-value
653 The new value for the option.  This field is only defined if the
654 @code{default} flag is not set.  The format is that of an @emph{option
655 argument}.  If it is empty (or the field is omitted), the default
656 argument is used (only allowed if the argument is optional for this
657 option).  Otherwise, the option will be set to the specified value.
658 @end table
659
660 Examples:
661
662 To set the force option, which is of basic type @code{none (0)}:
663
664 @example
665 $ echo 'force:0:1' | gpgconf --change-options dirmngr
666 @end example
667
668 To delete the force option:
669
670 @example
671 $ echo 'force:16:' | gpgconf --change-options dirmngr
672 @end example
673
674 The @code{--runtime} option can influence when the changes take
675 effect.
676
677 @mansect files
678 @node Files used by gpgconf
679 @subsection Files used by gpgconf
680
681 @table @file
682
683 @item /etc/gnupg/gpg-agent.conf
684 @cindex gpgconf.conf
685   If this file exists, it is processed as a global configuration file.
686   A commented example can be found in the @file{examples} directory of
687   the distribution.
688 @end table
689
690
691 @mansect see also
692 @command{gpg}(1), 
693 @command{gpgsm}(1), 
694 @command{gpg-agent}(1), 
695 @command{scdaemon}(1),
696 @command{dirmngr}(1)
697 @include see-also-note.texi
698
699
700 @manpause
701 @c
702 @c    GPGSM-GENCERT.SH
703 @c
704 @node gpgsm-gencert.sh
705 @section Generate an X.509 certificate request
706 @manpage gpgsm-gencert.sh.1
707 @ifset manverb
708 .B gpgsm-gencert.sh
709 \- Generate an X.509 certificate request
710 @end ifset 
711
712 @mansect synopsis
713 @ifset manverb
714 .B  gpgsm-gencert.sh
715 @end ifset
716
717 @mansect description
718 This is a simple tool to interactivly generate a certificate request
719 which will be printed to stdout.
720
721 @manpause
722 @noindent
723 @command{gpgsm-gencert.sh} is invoked as:
724
725 @samp{gpgsm-cencert.sh}
726
727 @mansect see also
728 @command{gpgsm}(1), 
729 @command{gpg-agent}(1), 
730 @command{scdaemon}(1)
731 @include see-also-note.texi
732
733
734
735 @c
736 @c   GPG-PRESET-PASSPHRASE
737 @c
738 @node gpg-preset-passphrase
739 @section Put a passphrase into the cache.
740 @manpage gpg-preset-passphrase.1
741 @ifset manverb
742 .B gpg-preset-passphrase
743 \- Put a passphrase into gpg-agent's cache
744 @end ifset
745
746 @mansect synopsis
747 @ifset manverb
748 .B  gpg-preset-passphrase
749 .RI [ options ]
750 .RI [ command ]
751 .I keygrip
752 @end ifset
753
754 @mansect description
755 The @command{gpg-preset-passphrase} is a utility to seed the internal
756 cache of a running @command{gpg-agent} with passphrases.  It is mainly
757 useful for unattended machines, where the usual @command{pinentry} tool
758 may not be used and the passphrases for the to be used keys are given at
759 machine startup.
760
761 Passphrases set with this utility don't expire unless the
762 @option{--forget} option is used to explicitly clear them from the cache
763 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
764 SIGHUP to it).  It is necessary to allow this passphrase presetting by
765 starting @command{gpg-agent} with the
766 @option{--allow-preset-passphrase}.
767
768 @menu
769 * Invoking gpg-preset-passphrase::   List of all commands and options.
770 @end menu
771
772 @manpause
773 @node Invoking gpg-preset-passphrase
774 @subsection List of all commands and options.
775 @mancont
776
777 @noindent
778 @command{gpg-preset-passphrase} is invoked this way:
779
780 @example
781 gpg-preset-passphrase [options] [command] @var{keygrip}
782 @end example
783
784 @var{keygrip} is a 40 character string of hexadecimal characters
785 identifying the key for which the passphrase should be set or cleared.
786 This keygrip is listed along with the key when running the command:
787 @code{gpgsm --dump-secret-keys}. One of the following command options
788 must be given:
789
790 @table @gnupgtabopt
791 @item --preset
792 @opindex preset
793 Preset a passphrase. This is what you usually will
794 use. @command{gpg-preset-passphrase} will then read the passphrase from
795 @code{stdin}.
796
797 @item --forget
798 @opindex forget
799 Flush the passphrase for the given keygrip from the cache.
800
801 @end table
802
803 @noindent
804 The following additional options may be used:
805
806 @table @gnupgtabopt
807 @item -v
808 @itemx --verbose
809 @opindex verbose
810 Output additional information while running.  
811
812 @item -P @var{string}
813 @itemx --passphrase @var{string}
814 @opindex passphrase
815 Instead of reading the passphrase from @code{stdin}, use the supplied
816 @var{string} as passphrase.  Note that this makes the passphrase visible
817 for other users.
818 @end table
819
820 @mansect see also
821 @command{gpg}(1), 
822 @command{gpgsm}(1), 
823 @command{gpg-agent}(1), 
824 @command{scdaemon}(1)
825 @include see-also-note.texi
826
827
828
829
830 @c
831 @c   GPG-CONNECT-AGENT
832 @c
833 @node gpg-connect-agent
834 @section Communicate with a running agent.
835 @manpage gpg-connect-agent.1
836 @ifset manverb
837 .B gpg-connect-agent
838 \- Communicate with a running agent
839 @end ifset
840
841 @mansect synopsis
842 @ifset manverb
843 .B  gpg-connect-agent
844 .RI [ options ]
845 @end ifset
846
847 @mansect description
848 The @command{gpg-connect-agent} is a utility to communicate with a
849 running @command{gpg-agent}.  It is useful to check out the commands
850 gpg-agent provides using the Assuan interface.  It might also be useful
851 for scripting simple applications.  Inputis expected at stdin and out
852 put gets printed to stdout.
853
854 It is very similar to running @command{gpg-agent} in server mode; but
855 here we connect to a running instance.
856
857 @menu
858 * Invoking gpg-connect-agent::       List of all options.
859 * Controlling gpg-connect-agent::    Control commands.
860 @end menu
861
862 @manpause
863 @node Invoking gpg-connect-agent
864 @subsection List of all options.
865
866 @noindent
867 @command{gpg-connect-agent} is invoked this way:
868
869 @example
870 gpg-connect-agent [options]
871 @end example
872 @mancont
873
874 @noindent
875 The following options may be used:
876
877 @table @gnupgtabopt
878 @item -v
879 @itemx --verbose
880 @opindex verbose
881 Output additional information while running.  
882
883 @item -q
884 @item --quiet
885 @opindex q
886 @opindex quiet
887 Try to be as quiet as possible.
888
889 @include opt-homedir.texi
890
891 @item -S
892 @itemx --raw-socket @var{name}
893 @opindex S        
894 @opindex raw-socket
895 Connect to socket @var{name} assuming this is an Assuan style server.
896 Do not run any special initializations or environment checks.  This may
897 be used to directly connect to any Assuan style socket server.
898
899 @item -E
900 @itemx --exec
901 @opindex exec
902 Take the rest of the command line as a program and it's arguments and
903 execute it as an assuan server. Here is how you would run @command{gpgsm}:
904 @smallexample
905  gpg-connect-agent --exec gpgsm --server
906 @end smallexample
907
908
909 @item --no-ext-connect
910 @opindex no-ext-connect
911 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
912 connects to the assuan server in extended mode to allow descriptor
913 passing.  This option makes it use the old mode.
914
915 @end table
916
917 @mansect control commands
918 @node Controlling gpg-connect-agent
919 @subsection Control commands.
920
921 While reading Assuan commands, gpg-agent also allows a few special
922 commands to control its operation.  These control commands all start
923 with a slash (@code{/}).
924
925
926 @table @code
927
928 @item /echo @var{args}
929 Just print @var{args}.
930
931 @item /definqfile @var{name} @var{file}
932
933 Use content of @var{file} for inquiries with @var{name}.
934 @var{name} may be an asterisk (@code{*} to match any inquiry.
935
936 @item /definqprog @var{name} @var{prog}
937 Run @var{prog} for inquiries matching @var{name} and pass the
938 entire line to it as command line arguments
939
940 @item /showdef
941 Print all definitions
942
943 @item /cleardef
944 Delete all definitions
945
946 @item /sendfd @var{file} @var{mode}
947 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
948 mode string) and send the file descriptor to the server.  This is
949 usually followed by a command like @code{INPUT FD} to set the
950 input source for other commands.
951
952 @item /recvfd
953 Not yet implemented.
954
955 @item /help
956 Print a list of available control commands.
957
958 @end table
959
960
961 @ifset isman
962 @mansect see also
963 @command{gpg-agent}(1), 
964 @command{scdaemon}(1)
965 @include see-also-note.texi
966 @end ifset
967
968
969 @c
970 @c   GPGPARSEMAIL
971 @c
972 @node gpgparsemail
973 @section Parse a mail message into an annotated format
974
975 @manpage gpgparsemail.1
976 @ifset manverb
977 .B gpgparsemail
978 \- Parse a mail message into an annotated format
979 @end ifset
980
981 @mansect synopsis
982 @ifset manverb
983 .B  gpgparsemail
984 .RI [ options ]
985 .RI [ file ]
986 @end ifset
987
988 @mansect description
989 The @command{gpgparsemail} is a utility currently only useful for
990 debugging.  Run it with @code{--help} for usage information.
991
992
993
994 @c
995 @c   SYMCRYPTRUN
996 @c
997 @node symcryptrun
998 @section Call a simple symmetric encryption tool.
999 @manpage symcryptrun.1
1000 @ifset manverb
1001 .B symcryptrun
1002 \- Call a simple symmetric encryption tool
1003 @end ifset
1004
1005 @mansect synopsis
1006 @ifset manverb
1007 .B  symcryptrun
1008 .B \-\-class
1009 .I class
1010 .B \-\-program
1011 .I program
1012 .B \-\-keyfile
1013 .I keyfile
1014 .RB [ --decrypt | --encrypt ]
1015 .RI [ inputfile ]
1016 @end ifset
1017
1018 @mansect description
1019 Sometimes simple encryption tools are already in use for a long time and
1020 there might be a desire to integrate them into the GnuPG framework.  The
1021 protocols and encryption methods might be non-standard or not even
1022 properly documented, so that a full-fledged encryption tool with an
1023 interface like gpg is not doable.  @command{symcryptrun} provides a
1024 solution: It operates by calling the external encryption/decryption
1025 module and provides a passphrase for a key using the standard
1026 @command{pinentry} based mechanism through @command{gpg-agent}.
1027
1028 Note, that @command{symcryptrun} is only available if GnuPG has been
1029 configured with @samp{--enable-symcryptrun} at build time.
1030
1031 @menu
1032 * Invoking symcryptrun::   List of all commands and options.
1033 @end menu
1034
1035 @manpause
1036 @node Invoking symcryptrun
1037 @subsection List of all commands and options.
1038
1039 @noindent
1040 @command{symcryptrun} is invoked this way:
1041
1042 @example
1043 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1044    [--decrypt | --encrypt] [inputfile]
1045 @end example
1046 @mancont
1047
1048 For encryption, the plain text must be provided on STDIN or as the
1049 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1050 For decryption vice versa.
1051
1052 @var{CLASS} describes the calling conventions of the external tool.
1053 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1054 the full filename of that external tool.
1055  
1056 For the class @samp{confucius} the option @option{--keyfile} is
1057 required; @var{keyfile} is the name of a file containing the secret key,
1058 which may be protected by a passphrase.  For detailed calling
1059 conventions, see the source code.
1060  
1061 @noindent
1062 Note, that @command{gpg-agent} must be running before starting
1063 @command{symcryptrun}.
1064
1065 @noindent
1066 The following additional options may be used:
1067
1068 @table @gnupgtabopt
1069 @item -v
1070 @itemx --verbose
1071 @opindex verbose
1072 Output additional information while running.  
1073
1074 @item -q
1075 @item --quiet
1076 @opindex q
1077 @opindex quiet
1078 Try to be as quiet as possible.
1079
1080 @include opt-homedir.texi
1081
1082
1083 @item --log-file @var{file}
1084 @opindex log-file
1085 Append all logging output to @var{file}.  Default is to write logging
1086 informaton to STDERR.
1087
1088 @end table
1089
1090 @noindent
1091 The possible exit status codes of @command{symcryptrun} are:
1092
1093 @table @code
1094 @item 0 
1095         Success.
1096 @item 1 
1097         Some error occured.
1098 @item 2 
1099         No valid passphrase was provided.
1100 @item 3 
1101         The operation was canceled by the user.
1102
1103 @end table
1104
1105 @mansect see also
1106 @command{gpg}(1), 
1107 @command{gpgsm}(1), 
1108 @command{gpg-agent}(1), 
1109 @include see-also-note.texi
1110