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