diff options
Diffstat (limited to 'doc/tools.texi')
| -rw-r--r-- | doc/tools.texi | 884 |
1 files changed, 884 insertions, 0 deletions
diff --git a/doc/tools.texi b/doc/tools.texi new file mode 100644 index 000000000..d39d950f4 --- /dev/null +++ b/doc/tools.texi @@ -0,0 +1,884 @@ +@c Copyright (C) 2004 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file GnuPG.texi. + +@node Helper Tools +@chapter Helper Tools + +GnuPG comes with a couple of smaller tools: + +@menu +* watchgnupg:: Read logs from a socket. +* addgnupghome:: Create .gnupg home directories. +* gpgconf:: Modify .gnupg home directories. +* gpgsm-gencert.sh:: Generate an X.509 certificate request. +* gpg-preset-passphrase:: Put a passphrase into the cache. +* gpg-connect-agent:: Communicate with a running agent. +* gpgparsemail:: Parse a mail message into an annotated format +* symcryptrun:: Call a simple symmetric encryption tool. +@end menu + +@c +@c WATCHGNUPG +@c +@manpage watchgnupg.1 +@node watchgnupg +@section Read logs from a socket +@ifset manverb + watchgnupg \- Read and print logs from a socket +@end ifset + +@mansect description +Most of the main utilities are able to write there log files to a +Unix Domain socket if configured that way. @command{watchgnupg} is a simple +listener for such a socket. It ameliorates the output with a time +stamp and makes sure that long lines are not interspersed with log +output from other utilities. + +@manpause +@noindent +@command{watchgnupg} is commonly invoked as + +@mansect synopsis +@example +watchgnupg --force ~/.gnupg/S.log +@end example +@manpause + +@noindent +This starts it on the current terminal for listening on the socket +@file{~/.gnupg/S.log}. + +@noindent +@command{watchgnupg} understands these options: + +@table @gnupgtabopt +@mansect options + +@item --force +@opindex force +Delete an already existing socket file. + +@item --verbose +@opindex verbose +Enable extra informational output. + +@item --version +@opindex version +print version of the program and exit + +@item --help +@opindex help +Display a brief help page and exit + +@manpause +@end table + + +@c +@c ADDGNUPGHOME +@c +@manpage addgnupghome.8 +@node addgnupghome +@section Create .gnupg home directories. +@ifset manverb + addgnupghome \- Create .gnupg home directories +@end ifset + +@mansect description +If GnuPG is installed on a system with existing user accounts, it is +sometimes required to populate the GnuPG home directory with existing +files. Especially a @file{trustlist.txt} and a keybox with some +initial certificates are often desired. This scripts help to do this +by copying all files from @file{/etc/skel/.gnupg} to the home +directories of the accounts given on the command line. It takes care +not to overwrite existing GnuPG home directories. + +@manpause +@noindent +@command{addgnupghome} is invoked by root as: + +@mansect synopsis +@example +addgnupghome account1 account2 ... accountn +@end example + + +@c +@c GPGCONF +@c +@manpage gpgconf.1 +@node gpgconf +@section Modify .gnupg home directories. +@ifset manverb + gpgconf \- Modify .gnupg home directories +@end ifset + +@mansect description +The @command{gpgconf} is a utility to automatically and reasonable +safely query and modify configuration files in the @file{.gnupg} home +directory. It is designed not to be invoked manually by the user, but +automatically by graphical user interfaces (GUI).@footnote{Please note +that currently no locking is done, so concurrent access should be +avoided. There are some precautions to avoid corruption with +concurrent usage, but results may be inconsistent and some changes may +get lost. The stateless design makes it difficult to provide more +guarantees.} + +@command{gpgconf} provides access to the configuration of one or more +components of the GnuPG system. These components correspond more or +less to the programs that exist in the GnuPG framework, like GnuPG, +GPGSM, DirMngr, etc. But this is not a strict one-to-one +relationship. Not all configuration options are available through +@command{gpgconf}. @command{gpgconf} provides a generic and abstract +method to access the most important configuration options that can +feasibly be controlled via such a mechanism. + +@command{gpgconf} can be used to gather and change the options +available in each component, and can also provide their default +values. @command{gpgconf} will give detailed type information that +can be used to restrict the user's input without making an attempt to +commit the changes. + +@command{gpgconf} provides the backend of a configuration editor. The +configuration editor would usually be a graphical user interface +program, that allows to display the current options, their default +values, and allows the user to make changes to the options. These +changes can then be made active with @command{gpgconf} again. Such a +program that uses @command{gpgconf} in this way will be called GUI +throughout this section. + +@manpause +@menu +* Invoking gpgconf:: List of all commands and options. +* Format conventions:: Formatting conventions relevant for all commands. +* Listing components:: List all gpgconf components. +* Listing options:: List all options of a component. +* Changing options:: Changing options of a component. +@end menu + + +@node Invoking gpgconf +@subsection Invoking gpgconf + +@mansect commands +One of the following commands must be given: + +@manpause +@table @gnupgtabopt +@mancont + +@item --list-components +List all components. This is the default command used if none is +specified. + +@item --list-options @var{component} +List all options of the component @var{component}. + +@item --change-options @var{component} +Change the options of the component @var{component}. +@manpause +@end table + +@mansect options + +The following options may be used: + +@manpause +@table @gnupgtabopt +@mancont +@c FIXME: Not yet supported. +@c @item -o @var{file} +@c @itemx --output @var{file} +@c Use @var{file} as output file. + +@item -v +@itemx --verbose +Outputs additional information while running. Specifically, this +extends numerical field values by human-readable descriptions. + +@c FIXME: Not yet supported. +@c @item -n +@c @itemx --dry-run +@c Do not actually change anything. Useful together with +@c @code{--change-options} for testing purposes. + +@item -r +@itemx --runtime +Only used together with @code{--change-options}. If one of the +modified options can be changed in a running daemon process, signal +the running daemon to ask it to reparse its configuration file after +changing. + +This means that the changes will take effect at run-time, as far as +this is possible. Otherwise, they will take effect at the next start +of the respective backend programs. +@manpause +@end table + + +@node Format conventions +@subsection Format conventions + +Some lines in the output of @command{gpgconf} contain a list of +colon-separated fields. The following conventions apply: + +@itemize @bullet +@item +The GUI program is required to strip off trailing newline and/or +carriage return characters from the output. + +@item +@command{gpgconf} will never leave out fields. If a certain version +provides a certain field, this field will always be present in all +@command{gpgconf} versions from that time on. + +@item +Future versions of @command{gpgconf} might append fields to the list. +New fields will always be separated from the previously last field by +a colon separator. The GUI should be prepared to parse the last field +it knows about up until a colon or end of line. + +@item +Not all fields are defined under all conditions. You are required to +ignore the content of undefined fields. +@end itemize + +There are several standard types for the content of a field: + +@table @asis +@item verbatim +Some fields contain strings that are not escaped in any way. Such +fields are described to be used @emph{verbatim}. These fields will +never contain a colon character (for obvious reasons). No de-escaping +or other formatting is required to use the field content. This is for +easy parsing of the output, when it is known that the content can +never contain any special characters. + +@item percent-escaped +Some fields contain strings that are described to be +@emph{percent-escaped}. Such strings need to be de-escaped before +their content can be presented to the user. A percent-escaped string +is de-escaped by replacing all occurences of @code{%XY} by the byte +that has the hexadecimal value @code{XY}. @code{X} and @code{Y} are +from the set @code{0-9a-f}. + +@item localised +Some fields contain strings that are described to be @emph{localised}. +Such strings are translated to the active language and formatted in +the active character set. + +@item @w{unsigned number} +Some fields contain an @emph{unsigned number}. This number will +always fit into a 32-bit unsigned integer variable. The number may be +followed by a space, followed by a human readable description of that +value (if the verbose option is used). You should ignore everything +in the field that follows the number. + +@item @w{signed number} +Some fields contain a @emph{signed number}. This number will always +fit into a 32-bit signed integer variable. The number may be followed +by a space, followed by a human readable description of that value (if +the verbose option is used). You should ignore everything in the +field that follows the number. + +@item option +Some fields contain an @emph{option} argument. The format of an +option argument depends on the type of the option and on some flags: + +@table @asis +@item no argument +The simplest case is that the option does not take an argument at all +(@var{type} @code{0}). Then the option argument is an unsigned number +that specifies how often the option occurs. If the @code{list} flag +is not set, then the only valid number is @code{1}. Options that do +not take an argument never have the @code{default} or @code{optional +arg} flag set. + +@item number +If the option takes a number argument (@var{alt-type} is @code{2} or +@code{3}), and it can only occur once (@code{list} flag is not set), +then the option argument is either empty (only allowed if the argument +is optional), or it is a number. A number is a string that begins +with an optional minus character, followed by one or more digits. The +number must fit into an integer variable (unsigned or signed, +depending on @var{alt-type}). + +@item number list +If the option takes a number argument and it can occur more than once, +then the option argument is either empty, or it is a comma-separated +list of numbers as described above. + +@item string +If the option takes a string argument (@var{alt-type} is 1), and it +can only occur once (@code{list} flag is not set) then the option +argument is either empty (only allowed if the argument is optional), +or it starts with a double quote character (@code{"}) followed by a +percent-escaped string that is the argument value. Note that there is +only a leading double quote character, no trailing one. The double +quote character is only needed to be able to differentiate between no +value and the empty string as value. + +@item string list +If the option takes a number argument and it can occur more than once, +then the option argument is either empty, or it is a comma-separated +list of string arguments as described above. +@end table +@end table + +The active language and character set are currently determined from +the locale environment of the @command{gpgconf} program. + +@c FIXME: Document the active language and active character set. Allow +@c to change it via the command line? + + +@mansect usage +@node Listing components +@subsection Listing components + +The command @code{--list-components} will list all components that can +be configured with @command{gpgconf}. Usually, one component will +correspond to one GnuPG-related program and contain the options of +that programs configuration file that can be modified using +@command{gpgconf}. However, this is not necessarily the case. A +component might also be a group of selected options from several +programs, or contain entirely virtual options that have a special +effect rather than changing exactly one option in one configuration +file. + +A component is a set of configuration options that semantically belong +together. Furthermore, several changes to a component can be made in +an atomic way with a single operation. The GUI could for example +provide a menu with one entry for each component, or a window with one +tabulator sheet per component. + +The command argument @code{--list-components} lists all available +components, one per line. The format of each line is: + +@code{@var{name}:@var{description}} + +@table @var +@item name +This field contains a name tag of the component. The name tag is used +to specify the component in all communication with @command{gpgconf}. +The name tag is to be used @emph{verbatim}. It is thus not in any +escaped format. + +@item description +The @emph{string} in this field contains a human-readable description +of the component. It can be displayed to the user of the GUI for +informational purposes. It is @emph{percent-escaped} and +@emph{localized}. +@end table + +Example: +@example +$ gpgconf --list-components +gpg:GPG for OpenPGP +gpg-agent:GPG Agent +scdaemon:Smartcard Daemon +gpgsm:GPG for S/MIME +dirmngr:Directory Manager +@end example + + +@node Listing options +@subsection Listing options + +Every component contains one or more options. Options may be gathered +into option groups to allow the GUI to give visual hints to the user +about which options are related. + +The command argument @code{@w{--list-options @var{component}}} lists +all options (and the groups they belong to) in the component +@var{component}, one per line. @var{component} must be the string in +the field @var{name} in the output of the @code{--list-components} +command. + +There is one line for each option and each group. First come all +options that are not in any group. Then comes a line describing a +group. Then come all options that belong into each group. Then comes +the next group and so on. There does not need to be any group (and in +this case the output will stop after the last non-grouped option). + +The format of each line is: + +@code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}} + +@table @var +@item name +This field contains a name tag for the group or option. The name tag +is used to specify the group or option in all communication with +@command{gpgconf}. The name tag is to be used @emph{verbatim}. It is +thus not in any escaped format. + +@item flags +The flags field contains an @emph{unsigned number}. Its value is the +OR-wise combination of the following flag values: + +@table @code +@item group (1) +If this flag is set, this is a line describing a group and not an +option. +@end table + +The following flag values are only defined for options (that is, if +the @code{group} flag is not used). + +@table @code +@item optional arg (2) +If this flag is set, the argument is optional. This is never set for +@var{type} @code{0} (none) options. + +@item list (4) +If this flag is set, the option can be given multiple times. + +@item runtime (8) +If this flag is set, the option can be changed at runtime. + +@item default (16) +If this flag is set, a default value is available. + +@item default desc (32) +If this flag is set, a (runtime) default is available. This and the +@code{default} flag are mutually exclusive. + +@item no arg desc (64) +If this flag is set, and the @code{optional arg} flag is set, then the +option has a special meaning if no argument is given. +@end table + +@item level +This field is defined for options and for groups. It contains an +@emph{unsigned number} that specifies the expert level under which +this group or option should be displayed. The following expert levels +are defined for options (they have analogous meaning for groups): + +@table @code +@item basic (0) +This option should always be offered to the user. + +@item advanced (1) +This option may be offered to advanced users. + +@item expert (2) +This option should only be offered to expert users. + +@item invisible (3) +This option should normally never be displayed, not even to expert +users. + +@item internal (4) +This option is for internal use only. Ignore it. +@end table + +The level of a group will always be the lowest level of all options it +contains. + +@item description +This field is defined for options and groups. The @emph{string} in +this field contains a human-readable description of the option or +group. It can be displayed to the user of the GUI for informational +purposes. It is @emph{percent-escaped} and @emph{localized}. + +@item type +This field is only defined for options. It contains an @emph{unsigned +number} that specifies the type of the option's argument, if any. The +following types are defined: + +Basic types: + +@table @code +@item none (0) +No argument allowed. + +@item string (1) +An @emph{unformatted string}. + +@item int32 (2) +A @emph{signed number}. + +@item uint32 (3) +An @emph{unsigned number}. +@end table + +Complex types: + +@table @code +@item pathname (32) +A @emph{string} that describes the pathname of a file. The file does +not necessarily need to exist. + +@item ldap server (33) +A @emph{string} that describes an LDAP server in the format: + +@code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}} +@end table + +More types will be added in the future. Please see the @var{alt-type} +field for information on how to cope with unknown types. + +@item alt-type +This field is identical to @var{type}, except that only the types +@code{0} to @code{31} are allowed. The GUI is expected to present the +user the option in the format specified by @var{type}. But if the +argument type @var{type} is not supported by the GUI, it can still +display the option in the more generic basic type @var{alt-type}. The +GUI must support all the defined basic types to be able to display all +options. More basic types may be added in future versions. If the +GUI encounters a basic type it doesn't support, it should report an +error and abort the operation. + +@item argname +This field is only defined for options with an argument type +@var{type} that is not @code{0}. In this case it may contain a +@emph{percent-escaped} and @emph{localised string} that gives a short +name for the argument. The field may also be empty, though, in which +case a short name is not known. + +@item default +This field is defined only for options. Its format is that of an +@emph{option argument} (@xref{Format conventions}, for details). If +the default value is empty, then no default is known. Otherwise, the +value specifies the default value for this option. Note that this +field is also meaningful if the option itself does not take a real +argument. + +@item argdef +This field is defined only for options for which the @code{optional +arg} flag is set. If the @code{no arg desc} flag is not set, its +format is that of an @emph{option argument} (@xref{Format +conventions}, for details). If the default value is empty, then no +default is known. Otherwise, the value specifies the default value +for this option. If the @code{no arg desc} flag is set, the field is +either empty or contains a description of the effect of this option if +no argument is given. Note that this field is also meaningful if the +option itself does not take a real argument. + +@item value +This field is defined only for options. Its format is that of an +@emph{option argument}. If it is empty, then the option is not +explicitely set in the current configuration, and the default applies +(if any). Otherwise, it contains the current value of the option. +Note that this field is also meaningful if the option itself does not +take a real argument. +@end table + + +@node Changing options +@subsection Changing options + +The command @w{@code{--change-options @var{component}}} will attempt +to change the options of the component @var{component} to the +specified values. @var{component} must be the string in the field +@var{name} in the output of the @code{--list-components} command. You +have to provide the options that shall be changed in the following +format on standard input: + +@code{@var{name}:@var{flags}:@var{new-value}} + +@table @var +@item name +This is the name of the option to change. @var{name} must be the +string in the field @var{name} in the output of the +@code{--list-options} command. + +@item flags +The flags field contains an @emph{unsigned number}. Its value is the +OR-wise combination of the following flag values: + +@table @code +@item default (16) +If this flag is set, the option is deleted and the default value is +used instead (if applicable). +@end table + +@item new-value +The new value for the option. This field is only defined if the +@code{default} flag is not set. The format is that of an @emph{option +argument}. If it is empty (or the field is omitted), the default +argument is used (only allowed if the argument is optional for this +option). Otherwise, the option will be set to the specified value. +@end table + +Examples: + +To set the force option, which is of basic type @code{none (0)}: + +@example +$ echo 'force:0:1' | gpgconf --change-options dirmngr +@end example + +To delete the force option: + +@example +$ echo 'force:16:' | gpgconf --change-options dirmngr +@end example + +The @code{--runtime} option can influence when the changes take +effect. + +@manpause +@c +@c GPGSM-GENCERT.SH +@c +@node gpgsm-gencert.sh +@section Generate an X.509 certificate request + +This is a simple tool to interactivly generate a certificate request +which will be printed to stdout. + +@noindent +@command{gpgsm-gencert.sh} is invoked as: + +@samp{gpgsm-cencert.sh} + + + +@c +@c GPG-PRESET-PASSPHRASE +@c +@node gpg-preset-passphrase +@section Put a passphrase into the cache. + +The @command{gpg-preset-passphrase} is a utility to seed the internal +cache of a running @command{gpg-agent} with passphrases. It is mainly +useful for unattended machines, where the usual @command{pinentry} tool +may not be used and the passphrases for the to be used keys are given at +machine startup. + +Passphrases set with this utility don't expire unless the +@option{--forget} option is used to explicitly clear them from the cache +--- or @command{gpg-agent} is either restarted or reloaded (by sending a +SIGHUP to it). It is necessary to allow this passphrase presetting by +starting @command{gpg-agent} with the +@option{--allow-preset-passphrase}. + +@menu +* Invoking gpg-preset-passphrase:: List of all commands and options. +@end menu + + +@node Invoking gpg-preset-passphrase +@subsection List of all commands and options. + +@noindent +@command{gpg-preset-passphrase} is invoked this way: + +@example +gpg-preset-passphrase [options] [command] @var{keygrip} +@end example + +@var{keygrip} is a 40 character string of hexadecimal characters +identifying the key for which the passphrase should be set or cleared. +This keygrip is listed along with the key when running the command: +@code{gpgsm --dump-secret-keys}. One of the following command options +must be given: + +@table @gnupgtabopt +@item --preset +Preset a passphrase. This is what you usually will +use. @command{gpg-preset-passphrase} will then read the passphrase from +@code{stdin}. + +@item --forget +Flush the passphrase for the given keygrip from the cache. + +@end table + +@noindent +The following additional options may be used: + +@table @gnupgtabopt +@item -v +@itemx --verbose +@opindex verbose +Output additional information while running. + +@item -P @var{string} +@itemx --passphrase @var{string} +@opindex passphrase +Instead of reading the passphrase from @code{stdin}, use the supplied +@var{string} as passphrase. Note that this makes the passphrase visible +for other users. +@end table + + + + + +@c +@c GPG-CONNECT-AGENT +@c +@node gpg-connect-agent +@section Communicate with a runnig agent. + +The @command{gpg-connect-agent} is a utility to communicate with a +running @command{gpg-agent}. It is useful to check out the commands +gpg-agent provides using the Assuan interface. It might also be useful +for scripting simple applications. Inputis expected at stdin and out +put gets printed to stdout. + +It is very similar to running @command{gpg-agent} in server mode; but +here we connect to a running instance. + +@menu +* Invoking gpg-connect-agent:: List of all commands and options. +@end menu + + +@node Invoking gpg-connect-agent +@subsection List of all commands and options. + +@noindent +@command{gpg-connect-agent} is invoked this way: + +@example +gpg-connect-agent [options] +@end example + +@noindent +The following options may be used: + +@table @gnupgtabopt +@item -v +@itemx --verbose +@opindex verbose +Output additional information while running. + +@item -q +@item --quiet +@opindex q +@opindex quiet +Try to be as quiet as possible. + +@item --homedir @var{dir} +@opindex homedir +Set the name of the home directory to @var{dir}. If his option is not +used, the home directory defaults to @file{~/.gnupg}. It is only +recognized when given on the command line. It also overrides any home +directory stated through the environment variable @env{GNUPGHOME} or +(on W32 systems) by means on the Registry entry +@var{HKCU\Software\GNU\GnuPG:HomeDir}. + + +@item -S +@itemx --raw-socket @var{name} +@opindex S +@opindex raw-socket +Connect to socket @var{name} assuming this is an Assuan style server. +Do not run any special initializations or environment checks. This may +be used to directly connect to any Assuan style socket server. + + +@end table + +@c +@c GPGPARSEMAIL +@c +@node gpgparsemail +@section Parse a mail message into an annotated format + +The @command{gpgparsemail} is a utility currentlu only useful for +debugging. Run it with @code{--help} for usage information. + + + +@c +@c SYMCRYPTRUN +@c +@node symcryptrun +@section Call a simple symmetric encryption tool. + +Sometimes simple encryption tools are already in use for a long time and +there might be a desire to integrate them into the GnuPG framework. The +protocols and encryption methods might be non-standard or not even +properly documented, so that a full-fledged encryption tool with an +interface like gpg is not doable. @command{symcryptrun} provides a +solution: It operates by calling the external encryption/decryption +module and provides a passphrase for a key using the standard +@command{pinentry} based mechanism through @command{gpg-agent}. + +Note, that @command{symcryptrun} is only available if GnuPG has been +configured with @samp{--enable-symcryptrun} at build time. + +@menu +* Invoking symcryptrun:: List of all commands and options. +@end menu + + +@node Invoking symcryptrun +@subsection List of all commands and options. + +@noindent +@command{symcryptrun} is invoked this way: + +@example +symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE + [--decrypt | --encrypt] [inputfile] +@end example + +For encryption, the plain text must be provided on STDIN or as the +argument @var{inputfile}, and the ciphertext will be output to STDOUT. +For decryption vice versa. + +@var{CLASS} describes the calling conventions of the external tool. +Currently it must be given as @samp{confucius}. @var{PROGRAM} is the +the full filename of that external tool. + +For the class @samp{confucius} the option @option{--keyfile} is +required; @var{keyfile} is the name of a file containing the secret key, +which may be protected by a passphrase. For detailed calling +conventions, see the source code. + +@noindent +Note, that @command{gpg-agent} must be running before starting +@command{symcryptrun}. + +@noindent +The following additional options may be used: + +@table @gnupgtabopt +@item -v +@itemx --verbose +@opindex verbose +Output additional information while running. + +@item -q +@item --quiet +@opindex q +@opindex quiet +Try to be as quiet as possible. + +@item --homedir @var{dir} +@opindex homedir +Set the name of the home directory to @var{dir}. If his option is not +used, the home directory defaults to @file{~/.gnupg}. It is only +recognized when given on the command line. It also overrides any home +directory stated through the environment variable @env{GNUPGHOME} or +(on W32 systems) by means on the Registry entry +@var{HKCU\Software\GNU\GnuPG:HomeDir}. + +@item --log-file @var{file} +@opindex log-file +Append all logging output to @var{file}. Default is to write logging +informaton to STDERR. + +@end table + +@noindent +The possible exit status codes of @command{symcryptrun} are: + +@table @code +@item 0 + Success. +@item 1 + Some error occured. +@item 2 + No valid passphrase was provided. +@item 3 + The operation was canceled by the user. + +@end table + |