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