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