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