The Cherry XX44 keyboard's PINpad does now work.
[gnupg.git] / doc / tools.texi
1 @c Copyright (C) 2004 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 @end menu
22
23 @c
24 @c  WATCHGNUPG
25 @c
26 @manpage watchgnupg.1
27 @node watchgnupg
28 @section Read logs from a socket
29 @ifset manverb
30 .B watchgnupg
31 \- Read and print logs from a socket
32 @end ifset
33
34 @mansect synopsis
35 @ifset manverb
36 .B  watchgnupg
37 .RB [ \-\-force ]
38 .RB [ \-\-verbose ]
39 .I socketname
40 @end ifset
41
42 @mansect description
43 Most of the main utilities are able to write there log files to a
44 Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
45 listener for such a socket.  It ameliorates the output with a time
46 stamp and makes sure that long lines are not interspersed with log
47 output from other utilities.
48
49 @noindent
50 @command{watchgnupg} is commonly invoked as
51
52 @example
53 watchgnupg --force ~/.gnupg/S.log
54 @end example
55 @manpause
56
57 @noindent
58 This starts it on the current terminal for listening on the socket
59 @file{~/.gnupg/S.log}.  
60
61 @mansect options
62 @noindent
63 @command{watchgnupg} understands these options:
64
65 @table @gnupgtabopt
66
67 @item --force 
68 @opindex force
69 Delete an already existing socket file.
70
71 @item --verbose
72 @opindex verbose
73 Enable extra informational output.
74
75 @item --version
76 @opindex version
77 print version of the program and exit
78
79 @item --help
80 @opindex help
81 Display a brief help page and exit
82
83 @end table
84
85 @mansect see also
86 @ifset isman
87 @command{gpg}(1), 
88 @command{gpgsm}(1), 
89 @command{gpg-agent}(1), 
90 @command{scdaemon}(1)
91 @end ifset
92 @include see-also-note.texi
93
94
95 @c
96 @c  GPGV
97 @c
98 @include gpgv.texi
99
100
101 @c
102 @c    ADDGNUPGHOME
103 @c
104 @manpage addgnupghome.8
105 @node addgnupghome
106 @section Create .gnupg home directories.
107 @ifset manverb
108 .B addgnupghome 
109 \- Create .gnupg home directories
110 @end ifset
111
112 @mansect synopsis
113 @ifset manverb
114 .B  addgnupghome
115 .I account_1
116 .IR account_2 ... account_n
117 @end ifset
118
119 @mansect description
120 If GnuPG is installed on a system with existing user accounts, it is
121 sometimes required to populate the GnuPG home directory with existing
122 files.  Especially a @file{trustlist.txt} and a keybox with some
123 initial certificates are often desired.  This scripts help to do this
124 by copying all files from @file{/etc/skel/.gnupg} to the home
125 directories of the accounts given on the command line.  It takes care
126 not to overwrite existing GnuPG home directories.
127
128 @noindent
129 @command{addgnupghome} is invoked by root as:
130
131 @example
132 addgnupghome account1 account2 ... accountn
133 @end example
134
135
136 @c
137 @c   GPGCONF
138 @c
139 @manpage gpgconf.1
140 @node gpgconf
141 @section Modify .gnupg home directories.
142 @ifset manverb
143 .B gpgconf
144 \- Modify .gnupg home directories
145 @end ifset
146
147 @mansect synopsis
148 @ifset manverb
149 .B gpgconf
150 .RI [ options ]
151 .B \-\-list-components
152 .br
153 .B gpgconf
154 .RI [ options ]
155 .B \-\-list-options 
156 .I component
157 .br
158 .B gpgconf
159 .RI [ options ]
160 .B \-\-change-options
161 .I component
162 @end ifset
163
164
165 @mansect description
166 The @command{gpgconf} is a utility to automatically and reasonable
167 safely query and modify configuration files in the @file{.gnupg} home
168 directory.  It is designed not to be invoked manually by the user, but
169 automatically by graphical user interfaces (GUI).@footnote{Please note
170 that currently no locking is done, so concurrent access should be
171 avoided.  There are some precautions to avoid corruption with
172 concurrent usage, but results may be inconsistent and some changes may
173 get lost.  The stateless design makes it difficult to provide more
174 guarantees.}
175
176 @command{gpgconf} provides access to the configuration of one or more
177 components of the GnuPG system.  These components correspond more or
178 less to the programs that exist in the GnuPG framework, like GnuPG,
179 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
180 relationship.  Not all configuration options are available through
181 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
182 method to access the most important configuration options that can
183 feasibly be controlled via such a mechanism.
184
185 @command{gpgconf} can be used to gather and change the options
186 available in each component, and can also provide their default
187 values.  @command{gpgconf} will give detailed type information that
188 can be used to restrict the user's input without making an attempt to
189 commit the changes.
190
191 @command{gpgconf} provides the backend of a configuration editor.  The
192 configuration editor would usually be a graphical user interface
193 program, that allows to display the current options, their default
194 values, and allows the user to make changes to the options.  These
195 changes can then be made active with @command{gpgconf} again.  Such a
196 program that uses @command{gpgconf} in this way will be called GUI
197 throughout this section.
198
199 @menu
200 * Invoking gpgconf::      List of all commands and options.
201 * Format conventions::    Formatting conventions relevant for all commands.
202 * Listing components::    List all gpgconf components.
203 * Listing options::       List all options of a component.
204 * Changing options::      Changing options of a component.
205 * Files used by gpgconf:: What files are used by gpgconf.
206 @end menu
207
208 @manpause
209 @node Invoking gpgconf
210 @subsection Invoking gpgconf
211
212 @mansect commands
213 One of the following commands must be given:
214
215 @table @gnupgtabopt
216
217 @item --list-components
218 List all components.  This is the default command used if none is
219 specified.
220
221 @item --list-options @var{component}
222 List all options of the component @var{component}.
223
224 @item --change-options @var{component}
225 Change the options of the component @var{component}.
226
227 @item --apply-defaults
228 Update all configuration files with values taken from the global
229 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
230
231 @item --check-config [@var{filename}]
232 Run a syntax check ion the global configuration file.  If @var{filename}
233 is given, check that file instead.
234
235 @end table
236
237
238 @mansect options
239
240 The following options may be used:
241
242 @table @gnupgtabopt
243 @c FIXME: Not yet supported.
244 @c @item -o @var{file}
245 @c @itemx --output @var{file}
246 @c Use @var{file} as output file.
247
248 @item -v
249 @itemx --verbose
250 Outputs additional information while running.  Specifically, this
251 extends numerical field values by human-readable descriptions.
252
253 @c FIXME: Not yet supported.
254 @c @item -n
255 @c @itemx --dry-run
256 @c Do not actually change anything.  Useful together with
257 @c @code{--change-options} for testing purposes.
258
259 @item -r
260 @itemx --runtime
261 Only used together with @code{--change-options}.  If one of the
262 modified options can be changed in a running daemon process, signal
263 the running daemon to ask it to reparse its configuration file after
264 changing.
265
266 This means that the changes will take effect at run-time, as far as
267 this is possible.  Otherwise, they will take effect at the next start
268 of the respective backend programs.
269 @manpause
270 @end table
271
272
273 @node Format conventions
274 @subsection Format conventions
275
276 Some lines in the output of @command{gpgconf} contain a list of
277 colon-separated fields.  The following conventions apply:
278
279 @itemize @bullet
280 @item
281 The GUI program is required to strip off trailing newline and/or
282 carriage return characters from the output.
283
284 @item
285 @command{gpgconf} will never leave out fields.  If a certain version
286 provides a certain field, this field will always be present in all
287 @command{gpgconf} versions from that time on.
288
289 @item
290 Future versions of @command{gpgconf} might append fields to the list.
291 New fields will always be separated from the previously last field by
292 a colon separator.  The GUI should be prepared to parse the last field
293 it knows about up until a colon or end of line.
294
295 @item
296 Not all fields are defined under all conditions.  You are required to
297 ignore the content of undefined fields.
298 @end itemize
299
300 There are several standard types for the content of a field:
301
302 @table @asis
303 @item verbatim
304 Some fields contain strings that are not escaped in any way.  Such
305 fields are described to be used @emph{verbatim}.  These fields will
306 never contain a colon character (for obvious reasons).  No de-escaping
307 or other formatting is required to use the field content.  This is for
308 easy parsing of the output, when it is known that the content can
309 never contain any special characters.
310
311 @item percent-escaped
312 Some fields contain strings that are described to be
313 @emph{percent-escaped}.  Such strings need to be de-escaped before
314 their content can be presented to the user.  A percent-escaped string
315 is de-escaped by replacing all occurences of @code{%XY} by the byte
316 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
317 from the set @code{0-9a-f}.
318
319 @item localised
320 Some fields contain strings that are described to be @emph{localised}.
321 Such strings are translated to the active language and formatted in
322 the active character set.
323
324 @item @w{unsigned number}
325 Some fields contain an @emph{unsigned number}.  This number will
326 always fit into a 32-bit unsigned integer variable.  The number may be
327 followed by a space, followed by a human readable description of that
328 value (if the verbose option is used).  You should ignore everything
329 in the field that follows the number.
330
331 @item @w{signed number}
332 Some fields contain a @emph{signed number}.  This number will always
333 fit into a 32-bit signed integer variable.  The number may be followed
334 by a space, followed by a human readable description of that value (if
335 the verbose option is used).  You should ignore everything in the
336 field that follows the number.
337
338 @item option
339 Some fields contain an @emph{option} argument.  The format of an
340 option argument depends on the type of the option and on some flags:
341
342 @table @asis
343 @item no argument
344 The simplest case is that the option does not take an argument at all
345 (@var{type} @code{0}).  Then the option argument is an unsigned number
346 that specifies how often the option occurs.  If the @code{list} flag
347 is not set, then the only valid number is @code{1}.  Options that do
348 not take an argument never have the @code{default} or @code{optional
349 arg} flag set.
350
351 @item number
352 If the option takes a number argument (@var{alt-type} is @code{2} or
353 @code{3}), and it can only occur once (@code{list} flag is not set),
354 then the option argument is either empty (only allowed if the argument
355 is optional), or it is a number.  A number is a string that begins
356 with an optional minus character, followed by one or more digits.  The
357 number must fit into an integer variable (unsigned or signed,
358 depending on @var{alt-type}).
359
360 @item number list
361 If the option takes a number argument and it can occur more than once,
362 then the option argument is either empty, or it is a comma-separated
363 list of numbers as described above.
364
365 @item string
366 If the option takes a string argument (@var{alt-type} is 1), and it
367 can only occur once (@code{list} flag is not set) then the option
368 argument is either empty (only allowed if the argument is optional),
369 or it starts with a double quote character (@code{"}) followed by a
370 percent-escaped string that is the argument value.  Note that there is
371 only a leading double quote character, no trailing one.  The double
372 quote character is only needed to be able to differentiate between no
373 value and the empty string as value.
374
375 @item string list
376 If the option takes a number argument and it can occur more than once,
377 then the option argument is either empty, or it is a comma-separated
378 list of string arguments as described above.
379 @end table
380 @end table
381
382 The active language and character set are currently determined from
383 the locale environment of the @command{gpgconf} program.
384
385 @c FIXME: Document the active language and active character set.  Allow
386 @c to change it via the command line?
387
388
389 @mansect usage
390 @node Listing components
391 @subsection Listing components
392
393 The command @code{--list-components} will list all components that can
394 be configured with @command{gpgconf}.  Usually, one component will
395 correspond to one GnuPG-related program and contain the options of
396 that programs configuration file that can be modified using
397 @command{gpgconf}.  However, this is not necessarily the case.  A
398 component might also be a group of selected options from several
399 programs, or contain entirely virtual options that have a special
400 effect rather than changing exactly one option in one configuration
401 file.
402
403 A component is a set of configuration options that semantically belong
404 together.  Furthermore, several changes to a component can be made in
405 an atomic way with a single operation.  The GUI could for example
406 provide a menu with one entry for each component, or a window with one
407 tabulator sheet per component.
408
409 The command argument @code{--list-components} lists all available
410 components, one per line.  The format of each line is:
411
412 @code{@var{name}:@var{description}}
413
414 @table @var
415 @item name
416 This field contains a name tag of the component.  The name tag is used
417 to specify the component in all communication with @command{gpgconf}.
418 The name tag is to be used @emph{verbatim}.  It is thus not in any
419 escaped format.
420
421 @item description
422 The @emph{string} in this field contains a human-readable description
423 of the component.  It can be displayed to the user of the GUI for
424 informational purposes.  It is @emph{percent-escaped} and
425 @emph{localized}.
426 @end table
427
428 Example:
429 @example
430 $ gpgconf --list-components
431 gpg:GPG for OpenPGP
432 gpg-agent:GPG Agent
433 scdaemon:Smartcard Daemon
434 gpgsm:GPG for S/MIME
435 dirmngr:Directory Manager
436 @end example
437
438
439 @node Listing options
440 @subsection Listing options
441
442 Every component contains one or more options.  Options may be gathered
443 into option groups to allow the GUI to give visual hints to the user
444 about which options are related.
445
446 The command argument @code{@w{--list-options @var{component}}} lists
447 all options (and the groups they belong to) in the component
448 @var{component}, one per line.  @var{component} must be the string in
449 the field @var{name} in the output of the @code{--list-components}
450 command.
451
452 There is one line for each option and each group.  First come all
453 options that are not in any group.  Then comes a line describing a
454 group.  Then come all options that belong into each group.  Then comes
455 the next group and so on.  There does not need to be any group (and in
456 this case the output will stop after the last non-grouped option).
457
458 The format of each line is:
459
460 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
461
462 @table @var
463 @item name
464 This field contains a name tag for the group or option.  The name tag
465 is used to specify the group or option in all communication with
466 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
467 thus not in any escaped format.
468
469 @item flags
470 The flags field contains an @emph{unsigned number}.  Its value is the
471 OR-wise combination of the following flag values:
472
473 @table @code
474 @item group (1)
475 If this flag is set, this is a line describing a group and not an
476 option.
477 @end table
478
479 The following flag values are only defined for options (that is, if
480 the @code{group} flag is not used).
481
482 @table @code
483 @item optional arg (2)
484 If this flag is set, the argument is optional.  This is never set for
485 @var{type} @code{0} (none) options.
486
487 @item list (4)
488 If this flag is set, the option can be given multiple times.
489
490 @item runtime (8)
491 If this flag is set, the option can be changed at runtime.
492
493 @item default (16)
494 If this flag is set, a default value is available.
495
496 @item default desc (32)
497 If this flag is set, a (runtime) default is available.  This and the
498 @code{default} flag are mutually exclusive.
499
500 @item no arg desc (64)
501 If this flag is set, and the @code{optional arg} flag is set, then the
502 option has a special meaning if no argument is given.
503
504 @item no change (128)
505 If this flag is set, gpgconf ignores requests to change the value.  GUI
506 frontends should grey out this option.  Note, that manual changes of the
507 configuration files are still possible.
508 @end table
509
510 @item level
511 This field is defined for options and for groups.  It contains an
512 @emph{unsigned number} that specifies the expert level under which
513 this group or option should be displayed.  The following expert levels
514 are defined for options (they have analogous meaning for groups):
515
516 @table @code
517 @item basic (0)
518 This option should always be offered to the user.
519
520 @item advanced (1)
521 This option may be offered to advanced users.
522
523 @item expert (2)
524 This option should only be offered to expert users.
525
526 @item invisible (3)
527 This option should normally never be displayed, not even to expert
528 users.
529
530 @item internal (4)
531 This option is for internal use only.  Ignore it.
532 @end table
533
534 The level of a group will always be the lowest level of all options it
535 contains.
536
537 @item description
538 This field is defined for options and groups.  The @emph{string} in
539 this field contains a human-readable description of the option or
540 group.  It can be displayed to the user of the GUI for informational
541 purposes.  It is @emph{percent-escaped} and @emph{localized}.
542
543 @item type
544 This field is only defined for options.  It contains an @emph{unsigned
545 number} that specifies the type of the option's argument, if any.  The
546 following types are defined:
547
548 Basic types:
549
550 @table @code
551 @item none (0)
552 No argument allowed.
553
554 @item string (1)
555 An @emph{unformatted string}.
556
557 @item int32 (2)
558 A @emph{signed number}.
559
560 @item uint32 (3)
561 An @emph{unsigned number}.
562 @end table
563
564 Complex types:
565
566 @table @code
567 @item pathname (32)
568 A @emph{string} that describes the pathname of a file.  The file does
569 not necessarily need to exist.
570
571 @item ldap server (33)
572 A @emph{string} that describes an LDAP server in the format:
573
574 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
575 @end table
576
577 More types will be added in the future.  Please see the @var{alt-type}
578 field for information on how to cope with unknown types.
579
580 @item alt-type
581 This field is identical to @var{type}, except that only the types
582 @code{0} to @code{31} are allowed.  The GUI is expected to present the
583 user the option in the format specified by @var{type}.  But if the
584 argument type @var{type} is not supported by the GUI, it can still
585 display the option in the more generic basic type @var{alt-type}.  The
586 GUI must support all the defined basic types to be able to display all
587 options.  More basic types may be added in future versions.  If the
588 GUI encounters a basic type it doesn't support, it should report an
589 error and abort the operation.
590
591 @item argname
592 This field is only defined for options with an argument type
593 @var{type} that is not @code{0}.  In this case it may contain a
594 @emph{percent-escaped} and @emph{localised string} that gives a short
595 name for the argument.  The field may also be empty, though, in which
596 case a short name is not known.
597
598 @item default
599 This field is defined only for options.  Its format is that of an
600 @emph{option argument} (@xref{Format conventions}, for details).  If
601 the default value is empty, then no default is known.  Otherwise, the
602 value specifies the default value for this option.  Note that this
603 field is also meaningful if the option itself does not take a real
604 argument.
605
606 @item argdef
607 This field is defined only for options for which the @code{optional
608 arg} flag is set.  If the @code{no arg desc} flag is not set, its
609 format is that of an @emph{option argument} (@xref{Format
610 conventions}, for details).  If the default value is empty, then no
611 default is known.  Otherwise, the value specifies the default value
612 for this option.  If the @code{no arg desc} flag is set, the field is
613 either empty or contains a description of the effect of this option if
614 no argument is given.  Note that this field is also meaningful if the
615 option itself does not take a real argument.
616
617 @item value
618 This field is defined only for options.  Its format is that of an
619 @emph{option argument}.  If it is empty, then the option is not
620 explicitely set in the current configuration, and the default applies
621 (if any).  Otherwise, it contains the current value of the option.
622 Note that this field is also meaningful if the option itself does not
623 take a real argument.
624 @end table
625
626
627 @node Changing options
628 @subsection Changing options
629
630 The command @w{@code{--change-options @var{component}}} will attempt
631 to change the options of the component @var{component} to the
632 specified values.  @var{component} must be the string in the field
633 @var{name} in the output of the @code{--list-components} command.  You
634 have to provide the options that shall be changed in the following
635 format on standard input:
636
637 @code{@var{name}:@var{flags}:@var{new-value}}
638
639 @table @var
640 @item name
641 This is the name of the option to change.  @var{name} must be the
642 string in the field @var{name} in the output of the
643 @code{--list-options} command.
644
645 @item flags
646 The flags field contains an @emph{unsigned number}.  Its value is the
647 OR-wise combination of the following flag values:
648
649 @table @code
650 @item default (16)
651 If this flag is set, the option is deleted and the default value is
652 used instead (if applicable).
653 @end table
654
655 @item new-value
656 The new value for the option.  This field is only defined if the
657 @code{default} flag is not set.  The format is that of an @emph{option
658 argument}.  If it is empty (or the field is omitted), the default
659 argument is used (only allowed if the argument is optional for this
660 option).  Otherwise, the option will be set to the specified value.
661 @end table
662
663 Examples:
664
665 To set the force option, which is of basic type @code{none (0)}:
666
667 @example
668 $ echo 'force:0:1' | gpgconf --change-options dirmngr
669 @end example
670
671 To delete the force option:
672
673 @example
674 $ echo 'force:16:' | gpgconf --change-options dirmngr
675 @end example
676
677 The @code{--runtime} option can influence when the changes take
678 effect.
679
680 @mansect files
681 @node Files used by gpgconf
682 @subsection Files used by gpgconf
683
684 @table @file
685
686 @item /etc/gnupg/gpgconf.conf
687 @cindex gpgconf.conf
688   If this file exists, it is processed as a global configuration file.
689   A commented example can be found in the @file{examples} directory of
690   the distribution.
691 @end table
692
693
694 @mansect see also
695 @ifset isman
696 @command{gpg}(1), 
697 @command{gpgsm}(1), 
698 @command{gpg-agent}(1), 
699 @command{scdaemon}(1),
700 @command{dirmngr}(1)
701 @end ifset
702 @include see-also-note.texi
703
704
705
706 @c
707 @c    APPLYGNUPGDEFAULTS
708 @c
709 @manpage applygnupgdefaults.8
710 @node applygnupgdefaults
711 @section Run gpgconf for all users.
712 @ifset manverb
713 .B applygnupgdefaults
714 \- Run gpgconf --apply-defaults for all users.
715 @end ifset
716
717 @mansect synopsis
718 @ifset manverb
719 .B  applygnupgdefaults
720 @end ifset
721
722 @mansect description
723 This script is a wrapper around @command{gpgconf} to run it with the
724 command @code{--apply-defaults} for all real users with an existing
725 GnuPG home directory.  Admins might want to use this script to update he
726 GnuPG configuration files for all users after
727 @file{/etc/gnupg/gpgconf.conf} has been changed.  This allows to enforce
728 certain policies for all users.  Note, that this is not a bulletproof of
729 forcing a user to use certain options.  A user may always directly edit
730 the configuration files and bypass gpgconf.
731
732 @noindent
733 @command{applygnupgdefaults} is invoked by root as:
734
735 @example
736 applygnupgdefaults
737 @end example
738
739
740 @c
741 @c    GPGSM-GENCERT.SH
742 @c
743 @node gpgsm-gencert.sh
744 @section Generate an X.509 certificate request
745 @manpage gpgsm-gencert.sh.1
746 @ifset manverb
747 .B gpgsm-gencert.sh
748 \- Generate an X.509 certificate request
749 @end ifset 
750
751 @mansect synopsis
752 @ifset manverb
753 .B  gpgsm-gencert.sh
754 @end ifset
755
756 @mansect description
757 This is a simple tool to interactivly generate a certificate request
758 which will be printed to stdout.
759
760 @manpause
761 @noindent
762 @command{gpgsm-gencert.sh} is invoked as:
763
764 @samp{gpgsm-cencert.sh}
765
766 @mansect see also
767 @ifset isman
768 @command{gpgsm}(1), 
769 @command{gpg-agent}(1), 
770 @command{scdaemon}(1)
771 @end ifset
772 @include see-also-note.texi
773
774
775
776 @c
777 @c   GPG-PRESET-PASSPHRASE
778 @c
779 @node gpg-preset-passphrase
780 @section Put a passphrase into the cache.
781 @manpage gpg-preset-passphrase.1
782 @ifset manverb
783 .B gpg-preset-passphrase
784 \- Put a passphrase into gpg-agent's cache
785 @end ifset
786
787 @mansect synopsis
788 @ifset manverb
789 .B  gpg-preset-passphrase
790 .RI [ options ]
791 .RI [ command ]
792 .I keygrip
793 @end ifset
794
795 @mansect description
796 The @command{gpg-preset-passphrase} is a utility to seed the internal
797 cache of a running @command{gpg-agent} with passphrases.  It is mainly
798 useful for unattended machines, where the usual @command{pinentry} tool
799 may not be used and the passphrases for the to be used keys are given at
800 machine startup.
801
802 Passphrases set with this utility don't expire unless the
803 @option{--forget} option is used to explicitly clear them from the cache
804 --- or @command{gpg-agent} is either restarted or reloaded (by sending a
805 SIGHUP to it).  It is necessary to allow this passphrase presetting by
806 starting @command{gpg-agent} with the
807 @option{--allow-preset-passphrase}.
808
809 @menu
810 * Invoking gpg-preset-passphrase::   List of all commands and options.
811 @end menu
812
813 @manpause
814 @node Invoking gpg-preset-passphrase
815 @subsection List of all commands and options.
816 @mancont
817
818 @noindent
819 @command{gpg-preset-passphrase} is invoked this way:
820
821 @example
822 gpg-preset-passphrase [options] [command] @var{keygrip}
823 @end example
824
825 @var{keygrip} is a 40 character string of hexadecimal characters
826 identifying the key for which the passphrase should be set or cleared.
827 This keygrip is listed along with the key when running the command:
828 @code{gpgsm --dump-secret-keys}. One of the following command options
829 must be given:
830
831 @table @gnupgtabopt
832 @item --preset
833 @opindex preset
834 Preset a passphrase. This is what you usually will
835 use. @command{gpg-preset-passphrase} will then read the passphrase from
836 @code{stdin}.
837
838 @item --forget
839 @opindex forget
840 Flush the passphrase for the given keygrip from the cache.
841
842 @end table
843
844 @noindent
845 The following additional options may be used:
846
847 @table @gnupgtabopt
848 @item -v
849 @itemx --verbose
850 @opindex verbose
851 Output additional information while running.  
852
853 @item -P @var{string}
854 @itemx --passphrase @var{string}
855 @opindex passphrase
856 Instead of reading the passphrase from @code{stdin}, use the supplied
857 @var{string} as passphrase.  Note that this makes the passphrase visible
858 for other users.
859 @end table
860
861 @mansect see also
862 @ifset isman
863 @command{gpg}(1), 
864 @command{gpgsm}(1), 
865 @command{gpg-agent}(1), 
866 @command{scdaemon}(1)
867 @end ifset
868 @include see-also-note.texi
869
870
871
872
873 @c
874 @c   GPG-CONNECT-AGENT
875 @c
876 @node gpg-connect-agent
877 @section Communicate with a running agent.
878 @manpage gpg-connect-agent.1
879 @ifset manverb
880 .B gpg-connect-agent
881 \- Communicate with a running agent
882 @end ifset
883
884 @mansect synopsis
885 @ifset manverb
886 .B  gpg-connect-agent
887 .RI [ options ]
888 @end ifset
889
890 @mansect description
891 The @command{gpg-connect-agent} is a utility to communicate with a
892 running @command{gpg-agent}.  It is useful to check out the commands
893 gpg-agent provides using the Assuan interface.  It might also be useful
894 for scripting simple applications.  Inputis expected at stdin and out
895 put gets printed to stdout.
896
897 It is very similar to running @command{gpg-agent} in server mode; but
898 here we connect to a running instance.
899
900 @menu
901 * Invoking gpg-connect-agent::       List of all options.
902 * Controlling gpg-connect-agent::    Control commands.
903 @end menu
904
905 @manpause
906 @node Invoking gpg-connect-agent
907 @subsection List of all options.
908
909 @noindent
910 @command{gpg-connect-agent} is invoked this way:
911
912 @example
913 gpg-connect-agent [options]
914 @end example
915 @mancont
916
917 @noindent
918 The following options may be used:
919
920 @table @gnupgtabopt
921 @item -v
922 @itemx --verbose
923 @opindex verbose
924 Output additional information while running.  
925
926 @item -q
927 @item --quiet
928 @opindex q
929 @opindex quiet
930 Try to be as quiet as possible.
931
932 @include opt-homedir.texi
933
934 @item -S
935 @itemx --raw-socket @var{name}
936 @opindex S        
937 @opindex raw-socket
938 Connect to socket @var{name} assuming this is an Assuan style server.
939 Do not run any special initializations or environment checks.  This may
940 be used to directly connect to any Assuan style socket server.
941
942 @item -E
943 @itemx --exec
944 @opindex exec
945 Take the rest of the command line as a program and it's arguments and
946 execute it as an assuan server. Here is how you would run @command{gpgsm}:
947 @smallexample
948  gpg-connect-agent --exec gpgsm --server
949 @end smallexample
950
951
952 @item --no-ext-connect
953 @opindex no-ext-connect
954 When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
955 connects to the assuan server in extended mode to allow descriptor
956 passing.  This option makes it use the old mode.
957
958 @end table
959
960 @mansect control commands
961 @node Controlling gpg-connect-agent
962 @subsection Control commands.
963
964 While reading Assuan commands, gpg-agent also allows a few special
965 commands to control its operation.  These control commands all start
966 with a slash (@code{/}).
967
968
969 @table @code
970
971 @item /echo @var{args}
972 Just print @var{args}.
973
974 @item /definqfile @var{name} @var{file}
975
976 Use content of @var{file} for inquiries with @var{name}.
977 @var{name} may be an asterisk (@code{*} to match any inquiry.
978
979 @item /definqprog @var{name} @var{prog}
980 Run @var{prog} for inquiries matching @var{name} and pass the
981 entire line to it as command line arguments
982
983 @item /showdef
984 Print all definitions
985
986 @item /cleardef
987 Delete all definitions
988
989 @item /sendfd @var{file} @var{mode}
990 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
991 mode string) and send the file descriptor to the server.  This is
992 usually followed by a command like @code{INPUT FD} to set the
993 input source for other commands.
994
995 @item /recvfd
996 Not yet implemented.
997
998 @item /help
999 Print a list of available control commands.
1000
1001 @end table
1002
1003
1004 @ifset isman
1005 @mansect see also
1006 @command{gpg-agent}(1), 
1007 @command{scdaemon}(1)
1008 @include see-also-note.texi
1009 @end ifset
1010
1011
1012 @c
1013 @c   GPGPARSEMAIL
1014 @c
1015 @node gpgparsemail
1016 @section Parse a mail message into an annotated format
1017
1018 @manpage gpgparsemail.1
1019 @ifset manverb
1020 .B gpgparsemail
1021 \- Parse a mail message into an annotated format
1022 @end ifset
1023
1024 @mansect synopsis
1025 @ifset manverb
1026 .B  gpgparsemail
1027 .RI [ options ]
1028 .RI [ file ]
1029 @end ifset
1030
1031 @mansect description
1032 The @command{gpgparsemail} is a utility currently only useful for
1033 debugging.  Run it with @code{--help} for usage information.
1034
1035
1036
1037 @c
1038 @c   SYMCRYPTRUN
1039 @c
1040 @node symcryptrun
1041 @section Call a simple symmetric encryption tool.
1042 @manpage symcryptrun.1
1043 @ifset manverb
1044 .B symcryptrun
1045 \- Call a simple symmetric encryption tool
1046 @end ifset
1047
1048 @mansect synopsis
1049 @ifset manverb
1050 .B  symcryptrun
1051 .B \-\-class
1052 .I class
1053 .B \-\-program
1054 .I program
1055 .B \-\-keyfile
1056 .I keyfile
1057 .RB [ --decrypt | --encrypt ]
1058 .RI [ inputfile ]
1059 @end ifset
1060
1061 @mansect description
1062 Sometimes simple encryption tools are already in use for a long time and
1063 there might be a desire to integrate them into the GnuPG framework.  The
1064 protocols and encryption methods might be non-standard or not even
1065 properly documented, so that a full-fledged encryption tool with an
1066 interface like gpg is not doable.  @command{symcryptrun} provides a
1067 solution: It operates by calling the external encryption/decryption
1068 module and provides a passphrase for a key using the standard
1069 @command{pinentry} based mechanism through @command{gpg-agent}.
1070
1071 Note, that @command{symcryptrun} is only available if GnuPG has been
1072 configured with @samp{--enable-symcryptrun} at build time.
1073
1074 @menu
1075 * Invoking symcryptrun::   List of all commands and options.
1076 @end menu
1077
1078 @manpause
1079 @node Invoking symcryptrun
1080 @subsection List of all commands and options.
1081
1082 @noindent
1083 @command{symcryptrun} is invoked this way:
1084
1085 @example
1086 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1087    [--decrypt | --encrypt] [inputfile]
1088 @end example
1089 @mancont
1090
1091 For encryption, the plain text must be provided on STDIN or as the
1092 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1093 For decryption vice versa.
1094
1095 @var{CLASS} describes the calling conventions of the external tool.
1096 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1097 the full filename of that external tool.
1098  
1099 For the class @samp{confucius} the option @option{--keyfile} is
1100 required; @var{keyfile} is the name of a file containing the secret key,
1101 which may be protected by a passphrase.  For detailed calling
1102 conventions, see the source code.
1103  
1104 @noindent
1105 Note, that @command{gpg-agent} must be running before starting
1106 @command{symcryptrun}.
1107
1108 @noindent
1109 The following additional options may be used:
1110
1111 @table @gnupgtabopt
1112 @item -v
1113 @itemx --verbose
1114 @opindex verbose
1115 Output additional information while running.  
1116
1117 @item -q
1118 @item --quiet
1119 @opindex q
1120 @opindex quiet
1121 Try to be as quiet as possible.
1122
1123 @include opt-homedir.texi
1124
1125
1126 @item --log-file @var{file}
1127 @opindex log-file
1128 Append all logging output to @var{file}.  Default is to write logging
1129 informaton to STDERR.
1130
1131 @end table
1132
1133 @noindent
1134 The possible exit status codes of @command{symcryptrun} are:
1135
1136 @table @code
1137 @item 0 
1138         Success.
1139 @item 1 
1140         Some error occured.
1141 @item 2 
1142         No valid passphrase was provided.
1143 @item 3 
1144         The operation was canceled by the user.
1145
1146 @end table
1147
1148 @mansect see also
1149 @ifset isman
1150 @command{gpg}(1), 
1151 @command{gpgsm}(1), 
1152 @command{gpg-agent}(1), 
1153 @end ifset
1154 @include see-also-note.texi
1155