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