mirror of
git://git.gnupg.org/gnupg.git
synced 2024-09-06 12:46:22 +02:00
2250 lines
68 KiB
Plaintext
2250 lines
68 KiB
Plaintext
@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
|
|
@end example
|
|
|
|
which is a shorthand for
|
|
|
|
@example
|
|
watchgnupg --force $(gpgconf --list-dirs socketdir)/S.log
|
|
@end example
|
|
|
|
To watch GnuPG running with a different home directory, use
|
|
|
|
@example
|
|
watchgnupg --homedir DIR
|
|
@end example
|
|
@manpause
|
|
|
|
@noindent
|
|
This starts it on the current terminal for listening on the standard
|
|
logging socket (this is commonly @file{/var/run/user/UID/gnupg/S.log}
|
|
or if no such user directory hierarchy exists @file{~/.gnupg/S.log}).
|
|
|
|
@mansect options
|
|
@noindent
|
|
@command{watchgnupg} understands these options:
|
|
|
|
@table @gnupgtabopt
|
|
|
|
@item --force
|
|
@opindex force
|
|
Delete an already existing socket file. This option is implicitly used
|
|
if no socket name has been given on the command line.
|
|
|
|
@item --homedir @var{DIR}
|
|
If no socket name is given on the command line, pass @var{DIR} to
|
|
gpgconf so that the socket for a GnuPG running with DIR has its home
|
|
directory is used. Note that the environment variable @var{GNUPGHOME}
|
|
is ignored by watchgnupg.
|
|
|
|
@anchor{option watchgnupg --tcp}
|
|
@item --tcp @var{n}
|
|
Instead of reading from a local socket, listen for connects on TCP
|
|
port @var{n}. A Unix domain socket can optionally also be given as a
|
|
second source. This option does not use a default socket name.
|
|
|
|
@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 --time-only
|
|
@end example
|
|
|
|
This waits for connections on the local socket
|
|
(e.g. @file{/var/run/user/1234/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 configuration
|
|
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}.
|
|
|
|
@item --unlock @var{name}
|
|
@itemx --lock @var{name}
|
|
Remove a stale lock file hold for @file{file}. The file is
|
|
expected in the current GnuPG home directory. This command is usually
|
|
not required because GnuPG is able to detect and remove stale lock
|
|
files. Before using the command make sure that the file protected by
|
|
the lock file is actually not in use. The lock command may be used to
|
|
lock an accidently removed lock file. Note that the commands have no
|
|
effect on Windows because the mere existence of a lock file does not
|
|
mean that the lock is active.
|
|
|
|
@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 --chuid @var{uid}
|
|
@opindex chuid
|
|
Change the current user to @var{uid} which may either be a number or a
|
|
name. This can be used from the root account to get information on
|
|
the GnuPG environment of the specified user or to start or kill
|
|
daemons. If @var{uid} is not the current UID a standard PATH is set
|
|
and the envvar GNUPGHOME is unset. To override the latter the option
|
|
@option{--homedir} can be used. This option has currently no effect
|
|
on Windows.
|
|
|
|
@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.
|
|
|
|
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 gpgconf.ctl
|
|
@cindex gpgconf.ctl
|
|
Under Unix @file{gpgconf.ctl} may be used to change some of the
|
|
compiled in directories where the GnuPG components are expected. This
|
|
file is expected in the same directory as @file{gpgconf}. The
|
|
physical installation directories are evaluated and no symlinks.
|
|
Blank lines and lines starting with pound sign are ignored in the
|
|
file. The keywords must be followed by optional white space, an equal
|
|
sign, optional white space, and the value. Environment variables are
|
|
substituted in standard shell manner, the final value must start with
|
|
a slash, trailing slashes are stripped. Valid keywords are
|
|
@code{rootdir}, @code{sysconfdir}, @code{socketdir}, and
|
|
@code{.enable}. No errors are printed for unknown keywords. The
|
|
@code{.enable} keyword is special: if the keyword is used and its
|
|
value evaluates to true the entire file is ignored.
|
|
|
|
Under Windows this file is used to install GnuPG as a portable
|
|
application. An empty file named @file{gpgconf.ctl} is expected in
|
|
the same directory as the tool @file{gpgconf.exe}. The root of the
|
|
installation is then that directory; or, if @file{gpgconf.exe} has
|
|
been installed directly below a directory named @file{bin}, its parent
|
|
directory. You also need to make sure that the following directories
|
|
exist and are writable: @file{ROOT/home} for the GnuPG home and
|
|
@file{ROOT@value{LOCALCACHEDIR}} for internal cache files.
|
|
|
|
|
|
@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 together 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 --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 --keyboxd
|
|
@opindex keyboxd
|
|
Connect to a running keybox daemon instead of
|
|
to the gpg-agent. If a keyboxd 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 -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 --chuid @var{uid}
|
|
@opindex chuid
|
|
Change the current user to @var{uid} which may either be a number or a
|
|
name. This can be used from the root account to run gpg-connect-agent
|
|
for another user. If @var{uid} is not the current UID a standard PATH
|
|
is set and the envvar GNUPGHOME is unset. To override the latter the
|
|
option @option{--homedir} can be used. This option has only an effect
|
|
when used on the command line. This option has currently no effect at
|
|
all on Windows.
|
|
|
|
@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 --no-history
|
|
@opindex --no-history
|
|
In interactive mode the command line history is usually saved and
|
|
restored to and from a file below the GnuPG home directory. This
|
|
option inhibits the use of that file.
|
|
|
|
@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 --keyboxd-program @var{file}
|
|
@opindex keyboxd-program
|
|
Specify the keybox daemon program to be started if none is running.
|
|
This has only an effect if used together with the option
|
|
@option{--keyboxd}.
|
|
|
|
@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.
|
|
|
|
@item -u
|
|
@itemx --unbuffered
|
|
@opindex unbuffered
|
|
Set stdin and stdout into unbuffered I/O mode. This this sometimes
|
|
useful for scripting.
|
|
|
|
|
|
@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 /history --clear
|
|
Clear the command history.
|
|
|
|
@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.
|
|
If no file name is given (or it is "-") the archive is taken from
|
|
stdin.
|
|
|
|
@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. If no file name is given
|
|
(or it is "-") the archive is taken from stdin.
|
|
|
|
@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. If no file name is given
|
|
(or it is "-") the archive is taken from stdin.
|
|
|
|
@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 --no-compress
|
|
@opindex no-compress
|
|
This option tells gpg to disable compression (i.e. using option -z0).
|
|
It is useful for archiving only large files which are are already
|
|
compressed (e.g. a set of videos).
|
|
|
|
@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 --tar @var{command}
|
|
@opindex tar
|
|
This is a dummy option for backward compatibility.
|
|
@c ... to the gpg-zip script we provided in the past
|
|
|
|
@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
|