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