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