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