Include dirmngr manual
[gnupg.git] / doc / tools.texi
1 @c Copyright (C) 2004, 2008 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 * dirmngr-client::        How to use the Dirmngr client tool.
20 * gpgparsemail::          Parse a mail message into an annotated format
21 * symcryptrun::           Call a simple symmetric encryption tool.
22 * gpg-zip::               Encrypt or sign files into an archive.
23 @end menu
24
25 @c
26 @c  WATCHGNUPG
27 @c
28 @manpage watchgnupg.1
29 @node watchgnupg
30 @section Read logs from a socket
31 @ifset manverb
32 .B watchgnupg
33 \- Read and print logs from a socket
34 @end ifset
35
36 @mansect synopsis
37 @ifset manverb
38 .B  watchgnupg
39 .RB [ \-\-force ]
40 .RB [ \-\-verbose ]
41 .I socketname
42 @end ifset
43
44 @mansect description
45 Most of the main utilities are able to write their log files to a
46 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
47 listener for such a socket.  It ameliorates the output with a time
48 stamp and makes sure that long lines are not interspersed with log
49 output from other utilities.
50
51 @noindent
52 @command{watchgnupg} is commonly invoked as
53
54 @example
55 watchgnupg --force ~/.gnupg/S.log
56 @end example
57 @manpause
58
59 @noindent
60 This starts it on the current terminal for listening on the socket
61 @file{~/.gnupg/S.log}.  
62
63 @mansect options
64 @noindent
65 @command{watchgnupg} understands these options:
66
67 @table @gnupgtabopt
68
69 @item --force 
70 @opindex force
71 Delete an already existing socket file.
72
73 @item --verbose
74 @opindex verbose
75 Enable extra informational output.
76
77 @item --version
78 @opindex version
79 Print version of the program and exit.
80
81 @item --help
82 @opindex help
83 Display a brief help page and exit.
84
85 @end table
86
87 @mansect see also
88 @ifset isman
89 @command{gpg}(1), 
90 @command{gpgsm}(1), 
91 @command{gpg-agent}(1), 
92 @command{scdaemon}(1)
93 @end ifset
94 @include see-also-note.texi
95
96
97 @c
98 @c  GPGV
99 @c
100 @include gpgv.texi
101
102
103 @c
104 @c    ADDGNUPGHOME
105 @c
106 @manpage addgnupghome.8
107 @node addgnupghome
108 @section Create .gnupg home directories.
109 @ifset manverb
110 .B addgnupghome 
111 \- Create .gnupg home directories
112 @end ifset
113
114 @mansect synopsis
115 @ifset manverb
116 .B  addgnupghome
117 .I account_1
118 .IR account_2 ... account_n
119 @end ifset
120
121 @mansect description
122 If GnuPG is installed on a system with existing user accounts, it is
123 sometimes required to populate the GnuPG home directory with existing
124 files.  Especially a @file{trustlist.txt} and a keybox with some
125 initial certificates are often desired.  This scripts help to do this
126 by copying all files from @file{/etc/skel/.gnupg} to the home
127 directories of the accounts given on the command line.  It takes care
128 not to overwrite existing GnuPG home directories.
129
130 @noindent
131 @command{addgnupghome} is invoked by root as:
132
133 @example
134 addgnupghome account1 account2 ... accountn
135 @end example
136
137
138 @c
139 @c   GPGCONF
140 @c
141 @manpage gpgconf.1
142 @node gpgconf
143 @section Modify .gnupg home directories.
144 @ifset manverb
145 .B gpgconf
146 \- Modify .gnupg home directories
147 @end ifset
148
149 @mansect synopsis
150 @ifset manverb
151 .B gpgconf
152 .RI [ options ]
153 .B \-\-list-components
154 .br
155 .B gpgconf
156 .RI [ options ]
157 .B \-\-list-options 
158 .I component
159 .br
160 .B gpgconf
161 .RI [ options ]
162 .B \-\-change-options
163 .I component
164 @end ifset
165
166
167 @mansect description
168 The @command{gpgconf} is a utility to automatically and reasonable
169 safely query and modify configuration files in the @file{.gnupg} home
170 directory.  It is designed not to be invoked manually by the user, but
171 automatically by graphical user interfaces (GUI).@footnote{Please note
172 that currently no locking is done, so concurrent access should be
173 avoided.  There are some precautions to avoid corruption with
174 concurrent usage, but results may be inconsistent and some changes may
175 get lost.  The stateless design makes it difficult to provide more
176 guarantees.}
177
178 @command{gpgconf} provides access to the configuration of one or more
179 components of the GnuPG system.  These components correspond more or
180 less to the programs that exist in the GnuPG framework, like GnuPG,
181 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
182 relationship.  Not all configuration options are available through
183 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
184 method to access the most important configuration options that can
185 feasibly be controlled via such a mechanism.
186
187 @command{gpgconf} can be used to gather and change the options
188 available in each component, and can also provide their default
189 values.  @command{gpgconf} will give detailed type information that
190 can be used to restrict the user's input without making an attempt to
191 commit the changes.
192
193 @command{gpgconf} provides the backend of a configuration editor.  The
194 configuration editor would usually be a graphical user interface
195 program, that allows to display the current options, their default
196 values, and allows the user to make changes to the options.  These
197 changes can then be made active with @command{gpgconf} again.  Such a
198 program that uses @command{gpgconf} in this way will be called GUI
199 throughout this section.
200
201 @menu
202 * Invoking gpgconf::       List of all commands and options.
203 * Format conventions::     Formatting conventions relevant for all commands.
204 * Listing components::     List all gpgconf components.
205 * Checking programs::      Check all programs know to gpgconf.
206 * Listing options::        List all options of a component.
207 * Changing options::       Changing options of a component.
208 * Listing global options:: List all global options.
209 * Files used by gpgconf::  What files are used by gpgconf.
210 @end menu
211
212 @manpause
213 @node Invoking gpgconf
214 @subsection Invoking gpgconf
215
216 @mansect commands
217 One of the following commands must be given:
218
219 @table @gnupgtabopt
220
221 @item --list-components
222 List all components.  This is the default command used if none is
223 specified.
224
225 @item --check-programs
226 List all available backend programs and test whether they are runnable.
227
228 @item --list-options @var{component}
229 List all options of the component @var{component}.
230
231 @item --change-options @var{component}
232 Change the options of the component @var{component}.
233
234 @item --check-options @var{component}
235 Check the options for the component @var{component}.
236
237 @item --apply-defaults
238 Update all configuration files with values taken from the global
239 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
240
241 @item --list-dirs
242 Lists the directories used by @command{gpgconf}.  One directory is
243 listed per line, and each line consists of a colon-separated list where
244 the first field names the directory type (for example @code{sysconfdir})
245 and the second field contains the percent-escaped directory.  Although
246 they are not directories, the socket file names used by
247 @command{gpg-agent} and @command{dirmngr} are printed as well.  Note
248 that the socket file names and the @code{homedir} lines are the default
249 names and they may be overridden by command line switches.
250
251 @item --list-config [@var{filename}]
252 List the global configuration file in a colon separated format.  If
253 @var{filename} is given, check that file instead.
254
255 @item --check-config [@var{filename}]
256 Run a syntax check on the global configuration file.  If @var{filename}
257 is given, check that file instead.
258
259 @end table
260
261
262 @mansect options
263
264 The following options may be used:
265
266 @table @gnupgtabopt
267 @c FIXME: Not yet supported.
268 @c @item -o @var{file}
269 @c @itemx --output @var{file}
270 @c Use @var{file} as output file.
271
272 @item -v
273 @itemx --verbose
274 Outputs additional information while running.  Specifically, this
275 extends numerical field values by human-readable descriptions.
276
277 @item -n
278 @itemx --dry-run
279 Do not actually change anything.  This is currently only implemented
280 for @code{--change-options} and can be used for testing purposes.
281
282 @item -r
283 @itemx --runtime
284 Only used together with @code{--change-options}.  If one of the
285 modified options can be changed in a running daemon process, signal
286 the running daemon to ask it to reparse its configuration file after
287 changing.
288
289 This means that the changes will take effect at run-time, as far as
290 this is possible.  Otherwise, they will take effect at the next start
291 of the respective backend programs.
292 @manpause
293 @end table
294
295
296 @node Format conventions
297 @subsection Format conventions
298
299 Some lines in the output of @command{gpgconf} contain a list of
300 colon-separated fields.  The following conventions apply:
301
302 @itemize @bullet
303 @item
304 The GUI program is required to strip off trailing newline and/or
305 carriage return characters from the output.
306
307 @item
308 @command{gpgconf} will never leave out fields.  If a certain version
309 provides a certain field, this field will always be present in all
310 @command{gpgconf} versions from that time on.
311
312 @item
313 Future versions of @command{gpgconf} might append fields to the list.
314 New fields will always be separated from the previously last field by
315 a colon separator.  The GUI should be prepared to parse the last field
316 it knows about up until a colon or end of line.
317
318 @item
319 Not all fields are defined under all conditions.  You are required to
320 ignore the content of undefined fields.
321 @end itemize
322
323 There are several standard types for the content of a field:
324
325 @table @asis
326 @item verbatim
327 Some fields contain strings that are not escaped in any way.  Such
328 fields are described to be used @emph{verbatim}.  These fields will
329 never contain a colon character (for obvious reasons).  No de-escaping
330 or other formatting is required to use the field content.  This is for
331 easy parsing of the output, when it is known that the content can
332 never contain any special characters.
333
334 @item percent-escaped
335 Some fields contain strings that are described to be
336 @emph{percent-escaped}.  Such strings need to be de-escaped before
337 their content can be presented to the user.  A percent-escaped string
338 is de-escaped by replacing all occurrences of @code{%XY} by the byte
339 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
340 from the set @code{0-9a-f}.
341
342 @item localised
343 Some fields contain strings that are described to be @emph{localised}.
344 Such strings are translated to the active language and formatted in
345 the active character set.
346
347 @item @w{unsigned number}
348 Some fields contain an @emph{unsigned number}.  This number will
349 always fit into a 32-bit unsigned integer variable.  The number may be
350 followed by a space, followed by a human readable description of that
351 value (if the verbose option is used).  You should ignore everything
352 in the field that follows the number.
353
354 @item @w{signed number}
355 Some fields contain a @emph{signed number}.  This number will always
356 fit into a 32-bit signed integer variable.  The number may be followed
357 by a space, followed by a human readable description of that value (if
358 the verbose option is used).  You should ignore everything in the
359 field that follows the number.
360
361 @item @w{boolean value}
362 Some fields contain a @emph{boolean value}.  This is a number with
363 either the value 0 or 1.  The number may be followed by a space,
364 followed by a human readable description of that value (if the verbose
365 option is used).  You should ignore everything in the field that follows
366 the number; checking just the first character is sufficient in this
367 case.
368
369 @item option
370 Some fields contain an @emph{option} argument.  The format of an
371 option argument depends on the type of the option and on some flags:
372
373 @table @asis
374 @item no argument
375 The simplest case is that the option does not take an argument at all
376 (@var{type} @code{0}).  Then the option argument is an unsigned number
377 that specifies how often the option occurs.  If the @code{list} flag
378 is not set, then the only valid number is @code{1}.  Options that do
379 not take an argument never have the @code{default} or @code{optional
380 arg} flag set.
381
382 @item number
383 If the option takes a number argument (@var{alt-type} is @code{2} or
384 @code{3}), and it can only occur once (@code{list} flag is not set),
385 then the option argument is either empty (only allowed if the argument
386 is optional), or it is a number.  A number is a string that begins
387 with an optional minus character, followed by one or more digits.  The
388 number must fit into an integer variable (unsigned or signed,
389 depending on @var{alt-type}).
390
391 @item number list
392 If the option takes a number argument and it can occur more than once,
393 then the option argument is either empty, or it is a comma-separated
394 list of numbers as described above.
395
396 @item string
397 If the option takes a string argument (@var{alt-type} is 1), and it
398 can only occur once (@code{list} flag is not set) then the option
399 argument is either empty (only allowed if the argument is optional),
400 or it starts with a double quote character (@code{"}) followed by a
401 percent-escaped string that is the argument value.  Note that there is
402 only a leading double quote character, no trailing one.  The double
403 quote character is only needed to be able to differentiate between no
404 value and the empty string as value.
405
406 @item string list
407 If the option takes a number argument and it can occur more than once,
408 then the option argument is either empty, or it is a comma-separated
409 list of string arguments as described above.
410 @end table
411 @end table
412
413 The active language and character set are currently determined from
414 the locale environment of the @command{gpgconf} program.
415
416 @c FIXME: Document the active language and active character set.  Allow
417 @c to change it via the command line?
418
419
420 @mansect usage
421 @node Listing components
422 @subsection Listing components
423
424 The command @code{--list-components} will list all components that can
425 be configured with @command{gpgconf}.  Usually, one component will
426 correspond to one GnuPG-related program and contain the options of
427 that programs configuration file that can be modified using
428 @command{gpgconf}.  However, this is not necessarily the case.  A
429 component might also be a group of selected options from several
430 programs, or contain entirely virtual options that have a special
431 effect rather than changing exactly one option in one configuration
432 file.
433
434 A component is a set of configuration options that semantically belong
435 together.  Furthermore, several changes to a component can be made in
436 an atomic way with a single operation.  The GUI could for example
437 provide a menu with one entry for each component, or a window with one
438 tabulator sheet per component.
439
440 The command argument @code{--list-components} lists all available
441 components, one per line.  The format of each line is:
442
443 @code{@var{name}:@var{description}:@var{pgmname}:}
444
445 @table @var
446 @item name
447 This field contains a name tag of the component.  The name tag is used
448 to specify the component in all communication with @command{gpgconf}.
449 The name tag is to be used @emph{verbatim}.  It is thus not in any
450 escaped format.
451
452 @item description
453 The @emph{string} in this field contains a human-readable description
454 of the component.  It can be displayed to the user of the GUI for
455 informational purposes.  It is @emph{percent-escaped} and
456 @emph{localized}.
457
458 @item pgmname
459 The @emph{string} in this field contains the absolute name of the
460 program's file.  It can be used to unambiguously invoke that program.
461 It is @emph{percent-escaped}.
462 @end table
463
464 Example:
465 @example
466 $ gpgconf --list-components
467 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
468 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
469 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
470 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
471 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
472 @end example
473
474
475
476 @node Checking programs
477 @subsection Checking programs
478
479 The command @code{--check-programs} is similar to
480 @code{--list-components} but works on backend programs and not on
481 components.  It runs each program to test whether it is installed and
482 runnable.  This also includes a syntax check of all config file options
483 of the program.
484
485 The command argument @code{--check-programs} lists all available
486 programs, one per line.  The format of each line is:
487
488 @code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
489
490 @table @var
491 @item name
492 This field contains a name tag of the program which is identical to the
493 name of the component.  The name tag is to be used @emph{verbatim}.  It
494 is thus not in any escaped format.  This field may be empty to indicate
495 a continuation of error descriptions for the last name.  The description
496 and pgmname fields are then also empty.
497
498 @item description
499 The @emph{string} in this field contains a human-readable description
500 of the component.  It can be displayed to the user of the GUI for
501 informational purposes.  It is @emph{percent-escaped} and
502 @emph{localized}.
503
504 @item pgmname
505 The @emph{string} in this field contains the absolute name of the
506 program's file.  It can be used to unambiguously invoke that program.
507 It is @emph{percent-escaped}.
508
509 @item avail
510 The @emph{boolean value} in this field indicates whether the program is
511 installed and runnable.
512
513 @item okay
514 The @emph{boolean value} in this field indicates whether the program's
515 config file is syntactically okay.
516
517 @item cfgfile
518 If an error occurred in the configuration file (as indicated by a false
519 value in the field @code{okay}), this field has the name of the failing
520 configuration file.  It is @emph{percent-escaped}.
521
522 @item line
523 If an error occurred in the configuration file, this field has the line
524 number of the failing statement in the configuration file.  
525 It is an @emph{unsigned number}.
526
527 @item error
528 If an error occurred in the configuration file, this field has the error
529 text of the failing statement in the configuration file.  It is
530 @emph{percent-escaped} and @emph{localized}.
531
532 @end table
533
534 @noindent
535 In the following example the @command{dirmngr} is not runnable and the
536 configuration file of @command{scdaemon} is not okay.
537
538 @example
539 $ gpgconf --check-programs
540 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
541 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
542 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
543 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
544 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
545 @end example
546
547 @noindent
548 The command @w{@code{--check-options @var{component}}} will verify the
549 configuration file in the same manner as @code{--check-programs}, but
550 only for the component @var{component}.
551
552
553 @node Listing options
554 @subsection Listing options
555
556 Every component contains one or more options.  Options may be gathered
557 into option groups to allow the GUI to give visual hints to the user
558 about which options are related.
559
560 The command argument @code{@w{--list-options @var{component}}} lists
561 all options (and the groups they belong to) in the component
562 @var{component}, one per line.  @var{component} must be the string in
563 the field @var{name} in the output of the @code{--list-components}
564 command.
565
566 There is one line for each option and each group.  First come all
567 options that are not in any group.  Then comes a line describing a
568 group.  Then come all options that belong into each group.  Then comes
569 the next group and so on.  There does not need to be any group (and in
570 this case the output will stop after the last non-grouped option).
571
572 The format of each line is:
573
574 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
575
576 @table @var
577 @item name
578 This field contains a name tag for the group or option.  The name tag
579 is used to specify the group or option in all communication with
580 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
581 thus not in any escaped format.
582
583 @item flags
584 The flags field contains an @emph{unsigned number}.  Its value is the
585 OR-wise combination of the following flag values:
586
587 @table @code
588 @item group (1)
589 If this flag is set, this is a line describing a group and not an
590 option.
591 @end table
592
593 The following flag values are only defined for options (that is, if
594 the @code{group} flag is not used).
595
596 @table @code
597 @item optional arg (2)
598 If this flag is set, the argument is optional.  This is never set for
599 @var{type} @code{0} (none) options.
600
601 @item list (4)
602 If this flag is set, the option can be given multiple times.
603
604 @item runtime (8)
605 If this flag is set, the option can be changed at runtime.
606
607 @item default (16)
608 If this flag is set, a default value is available.
609
610 @item default desc (32)
611 If this flag is set, a (runtime) default is available.  This and the
612 @code{default} flag are mutually exclusive.
613
614 @item no arg desc (64)
615 If this flag is set, and the @code{optional arg} flag is set, then the
616 option has a special meaning if no argument is given.
617
618 @item no change (128)
619 If this flag is set, gpgconf ignores requests to change the value.  GUI
620 frontends should grey out this option.  Note, that manual changes of the
621 configuration files are still possible.
622 @end table
623
624 @item level
625 This field is defined for options and for groups.  It contains an
626 @emph{unsigned number} that specifies the expert level under which
627 this group or option should be displayed.  The following expert levels
628 are defined for options (they have analogous meaning for groups):
629
630 @table @code
631 @item basic (0)
632 This option should always be offered to the user.
633
634 @item advanced (1)
635 This option may be offered to advanced users.
636
637 @item expert (2)
638 This option should only be offered to expert users.
639
640 @item invisible (3)
641 This option should normally never be displayed, not even to expert
642 users.
643
644 @item internal (4)
645 This option is for internal use only.  Ignore it.
646 @end table
647
648 The level of a group will always be the lowest level of all options it
649 contains.
650
651 @item description
652 This field is defined for options and groups.  The @emph{string} in
653 this field contains a human-readable description of the option or
654 group.  It can be displayed to the user of the GUI for informational
655 purposes.  It is @emph{percent-escaped} and @emph{localized}.
656
657 @item type
658 This field is only defined for options.  It contains an @emph{unsigned
659 number} that specifies the type of the option's argument, if any.  The
660 following types are defined:
661
662 Basic types:
663
664 @table @code
665 @item none (0)
666 No argument allowed.
667
668 @item string (1)
669 An @emph{unformatted string}.
670
671 @item int32 (2)
672 A @emph{signed number}.
673
674 @item uint32 (3)
675 An @emph{unsigned number}.
676 @end table
677
678 Complex types:
679
680 @table @code
681 @item pathname (32)
682 A @emph{string} that describes the pathname of a file.  The file does
683 not necessarily need to exist.
684
685 @item ldap server (33)
686 A @emph{string} that describes an LDAP server in the format:
687
688 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
689
690 @item key fingerprint (34)
691 A @emph{string} with a 40 digit fingerprint specifying a certificate.
692
693 @item pub key (35)
694 A @emph{string} that describes a certificate by user ID, key ID or
695 fingerprint.
696
697 @item sec key (36)
698 A @emph{string} that describes a certificate with a key by user ID,
699 key ID or fingerprint.
700
701 @item alias list (37)
702 A @emph{string} that describes an alias list, like the one used with
703 gpg's group option.  The list consists of a key, an equal sign and space
704 separated values.
705 @end table
706
707 More types will be added in the future.  Please see the @var{alt-type}
708 field for information on how to cope with unknown types.
709
710 @item alt-type
711 This field is identical to @var{type}, except that only the types
712 @code{0} to @code{31} are allowed.  The GUI is expected to present the
713 user the option in the format specified by @var{type}.  But if the
714 argument type @var{type} is not supported by the GUI, it can still
715 display the option in the more generic basic type @var{alt-type}.  The
716 GUI must support all the defined basic types to be able to display all
717 options.  More basic types may be added in future versions.  If the
718 GUI encounters a basic type it doesn't support, it should report an
719 error and abort the operation.
720
721 @item argname
722 This field is only defined for options with an argument type
723 @var{type} that is not @code{0}.  In this case it may contain a
724 @emph{percent-escaped} and @emph{localised string} that gives a short
725 name for the argument.  The field may also be empty, though, in which
726 case a short name is not known.
727
728 @item default
729 This field is defined only for options for which the @code{default} or
730 @code{default desc} flag is set.  If the @code{default} flag is set,
731 its format is that of an @emph{option argument} (@xref{Format
732 conventions}, for details).  If the default value is empty, then no
733 default is known.  Otherwise, the value specifies the default value
734 for this option.  If the @code{default desc} flag is set, the field is
735 either empty or contains a description of the effect if the option is
736 not given.
737
738 @item argdef
739 This field is defined only for options for which the @code{optional
740 arg} flag is set.  If the @code{no arg desc} flag is not set, its
741 format is that of an @emph{option argument} (@xref{Format
742 conventions}, for details).  If the default value is empty, then no
743 default is known.  Otherwise, the value specifies the default argument
744 for this option.  If the @code{no arg desc} flag is set, the field is
745 either empty or contains a description of the effect of this option if
746 no argument is given.
747
748 @item value
749 This field is defined only for options.  Its format is that of an
750 @emph{option argument}.  If it is empty, then the option is not
751 explicitly set in the current configuration, and the default applies
752 (if any).  Otherwise, it contains the current value of the option.
753 Note that this field is also meaningful if the option itself does not
754 take a real argument (in this case, it contains the number of times
755 the option appears).
756 @end table
757
758
759 @node Changing options
760 @subsection Changing options
761
762 The command @w{@code{--change-options @var{component}}} will attempt
763 to change the options of the component @var{component} to the
764 specified values.  @var{component} must be the string in the field
765 @var{name} in the output of the @code{--list-components} command.  You
766 have to provide the options that shall be changed in the following
767 format on standard input:
768
769 @code{@var{name}:@var{flags}:@var{new-value}}
770
771 @table @var
772 @item name
773 This is the name of the option to change.  @var{name} must be the
774 string in the field @var{name} in the output of the
775 @code{--list-options} command.
776
777 @item flags
778 The flags field contains an @emph{unsigned number}.  Its value is the
779 OR-wise combination of the following flag values:
780
781 @table @code
782 @item default (16)
783 If this flag is set, the option is deleted and the default value is
784 used instead (if applicable).
785 @end table
786
787 @item new-value
788 The new value for the option.  This field is only defined if the
789 @code{default} flag is not set.  The format is that of an @emph{option
790 argument}.  If it is empty (or the field is omitted), the default
791 argument is used (only allowed if the argument is optional for this
792 option).  Otherwise, the option will be set to the specified value.
793 @end table
794
795 @noindent
796 The output of the command is the same as that of
797 @code{--check-options} for the modified configuration file.
798
799 Examples:
800
801 To set the force option, which is of basic type @code{none (0)}:
802
803 @example
804 $ echo 'force:0:1' | gpgconf --change-options dirmngr
805 @end example
806
807 To delete the force option:
808
809 @example
810 $ echo 'force:16:' | gpgconf --change-options dirmngr
811 @end example
812
813 The @code{--runtime} option can influence when the changes take
814 effect.
815
816
817 @node Listing global options
818 @subsection Listing global options
819
820 Sometimes it is useful for applications to look at the global options
821 file @file{gpgconf.conf}. 
822 The colon separated listing format is record oriented and uses the first
823 field to identify the record type:
824
825 @table @code
826 @item k
827 This describes a key record to start the definition of a new ruleset for
828 a user/group.  The format of a key record is:
829
830   @code{k:@var{user}:@var{group}:}
831
832 @table @var
833 @item user
834 This is the user field of the key.  It is percent escaped.  See the
835 definition of the gpgconf.conf format for details.
836
837 @item group
838 This is the group field of the key.  It is percent escaped.
839 @end table
840
841 @item r
842 This describes a rule record. All rule records up to the next key record
843 make up a rule set for that key.  The format of a rule record is:
844
845   @code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}
846
847 @table @var
848 @item component
849 This is the component part of a rule.  It is a plain string.
850
851 @item option
852 This is the option part of a rule.  It is a plain string.
853
854 @item flag
855 This is the flags part of a rule.  There may be only one flag per rule
856 but by using the same component and option, several flags may be
857 assigned to an option.  It is a plain string.
858
859 @item value
860 This is the optional value for the option.  It is a percent escaped
861 string with a single quotation mark to indicate a string.  The quotation
862 mark is only required to distinguish between no value specified and an
863 empty string.
864 @end table
865
866 @end table
867
868 @noindent
869 Unknown record types should be ignored.  Note that there is intentionally
870 no feature to change the global option file through @command{gpgconf}.
871
872
873
874 @mansect files
875 @node Files used by gpgconf
876 @subsection Files used by gpgconf
877
878 @table @file
879
880 @item /etc/gnupg/gpgconf.conf
881 @cindex gpgconf.conf
882   If this file exists, it is processed as a global configuration file.
883   A commented example can be found in the @file{examples} directory of
884   the distribution.
885 @end table
886
887
888 @mansect see also
889 @ifset isman
890 @command{gpg}(1), 
891 @command{gpgsm}(1), 
892 @command{gpg-agent}(1), 
893 @command{scdaemon}(1),
894 @command{dirmngr}(1)
895 @end ifset
896 @include see-also-note.texi
897
898
899
900 @c
901 @c    APPLYGNUPGDEFAULTS
902 @c
903 @manpage applygnupgdefaults.8
904 @node applygnupgdefaults
905 @section Run gpgconf for all users.
906 @ifset manverb
907 .B applygnupgdefaults
908 \- Run gpgconf --apply-defaults for all users.
909 @end ifset
910
911 @mansect synopsis
912 @ifset manverb
913 .B  applygnupgdefaults
914 @end ifset
915
916 @mansect description
917 This script is a wrapper around @command{gpgconf} to run it with the
918 command @code{--apply-defaults} for all real users with an existing
919 GnuPG home directory.  Admins might want to use this script to update he
920 GnuPG configuration files for all users after
921 @file{/etc/gnupg/gpgconf.conf} has been changed.  This allows to enforce
922 certain policies for all users.  Note, that this is not a bulletproof of
923 forcing a user to use certain options.  A user may always directly edit
924 the configuration files and bypass gpgconf.
925
926 @noindent
927 @command{applygnupgdefaults} is invoked by root as:
928
929 @example
930 applygnupgdefaults
931 @end example
932
933
934 @c
935 @c    GPGSM-GENCERT.SH
936 @c
937 @node gpgsm-gencert.sh
938 @section Generate an X.509 certificate request
939 @manpage gpgsm-gencert.sh.1
940 @ifset manverb
941 .B gpgsm-gencert.sh
942 \- Generate an X.509 certificate request
943 @end ifset 
944
945 @mansect synopsis
946 @ifset manverb
947 .B  gpgsm-gencert.sh
948 @end ifset
949
950 @mansect description
951 This is a simple tool to interactively generate a certificate request
952 which will be printed to stdout.
953
954 @manpause
955 @noindent
956 @command{gpgsm-gencert.sh} is invoked as:
957
958 @samp{gpgsm-cencert.sh}
959
960 @mansect see also
961 @ifset isman
962 @command{gpgsm}(1), 
963 @command{gpg-agent}(1), 
964 @command{scdaemon}(1)
965 @end ifset
966 @include see-also-note.texi
967
968
969
970 @c
971 @c   GPG-PRESET-PASSPHRASE
972 @c
973 @node gpg-preset-passphrase
974 @section Put a passphrase into the cache.
975 @manpage gpg-preset-passphrase.1
976 @ifset manverb
977 .B gpg-preset-passphrase
978 \- Put a passphrase into gpg-agent's cache
979 @end ifset
980
981 @mansect synopsis
982 @ifset manverb
983 .B  gpg-preset-passphrase
984 .RI [ options ]
985 .RI [ command ]
986 .I cache-id
987 @end ifset
988
989 @mansect description
990 The @command{gpg-preset-passphrase} is a utility to seed the internal
991 cache of a running @command{gpg-agent} with passphrases.  It is mainly
992 useful for unattended machines, where the usual @command{pinentry} tool
993 may not be used and the passphrases for the to be used keys are given at
994 machine startup.
995
996 Passphrases set with this utility don't expire unless the
997 @option{--forget} option is used to explicitly clear them from the cache
998 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
999 SIGHUP to it).  It is necessary to allow this passphrase presetting by
1000 starting @command{gpg-agent} with the
1001 @option{--allow-preset-passphrase}.
1002
1003 @menu
1004 * Invoking gpg-preset-passphrase::   List of all commands and options.
1005 @end menu
1006
1007 @manpause
1008 @node Invoking gpg-preset-passphrase
1009 @subsection List of all commands and options.
1010 @mancont
1011
1012 @noindent
1013 @command{gpg-preset-passphrase} is invoked this way:
1014
1015 @example
1016 gpg-preset-passphrase [options] [command] @var{cacheid}
1017 @end example
1018
1019 @var{cacheid} is either a 40 character keygrip of hexadecimal
1020 characters identifying the key for which the passphrase should be set
1021 or cleared.  The keygrip is listed along with the key when running the
1022 command: @code{gpgsm --dump-secret-keys}.  Alternatively an arbitrary
1023 string may be used to identify a passphrase; it is suggested that such
1024 a string is prefixed with the name of the application (e.g
1025 @code{foo:12346}).
1026
1027 @noindent
1028 One of the following command options must be given:
1029
1030 @table @gnupgtabopt
1031 @item --preset
1032 @opindex preset
1033 Preset a passphrase. This is what you usually will
1034 use. @command{gpg-preset-passphrase} will then read the passphrase from
1035 @code{stdin}.
1036
1037 @item --forget
1038 @opindex forget
1039 Flush the passphrase for the given cache ID from the cache.
1040
1041 @end table
1042
1043 @noindent
1044 The following additional options may be used:
1045
1046 @table @gnupgtabopt
1047 @item -v
1048 @itemx --verbose
1049 @opindex verbose
1050 Output additional information while running.  
1051
1052 @item -P @var{string}
1053 @itemx --passphrase @var{string}
1054 @opindex passphrase
1055 Instead of reading the passphrase from @code{stdin}, use the supplied
1056 @var{string} as passphrase.  Note that this makes the passphrase visible
1057 for other users.
1058 @end table
1059
1060 @mansect see also
1061 @ifset isman
1062 @command{gpg}(1), 
1063 @command{gpgsm}(1), 
1064 @command{gpg-agent}(1), 
1065 @command{scdaemon}(1)
1066 @end ifset
1067 @include see-also-note.texi
1068
1069
1070
1071
1072 @c
1073 @c   GPG-CONNECT-AGENT
1074 @c
1075 @node gpg-connect-agent
1076 @section Communicate with a running agent.
1077 @manpage gpg-connect-agent.1
1078 @ifset manverb
1079 .B gpg-connect-agent
1080 \- Communicate with a running agent
1081 @end ifset
1082
1083 @mansect synopsis
1084 @ifset manverb
1085 .B  gpg-connect-agent
1086 .RI [ options ] [commands]
1087 @end ifset
1088
1089 @mansect description
1090 The @command{gpg-connect-agent} is a utility to communicate with a
1091 running @command{gpg-agent}.  It is useful to check out the commands
1092 gpg-agent provides using the Assuan interface.  It might also be useful
1093 for scripting simple applications.  Input is expected at stdin and out
1094 put gets printed to stdout.
1095
1096 It is very similar to running @command{gpg-agent} in server mode; but
1097 here we connect to a running instance.
1098
1099 @menu
1100 * Invoking gpg-connect-agent::       List of all options.
1101 * Controlling gpg-connect-agent::    Control commands.
1102 @end menu
1103
1104 @manpause
1105 @node Invoking gpg-connect-agent
1106 @subsection List of all options.
1107
1108 @noindent
1109 @command{gpg-connect-agent} is invoked this way:
1110
1111 @example
1112 gpg-connect-agent [options] [commands]
1113 @end example
1114 @mancont
1115
1116 @noindent
1117 The following options may be used:
1118
1119 @table @gnupgtabopt
1120 @item -v
1121 @itemx --verbose
1122 @opindex verbose
1123 Output additional information while running.  
1124
1125 @item -q
1126 @item --quiet
1127 @opindex q
1128 @opindex quiet
1129 Try to be as quiet as possible.
1130
1131 @include opt-homedir.texi
1132
1133 @item -S
1134 @itemx --raw-socket @var{name}
1135 @opindex S        
1136 @opindex raw-socket
1137 Connect to socket @var{name} assuming this is an Assuan style server.
1138 Do not run any special initializations or environment checks.  This may
1139 be used to directly connect to any Assuan style socket server.
1140
1141 @item -E
1142 @itemx --exec
1143 @opindex exec
1144 Take the rest of the command line as a program and it's arguments and
1145 execute it as an assuan server. Here is how you would run @command{gpgsm}:
1146 @smallexample
1147  gpg-connect-agent --exec gpgsm --server
1148 @end smallexample
1149 Note that you may not use options on the command line in this case.
1150
1151 @item --no-ext-connect
1152 @opindex no-ext-connect
1153 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
1154 connects to the assuan server in extended mode to allow descriptor
1155 passing.  This option makes it use the old mode.
1156
1157 @item --run @var{file}
1158 @opindex run 
1159 Run the commands from @var{file} at startup and then continue with the
1160 regular input method.  Note, that commands given on the command line are
1161 executed after this file.
1162
1163 @item -s
1164 @itemx --subst
1165 @opindex subst
1166 Run the command @code{/subst} at startup.
1167
1168 @item --hex
1169 @opindex hex
1170 Print data lines in a hex format and the ASCII representation of
1171 non-control characters.
1172
1173 @item --decode
1174 @opindex decode
1175 Decode data lines.  That is to remove percent escapes but make sure that
1176 a new line always starts with a D and a space.
1177
1178 @end table
1179
1180 @mansect control commands
1181 @node Controlling gpg-connect-agent
1182 @subsection Control commands.
1183
1184 While reading Assuan commands, gpg-agent also allows a few special
1185 commands to control its operation.  These control commands all start
1186 with a slash (@code{/}).
1187
1188 @table @code
1189
1190 @item /echo @var{args}
1191 Just print @var{args}.
1192
1193 @item /let @var{name} @var{value}
1194 Set the variable @var{name} to @var{value}.  Variables are only
1195 substituted on the input if the @command{/subst} has been used.
1196 Variables are referenced by prefixing the name with a dollar sign and
1197 optionally include the name in curly braces.  The rules for a valid name
1198 are identically to those of the standard bourne shell.  This is not yet
1199 enforced but may be in the future.  When used with curly braces no
1200 leading or trailing white space is allowed. 
1201
1202 If a variable is not found, it is searched in the environment and if
1203 found copied to the table of variables.
1204
1205 Variable functions are available: The name of the function must be
1206 followed by at least one space and the at least one argument.  The
1207 following functions are available:
1208
1209 @table @code
1210 @item get
1211 Return a value described by the argument.  Available arguments are:
1212
1213 @table @code    
1214 @item cwd
1215 The current working directory.
1216 @item homedir
1217 The gnupg homedir.
1218 @item sysconfdir
1219 GnuPG's system configuration directory.
1220 @item bindir
1221 GnuPG's binary directory.
1222 @item libdir
1223 GnuPG's library directory.
1224 @item libexecdir
1225 GnuPG's library directory for executable files.
1226 @item datadir
1227 GnuPG's data directory.
1228 @item serverpid
1229 The PID of the current server. Command @command{/serverpid} must
1230 have been given to return a useful value.
1231 @end table
1232
1233 @item unescape @var{args}
1234 Remove C-style escapes from @var{args}.  Note that @code{\0} and
1235 @code{\x00} terminate the returned string implicitly.  The string to be
1236 converted are the entire arguments right behind the delimiting space of
1237 the function name.
1238
1239 @item unpercent @var{args}
1240 @itemx unpercent+ @var{args}
1241 Remove percent style escaping from @var{args}.  Note that @code{%00}
1242 terminates the string implicitly.  The string to be converted are the
1243 entire arguments right behind the delimiting space of the function
1244 name. @code{unpercent+} also maps plus signs to a spaces.
1245
1246 @item percent @var{args}
1247 @itemx percent+ @var{args}
1248 Escape the @var{args} using percent style escaping.  Tabs, formfeeds,
1249 linefeeds, carriage returns and colons are escaped. @code{percent+} also
1250 maps spaces to plus signs.
1251
1252 @item errcode @var{arg}
1253 @itemx errsource @var{arg}
1254 @itemx errstring @var{arg}
1255 Assume @var{arg} is an integer and evaluate it using @code{strtol}.  Return
1256 the gpg-error error code, error source or a formatted string with the
1257 error code and error source.
1258
1259
1260 @item +
1261 @itemx -
1262 @itemx *
1263 @itemx /
1264 @itemx %
1265 Evaluate all arguments as long integers using @code{strtol} and apply
1266 this operator.  A division by zero yields an empty string.
1267
1268 @item !
1269 @itemx |
1270 @itemx &
1271 Evaluate all arguments as long integers using @code{strtol} and apply
1272 the logical oeprators NOT, OR or AND.  The NOT operator works on the
1273 last argument only.
1274
1275
1276 @end table
1277
1278
1279 @item /definq @var{name} @var{var}
1280 Use content of the variable @var{var} for inquiries with @var{name}.
1281 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1282
1283
1284 @item /definqfile @var{name} @var{file}
1285 Use content of @var{file} for inquiries with @var{name}.
1286 @var{name} may be an asterisk (@code{*}) to match any inquiry.
1287
1288 @item /definqprog @var{name} @var{prog}
1289 Run @var{prog} for inquiries matching @var{name} and pass the
1290 entire line to it as command line arguments.
1291
1292 @item /datafile @var{name}
1293 Write all data lines from the server to the file @var{name}.  The file
1294 is opened for writing and created if it does not exists.  An existing
1295 file is first truncated to 0.  The data written to the file fully
1296 decoded.  Using a single dash for @var{name} writes to stdout.  The
1297 file is kept open until a new file is set using this command or this
1298 command is used without an argument.
1299
1300 @item /showdef
1301 Print all definitions
1302
1303 @item /cleardef
1304 Delete all definitions
1305
1306 @item /sendfd @var{file} @var{mode}
1307 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1308 mode string) and send the file descriptor to the server.  This is
1309 usually followed by a command like @code{INPUT FD} to set the
1310 input source for other commands.
1311
1312 @item /recvfd
1313 Not yet implemented.
1314
1315 @item /open @var{var} @var{file} [@var{mode}]
1316 Open @var{file} and assign the file descriptor to @var{var}.  Warning:
1317 This command is experimental and might change in future versions.
1318
1319 @item /close @var{fd}
1320 Close the file descriptor @var{fd}.  Warning: This command is
1321 experimental and might change in future versions.
1322
1323 @item /showopen
1324 Show a list of open files.
1325
1326 @item /serverpid
1327 Send the Assuan command @command{GETINFO pid} to the server and store
1328 the returned PID for internal purposes.
1329
1330 @item /sleep
1331 Sleep for a second.
1332
1333 @item /hex
1334 @itemx /nohex
1335 Same as the command line option @option{--hex}.
1336
1337 @item /decode
1338 @itemx /nodecode
1339 Same as the command line option @option{--decode}.
1340
1341 @item /subst
1342 @itemx /nosubst
1343 Enable and disable variable substitution.  It defaults to disabled
1344 unless the command line option @option{--subst} has been used.
1345 If /subst as been enabled once, leading whitespace is removed from
1346 input lines which makes scripts easier to read.
1347
1348 @item /while @var{condition}
1349 @itemx /end
1350 These commands provide a way for executing loops.  All lines between the
1351 @code{while} and the corresponding @code{end} are executed as long as
1352 the evaluation of @var{condition} yields a non-zero value.  The
1353 evaluation is done by passing @var{condition} to the @code{strtol}
1354 function.  Example:
1355
1356 @smallexample
1357   /subst
1358   /let i 3
1359   /while $i
1360     /echo loop couter is $i
1361     /let i $@{- $i 1@}
1362   /end
1363 @end smallexample
1364
1365
1366 @item /run @var{file}
1367 Run commands from @var{file}.
1368
1369 @item /bye
1370 Terminate the connection and the program
1371
1372 @item /help
1373 Print a list of available control commands.
1374
1375 @end table
1376
1377
1378 @ifset isman
1379 @mansect see also
1380 @command{gpg-agent}(1), 
1381 @command{scdaemon}(1)
1382 @include see-also-note.texi
1383 @end ifset
1384
1385 @c
1386 @c   DIRMNGR-CLIENT
1387 @c
1388 @node dirmngr-client
1389 @section The Dirmngr Client Tool
1390
1391 @manpage dirmngr-client.1
1392 @ifset manverb
1393 .B dirmngr-client
1394 \- Tool to access the Dirmngr services
1395 @end ifset
1396
1397 @mansect synopsis
1398 @ifset manverb
1399 .B  dirmngr-client
1400 .RI [ options ]  
1401 .RI [ certfile | pattern ]  
1402 @end ifset
1403
1404 @mansect description
1405 The @command{dirmngr-client} is a simple tool to contact a running
1406 dirmngr and test whether a certificate has been revoked --- either by
1407 being listed in the corresponding CRL or by running the OCSP protocol.
1408 If no dirmngr is running, a new instances will be started but this is
1409 in general not a good idea due to the huge performance overhead.
1410
1411 @noindent
1412 The usual way to run this tool is either:
1413
1414 @example
1415 dirmngr-client @var{acert}
1416 @end example
1417
1418 @noindent
1419 or
1420
1421 @example
1422 dirmngr-client <@var{acert}
1423 @end example
1424
1425 Where @var{acert} is one DER encoded (binary) X.509 certificates to be
1426 tested. 
1427 @ifclear isman
1428 The return value of this command is
1429 @end ifclear
1430
1431 @mansect return value
1432 @ifset isman
1433 @command{dirmngr-client} returns these values:
1434 @end ifset
1435 @table @code
1436
1437 @item 0 
1438 The certificate under question is valid; i.e. there is a valid CRL
1439 available and it is not listed tehre or teh OCSP request returned that
1440 that certificate is valid.
1441
1442 @item 1
1443 The certificate has been revoked
1444
1445 @item 2 (and other values)
1446 There was a problem checking the revocation state of the certificate.
1447 A message to stderr has given more detailed information.  Most likely
1448 this is due to a missing or expired CRL or due to a network problem.
1449
1450 @end table
1451
1452 @mansect options
1453 @noindent
1454 @command{dirmngr-client} may be called with the following options:
1455
1456
1457 @table @gnupgtabopt
1458 @item --version
1459 @opindex version
1460 Print the program version and licensing information.  Note that you cannot
1461 abbreviate this command.
1462
1463 @item --help, -h
1464 @opindex help
1465 Print a usage message summarizing the most useful command-line options.
1466 Note that you cannot abbreviate this command.
1467
1468 @item --quiet, -q
1469 @opindex quiet
1470 Make the output extra brief by suppressing any informational messages.
1471
1472 @item -v
1473 @item --verbose
1474 @opindex v
1475 @opindex verbose
1476 Outputs additional information while running.
1477 You can increase the verbosity by giving several
1478 verbose commands to @sc{dirmngr}, such as @samp{-vv}.
1479
1480 @item --pem
1481 @opindex pem
1482 Assume that the given certificate is in PEM (armored) format.
1483
1484 @item --ocsp
1485 @opindex ocsp
1486 Do the check using the OCSP protocol and ignore any CRLs.
1487
1488 @item --force-default-responder
1489 @opindex force-default-responder
1490 When checking using the OCSP protocl, force the use of the default OCSP
1491 responder.  That is not to use the Reponder as given by the certificate.
1492
1493 @item --ping
1494 @opindex ping
1495 Check whether the dirmngr daemon is up and running.
1496
1497 @item --cache-cert
1498 @opindex cache-cert
1499 Put the given certificate into the cache of a running dirmngr.  This is
1500 mainly useful for debugging.
1501
1502 @item --validate
1503 @opindex validate
1504 Validate the given certificate using dirmngr's internal validation code.
1505 This is mainly useful for debugging.
1506
1507 @item --load-crl
1508 @opindex load-crl
1509 This command expects a list of filenames with DER encoded CRL files.
1510 With the option @option{--url} URLs are expected in place of filenames
1511 and they are loaded directly from the given location.  All CRLs will be
1512 validated and then loaded into dirmngr's cache.
1513
1514 @item --lookup
1515 @opindex lookup
1516 Take the remaining arguments and run a lookup command on each of them.
1517 The results are Base-64 encoded outputs (without header lines).  This
1518 may be used to retrieve certificates from a server. However the output
1519 format is not very well suited if more than one certificate is returned.
1520
1521 @item --url
1522 @itemx -u
1523 @opindex url
1524 Modify the @command{lookup} and @command{load-crl} commands to take an URL.
1525
1526 @item --local
1527 @itemx -l
1528 @opindex url
1529 Let the @command{lookup} command only search the local cache.
1530
1531 @item --squid-mode
1532 @opindex squid-mode
1533 Run @sc{dirmngr-client} in a mode suitable as a helper program for
1534 Squid's @option{external_acl_type} option.
1535
1536
1537 @end table
1538
1539 @ifset isman
1540 @mansect see also
1541 @command{dirmngr}(8),
1542 @command{gpgsm}(1)
1543 @include see-also-note.texi
1544 @end ifset
1545
1546
1547 @c
1548 @c   GPGPARSEMAIL
1549 @c
1550 @node gpgparsemail
1551 @section Parse a mail message into an annotated format
1552
1553 @manpage gpgparsemail.1
1554 @ifset manverb
1555 .B gpgparsemail
1556 \- Parse a mail message into an annotated format
1557 @end ifset
1558
1559 @mansect synopsis
1560 @ifset manverb
1561 .B  gpgparsemail
1562 .RI [ options ]
1563 .RI [ file ]
1564 @end ifset
1565
1566 @mansect description
1567 The @command{gpgparsemail} is a utility currently only useful for
1568 debugging.  Run it with @code{--help} for usage information.
1569
1570
1571
1572 @c
1573 @c   SYMCRYPTRUN
1574 @c
1575 @node symcryptrun
1576 @section Call a simple symmetric encryption tool.
1577 @manpage symcryptrun.1
1578 @ifset manverb
1579 .B symcryptrun
1580 \- Call a simple symmetric encryption tool
1581 @end ifset
1582
1583 @mansect synopsis
1584 @ifset manverb
1585 .B  symcryptrun
1586 .B \-\-class
1587 .I class
1588 .B \-\-program
1589 .I program
1590 .B \-\-keyfile
1591 .I keyfile
1592 .RB [ --decrypt | --encrypt ]
1593 .RI [ inputfile ]
1594 @end ifset
1595
1596 @mansect description
1597 Sometimes simple encryption tools are already in use for a long time and
1598 there might be a desire to integrate them into the GnuPG framework.  The
1599 protocols and encryption methods might be non-standard or not even
1600 properly documented, so that a full-fledged encryption tool with an
1601 interface like gpg is not doable.  @command{symcryptrun} provides a
1602 solution: It operates by calling the external encryption/decryption
1603 module and provides a passphrase for a key using the standard
1604 @command{pinentry} based mechanism through @command{gpg-agent}.
1605
1606 Note, that @command{symcryptrun} is only available if GnuPG has been
1607 configured with @samp{--enable-symcryptrun} at build time.
1608
1609 @menu
1610 * Invoking symcryptrun::   List of all commands and options.
1611 @end menu
1612
1613 @manpause
1614 @node Invoking symcryptrun
1615 @subsection List of all commands and options.
1616
1617 @noindent
1618 @command{symcryptrun} is invoked this way:
1619
1620 @example
1621 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1622    [--decrypt | --encrypt] [inputfile]
1623 @end example
1624 @mancont
1625
1626 For encryption, the plain text must be provided on STDIN or as the
1627 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1628 For decryption vice versa.
1629
1630 @var{CLASS} describes the calling conventions of the external tool.
1631 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is
1632 the full filename of that external tool.
1633  
1634 For the class @samp{confucius} the option @option{--keyfile} is
1635 required; @var{keyfile} is the name of a file containing the secret key,
1636 which may be protected by a passphrase.  For detailed calling
1637 conventions, see the source code.
1638  
1639 @noindent
1640 Note, that @command{gpg-agent} must be running before starting
1641 @command{symcryptrun}.
1642
1643 @noindent
1644 The following additional options may be used:
1645
1646 @table @gnupgtabopt
1647 @item -v
1648 @itemx --verbose
1649 @opindex verbose
1650 Output additional information while running.  
1651
1652 @item -q
1653 @item --quiet
1654 @opindex q
1655 @opindex quiet
1656 Try to be as quiet as possible.
1657
1658 @include opt-homedir.texi
1659
1660
1661 @item --log-file @var{file}
1662 @opindex log-file
1663 Append all logging output to @var{file}.  Default is to write logging
1664 information to STDERR.
1665
1666 @end table
1667
1668 @noindent
1669 The possible exit status codes of @command{symcryptrun} are:
1670
1671 @table @code
1672 @item 0 
1673         Success.
1674 @item 1 
1675         Some error occured.
1676 @item 2 
1677         No valid passphrase was provided.
1678 @item 3 
1679         The operation was canceled by the user.
1680
1681 @end table
1682
1683 @mansect see also
1684 @ifset isman
1685 @command{gpg}(1), 
1686 @command{gpgsm}(1), 
1687 @command{gpg-agent}(1), 
1688 @end ifset
1689 @include see-also-note.texi
1690
1691
1692 @c
1693 @c  GPG-ZIP
1694 @c
1695 @c The original manpage on which this section is based was written 
1696 @c by Colin Tuckley  <colin@tuckley.org> and Daniel Leidert 
1697 @c <daniel.leidert@wgdd.de> for the Debian distribution (but may be used by
1698 @c others).
1699 @manpage gpg-zip.1
1700 @node gpg-zip
1701 @section Encrypt or sign files into an archive
1702 @ifset manverb
1703 .B gpg-zip \- Encrypt or sign files into an archive
1704 @end ifset
1705
1706 @mansect synopsis
1707 @ifset manverb
1708 .B  gpg-zip
1709 .RI [ options ]
1710 .I filename1
1711 .I [ filename2, ... ]
1712 .I directory1
1713 .I [ directory2, ... ]
1714 @end ifset
1715
1716 @mansect description
1717 @command{gpg-zip} encrypts or signs files into an archive.  It is an
1718 gpg-ized tar using the same format as used by PGP's PGP Zip.
1719
1720 @manpause
1721 @noindent
1722 @command{gpg-zip} is invoked this way:
1723
1724 @example
1725 gpg-zip [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
1726 @end example
1727
1728 @mansect options
1729 @noindent
1730 @command{gpg-zip} understands these options:
1731
1732 @table @gnupgtabopt
1733
1734 @item --encrypt
1735 @itemx -e
1736 @opindex encrypt
1737 Encrypt data.  This option may be combined with @option{--symmetric} (for  output that may be decrypted via a secret key or a passphrase).
1738
1739 @item --decrypt
1740 @itemx -d
1741 @opindex decrypt
1742 Decrypt data.
1743
1744 @item --symmetric
1745 @itemx -c
1746 Encrypt with a symmetric cipher using a passphrase.  The default
1747 symmetric cipher used is CAST5, but may be chosen with the
1748 @option{--cipher-algo} option to @command{gpg}.
1749
1750 @item --sign
1751 @itemx -s
1752 Make a signature.  See @command{gpg}.
1753
1754 @item --recipient @var{user}
1755 @itemx -r @var{user}
1756 @opindex recipient
1757 Encrypt for user id @var{user}. See @command{gpg}.
1758
1759 @item --local-user @var{user}
1760 @itemx -u @var{user}
1761 @opindex local-user
1762 Use @var{user} as the key to sign with.  See @command{gpg}.
1763
1764 @item --list-archive
1765 @opindex list-archive
1766 List the contents of the specified archive.
1767
1768 @item --output @var{file}
1769 @itemx -o @var{file}
1770 @opindex output
1771 Write output to specified file @var{file}.
1772
1773 @item --gpg @var{gpgcmd}
1774 @opindex gpg
1775 Use the specified command @var{gpgcmd} instead of @command{gpg}.
1776
1777 @item --gpg-args @var{args}
1778 @opindex gpg-args
1779 Pass the specified options to @command{gpg}.
1780
1781 @item --tar @var{tarcmd}
1782 @opindex tar
1783 Use the specified command @var{tarcmd} instead of @command{tar}.
1784
1785 @item --tar-args @var{args}
1786 @opindex tar-args
1787 Pass the specified options to @command{tar}.
1788
1789 @item --version
1790 @opindex version
1791 Print version of the program and exit.
1792
1793 @item --help
1794 @opindex help
1795 Display a brief help page and exit.
1796
1797 @end table
1798
1799 @mansect diagnostics
1800 @noindent
1801 The program returns 0 if everything was fine, 1 otherwise.
1802
1803
1804 @mansect examples
1805 @ifclear isman
1806 @noindent
1807 Some examples:
1808
1809 @end ifclear
1810 @noindent
1811 Encrypt the contents of directory @file{mydocs} for user Bob to file
1812 @file{test1}:
1813
1814 @example
1815 gpg-zip --encrypt --output test1 --gpg-args  -r Bob mydocs
1816 @end example
1817
1818 @noindent
1819 List the contents of archive @file{test1}:
1820
1821 @example
1822 gpg-zip --list-archive test1
1823 @end example
1824
1825
1826 @mansect see also
1827 @ifset isman
1828 @command{gpg}(1), 
1829 @command{tar}(1), 
1830 @end ifset
1831 @include see-also-note.texi
1832