diff options
Diffstat (limited to 'doc/tools.texi')
| -rw-r--r-- | doc/tools.texi | 2136 |
1 files changed, 2136 insertions, 0 deletions
diff --git a/doc/tools.texi b/doc/tools.texi new file mode 100644 index 0000000..6b9a9fe --- /dev/null +++ b/doc/tools.texi @@ -0,0 +1,2136 @@ +@c Copyright (C) 2004, 2008 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file GnuPG.texi. + +@include defs.inc + +@node Helper Tools +@chapter Helper Tools + +GnuPG comes with a couple of smaller tools: + +@menu +* watchgnupg:: Read logs from a socket. +* gpgv:: Verify OpenPGP signatures. +* addgnupghome:: Create .gnupg home directories. +* gpgconf:: Modify .gnupg home directories. +* applygnupgdefaults:: Run gpgconf for all users. +* gpg-preset-passphrase:: Put a passphrase into the cache. +* gpg-connect-agent:: Communicate with a running agent. +* dirmngr-client:: How to use the Dirmngr client tool. +* gpgparsemail:: Parse a mail message into an annotated format +* gpgtar:: Encrypt or sign files into an archive. +* gpg-check-pattern:: Check a passphrase on stdin against the patternfile. +@end menu + +@c +@c WATCHGNUPG +@c +@manpage watchgnupg.1 +@node watchgnupg +@section Read logs from a socket +@ifset manverb +.B watchgnupg +\- Read and print logs from a socket +@end ifset + +@mansect synopsis +@ifset manverb +.B watchgnupg +.RB [ \-\-force ] +.RB [ \-\-verbose ] +.I socketname +@end ifset + +@mansect description +Most of the main utilities are able to write their 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. This tool is not available for Windows. + + +@noindent +@command{watchgnupg} is commonly invoked as + +@example +watchgnupg --force $(gpgconf --list-dirs socketdir)/S.log +@end example +@manpause + +@noindent +This starts it on the current terminal for listening on the standard +logging socket (which is either @file{~/.gnupg/S.log} or +@file{/var/run/user/UID/gnupg/S.log}). + +@mansect options +@noindent +@command{watchgnupg} understands these options: + +@table @gnupgtabopt + +@item --force +@opindex force +Delete an already existing socket file. + +@anchor{option watchgnupg --tcp} +@item --tcp @var{n} +Instead of reading from a local socket, listen for connects on TCP port +@var{n}. + +@item --time-only +@opindex time-only +Do not print the date part of the timestamp. + +@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. + +@end table + +@noindent +@mansect examples +@chapheading Examples + +@example +$ watchgnupg --force --time-only $(gpgconf --list-dirs socketdir)/S.log +@end example + +This waits for connections on the local socket +(e.g. @file{/home/foo/.gnupg/S.log}) and shows all log entries. To +make this work the option @option{log-file} needs to be used with all +modules which logs are to be shown. The suggested entry for the +configuration files is: + +@example +log-file socket:// +@end example + +If the default socket as given above and returned by "echo $(gpgconf +--list-dirs socketdir)/S.log" is not desired an arbitrary socket name +can be specified, for example @file{socket:///home/foo/bar/mysocket}. +For debugging purposes it is also possible to do remote logging. Take +care if you use this feature because the information is send in the +clear over the network. Use this syntax in the conf files: + +@example +log-file tcp://192.168.1.1:4711 +@end example + +You may use any port and not just 4711 as shown above; only IP +addresses are supported (v4 and v6) and no host names. You need to +start @command{watchgnupg} with the @option{tcp} option. Note that +under Windows the registry entry +@var{HKCU\Software\GNU\GnuPG:DefaultLogFile} can be used to change the +default log output from @code{stderr} to whatever is given by that +entry. However the only useful entry is a TCP name for remote +debugging. + + +@mansect see also +@ifset isman +@command{gpg}(1), +@command{gpgsm}(1), +@command{gpg-agent}(1), +@command{scdaemon}(1) +@end ifset +@include see-also-note.texi + + +@c +@c GPGV +@c +@include gpgv.texi + + +@c +@c ADDGNUPGHOME +@c +@manpage addgnupghome.8 +@node addgnupghome +@section Create .gnupg home directories +@ifset manverb +.B addgnupghome +\- Create .gnupg home directories +@end ifset + +@mansect synopsis +@ifset manverb +.B addgnupghome +.I account_1 +.IR account_2 ... account_n +@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 script helps 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. + +@noindent +@command{addgnupghome} is invoked by root as: + +@example +addgnupghome account1 account2 ... accountn +@end example + + +@c +@c GPGCONF +@c +@manpage gpgconf.1 +@node gpgconf +@section Modify .gnupg home directories +@ifset manverb +.B gpgconf +\- Modify .gnupg home directories +@end ifset + +@mansect synopsis +@ifset manverb +.B gpgconf +.RI [ options ] +.B \-\-list-components +.br +.B gpgconf +.RI [ options ] +.B \-\-list-options +.I component +.br +.B gpgconf +.RI [ options ] +.B \-\-change-options +.I component +@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 GPG, +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 displays 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. + +@menu +* Invoking gpgconf:: List of all commands and options. +* Format conventions:: Formatting conventions relevant for all commands. +* Listing components:: List all gpgconf components. +* Checking programs:: Check all programs known to gpgconf. +* Listing options:: List all options of a component. +* Changing options:: Changing options of a component. +* Listing global options:: List all global options. +* Querying versions:: Get and compare software versions. +* Files used by gpgconf:: What files are used by gpgconf. +@end menu + +@manpause +@node Invoking gpgconf +@subsection Invoking gpgconf + +@mansect commands +One of the following commands must be given: + +@table @gnupgtabopt + +@item --list-components +List all components. This is the default command used if none is +specified. + +@item --check-programs +List all available backend programs and test whether they are runnable. + +@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}. + +@item --check-options @var{component} +Check the options for the component @var{component}. + +@item --apply-profile @var{file} +Apply the configuration settings listed in @var{file} to the +configuration files. If @var{file} has no suffix and no slashes the +command first tries to read a file with the suffix @code{.prf} from +the data directory (@code{gpgconf --list-dirs datadir}) before it +reads the file verbatim. A profile is divided into sections using the +bracketed component name. Each section then lists the option which +shall go into the respective configuration file. + +@item --apply-defaults +Update all configuration files with values taken from the global +configuration file (usually @file{/etc/gnupg/gpgconf.conf}). +Note: This is a legacy mechanism. Please use global configuraion +files instead. + +@item --list-dirs [@var{names}] +@itemx -L +Lists the directories used by @command{gpgconf}. One directory is +listed per line, and each line consists of a colon-separated list where +the first field names the directory type (for example @code{sysconfdir}) +and the second field contains the percent-escaped directory. Although +they are not directories, the socket file names used by +@command{gpg-agent} and @command{dirmngr} are printed as well. Note +that the socket file names and the @code{homedir} lines are the default +names and they may be overridden by command line switches. If +@var{names} are given only the directories or file names specified by +the list names are printed without any escaping. + +@item --list-config [@var{filename}] +List the global configuration file in a colon separated format. If +@var{filename} is given, check that file instead. + +@item --check-config [@var{filename}] +Run a syntax check on the global configuration file. If @var{filename} +is given, check that file instead. + + +@item --query-swdb @var{package_name} [@var{version_string}] +Returns the current version for @var{package_name} and if +@var{version_string} is given also an indicator on whether an update +is available. The actual file with the software version is +automatically downloaded and checked by @command{dirmngr}. +@command{dirmngr} uses a thresholds to avoid download the file too +often and it does this by default only if it can be done via Tor. To +force an update of that file this command can be used: + +@example + gpg-connect-agent --dirmngr 'loadswdb --force' /bye +@end example + +@item --reload [@var{component}] +@itemx -R +@opindex reload +Reload all or the given component. This is basically the same as +sending a SIGHUP to the component. Components which don't support +reloading are ignored. Without @var{component} or by using "all" for +@var{component} all components which are daemons are reloaded. + +@item --launch [@var{component}] +@opindex launch +If the @var{component} is not already running, start it. +@command{component} must be a daemon. This is in general not required +because the system starts these daemons as needed. However, external +software making direct use of @command{gpg-agent} or @command{dirmngr} +may use this command to ensure that they are started. Using "all" for +@var{component} launches all components which are daemons. + +@item --kill [@var{component}] +@itemx -K +@opindex kill +Kill the given component that runs as a daemon, including +@command{gpg-agent}, @command{dirmngr}, and @command{scdaemon}. A +@command{component} which does not run as a daemon will be ignored. +Using "all" for @var{component} kills all components running as +daemons. Note that as of now reload and kill have the same effect for +@command{scdaemon}. + +@item --create-socketdir +@opindex create-socketdir +Create a directory for sockets below /run/user or /var/run/user. This +is command is only required if a non default home directory is used +and the /run based sockets shall be used. For the default home +directory GnUPG creates a directory on the fly. + +@item --remove-socketdir +@opindex remove-socketdir +Remove a directory created with command @option{--create-socketdir}. + +@end table + + +@mansect options + +The following options may be used: + +@table @gnupgtabopt + +@item -o @var{file} +@itemx --output @var{file} +Write output to @var{file}. Default is to write to stdout. + +@item -v +@itemx --verbose +Outputs additional information while running. Specifically, this +extends numerical field values by human-readable descriptions. + +@item -q +@itemx --quiet +@opindex quiet +Try to be as quiet as possible. + +@include opt-homedir.texi + +@item -n +@itemx --dry-run +Do not actually change anything. This is currently only implemented +for @code{--change-options} and can be used 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. + +@item --status-fd @var{n} +@opindex status-fd +Write special status strings to the file descriptor @var{n}. This +program returns the status messages SUCCESS or FAILURE which are +helpful when the caller uses a double fork approach and can't easily +get the return code of the process. + +@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 occurrences 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 localized +Some fields contain strings that are described to be @emph{localized}. +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 @w{boolean value} +Some fields contain a @emph{boolean value}. This is a number with +either the value 0 or 1. 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; checking just the first character is sufficient in this +case. + +@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 string 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 program's 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 @code{--list-components} lists all available +components, one per line. The format of each line is: + +@code{@var{name}:@var{description}:@var{pgmname}:} + +@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}. + +@item pgmname +The @emph{string} in this field contains the absolute name of the +program's file. It can be used to unambiguously invoke that program. +It is @emph{percent-escaped}. +@end table + +Example: +@example +$ gpgconf --list-components +gpg:GPG for OpenPGP:/usr/local/bin/gpg2: +gpg-agent:GPG Agent:/usr/local/bin/gpg-agent: +scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon: +gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm: +dirmngr:Directory Manager:/usr/local/bin/dirmngr: +@end example + + + +@node Checking programs +@subsection Checking programs + +The command @code{--check-programs} is similar to +@code{--list-components} but works on backend programs and not on +components. It runs each program to test whether it is installed and +runnable. This also includes a syntax check of all config file options +of the program. + +The command @code{--check-programs} lists all available +programs, one per line. The format of each line is: + +@code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:} + +@table @var +@item name +This field contains a name tag of the program which is identical to the +name of the component. The name tag is to be used @emph{verbatim}. It +is thus not in any escaped format. This field may be empty to indicate +a continuation of error descriptions for the last name. The description +and pgmname fields are then also empty. + +@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}. + +@item pgmname +The @emph{string} in this field contains the absolute name of the +program's file. It can be used to unambiguously invoke that program. +It is @emph{percent-escaped}. + +@item avail +The @emph{boolean value} in this field indicates whether the program is +installed and runnable. + +@item okay +The @emph{boolean value} in this field indicates whether the program's +config file is syntactically okay. + +@item cfgfile +If an error occurred in the configuration file (as indicated by a false +value in the field @code{okay}), this field has the name of the failing +configuration file. It is @emph{percent-escaped}. + +@item line +If an error occurred in the configuration file, this field has the line +number of the failing statement in the configuration file. +It is an @emph{unsigned number}. + +@item error +If an error occurred in the configuration file, this field has the error +text of the failing statement in the configuration file. It is +@emph{percent-escaped} and @emph{localized}. + +@end table + +@noindent +In the following example the @command{dirmngr} is not runnable and the +configuration file of @command{scdaemon} is not okay. + +@example +$ gpgconf --check-programs +gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1: +gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1: +scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0: +gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1: +dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0: +@end example + +@noindent +The command @w{@code{--check-options @var{component}}} will verify the +configuration file in the same manner as @code{--check-programs}, but +only for the component @var{component}. + + +@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 @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. + +Take care if system-wide options are used: gpgconf may not be able to +properly show the options and the listed options may have no actual +effect in case the system-wide options enforced their own settings. + +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. + +@item no change (128) +If this flag is set, @command{gpgconf} ignores requests to change the +value. GUI frontends should grey out this option. Note, that manual +changes of the configuration files are still possible. +@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}} + +@item key fingerprint (34) +A @emph{string} with a 40 digit fingerprint specifying a certificate. + +@item pub key (35) +A @emph{string} that describes a certificate by user ID, key ID or +fingerprint. + +@item sec key (36) +A @emph{string} that describes a certificate with a key by user ID, +key ID or fingerprint. + +@item alias list (37) +A @emph{string} that describes an alias list, like the one used with +gpg's group option. The list consists of a key, an equal sign and space +separated values. +@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{localized 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 for which the @code{default} or +@code{default desc} flag is set. If the @code{default} flag is set, +its format is that of an @emph{option argument} (@pxref{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{default desc} flag is set, the field is +either empty or contains a description of the effect if the option is +not given. + +@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} (@pxref{Format +conventions}, for details). If the default value is empty, then no +default is known. Otherwise, the value specifies the default argument +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. + +@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 +explicitly 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 (in this case, it contains the number of times +the option appears). +@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 + +@noindent +The output of the command is the same as that of +@code{--check-options} for the modified configuration file. + +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. + + +@node Listing global options +@subsection Listing global options + +Some legacy applications look at the global configuration file for the +gpgconf tool itself; this is the file @file{gpgconf.conf}. Modern +applications should not use it but use per component global +configuration files which are more flexible than the +@file{gpgconf.conf}. Using both files is not suggested. + +The colon separated listing format is record oriented and uses the first +field to identify the record type: + +@table @code +@item k +This describes a key record to start the definition of a new ruleset for +a user/group. The format of a key record is: + + @code{k:@var{user}:@var{group}:} + +@table @var +@item user +This is the user field of the key. It is percent escaped. See the +definition of the gpgconf.conf format for details. + +@item group +This is the group field of the key. It is percent escaped. +@end table + +@item r +This describes a rule record. All rule records up to the next key record +make up a rule set for that key. The format of a rule record is: + + @code{r:::@var{component}:@var{option}:@var{flag}:@var{value}:} + +@table @var +@item component +This is the component part of a rule. It is a plain string. + +@item option +This is the option part of a rule. It is a plain string. + +@item flag +This is the flags part of a rule. There may be only one flag per rule +but by using the same component and option, several flags may be +assigned to an option. It is a plain string. + +@item value +This is the optional value for the option. It is a percent escaped +string with a single quotation mark to indicate a string. The quotation +mark is only required to distinguish between no value specified and an +empty string. +@end table + +@end table + +@noindent +Unknown record types should be ignored. Note that there is intentionally +no feature to change the global option file through @command{gpgconf}. + + +@node Querying versions +@subsection Get and compare software versions. + +The GnuPG Project operates a server to query the current versions of +software packages related to GnuPG. @command{gpgconf} can be used to +access this online database. To allow for offline operations, this +feature works by having @command{dirmngr} download a file from +@code{https://versions.gnupg.org}, checking the signature of that file +and storing the file in the GnuPG home directory. If +@command{gpgconf} is used and @command{dirmngr} is running, it may ask +@command{dirmngr} to refresh that file before itself uses the file. + +The command @option{--query-swdb} returns information for the given +package in a colon delimited format: + +@table @var + +@item name +This is the name of the package as requested. Note that "gnupg" is a +special name which is replaced by the actual package implementing this +version of GnuPG. For this name it is also not required to specify a +version because @command{gpgconf} takes its own version in this case. + +@item iversion +The currently installed version or an empty string. The value is +taken from the command line argument but may be provided by gpg +if not given. + +@item status +The status of the software package according to this table: +@table @code +@item - +No information available. This is either because no current version +has been specified or due to an error. +@item ? +The given name is not known in the online database. +@item u +An update of the software is available. +@item c +The installed version of the software is current. +@item n +The installed version is already newer than the released version. +@end table + +@item urgency +If the value (the empty string should be considered as zero) is +greater than zero an important update is available. + +@item error +This returns an @command{gpg-error} error code to distinguish between +various failure modes. + +@item filedate +This gives the date of the file with the version numbers in standard +ISO format (@code{yyyymmddThhmmss}). The date has been extracted by +@command{dirmngr} from the signature of the file. + +@item verified +This gives the date in ISO format the file was downloaded. This value +can be used to evaluate the freshness of the information. + +@item version +This returns the version string for the requested software from the +file. + +@item reldate +This returns the release date in ISO format. + +@item size +This returns the size of the package as decimal number of bytes. + +@item hash +This returns a hexified SHA-2 hash of the package. + +@end table + +@noindent +More fields may be added in future to the output. + + +@mansect files +@node Files used by gpgconf +@subsection Files used by gpgconf + +@table @file + +@item /etc/gnupg/gpgconf.conf +@cindex gpgconf.conf + If this file exists, it is processed as a global configuration file. + This is a legacy mechanism which should not be used tigether with + the modern global per component configuration files. A commented + example can be found in the @file{examples} directory of the + distribution. + +@item @var{GNUPGHOME}/swdb.lst +@cindex swdb.lst + A file with current software versions. @command{dirmngr} creates + this file on demand from an online resource. + +@end table + + +@mansect see also +@ifset isman +@command{gpg}(1), +@command{gpgsm}(1), +@command{gpg-agent}(1), +@command{scdaemon}(1), +@command{dirmngr}(1) +@end ifset +@include see-also-note.texi + + + +@c +@c APPLYGNUPGDEFAULTS +@c +@manpage applygnupgdefaults.8 +@node applygnupgdefaults +@section Run gpgconf for all users +@ifset manverb +.B applygnupgdefaults +\- Run gpgconf --apply-defaults for all users. +@end ifset + +@mansect synopsis +@ifset manverb +.B applygnupgdefaults +@end ifset + +@mansect description +This is a legacy script. Modern application should use the per +component global configuration files under @file{/etc/gnupg/}. + +This script is a wrapper around @command{gpgconf} to run it with the +command @code{--apply-defaults} for all real users with an existing +GnuPG home directory. Admins might want to use this script to update he +GnuPG configuration files for all users after +@file{/etc/gnupg/gpgconf.conf} has been changed. This allows enforcing +certain policies for all users. Note, that this is not a bulletproof way to +force a user to use certain options. A user may always directly edit +the configuration files and bypass gpgconf. + +@noindent +@command{applygnupgdefaults} is invoked by root as: + +@example +applygnupgdefaults +@end example + + +@c +@c GPG-PRESET-PASSPHRASE +@c +@node gpg-preset-passphrase +@section Put a passphrase into the cache +@manpage gpg-preset-passphrase.1 +@ifset manverb +.B gpg-preset-passphrase +\- Put a passphrase into gpg-agent's cache +@end ifset + +@mansect synopsis +@ifset manverb +.B gpg-preset-passphrase +.RI [ options ] +.RI [ command ] +.I cache-id +@end ifset + +@mansect description +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. + +This program works with GnuPG 2 and later. GnuPG 1.x is not supported. + +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). Note that the maximum cache time as set with +@option{--max-cache-ttl} is still honored. 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 + +@manpause +@node Invoking gpg-preset-passphrase +@subsection List of all commands and options +@mancont + +@noindent +@command{gpg-preset-passphrase} is invoked this way: + +@example +gpg-preset-passphrase [options] [command] @var{cacheid} +@end example + +@var{cacheid} is either a 40 character keygrip of hexadecimal +characters identifying the key for which the passphrase should be set +or cleared. The keygrip is listed along with the key when running the +command: @code{gpgsm --with-keygrip --list-secret-keys}. +Alternatively an arbitrary string may be used to identify a +passphrase; it is suggested that such a string is prefixed with the +name of the application (e.g @code{foo:12346}). Scripts should always +use the option @option{--with-colons}, which provides the keygrip in a +"grp" line (cf. @file{doc/DETAILS})/ + +@noindent +One of the following command options must be given: + +@table @gnupgtabopt +@item --preset +@opindex 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 +@opindex forget +Flush the passphrase for the given cache ID 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 + +@mansect see also +@ifset isman +@command{gpg}(1), +@command{gpgsm}(1), +@command{gpg-agent}(1), +@command{scdaemon}(1) +@end ifset +@include see-also-note.texi + + + + +@c +@c GPG-CONNECT-AGENT +@c +@node gpg-connect-agent +@section Communicate with a running agent +@manpage gpg-connect-agent.1 +@ifset manverb +.B gpg-connect-agent +\- Communicate with a running agent +@end ifset + +@mansect synopsis +@ifset manverb +.B gpg-connect-agent +.RI [ options ] [commands] +@end ifset + +@mansect description +The @command{gpg-connect-agent} is a utility to communicate with a +running @command{gpg-agent}. It is useful to check out the commands +@command{gpg-agent} provides using the Assuan interface. It might +also be useful for scripting simple applications. Input is expected +at stdin and output 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 options. +* Controlling gpg-connect-agent:: Control commands. +@end menu + +@manpause +@node Invoking gpg-connect-agent +@subsection List of all options + +@noindent +@command{gpg-connect-agent} is invoked this way: + +@example +gpg-connect-agent [options] [commands] +@end example +@mancont + +@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. + +@include opt-homedir.texi + +@item --agent-program @var{file} +@opindex agent-program +Specify the agent program to be started if none is running. The +default value is determined by running @command{gpgconf} with the +option @option{--list-dirs}. Note that the pipe symbol (@code{|}) is +used for a regression test suite hack and may thus not be used in the +file name. + +@item --dirmngr-program @var{file} +@opindex dirmngr-program +Specify the directory manager (keyserver client) program to be started +if none is running. This has only an effect if used together with the +option @option{--dirmngr}. + +@item --dirmngr +@opindex dirmngr +Connect to a running directory manager (keyserver client) instead of +to the gpg-agent. If a dirmngr is not running, start it. + +@item -S +@itemx --raw-socket @var{name} +@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. + +@item -E +@itemx --exec +@opindex exec +Take the rest of the command line as a program and it's arguments and +execute it as an Assuan server. Here is how you would run @command{gpgsm}: +@smallexample + gpg-connect-agent --exec gpgsm --server +@end smallexample +Note that you may not use options on the command line in this case. + +@item --no-ext-connect +@opindex no-ext-connect +When using @option{-S} or @option{--exec}, @command{gpg-connect-agent} +connects to the Assuan server in extended mode to allow descriptor +passing. This option makes it use the old mode. + +@item --no-autostart +@opindex no-autostart +Do not start the gpg-agent or the dirmngr if it has not yet been +started. + +@item -r @var{file} +@itemx --run @var{file} +@opindex run +Run the commands from @var{file} at startup and then continue with the +regular input method. Note, that commands given on the command line are +executed after this file. + +@item -s +@itemx --subst +@opindex subst +Run the command @code{/subst} at startup. + +@item --hex +@opindex hex +Print data lines in a hex format and the ASCII representation of +non-control characters. + +@item --decode +@opindex decode +Decode data lines. That is to remove percent escapes but make sure that +a new line always starts with a D and a space. + +@end table + +@mansect control commands +@node Controlling gpg-connect-agent +@subsection Control commands + +While reading Assuan commands, gpg-agent also allows a few special +commands to control its operation. These control commands all start +with a slash (@code{/}). + +@table @code + +@item /echo @var{args} +Just print @var{args}. + +@item /let @var{name} @var{value} +Set the variable @var{name} to @var{value}. Variables are only +substituted on the input if the @command{/subst} has been used. +Variables are referenced by prefixing the name with a dollar sign and +optionally include the name in curly braces. The rules for a valid name +are identically to those of the standard bourne shell. This is not yet +enforced but may be in the future. When used with curly braces no +leading or trailing white space is allowed. + +If a variable is not found, it is searched in the environment and if +found copied to the table of variables. + +Variable functions are available: The name of the function must be +followed by at least one space and the at least one argument. The +following functions are available: + +@table @code +@item get +Return a value described by the argument. Available arguments are: + +@table @code +@item cwd +The current working directory. +@item homedir +The gnupg homedir. +@item sysconfdir +GnuPG's system configuration directory. +@item bindir +GnuPG's binary directory. +@item libdir +GnuPG's library directory. +@item libexecdir +GnuPG's library directory for executable files. +@item datadir +GnuPG's data directory. +@item serverpid +The PID of the current server. Command @command{/serverpid} must +have been given to return a useful value. +@end table + +@item unescape @var{args} +Remove C-style escapes from @var{args}. Note that @code{\0} and +@code{\x00} terminate the returned string implicitly. The string to be +converted are the entire arguments right behind the delimiting space of +the function name. + +@item unpercent @var{args} +@itemx unpercent+ @var{args} +Remove percent style escaping from @var{args}. Note that @code{%00} +terminates the string implicitly. The string to be converted are the +entire arguments right behind the delimiting space of the function +name. @code{unpercent+} also maps plus signs to a spaces. + +@item percent @var{args} +@itemx percent+ @var{args} +Escape the @var{args} using percent style escaping. Tabs, formfeeds, +linefeeds, carriage returns and colons are escaped. @code{percent+} also +maps spaces to plus signs. + +@item errcode @var{arg} +@itemx errsource @var{arg} +@itemx errstring @var{arg} +Assume @var{arg} is an integer and evaluate it using @code{strtol}. Return +the gpg-error error code, error source or a formatted string with the +error code and error source. + + +@item + +@itemx - +@itemx * +@itemx / +@itemx % +Evaluate all arguments as long integers using @code{strtol} and apply +this operator. A division by zero yields an empty string. + +@item ! +@itemx | +@itemx & +Evaluate all arguments as long integers using @code{strtol} and apply +the logical operators NOT, OR or AND. The NOT operator works on the +last argument only. + + +@end table + + +@item /definq @var{name} @var{var} +Use content of the variable @var{var} for inquiries with @var{name}. +@var{name} may be an asterisk (@code{*}) to match any inquiry. + + +@item /definqfile @var{name} @var{file} +Use content of @var{file} for inquiries with @var{name}. +@var{name} may be an asterisk (@code{*}) to match any inquiry. + +@item /definqprog @var{name} @var{prog} +Run @var{prog} for inquiries matching @var{name} and pass the +entire line to it as command line arguments. + +@item /datafile @var{name} +Write all data lines from the server to the file @var{name}. The file +is opened for writing and created if it does not exists. An existing +file is first truncated to 0. The data written to the file fully +decoded. Using a single dash for @var{name} writes to stdout. The +file is kept open until a new file is set using this command or this +command is used without an argument. + +@item /showdef +Print all definitions + +@item /cleardef +Delete all definitions + +@item /sendfd @var{file} @var{mode} +Open @var{file} in @var{mode} (which needs to be a valid @code{fopen} +mode string) and send the file descriptor to the server. This is +usually followed by a command like @code{INPUT FD} to set the +input source for other commands. + +@item /recvfd +Not yet implemented. + +@item /open @var{var} @var{file} [@var{mode}] +Open @var{file} and assign the file descriptor to @var{var}. Warning: +This command is experimental and might change in future versions. + +@item /close @var{fd} +Close the file descriptor @var{fd}. Warning: This command is +experimental and might change in future versions. + +@item /showopen +Show a list of open files. + +@item /serverpid +Send the Assuan command @command{GETINFO pid} to the server and store +the returned PID for internal purposes. + +@item /sleep +Sleep for a second. + +@item /hex +@itemx /nohex +Same as the command line option @option{--hex}. + +@item /decode +@itemx /nodecode +Same as the command line option @option{--decode}. + +@item /subst +@itemx /nosubst +Enable and disable variable substitution. It defaults to disabled +unless the command line option @option{--subst} has been used. +If /subst as been enabled once, leading whitespace is removed from +input lines which makes scripts easier to read. + +@item /while @var{condition} +@itemx /end +These commands provide a way for executing loops. All lines between +the @code{while} and the corresponding @code{end} are executed as long +as the evaluation of @var{condition} yields a non-zero value or is the +string @code{true} or @code{yes}. The evaluation is done by passing +@var{condition} to the @code{strtol} function. Example: + +@smallexample + /subst + /let i 3 + /while $i + /echo loop counter is $i + /let i $@{- $i 1@} + /end +@end smallexample + +@item /if @var{condition} +@itemx /end +These commands provide a way for conditional execution. All lines between +the @code{if} and the corresponding @code{end} are executed only if +the evaluation of @var{condition} yields a non-zero value or is the +string @code{true} or @code{yes}. The evaluation is done by passing +@var{condition} to the @code{strtol} function. + +@item /run @var{file} +Run commands from @var{file}. + +@item /bye +Terminate the connection and the program. + +@item /help +Print a list of available control commands. + +@end table + + +@ifset isman +@mansect see also +@command{gpg-agent}(1), +@command{scdaemon}(1) +@include see-also-note.texi +@end ifset + +@c +@c DIRMNGR-CLIENT +@c +@node dirmngr-client +@section The Dirmngr Client Tool + +@manpage dirmngr-client.1 +@ifset manverb +.B dirmngr-client +\- Tool to access the Dirmngr services +@end ifset + +@mansect synopsis +@ifset manverb +.B dirmngr-client +.RI [ options ] +.RI [ certfile | pattern ] +@end ifset + +@mansect description +The @command{dirmngr-client} is a simple tool to contact a running +dirmngr and test whether a certificate has been revoked --- either by +being listed in the corresponding CRL or by running the OCSP protocol. +If no dirmngr is running, a new instances will be started but this is +in general not a good idea due to the huge performance overhead. + +@noindent +The usual way to run this tool is either: + +@example +dirmngr-client @var{acert} +@end example + +@noindent +or + +@example +dirmngr-client <@var{acert} +@end example + +Where @var{acert} is one DER encoded (binary) X.509 certificates to be +tested. +@ifclear isman +The return value of this command is +@end ifclear + +@mansect return value +@ifset isman +@command{dirmngr-client} returns these values: +@end ifset +@table @code + +@item 0 +The certificate under question is valid; i.e. there is a valid CRL +available and it is not listed there or the OCSP request returned that +that certificate is valid. + +@item 1 +The certificate has been revoked + +@item 2 (and other values) +There was a problem checking the revocation state of the certificate. +A message to stderr has given more detailed information. Most likely +this is due to a missing or expired CRL or due to a network problem. + +@end table + +@mansect options +@noindent +@command{dirmngr-client} may be called with the following options: + + +@table @gnupgtabopt +@item --version +@opindex version +Print the program version and licensing information. Note that you cannot +abbreviate this command. + +@item --help, -h +@opindex help +Print a usage message summarizing the most useful command-line options. +Note that you cannot abbreviate this command. + +@item --quiet, -q +@opindex quiet +Make the output extra brief by suppressing any informational messages. + +@item -v +@item --verbose +@opindex v +@opindex verbose +Outputs additional information while running. +You can increase the verbosity by giving several +verbose commands to @sc{dirmngr}, such as @samp{-vv}. + +@item --pem +@opindex pem +Assume that the given certificate is in PEM (armored) format. + +@item --ocsp +@opindex ocsp +Do the check using the OCSP protocol and ignore any CRLs. + +@item --force-default-responder +@opindex force-default-responder +When checking using the OCSP protocol, force the use of the default OCSP +responder. That is not to use the Reponder as given by the certificate. + +@item --ping +@opindex ping +Check whether the dirmngr daemon is up and running. + +@item --cache-cert +@opindex cache-cert +Put the given certificate into the cache of a running dirmngr. This is +mainly useful for debugging. + +@item --validate +@opindex validate +Validate the given certificate using dirmngr's internal validation code. +This is mainly useful for debugging. + +@item --load-crl +@opindex load-crl +This command expects a list of filenames with DER encoded CRL files. +With the option @option{--url} URLs are expected in place of filenames +and they are loaded directly from the given location. All CRLs will be +validated and then loaded into dirmngr's cache. + +@item --lookup +@opindex lookup +Take the remaining arguments and run a lookup command on each of them. +The results are Base-64 encoded outputs (without header lines). This +may be used to retrieve certificates from a server. However the output +format is not very well suited if more than one certificate is returned. + +@item --url +@itemx -u +@opindex url +Modify the @command{lookup} and @command{load-crl} commands to take an URL. + +@item --local +@itemx -l +@opindex url +Let the @command{lookup} command only search the local cache. + +@item --squid-mode +@opindex squid-mode +Run @sc{dirmngr-client} in a mode suitable as a helper program for +Squid's @option{external_acl_type} option. + + +@end table + +@ifset isman +@mansect see also +@command{dirmngr}(8), +@command{gpgsm}(1) +@include see-also-note.texi +@end ifset + + +@c +@c GPGPARSEMAIL +@c +@node gpgparsemail +@section Parse a mail message into an annotated format + +@manpage gpgparsemail.1 +@ifset manverb +.B gpgparsemail +\- Parse a mail message into an annotated format +@end ifset + +@mansect synopsis +@ifset manverb +.B gpgparsemail +.RI [ options ] +.RI [ file ] +@end ifset + +@mansect description +The @command{gpgparsemail} is a utility currently only useful for +debugging. Run it with @code{--help} for usage information. + + + +@c +@c GPGTAR +@c +@manpage gpgtar.1 +@node gpgtar +@section Encrypt or sign files into an archive +@ifset manverb +.B gpgtar +\- Encrypt or sign files into an archive +@end ifset + +@mansect synopsis +@ifset manverb +.B gpgtar +.RI [ options ] +.I filename1 +.I [ filename2, ... ] +.I directory1 +.I [ directory2, ... ] +@end ifset + +@mansect description +@command{gpgtar} encrypts or signs files into an archive. It is an +gpg-ized tar using the same format as used by PGP's PGP Zip. + +@manpause +@noindent +@command{gpgtar} is invoked this way: + +@example +gpgtar [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...] +@end example + +@mansect options +@noindent +@command{gpgtar} understands these options: + +@table @gnupgtabopt + +@item --create +@opindex create +Put given files and directories into a vanilla ``ustar'' archive. + +@item --extract +@opindex extract +Extract all files from a vanilla ``ustar'' archive. + +@item --encrypt +@itemx -e +@opindex encrypt +Encrypt given files and directories into an archive. This option may +be combined with option @option{--symmetric} for an archive that may +be decrypted via a secret key or a passphrase. + +@item --decrypt +@itemx -d +@opindex decrypt +Extract all files from an encrypted archive. + +@item --sign +@itemx -s +Make a signed archive from the given files and directories. This can +be combined with option @option{--encrypt} to create a signed and then +encrypted archive. + +@item --list-archive +@itemx -t +@opindex list-archive +List the contents of the specified archive. + +@item --symmetric +@itemx -c +Encrypt with a symmetric cipher using a passphrase. The default +symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the +@option{--cipher-algo} option to @command{gpg}. + +@item --recipient @var{user} +@itemx -r @var{user} +@opindex recipient +Encrypt for user id @var{user}. For details see @command{gpg}. + +@item --local-user @var{user} +@itemx -u @var{user} +@opindex local-user +Use @var{user} as the key to sign with. For details see @command{gpg}. + +@item --output @var{file} +@itemx -o @var{file} +@opindex output +Write the archive to the specified file @var{file}. + +@item --verbose +@itemx -v +@opindex verbose +Enable extra informational output. + +@item --quiet +@itemx -q +@opindex quiet +Try to be as quiet as possible. + +@item --skip-crypto +@opindex skip-crypto +Skip all crypto operations and create or extract vanilla ``ustar'' +archives. + +@item --dry-run +@opindex dry-run +Do not actually output the extracted files. + +@item --directory @var{dir} +@itemx -C @var{dir} +@opindex directory +Extract the files into the directory @var{dir}. The default is to +take the directory name from the input filename. If no input filename +is known a directory named @file{GPGARCH} is used. For tarball +creation, switch to directory @var{dir} before performing any +operations. + +@item --files-from @var{file} +@itemx -T @var{file} +Take the file names to work from the file @var{file}; one file per +line. + +@item --null +@opindex null +Modify option @option{--files-from} to use a binary nul instead of a +linefeed to separate file names. + +@item --utf8-strings +@opindex utf8-strings +Assume that the file names read by @option{--files-from} are UTF-8 +encoded. This option has an effect only on Windows where the active +code page is otherwise assumed. + +@item --openpgp +@opindex openpgp +This option has no effect because OpenPGP encryption and signing is +the default. + +@item --cms +@opindex cms +This option is reserved and shall not be used. It will eventually be +used to encrypt or sign using the CMS protocol; but that is not yet +implemented. + +@item --batch +@opindex batch +Use batch mode. Never ask but use the default action. This option is +passed directly to @command{gpg}. + +@item --yes +@opindex yes +Assume "yes" on most questions. Often used together with +@option{--batch} to overwrite existing files. This option is passed +directly to @command{gpg}. + +@item --no +@opindex no +Assume "no" on most questions. This option is passed directly to +@command{gpg}. + +@item --require-compliance +@opindex require-compliance +This option is passed directly to @command{gpg}. + +@item --status-fd @var{n} +@opindex status-fd +Write special status strings to the file descriptor @var{n}. +See the file DETAILS in the documentation for a listing of them. + +@item --with-log +@opindex with-log +When extracting an encrypted tarball also write a log file with the +gpg output to a file named after the extraction directory with the +suffix ".log". + +@item --set-filename @var{file} +@opindex set-filename +Use the last component of @var{file} as the output directory. The +default is to take the directory name from the input filename. If no +input filename is known a directory named @file{GPGARCH} is used. +This option is deprecated in favor of option @option{--directory}. + +@item --gpg @var{gpgcmd} +@opindex gpg +Use the specified command @var{gpgcmd} instead of @command{gpg}. + +@item --gpg-args @var{args} +@opindex gpg-args +Pass the specified extra options to @command{gpg}. + +@item --tar-args @var{args} +@opindex tar-args +Assume @var{args} are standard options of the command @command{tar} +and parse them. The only supported tar options are "--directory", +"--files-from", and "--null" This is an obsolete options because those +supported tar options can also be given directly. + +@item --version +@opindex version +Print version of the program and exit. + +@item --help +@opindex help +Display a brief help page and exit. + +@end table + +@mansect diagnostics +@noindent +The program returns 0 if everything was fine, 1 otherwise. + + +@mansect examples +@ifclear isman +@noindent +Some examples: + +@end ifclear +@noindent +Encrypt the contents of directory @file{mydocs} for user Bob to file +@file{test1}: + +@example +gpgtar --encrypt --output test1 -r Bob mydocs +@end example + +@noindent +List the contents of archive @file{test1}: + +@example +gpgtar --list-archive test1 +@end example + + +@mansect see also +@ifset isman +@command{gpg}(1), +@command{tar}(1), +@end ifset +@include see-also-note.texi + +@c +@c GPG-CHECK-PATTERN +@c +@manpage gpg-check-pattern.1 +@node gpg-check-pattern +@section Check a passphrase on stdin against the patternfile +@ifset manverb +.B gpg-check-pattern +\- Check a passphrase on stdin against the patternfile +@end ifset + +@mansect synopsis +@ifset manverb +.B gpg\-check\-pattern +.RI [ options ] +.I patternfile +@end ifset + +@mansect description +@command{gpg-check-pattern} checks a passphrase given on stdin against +a specified pattern file. + +The pattern file is line based with comment lines beginning on the +@emph{first} position with a @code{#}. Empty lines and lines with +only white spaces are ignored. The actual pattern lines may either be +verbatim string pattern and match as they are (trailing spaces are +ignored) or extended regular expressions indicated by a @code{/} or +@code{!/} in the first column and terminated by another @code{/} or +end of line. If a regular expression starts with @code{!/} the match +result is reversed. By default all comparisons are case insensitive. + +Tag lines may be used to further control the operation of this tool. +The currently defined tags are: + +@table @code +@item [icase] +Switch to case insensitive comparison for all further patterns. This +is the default. + +@item [case] +Switch to case sensitive comparison for all further patterns. + +@item [reject] +Switch to reject mode. This is the default mode. + +@item [accept] +Switch to accept mode. +@end table + +In the future more tags may be introduced and thus it is advisable not to +start a plain pattern string with an open bracket. The tags must be +given verbatim on the line with no spaces to the left or any non white +space characters to the right. + +In reject mode the program exits on the first match with an exit code +of 1 (failure). If at the end of the pattern list the reject mode is +still active the program exits with code 0 (success). + +In accept mode blocks of patterns are used. A block starts at the +next pattern after an "accept" tag and ends with the last pattern +before the next "accept" or "reject" tag or at the end of the pattern +list. If all patterns in a block match the program exits with an exit +code of 0 (success). If any pattern in a block do not match the next +pattern block is evaluated. If at the end of the pattern list the +accept mode is still active the program exits with code 1 (failure). + + +@mansect options +@noindent + +@table @gnupgtabopt + +@item --verbose +@opindex verbose +Enable extra informational output. + +@item --check +@opindex check +Run only a syntax check on the patternfile. + +@item --null +@opindex null +Input is expected to be null delimited. + +@end table + +@mansect see also +@ifset isman +@command{gpg-agent}(1), +@end ifset +@include see-also-note.texi |