cce773d9bd643603b15d266285b42906a7ee3a42
[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 on 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 @item --hex
959 @opindex hex
960 Print data lines in a hex format and the ASCII representation of
961 non-control characters.
962
963 @item --decode
964 @opindex decode
965 Decode data lines.  That is to remove percent escapes but make sure that
966 a new line always starts with a D and a space.
967
968 @end table
969
970 @mansect control commands
971 @node Controlling gpg-connect-agent
972 @subsection Control commands.
973
974 While reading Assuan commands, gpg-agent also allows a few special
975 commands to control its operation.  These control commands all start
976 with a slash (@code{/}).
977
978
979 @table @code
980
981 @item /echo @var{args}
982 Just print @var{args}.
983
984 @item /definqfile @var{name} @var{file}
985
986 Use content of @var{file} for inquiries with @var{name}.
987 @var{name} may be an asterisk (@code{*} to match any inquiry.
988
989 @item /definqprog @var{name} @var{prog}
990 Run @var{prog} for inquiries matching @var{name} and pass the
991 entire line to it as command line arguments
992
993 @item /showdef
994 Print all definitions
995
996 @item /cleardef
997 Delete all definitions
998
999 @item /sendfd @var{file} @var{mode}
1000 Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1001 mode string) and send the file descriptor to the server.  This is
1002 usually followed by a command like @code{INPUT FD} to set the
1003 input source for other commands.
1004
1005 @item /recvfd
1006 Not yet implemented.
1007
1008 @item /hex
1009 @itemx /nohex
1010 Same as the command line option @option{--hex}.
1011
1012 @item /decode
1013 @itemx /nodecode
1014 Same as the command line option @option{--decode}.
1015
1016 @item /help
1017 Print a list of available control commands.
1018
1019 @end table
1020
1021
1022 @ifset isman
1023 @mansect see also
1024 @command{gpg-agent}(1), 
1025 @command{scdaemon}(1)
1026 @include see-also-note.texi
1027 @end ifset
1028
1029
1030 @c
1031 @c   GPGPARSEMAIL
1032 @c
1033 @node gpgparsemail
1034 @section Parse a mail message into an annotated format
1035
1036 @manpage gpgparsemail.1
1037 @ifset manverb
1038 .B gpgparsemail
1039 \- Parse a mail message into an annotated format
1040 @end ifset
1041
1042 @mansect synopsis
1043 @ifset manverb
1044 .B  gpgparsemail
1045 .RI [ options ]
1046 .RI [ file ]
1047 @end ifset
1048
1049 @mansect description
1050 The @command{gpgparsemail} is a utility currently only useful for
1051 debugging.  Run it with @code{--help} for usage information.
1052
1053
1054
1055 @c
1056 @c   SYMCRYPTRUN
1057 @c
1058 @node symcryptrun
1059 @section Call a simple symmetric encryption tool.
1060 @manpage symcryptrun.1
1061 @ifset manverb
1062 .B symcryptrun
1063 \- Call a simple symmetric encryption tool
1064 @end ifset
1065
1066 @mansect synopsis
1067 @ifset manverb
1068 .B  symcryptrun
1069 .B \-\-class
1070 .I class
1071 .B \-\-program
1072 .I program
1073 .B \-\-keyfile
1074 .I keyfile
1075 .RB [ --decrypt | --encrypt ]
1076 .RI [ inputfile ]
1077 @end ifset
1078
1079 @mansect description
1080 Sometimes simple encryption tools are already in use for a long time and
1081 there might be a desire to integrate them into the GnuPG framework.  The
1082 protocols and encryption methods might be non-standard or not even
1083 properly documented, so that a full-fledged encryption tool with an
1084 interface like gpg is not doable.  @command{symcryptrun} provides a
1085 solution: It operates by calling the external encryption/decryption
1086 module and provides a passphrase for a key using the standard
1087 @command{pinentry} based mechanism through @command{gpg-agent}.
1088
1089 Note, that @command{symcryptrun} is only available if GnuPG has been
1090 configured with @samp{--enable-symcryptrun} at build time.
1091
1092 @menu
1093 * Invoking symcryptrun::   List of all commands and options.
1094 @end menu
1095
1096 @manpause
1097 @node Invoking symcryptrun
1098 @subsection List of all commands and options.
1099
1100 @noindent
1101 @command{symcryptrun} is invoked this way:
1102
1103 @example
1104 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
1105    [--decrypt | --encrypt] [inputfile]
1106 @end example
1107 @mancont
1108
1109 For encryption, the plain text must be provided on STDIN or as the
1110 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
1111 For decryption vice versa.
1112
1113 @var{CLASS} describes the calling conventions of the external tool.
1114 Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
1115 the full filename of that external tool.
1116  
1117 For the class @samp{confucius} the option @option{--keyfile} is
1118 required; @var{keyfile} is the name of a file containing the secret key,
1119 which may be protected by a passphrase.  For detailed calling
1120 conventions, see the source code.
1121  
1122 @noindent
1123 Note, that @command{gpg-agent} must be running before starting
1124 @command{symcryptrun}.
1125
1126 @noindent
1127 The following additional options may be used:
1128
1129 @table @gnupgtabopt
1130 @item -v
1131 @itemx --verbose
1132 @opindex verbose
1133 Output additional information while running.  
1134
1135 @item -q
1136 @item --quiet
1137 @opindex q
1138 @opindex quiet
1139 Try to be as quiet as possible.
1140
1141 @include opt-homedir.texi
1142
1143
1144 @item --log-file @var{file}
1145 @opindex log-file
1146 Append all logging output to @var{file}.  Default is to write logging
1147 informaton to STDERR.
1148
1149 @end table
1150
1151 @noindent
1152 The possible exit status codes of @command{symcryptrun} are:
1153
1154 @table @code
1155 @item 0 
1156         Success.
1157 @item 1 
1158         Some error occured.
1159 @item 2 
1160         No valid passphrase was provided.
1161 @item 3 
1162         The operation was canceled by the user.
1163
1164 @end table
1165
1166 @mansect see also
1167 @ifset isman
1168 @command{gpg}(1), 
1169 @command{gpgsm}(1), 
1170 @command{gpg-agent}(1), 
1171 @end ifset
1172 @include see-also-note.texi
1173