Page MenuHome GnuPG
Files F20064540

No OneTemporary
Actions

View Options

diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
index 37774dde2..cd5d7518d 100644
--- a/doc/gpg-agent.texi
+++ b/doc/gpg-agent.texi
@@ -1,1505 +1,1505 @@
@c Copyright (C) 2002 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 Invoking GPG-AGENT
@chapter Invoking GPG-AGENT
@cindex GPG-AGENT command options
@cindex command options
@cindex options, GPG-AGENT command
@manpage gpg-agent.1
@ifset manverb
.B gpg-agent
\- Secret key management for GnuPG
@end ifset
@mansect synopsis
@ifset manverb
.B gpg-agent
.RB [ \-\-homedir
.IR dir ]
.RB [ \-\-options
.IR file ]
.RI [ options ]
.br
.B gpg-agent
.RB [ \-\-homedir
.IR dir ]
.RB [ \-\-options
.IR file ]
.RI [ options ]
.B \-\-server
.br
.B gpg-agent
.RB [ \-\-homedir
.IR dir ]
.RB [ \-\-options
.IR file ]
.RI [ options ]
.B \-\-daemon
.RI [ command_line ]
@end ifset
@mansect description
@command{gpg-agent} is a daemon to manage secret (private) keys
independently from any protocol. It is used as a backend for
@command{gpg} and @command{gpgsm} as well as for a couple of other
utilities.
The agent is automatically started on demand by @command{gpg},
@command{gpgsm}, @command{gpgconf}, or @command{gpg-connect-agent}.
Thus there is no reason to start it manually. In case you want to use
the included Secure Shell Agent you may start the agent using:
@c From dkg on gnupg-devel on 2016-04-21:
@c
@c Here's an attempt at writing a short description of the goals of an
@c isolated cryptographic agent:
@c
@c A cryptographic agent should control access to secret key material.
@c The agent permits use of the secret key material by a supplicant
@c without providing a copy of the secret key material to the supplicant.
@c
@c An isolated cryptographic agent separates the request for use of
@c secret key material from permission for use of secret key material.
@c That is, the system or process requesting use of the key (the
@c "supplicant") can be denied use of the key by the owner/operator of
@c the agent (the "owner"), which the supplicant has no control over.
@c
@c One way of enforcing this split is a per-key or per-session
@c passphrase, known only by the owner, which must be supplied to the
@c agent to permit the use of the secret key material. Another way is
@c with an out-of-band permission mechanism (e.g. a button or GUI
@c interface that the owner has access to, but the supplicant does not).
@c
@c The rationale for this separation is that it allows access to the
@c secret key to be tightly controled and audited, and it doesn't permit
@c the the supplicant to either copy the key or to override the owner's
@c intentions.
@example
gpg-connect-agent /bye
@end example
@noindent
@efindex GPG_TTY
You should always add the following lines to your @code{.bashrc} or
whatever initialization file is used for all shell invocations:
@smallexample
GPG_TTY=$(tty)
export GPG_TTY
@end smallexample
@noindent
It is important that this environment variable always reflects the
output of the @code{tty} command. For W32 systems this option is not
required.
Please make sure that a proper pinentry program has been installed
under the default filename (which is system dependent) or use the
option @option{pinentry-program} to specify the full name of that program.
It is often useful to install a symbolic link from the actual used
pinentry (e.g. @file{@value{BINDIR}/pinentry-gtk}) to the expected
one (e.g. @file{@value{BINDIR}/pinentry}).
@manpause
@noindent
@xref{Option Index},for an index to @command{GPG-AGENT}'s commands and options.
@mancont
@menu
* Agent Commands:: List of all commands.
* Agent Options:: List of all options.
* Agent Configuration:: Configuration files.
* Agent Signals:: Use of some signals.
* Agent Examples:: Some usage examples.
* Agent Protocol:: The protocol the agent uses.
@end menu
@mansect commands
@node Agent Commands
@section Commands
Commands are not distinguished from options except for the fact that
only one command is allowed.
@table @gnupgtabopt
@item --version
@opindex version
Print the program version and licensing information. Note that you cannot
abbreviate this command.
@item --help
@itemx -h
@opindex help
Print a usage message summarizing the most useful command-line options.
Note that you cannot abbreviate this command.
@item --dump-options
@opindex dump-options
Print a list of all available options and commands. Note that you cannot
abbreviate this command.
@item --server
@opindex server
Run in server mode and wait for commands on the @code{stdin}. The
default mode is to create a socket and listen for commands there.
@item --daemon [@var{command line}]
@opindex daemon
Start the gpg-agent as a daemon; that is, detach it from the console
and run it in the background.
As an alternative you may create a new process as a child of
gpg-agent: @code{gpg-agent --daemon /bin/sh}. This way you get a new
shell with the environment setup properly; after you exit from this
shell, gpg-agent terminates within a few seconds.
@end table
@mansect options
@node Agent Options
@section Option Summary
@table @gnupgtabopt
@anchor{option --options}
@item --options @var{file}
@opindex options
Reads configuration from @var{file} instead of from the default
per-user configuration file. The default configuration file is named
@file{gpg-agent.conf} and expected in the @file{.gnupg} directory directly
below the home directory of the user.
@anchor{option --homedir}
@include opt-homedir.texi
@item -v
@item --verbose
@opindex verbose
Outputs additional information while running.
You can increase the verbosity by giving several
verbose commands to @command{gpgsm}, such as @samp{-vv}.
@item -q
@item --quiet
@opindex quiet
Try to be as quiet as possible.
@item --batch
@opindex batch
Don't invoke a pinentry or do any other thing requiring human interaction.
@item --faked-system-time @var{epoch}
@opindex faked-system-time
This option is only useful for testing; it sets the system time back or
forth to @var{epoch} which is the number of seconds elapsed since the year
1970.
@item --debug-level @var{level}
@opindex debug-level
Select the debug level for investigating problems. @var{level} may be
a numeric value or a keyword:
@table @code
@item none
No debugging at all. A value of less than 1 may be used instead of
the keyword.
@item basic
Some basic debug messages. A value between 1 and 2 may be used
instead of the keyword.
@item advanced
More verbose debug messages. A value between 3 and 5 may be used
instead of the keyword.
@item expert
Even more detailed messages. A value between 6 and 8 may be used
instead of the keyword.
@item guru
All of the debug messages you can get. A value greater than 8 may be
used instead of the keyword. The creation of hash tracing files is
only enabled if the keyword is used.
@end table
How these messages are mapped to the actual debugging flags is not
specified and may change with newer releases of this program. They are
however carefully selected to best aid in debugging.
@item --debug @var{flags}
@opindex debug
This option is only useful for debugging and the behaviour may change at
any time without notice. FLAGS are bit encoded and may be given in
usual C-Syntax. The currently defined bits are:
@table @code
@item 0 (1)
X.509 or OpenPGP protocol related data
@item 1 (2)
values of big number integers
@item 2 (4)
low level crypto operations
@item 5 (32)
memory allocation
@item 6 (64)
caching
@item 7 (128)
show memory statistics.
@item 9 (512)
write hashed data to files named @code{dbgmd-000*}
@item 10 (1024)
trace Assuan protocol
@item 12 (4096)
bypass all certificate validation
@end table
@item --debug-all
@opindex debug-all
Same as @code{--debug=0xffffffff}
@item --debug-wait @var{n}
@opindex debug-wait
When running in server mode, wait @var{n} seconds before entering the
actual processing loop and print the pid. This gives time to attach a
debugger.
@item --debug-quick-random
@opindex debug-quick-random
This option inhibits the use of the very secure random quality level
(Libgcrypt’s @code{GCRY_VERY_STRONG_RANDOM}) and degrades all request
down to standard random quality. It is only used for testing and
should not be used for any production quality keys. This option is
only effective when given on the command line.
On GNU/Linux, another way to quickly generate insecure keys is to use
@command{rngd} to fill the kernel's entropy pool with lower quality
random data. @command{rngd} is typically provided by the
@command{rng-tools} package. It can be run as follows: @samp{sudo
rngd -f -r /dev/urandom}.
@item --debug-pinentry
@opindex debug-pinentry
This option enables extra debug information pertaining to the
Pinentry. As of now it is only useful when used along with
@code{--debug 1024}.
@item --no-detach
@opindex no-detach
Don't detach the process from the console. This is mainly useful for
debugging.
@item -s
@itemx --sh
@itemx -c
@itemx --csh
@opindex sh
@opindex csh
@efindex SHELL
Format the info output in daemon mode for use with the standard Bourne
shell or the C-shell respectively. The default is to guess it based on
the environment variable @code{SHELL} which is correct in almost all
cases.
@item --no-grab
@opindex no-grab
Tell the pinentry not to grab the keyboard and mouse. This option
should in general not be used to avoid X-sniffing attacks.
@anchor{option --log-file}
@item --log-file @var{file}
@opindex log-file
@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile
Append all logging output to @var{file}. This is very helpful in seeing
what the agent actually does. If neither a log file nor a log file
descriptor has been set on a Windows platform, the Registry entry
@code{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to specify
the logging output.
@anchor{option --no-allow-mark-trusted}
@item --no-allow-mark-trusted
@opindex no-allow-mark-trusted
Do not allow clients to mark keys as trusted, i.e. put them into the
@file{trustlist.txt} file. This makes it harder for users to inadvertently
accept Root-CA keys.
@anchor{option --allow-preset-passphrase}
@item --allow-preset-passphrase
@opindex allow-preset-passphrase
This option allows the use of @command{gpg-preset-passphrase} to seed the
internal cache of @command{gpg-agent} with passphrases.
@anchor{option --no-allow-loopback-pinentry}
@item --no-allow-loopback-pinentry
@item --allow-loopback-pinentry
@opindex no-allow-loopback-pinentry
@opindex allow-loopback-pinentry
Disallow or allow clients to use the loopback pinentry features; see
the option @option{pinentry-mode} for details. Allow is the default.
The @option{--force} option of the Assuan command @command{DELETE_KEY}
is also controlled by this option: The option is ignored if a loopback
pinentry is disallowed.
@item --no-allow-external-cache
@opindex no-allow-external-cache
Tell Pinentry not to enable features which use an external cache for
passphrases.
Some desktop environments prefer to unlock all
credentials with one master password and may have installed a Pinentry
which employs an additional external cache to implement such a policy.
By using this option the Pinentry is advised not to make use of such a
cache and instead always ask the user for the requested passphrase.
@item --allow-emacs-pinentry
@opindex allow-emacs-pinentry
Tell Pinentry to allow features to divert the passphrase entry to a
running Emacs instance. How this is exactly handled depends on the
version of the used Pinentry.
@item --ignore-cache-for-signing
@opindex ignore-cache-for-signing
This option will let @command{gpg-agent} bypass the passphrase cache for all
signing operation. Note that there is also a per-session option to
control this behaviour but this command line option takes precedence.
@item --default-cache-ttl @var{n}
@opindex default-cache-ttl
Set the time a cache entry is valid to @var{n} seconds. The default
is 600 seconds. Each time a cache entry is accessed, the entry's
timer is reset. To set an entry's maximum lifetime, use
@command{max-cache-ttl}.
@item --default-cache-ttl-ssh @var{n}
@opindex default-cache-ttl
Set the time a cache entry used for SSH keys is valid to @var{n}
seconds. The default is 1800 seconds. Each time a cache entry is
accessed, the entry's timer is reset. To set an entry's maximum
lifetime, use @command{max-cache-ttl-ssh}.
@item --max-cache-ttl @var{n}
@opindex max-cache-ttl
Set the maximum time a cache entry is valid to @var{n} seconds. After
this time a cache entry will be expired even if it has been accessed
recently or has been set using @command{gpg-preset-passphrase}. The
default is 2 hours (7200 seconds).
@item --max-cache-ttl-ssh @var{n}
@opindex max-cache-ttl-ssh
Set the maximum time a cache entry used for SSH keys is valid to
@var{n} seconds. After this time a cache entry will be expired even
if it has been accessed recently or has been set using
@command{gpg-preset-passphrase}. The default is 2 hours (7200
seconds).
@item --enforce-passphrase-constraints
@opindex enforce-passphrase-constraints
Enforce the passphrase constraints by not allowing the user to bypass
them using the ``Take it anyway'' button.
@item --min-passphrase-len @var{n}
@opindex min-passphrase-len
Set the minimal length of a passphrase. When entering a new passphrase
shorter than this value a warning will be displayed. Defaults to 8.
@item --min-passphrase-nonalpha @var{n}
@opindex min-passphrase-nonalpha
Set the minimal number of digits or special characters required in a
passphrase. When entering a new passphrase with less than this number
of digits or special characters a warning will be displayed. Defaults
to 1.
@item --check-passphrase-pattern @var{file}
@opindex check-passphrase-pattern
Check the passphrase against the pattern given in @var{file}. When
entering a new passphrase matching one of these pattern a warning will
be displayed. @var{file} should be an absolute filename. The default is
not to use any pattern file.
Security note: It is known that checking a passphrase against a list of
pattern or even against a complete dictionary is not very effective to
enforce good passphrases. Users will soon figure up ways to bypass such
a policy. A better policy is to educate users on good security
behavior and optionally to run a passphrase cracker regularly on all
users passphrases to catch the very simple ones.
@item --max-passphrase-days @var{n}
@opindex max-passphrase-days
Ask the user to change the passphrase if @var{n} days have passed since
the last change. With @option{--enforce-passphrase-constraints} set the
user may not bypass this check.
@item --enable-passphrase-history
@opindex enable-passphrase-history
This option does nothing yet.
@item --pinentry-invisible-char @var{char}
@opindex pinentry-invisible-char
This option asks the Pinentry to use @var{char} for displaying hidden
characters. @var{char} must be one character UTF-8 string. A
Pinentry may or may not honor this request.
@item --pinentry-timeout @var{n}
@opindex pinentry-timeout
This option asks the Pinentry to timeout after @var{n} seconds with no
user input. The default value of 0 does not ask the pinentry to
timeout, however a Pinentry may use its own default timeout value in
this case. A Pinentry may or may not honor this request.
@item --pinentry-program @var{filename}
@opindex pinentry-program
Use program @var{filename} as the PIN entry. The default is
installation dependent. With the default configuration the name of
the default pinentry is @file{pinentry}; if that file does not exist
but a @file{pinentry-basic} exist the latter is used.
On a Windows platform the default is to use the first existing program
from this list:
@file{bin\pinentry.exe},
@file{..\Gpg4win\bin\pinentry.exe},
@file{..\Gpg4win\pinentry.exe},
@file{..\GNU\GnuPG\pinentry.exe},
@file{..\GNU\bin\pinentry.exe},
@file{bin\pinentry-basic.exe}
where the file names are relative to the GnuPG installation directory.
@item --pinentry-touch-file @var{filename}
@opindex pinentry-touch-file
By default the filename of the socket gpg-agent is listening for
requests is passed to Pinentry, so that it can touch that file before
exiting (it does this only in curses mode). This option changes the
file passed to Pinentry to @var{filename}. The special name
@code{/dev/null} may be used to completely disable this feature. Note
that Pinentry will not create that file, it will only change the
modification and access time.
@item --scdaemon-program @var{filename}
@opindex scdaemon-program
Use program @var{filename} as the Smartcard daemon. The default is
installation dependent and can be shown with the @command{gpgconf}
command.
@item --disable-scdaemon
@opindex disable-scdaemon
Do not make use of the scdaemon tool. This option has the effect of
disabling the ability to do smartcard operations. Note, that enabling
this option at runtime does not kill an already forked scdaemon.
@item --disable-check-own-socket
@opindex disable-check-own-socket
@command{gpg-agent} employs a periodic self-test to detect a stolen
socket. This usually means a second instance of @command{gpg-agent}
has taken over the socket and @command{gpg-agent} will then terminate
itself. This option may be used to disable this self-test for
debugging purposes.
@item --use-standard-socket
@itemx --no-use-standard-socket
@itemx --use-standard-socket-p
@opindex use-standard-socket
@opindex no-use-standard-socket
@opindex use-standard-socket-p
Since GnuPG 2.1 the standard socket is always used. These options
have no more effect. The command @code{gpg-agent
--use-standard-socket-p} will thus always return success.
@item --display @var{string}
@itemx --ttyname @var{string}
@itemx --ttytype @var{string}
@itemx --lc-ctype @var{string}
@itemx --lc-messages @var{string}
@itemx --xauthority @var{string}
@opindex display
@opindex ttyname
@opindex ttytype
@opindex lc-ctype
@opindex lc-messages
@opindex xauthority
These options are used with the server mode to pass localization
information.
@item --keep-tty
@itemx --keep-display
@opindex keep-tty
@opindex keep-display
Ignore requests to change the current @code{tty} or X window system's
@code{DISPLAY} variable respectively. This is useful to lock the
pinentry to pop up at the @code{tty} or display you started the agent.
@anchor{option --extra-socket}
@item --extra-socket @var{name}
@opindex extra-socket
Also listen on native gpg-agent connections on the given socket. The
intended use for this extra socket is to setup a Unix domain socket
forwarding from a remote machine to this socket on the local machine.
A @command{gpg} running on the remote machine may then connect to the
local gpg-agent and use its private keys. This allows to decrypt or
sign data on a remote machine without exposing the private keys to the
remote machine.
@anchor{option --enable-ssh-support}
@item --enable-ssh-support
@itemx --enable-putty-support
@opindex enable-ssh-support
@opindex enable-putty-support
Enable the OpenSSH Agent protocol.
In this mode of operation, the agent does not only implement the
gpg-agent protocol, but also the agent protocol used by OpenSSH
(through a separate socket). Consequently, it should be possible to use
the gpg-agent as a drop-in replacement for the well known ssh-agent.
SSH Keys, which are to be used through the agent, need to be added to
the gpg-agent initially through the ssh-add utility. When a key is
added, ssh-add will ask for the password of the provided key file and
send the unprotected key material to the agent; this causes the
gpg-agent to ask for a passphrase, which is to be used for encrypting
the newly received key and storing it in a gpg-agent specific
directory.
Once a key has been added to the gpg-agent this way, the gpg-agent
will be ready to use the key.
Note: in case the gpg-agent receives a signature request, the user might
need to be prompted for a passphrase, which is necessary for decrypting
the stored key. Since the ssh-agent protocol does not contain a
mechanism for telling the agent on which display/terminal it is running,
gpg-agent's ssh-support will use the TTY or X display where gpg-agent
has been started. To switch this display to the current one, the
following command may be used:
@smallexample
gpg-connect-agent updatestartuptty /bye
@end smallexample
Although all GnuPG components try to start the gpg-agent as needed, this
is not possible for the ssh support because ssh does not know about it.
Thus if no GnuPG tool which accesses the agent has been run, there is no
guarantee that ssh is able to use gpg-agent for authentication. To fix
this you may start gpg-agent if needed using this simple command:
@smallexample
gpg-connect-agent /bye
@end smallexample
Adding the @option{--verbose} shows the progress of starting the agent.
The @option{--enable-putty-support} is only available under Windows
and allows the use of gpg-agent with the ssh implementation
@command{putty}. This is similar to the regular ssh-agent support but
makes use of Windows message queue as required by @command{putty}.
@end table
All the long options may also be given in the configuration file after
stripping off the two leading dashes.
@mansect files
@node Agent Configuration
@section Configuration
There are a few configuration files needed for the operation of the
agent. By default they may all be found in the current home directory
(@pxref{option --homedir}).
@table @file
@item gpg-agent.conf
@efindex gpg-agent.conf
This is the standard configuration file read by @command{gpg-agent} on
startup. It may contain any valid long option; the leading
two dashes may not be entered and the option may not be abbreviated.
This file is also read after a @code{SIGHUP} however only a few
options will actually have an effect. This default name may be
changed on the command line (@pxref{option --options}).
You should backup this file.
@item trustlist.txt
@efindex trustlist.txt
This is the list of trusted keys. You should backup this file.
Comment lines, indicated by a leading hash mark, as well as empty
lines are ignored. To mark a key as trusted you need to enter its
fingerprint followed by a space and a capital letter @code{S}. Colons
may optionally be used to separate the bytes of a fingerprint; this
allows to cut and paste the fingerprint from a key listing output. If
the line is prefixed with a @code{!} the key is explicitly marked as
not trusted.
Here is an example where two keys are marked as ultimately trusted
and one as not trusted:
@cartouche
@smallexample
# CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
A6935DD34EF3087973C706FC311AA2CCF733765B S
# CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
# CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
!14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
@end smallexample
@end cartouche
Before entering a key into this file, you need to ensure its
authenticity. How to do this depends on your organisation; your
administrator might have already entered those keys which are deemed
trustworthy enough into this file. Places where to look for the
fingerprint of a root certificate are letters received from the CA or
the website of the CA (after making 100% sure that this is indeed the
website of that CA). You may want to consider disallowing interactive
updates of this file by using the @xref{option --no-allow-mark-trusted}.
It might even be advisable to change the permissions to read-only so
that this file can't be changed inadvertently.
As a special feature a line @code{include-default} will include a global
list of trusted certificates (e.g. @file{@value{SYSCONFDIR}/trustlist.txt}).
This global list is also used if the local list is not available.
It is possible to add further flags after the @code{S} for use by the
caller:
@table @code
@item relax
@cindex relax
Relax checking of some root certificate requirements. As of now this
flag allows the use of root certificates with a missing basicConstraints
attribute (despite that it is a MUST for CA certificates) and disables
CRL checking for the root certificate.
@item cm
If validation of a certificate finally issued by a CA with this flag set
fails, try again using the chain validation model.
@end table
@item sshcontrol
@efindex sshcontrol
This file is used when support for the secure shell agent protocol has
been enabled (@pxref{option --enable-ssh-support}). Only keys present in
this file are used in the SSH protocol. You should backup this file.
The @command{ssh-add} tool may be used to add new entries to this file;
you may also add them manually. Comment lines, indicated by a leading
hash mark, as well as empty lines are ignored. An entry starts with
optional whitespace, followed by the keygrip of the key given as 40 hex
digits, optionally followed by the caching TTL in seconds and another
optional field for arbitrary flags. A non-zero TTL overrides the global
default as set by @option{--default-cache-ttl-ssh}.
The only flag support is @code{confirm}. If this flag is found for a
key, each use of the key will pop up a pinentry to confirm the use of
that key. The flag is automatically set if a new key was loaded into
@code{gpg-agent} using the option @option{-c} of the @code{ssh-add}
command.
The keygrip may be prefixed with a @code{!} to disable an entry entry.
The following example lists exactly one key. Note that keys available
through a OpenPGP smartcard in the active smartcard reader are
implicitly added to this list; i.e. there is no need to list them.
@cartouche
@smallexample
# Key added on: 2011-07-20 20:38:46
# Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
@end smallexample
@end cartouche
@item private-keys-v1.d/
@efindex private-keys-v1.d
This is the directory where gpg-agent stores the private keys. Each
key is stored in a file with the name made up of the keygrip and the
suffix @file{key}. You should backup all files in this directory
and take great care to keep this backup closed away.
@end table
Note that on larger installations, it is useful to put predefined
files into the directory @file{@value{SYSCONFSKELDIR}} so that newly created
users start up with a working configuration. For existing users the
a small helper script is provided to create these files (@pxref{addgnupghome}).
@c
@c Agent Signals
@c
@mansect signals
@node Agent Signals
@section Use of some signals.
A running @command{gpg-agent} may be controlled by signals, i.e. using
the @command{kill} command to send a signal to the process.
Here is a list of supported signals:
@table @gnupgtabopt
@item SIGHUP
@cpindex SIGHUP
This signal flushes all cached passphrases and if the program has been
started with a configuration file, the configuration file is read
again. Only certain options are honored: @code{quiet},
@code{verbose}, @code{debug}, @code{debug-all}, @code{debug-level},
@code{debug-pinentry},
@code{no-grab},
@code{pinentry-program},
@code{pinentry-invisible-char},
@code{default-cache-ttl},
@code{max-cache-ttl}, @code{ignore-cache-for-signing},
@code{no-allow-external-cache}, @code{allow-emacs-pinentry},
@code{no-allow-mark-trusted}, @code{disable-scdaemon}, and
@code{disable-check-own-socket}. @code{scdaemon-program} is also
supported but due to the current implementation, which calls the
scdaemon only once, it is not of much use unless you manually kill the
scdaemon.
@item SIGTERM
@cpindex SIGTERM
Shuts down the process but waits until all current requests are
fulfilled. If the process has received 3 of these signals and requests
are still pending, a shutdown is forced.
@item SIGINT
@cpindex SIGINT
Shuts down the process immediately.
@item SIGUSR1
@cpindex SIGUSR1
Dump internal information to the log file.
@item SIGUSR2
@cpindex SIGUSR2
This signal is used for internal purposes.
@end table
@c
@c Examples
@c
@mansect examples
@node Agent Examples
@section Examples
It is important to set the environment variable @code{GPG_TTY} in
your login shell, for example in the @file{~/.bashrc} init script:
@cartouche
@example
export GPG_TTY=$(tty)
@end example
@end cartouche
If you enabled the Ssh Agent Support, you also need to tell ssh about
it by adding this to your init script:
@cartouche
@example
unset SSH_AGENT_PID
if [ "$@{gnupg_SSH_AUTH_SOCK_by:-0@}" -ne $$ ]; then
- export SSH_AUTH_SOCK="$@{HOME@}/.gnupg/S.gpg-agent.ssh"
+ export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi
@end example
@end cartouche
@c
@c Assuan Protocol
@c
@manpause
@node Agent Protocol
@section Agent's Assuan Protocol
Note: this section does only document the protocol, which is used by
GnuPG components; it does not deal with the ssh-agent protocol. To
see the full specification of each command, use
@example
gpg-connect-agent 'help COMMAND' /bye
@end example
@noindent
or just 'help' to list all available commands.
@noindent
The @command{gpg-agent} daemon is started on demand by the GnuPG
components.
To identify a key we use a thing called keygrip which is the SHA-1 hash
of an canonical encoded S-Expression of the public key as used in
Libgcrypt. For the purpose of this interface the keygrip is given as a
hex string. The advantage of using this and not the hash of a
certificate is that it will be possible to use the same keypair for
different protocols, thereby saving space on the token used to keep the
secret keys.
The @command{gpg-agent} may send status messages during a command or when
returning from a command to inform a client about the progress or result of an
operation. For example, the @var{INQUIRE_MAXLEN} status message may be sent
during a server inquire to inform the client of the maximum usable length of
the inquired data (which should not be exceeded).
@menu
* Agent PKDECRYPT:: Decrypting a session key
* Agent PKSIGN:: Signing a Hash
* Agent GENKEY:: Generating a Key
* Agent IMPORT:: Importing a Secret Key
* Agent EXPORT:: Exporting a Secret Key
* Agent ISTRUSTED:: Importing a Root Certificate
* Agent GET_PASSPHRASE:: Ask for a passphrase
* Agent CLEAR_PASSPHRASE:: Expire a cached passphrase
* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
* Agent GET_CONFIRMATION:: Ask for confirmation
* Agent HAVEKEY:: Check whether a key is available
* Agent LEARN:: Register a smartcard
* Agent PASSWD:: Change a Passphrase
* Agent UPDATESTARTUPTTY:: Change the Standard Display
* Agent GETEVENTCOUNTER:: Get the Event Counters
* Agent GETINFO:: Return information about the process
* Agent OPTION:: Set options for the session
@end menu
@node Agent PKDECRYPT
@subsection Decrypting a session key
The client asks the server to decrypt a session key. The encrypted
session key should have all information needed to select the
appropriate secret key or to delegate it to a smartcard.
@example
SETKEY <keyGrip>
@end example
Tell the server about the key to be used for decryption. If this is
not used, @command{gpg-agent} may try to figure out the key by trying to
decrypt the message with each key available.
@example
PKDECRYPT
@end example
The agent checks whether this command is allowed and then does an
INQUIRY to get the ciphertext the client should then send the cipher
text.
@example
S: INQUIRE CIPHERTEXT
C: D (xxxxxx
C: D xxxx)
C: END
@end example
Please note that the server may send status info lines while reading the
data lines from the client. The data send is a SPKI like S-Exp with
this structure:
@example
(enc-val
(<algo>
(<param_name1> <mpi>)
...
(<param_namen> <mpi>)))
@end example
Where algo is a string with the name of the algorithm; see the libgcrypt
documentation for a list of valid algorithms. The number and names of
the parameters depend on the algorithm. The agent does return an error
if there is an inconsistency.
If the decryption was successful the decrypted data is returned by
means of "D" lines.
Here is an example session:
@cartouche
@smallexample
C: PKDECRYPT
S: INQUIRE CIPHERTEXT
C: D (enc-val elg (a 349324324)
C: D (b 3F444677CA)))
C: END
S: # session key follows
S: S PADDING 0
S: D (value 1234567890ABCDEF0)
S: OK descryption successful
@end smallexample
@end cartouche
The “PADDING” status line is only send if gpg-agent can tell what kind
of padding is used. As of now only the value 0 is used to indicate
that the padding has been removed.
@node Agent PKSIGN
@subsection Signing a Hash
The client ask the agent to sign a given hash value. A default key
will be chosen if no key has been set. To set a key a client first
uses:
@example
SIGKEY <keyGrip>
@end example
This can be used multiple times to create multiple signature, the list
of keys is reset with the next PKSIGN command or a RESET. The server
test whether the key is a valid key to sign something and responds with
okay.
@example
SETHASH --hash=<name>|<algo> <hexstring>
@end example
The client can use this command to tell the server about the data <hexstring>
(which usually is a hash) to be signed. <algo> is the decimal encoded hash
algorithm number as used by Libgcrypt. Either <algo> or --hash=<name>
must be given. Valid names for <name> are:
@table @code
@item sha1
The SHA-1 hash algorithm
@item sha256
The SHA-256 hash algorithm
@item rmd160
The RIPE-MD160 hash algorithm
@item md5
The old and broken MD5 hash algorithm
@item tls-md5sha1
A combined hash algorithm as used by the TLS protocol.
@end table
@noindent
The actual signing is done using
@example
PKSIGN <options>
@end example
Options are not yet defined, but my later be used to choose among
different algorithms. The agent does then some checks, asks for the
passphrase and as a result the server returns the signature as an SPKI
like S-expression in "D" lines:
@example
(sig-val
(<algo>
(<param_name1> <mpi>)
...
(<param_namen> <mpi>)))
@end example
The operation is affected by the option
@example
OPTION use-cache-for-signing=0|1
@end example
The default of @code{1} uses the cache. Setting this option to @code{0}
will lead @command{gpg-agent} to ignore the passphrase cache. Note, that there is
also a global command line option for @command{gpg-agent} to globally disable the
caching.
Here is an example session:
@cartouche
@smallexample
C: SIGKEY <keyGrip>
S: OK key available
C: SIGKEY <keyGrip>
S: OK key available
C: PKSIGN
S: # I did ask the user whether he really wants to sign
S: # I did ask the user for the passphrase
S: INQUIRE HASHVAL
C: D ABCDEF012345678901234
C: END
S: # signature follows
S: D (sig-val rsa (s 45435453654612121212))
S: OK
@end smallexample
@end cartouche
@node Agent GENKEY
@subsection Generating a Key
This is used to create a new keypair and store the secret key inside the
active PSE --- which is in most cases a Soft-PSE. An not yet defined
option allows to choose the storage location. To get the secret key out
of the PSE, a special export tool has to be used.
@example
GENKEY [--no-protection] [--preset] [<cache_nonce>]
@end example
Invokes the key generation process and the server will then inquire
on the generation parameters, like:
@example
S: INQUIRE KEYPARM
C: D (genkey (rsa (nbits 1024)))
C: END
@end example
The format of the key parameters which depends on the algorithm is of
the form:
@example
(genkey
(algo
(parameter_name_1 ....)
....
(parameter_name_n ....)))
@end example
If everything succeeds, the server returns the *public key* in a SPKI
like S-Expression like this:
@example
(public-key
(rsa
(n <mpi>)
(e <mpi>)))
@end example
Here is an example session:
@cartouche
@smallexample
C: GENKEY
S: INQUIRE KEYPARM
C: D (genkey (rsa (nbits 1024)))
C: END
S: D (public-key
S: D (rsa (n 326487324683264) (e 10001)))
S OK key created
@end smallexample
@end cartouche
The @option{--no-protection} option may be used to prevent prompting for a
passphrase to protect the secret key while leaving the secret key unprotected.
The @option{--preset} option may be used to add the passphrase to the cache
using the default cache parameters.
The @option{--inq-passwd} option may be used to create the key with a
supplied passphrase. When used the agent does an inquiry with the
keyword @code{NEWPASSWD} to retrieve that passphrase. This option
takes precedence over @option{--no-protection}; however if the client
sends a empty (zero-length) passphrase, this is identical to
@option{--no-protection}.
@node Agent IMPORT
@subsection Importing a Secret Key
This operation is not yet supported by GpgAgent. Specialized tools
are to be used for this.
There is no actual need because we can expect that secret keys
created by a 3rd party are stored on a smartcard. If we have
generated the key ourself, we do not need to import it.
@node Agent EXPORT
@subsection Export a Secret Key
Not implemented.
Should be done by an extra tool.
@node Agent ISTRUSTED
@subsection Importing a Root Certificate
Actually we do not import a Root Cert but provide a way to validate
any piece of data by storing its Hash along with a description and
an identifier in the PSE. Here is the interface description:
@example
ISTRUSTED <fingerprint>
@end example
Check whether the OpenPGP primary key or the X.509 certificate with the
given fingerprint is an ultimately trusted key or a trusted Root CA
certificate. The fingerprint should be given as a hexstring (without
any blanks or colons or whatever in between) and may be left padded with
00 in case of an MD5 fingerprint. GPGAgent will answer with:
@example
OK
@end example
The key is in the table of trusted keys.
@example
ERR 304 (Not Trusted)
@end example
The key is not in this table.
Gpg needs the entire list of trusted keys to maintain the web of
trust; the following command is therefore quite helpful:
@example
LISTTRUSTED
@end example
GpgAgent returns a list of trusted keys line by line:
@example
S: D 000000001234454556565656677878AF2F1ECCFF P
S: D 340387563485634856435645634856438576457A P
S: D FEDC6532453745367FD83474357495743757435D S
S: OK
@end example
The first item on a line is the hexified fingerprint where MD5
fingerprints are @code{00} padded to the left and the second item is a
flag to indicate the type of key (so that gpg is able to only take care
of PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest
of the line, so that we can extend the format in the future.
Finally a client should be able to mark a key as trusted:
@example
MARKTRUSTED @var{fingerprint} "P"|"S"
@end example
The server will then pop up a window to ask the user whether she
really trusts this key. For this it will probably ask for a text to
be displayed like this:
@example
S: INQUIRE TRUSTDESC
C: D Do you trust the key with the fingerprint @@FPR@@
C: D bla fasel blurb.
C: END
S: OK
@end example
Known sequences with the pattern @@foo@@ are replaced according to this
table:
@table @code
@item @@FPR16@@
Format the fingerprint according to gpg rules for a v3 keys.
@item @@FPR20@@
Format the fingerprint according to gpg rules for a v4 keys.
@item @@FPR@@
Choose an appropriate format to format the fingerprint.
@item @@@@
Replaced by a single @code{@@}
@end table
@node Agent GET_PASSPHRASE
@subsection Ask for a passphrase
This function is usually used to ask for a passphrase to be used for
symmetric encryption, but may also be used by programs which need
special handling of passphrases. This command uses a syntax which helps
clients to use the agent with minimum effort.
@example
GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \
[--qualitybar] @var{cache_id} \
[@var{error_message} @var{prompt} @var{description}]
@end example
@var{cache_id} is expected to be a string used to identify a cached
passphrase. Use a @code{X} to bypass the cache. With no other
arguments the agent returns a cached passphrase or an error. By
convention either the hexified fingerprint of the key shall be used for
@var{cache_id} or an arbitrary string prefixed with the name of the
calling application and a colon: Like @code{gpg:somestring}.
@var{error_message} is either a single @code{X} for no error message or
a string to be shown as an error message like (e.g. "invalid
passphrase"). Blanks must be percent escaped or replaced by @code{+}'.
@var{prompt} is either a single @code{X} for a default prompt or the
text to be shown as the prompt. Blanks must be percent escaped or
replaced by @code{+}.
@var{description} is a text shown above the entry field. Blanks must be
percent escaped or replaced by @code{+}.
The agent either returns with an error or with a OK followed by the hex
encoded passphrase. Note that the length of the strings is implicitly
limited by the maximum length of a command. If the option
@option{--data} is used, the passphrase is not returned on the OK line
but by regular data lines; this is the preferred method.
If the option @option{--check} is used, the standard passphrase
constraints checks are applied. A check is not done if the passphrase
has been found in the cache.
If the option @option{--no-ask} is used and the passphrase is not in the
cache the user will not be asked to enter a passphrase but the error
code @code{GPG_ERR_NO_DATA} is returned.
If the option @option{--qualitybar} is used and a minimum passphrase
length has been configured, a visual indication of the entered
passphrase quality is shown.
@example
CLEAR_PASSPHRASE @var{cache_id}
@end example
may be used to invalidate the cache entry for a passphrase. The
function returns with OK even when there is no cached passphrase.
@node Agent CLEAR_PASSPHRASE
@subsection Remove a cached passphrase
Use this command to remove a cached passphrase.
@example
CLEAR_PASSPHRASE [--mode=normal] <cache_id>
@end example
The @option{--mode=normal} option can be used to clear a @var{cache_id} that
was set by gpg-agent.
@node Agent PRESET_PASSPHRASE
@subsection Set a passphrase for a keygrip
This command adds a passphrase to the cache for the specified @var{keygrip}.
@example
PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
@end example
The passphrase is a hexidecimal string when specified. When not specified, the
passphrase will be retrieved from the pinentry module unless the
@option{--inquire} option was specified in which case the passphrase will be
retrieved from the client.
The @var{timeout} parameter keeps the passphrase cached for the specified
number of seconds. A value of @code{-1} means infinate while @code{0} means
the default (currently only a timeout of -1 is allowed, which means to never
expire it).
@node Agent GET_CONFIRMATION
@subsection Ask for confirmation
This command may be used to ask for a simple confirmation by
presenting a text and 2 buttons: Okay and Cancel.
@example
GET_CONFIRMATION @var{description}
@end example
@var{description}is displayed along with a Okay and Cancel
button. Blanks must be percent escaped or replaced by @code{+}. A
@code{X} may be used to display confirmation dialog with a default
text.
The agent either returns with an error or with a OK. Note, that the
length of @var{description} is implicitly limited by the maximum
length of a command.
@node Agent HAVEKEY
@subsection Check whether a key is available
This can be used to see whether a secret key is available. It does
not return any information on whether the key is somehow protected.
@example
HAVEKEY @var{keygrips}
@end example
The agent answers either with OK or @code{No_Secret_Key} (208). The
caller may want to check for other error codes as well. More than one
keygrip may be given. In this case the command returns success if at
least one of the keygrips corresponds to an available secret key.
@node Agent LEARN
@subsection Register a smartcard
@example
LEARN [--send]
@end example
This command is used to register a smartcard. With the --send
option given the certificates are send back.
@node Agent PASSWD
@subsection Change a Passphrase
@example
PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] @var{keygrip}
@end example
This command is used to interactively change the passphrase of the key
identified by the hex string @var{keygrip}. The @option{--preset}
option may be used to add the new passphrase to the cache using the
default cache parameters.
@node Agent UPDATESTARTUPTTY
@subsection Change the standard display
@example
UPDATESTARTUPTTY
@end example
Set the startup TTY and X-DISPLAY variables to the values of this
session. This command is useful to direct future pinentry invocations
to another screen. It is only required because there is no way in the
ssh-agent protocol to convey this information.
@node Agent GETEVENTCOUNTER
@subsection Get the Event Counters
@example
GETEVENTCOUNTER
@end example
This function return one status line with the current values of the
event counters. The event counters are useful to avoid polling by
delaying a poll until something has changed. The values are decimal
numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to
0. The actual values should not be relied upon; they shall only be used
to detect a change.
The currently defined counters are are:
@table @code
@item ANY
Incremented with any change of any of the other counters.
@item KEY
Incremented for added or removed private keys.
@item CARD
Incremented for changes of the card readers stati.
@end table
@node Agent GETINFO
@subsection Return information about the process
This is a multipurpose function to return a variety of information.
@example
GETINFO @var{what}
@end example
The value of @var{what} specifies the kind of information returned:
@table @code
@item version
Return the version of the program.
@item pid
Return the process id of the process.
@item socket_name
Return the name of the socket used to connect the agent.
@item ssh_socket_name
Return the name of the socket used for SSH connections. If SSH support
has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned.
@end table
@node Agent OPTION
@subsection Set options for the session
Here is a list of session options which are not yet described with
other commands. The general syntax for an Assuan option is:
@smallexample
OPTION @var{key}=@var{value}
@end smallexample
@noindent
Supported @var{key}s are:
@table @code
@item agent-awareness
This may be used to tell gpg-agent of which gpg-agent version the
client is aware of. gpg-agent uses this information to enable
features which might break older clients.
@item putenv
Change the session's environment to be used for the
Pinentry. Valid values are:
@table @code
@item @var{name}
Delete envvar @var{name}
@item @var{name}=
Set envvar @var{name} to the empty string
@item @var{name}=@var{value}
Set envvar @var{name} to the string @var{value}.
@end table
@item use-cache-for-signing
See Assuan command @code{PKSIGN}.
@item allow-pinentry-notify
This does not need any value. It is used to enable the
PINENTRY_LAUNCHED inquiry.
@item pinentry-mode
This option is used to change the operation mode of the pinentry. The
following values are defined:
@table @code
@item ask
This is the default mode which pops up a pinentry as needed.
@item cancel
Instead of popping up a pinentry, return the error code
@code{GPG_ERR_CANCELED}.
@item error
Instead of popping up a pinentry, return the error code
@code{GPG_ERR_NO_PIN_ENTRY}.
@item loopback
Use a loopback pinentry. This fakes a pinentry by using inquiries
back to the caller to ask for a passphrase. This option may only be
set if the agent has been configured for that.
To disable this feature use @xref{option --no-allow-loopback-pinentry}.
@end table
@item cache-ttl-opt-preset
This option sets the cache TTL for new entries created by GENKEY and
PASSWD commands when using the @option{--preset} option. It it is not
used a default value is used.
@item s2k-count
Instead of using the standard S2K count (which is computed on the
fly), the given S2K count is used for new keys or when changing the
passphrase of a key. Values below 65536 are considered to be 0. This
option is valid for the entire session or until reset to 0. This
option is useful if the key is later used on boxes which are either
much slower or faster than the actual box.
@end table
@mansect see also
@ifset isman
@command{gpg2}(1),
@command{gpgsm}(1),
@command{gpg-connect-agent}(1),
@command{scdaemon}(1)
@end ifset
@include see-also-note.texi
diff --git a/doc/tools.texi b/doc/tools.texi
index 8fdaa96a7..577df8ea1 100644
--- a/doc/tools.texi
+++ b/doc/tools.texi
@@ -1,1906 +1,1908 @@
@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
* symcryptrun:: Call a simple symmetric encryption tool.
* gpg-zip:: Encrypt or sign files into an archive.
@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 ~/.gnupg/S.log
@end example
@manpause
@noindent
This starts it on the current terminal for listening on the socket
@file{~/.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 --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 /home/foo/.gnupg/S.log
@end example
This waits for connections on the local socket
@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 value for that option must be given
with a special prefix (e.g. in the conf file):
@example
log-file socket:///home/foo/.gnupg/S.log
@end example
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 scripts help to do this
by copying all files from @file{/etc/skel/.gnupg} to the home
directories of the accounts given on the command line. It takes care
not to overwrite existing GnuPG home directories.
@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 GnuPG,
GPGSM, DirMngr, etc. But this is not a strict one-to-one
relationship. Not all configuration options are available through
@command{gpgconf}. @command{gpgconf} provides a generic and abstract
method to access the most important configuration options that can
feasibly be controlled via such a mechanism.
@command{gpgconf} can be used to gather and change the options
available in each component, and can also provide their default
values. @command{gpgconf} will give detailed type information that
can be used to restrict the user's input without making an attempt to
commit the changes.
@command{gpgconf} provides the backend of a configuration editor. The
configuration editor would usually be a graphical user interface
program, that allows to display the current options, their default
values, and allows the user to make changes to the options. These
changes can then be made active with @command{gpgconf} again. Such a
program that uses @command{gpgconf} in this way will be called GUI
throughout this section.
@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 know to gpgconf.
* Listing options:: List all options of a component.
* Changing options:: Changing options of a component.
* Listing global options:: List all global options.
* 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-defaults
Update all configuration files with values taken from the global
configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
-@item --list-dirs
+@item --list-dirs [@var{names}]
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.
+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 --reload [@var{component}]
@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.
@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.
@item --kill [@var{component}]
@opindex kill
Kill the given component. Components which support killing are
gpg-agent and scdaemon. Components which don't support reloading are
ignored. Note that as of now reload and kill have the same effect for
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.
@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.
@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 localised
Some fields contain strings that are described to be @emph{localised}.
Such strings are translated to the active language and formatted in
the active character set.
@item @w{unsigned number}
Some fields contain an @emph{unsigned number}. This number will
always fit into a 32-bit unsigned integer variable. The number may be
followed by a space, followed by a human readable description of that
value (if the verbose option is used). You should ignore everything
in the field that follows the number.
@item @w{signed number}
Some fields contain a @emph{signed number}. This number will always
fit into a 32-bit signed integer variable. The number may be followed
by a space, followed by a human readable description of that value (if
the verbose option is used). You should ignore everything in the
field that follows the number.
@item @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 number argument and it can occur more than once,
then the option argument is either empty, or it is a comma-separated
list of string arguments as described above.
@end table
@end table
The active language and character set are currently determined from
the locale environment of the @command{gpgconf} program.
@c FIXME: Document the active language and active character set. Allow
@c to change it via the command line?
@mansect usage
@node Listing components
@subsection Listing components
The command @code{--list-components} will list all components that can
be configured with @command{gpgconf}. Usually, one component will
correspond to one GnuPG-related program and contain the options of
that programs configuration file that can be modified using
@command{gpgconf}. However, this is not necessarily the case. A
component might also be a group of selected options from several
programs, or contain entirely virtual options that have a special
effect rather than changing exactly one option in one configuration
file.
A component is a set of configuration options that semantically belong
together. Furthermore, several changes to a component can be made in
an atomic way with a single operation. The GUI could for example
provide a menu with one entry for each component, or a window with one
tabulator sheet per component.
The command argument @code{--list-components} lists all available
components, one per line. The format of each line is:
@code{@var{name}:@var{description}:@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 argument @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 argument @code{@w{--list-options @var{component}}} lists
all options (and the groups they belong to) in the component
@var{component}, one per line. @var{component} must be the string in
the field @var{name} in the output of the @code{--list-components}
command.
There is one line for each option and each group. First come all
options that are not in any group. Then comes a line describing a
group. Then come all options that belong into each group. Then comes
the next group and so on. There does not need to be any group (and in
this case the output will stop after the last non-grouped option).
The format of each line is:
@code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
@table @var
@item name
This field contains a name tag for the group or option. The name tag
is used to specify the group or option in all communication with
@command{gpgconf}. The name tag is to be used @emph{verbatim}. It is
thus not in any escaped format.
@item flags
The flags field contains an @emph{unsigned number}. Its value is the
OR-wise combination of the following flag values:
@table @code
@item group (1)
If this flag is set, this is a line describing a group and not an
option.
@end table
The following flag values are only defined for options (that is, if
the @code{group} flag is not used).
@table @code
@item optional arg (2)
If this flag is set, the argument is optional. This is never set for
@var{type} @code{0} (none) options.
@item list (4)
If this flag is set, the option can be given multiple times.
@item runtime (8)
If this flag is set, the option can be changed at runtime.
@item default (16)
If this flag is set, a default value is available.
@item default desc (32)
If this flag is set, a (runtime) default is available. This and the
@code{default} flag are mutually exclusive.
@item no arg desc (64)
If this flag is set, and the @code{optional arg} flag is set, then the
option has a special meaning if no argument is given.
@item no change (128)
If this flag is set, 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{localised string} that gives a short
name for the argument. The field may also be empty, though, in which
case a short name is not known.
@item default
This field is defined only for options 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} (@xref{Format
conventions}, for details). If the default value is empty, then no
default is known. Otherwise, the value specifies the default value
for this option. If the @code{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} (@xref{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
Sometimes it is useful for applications to look at the global options
file @file{gpgconf.conf}.
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{flags}:@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}.
@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.
A commented example can be found in the @file{examples} directory of
the distribution.
@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 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 to enforce
certain policies for all users. Note, that this is not a bulletproof of
forcing 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.
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 --dump-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}).
@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
gpg-agent provides using the Assuan interface. It might also be useful
for scripting simple applications. Input is expected at stdin and out
put gets printed to stdout.
It is very similar to running @command{gpg-agent} in server mode; but
here we connect to a running instance.
@menu
* Invoking gpg-connect-agent:: List of all 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 couter 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 protocl, 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 SYMCRYPTRUN
@c
@node symcryptrun
@section Call a simple symmetric encryption tool.
@manpage symcryptrun.1
@ifset manverb
.B symcryptrun
\- Call a simple symmetric encryption tool
@end ifset
@mansect synopsis
@ifset manverb
.B symcryptrun
.B \-\-class
.I class
.B \-\-program
.I program
.B \-\-keyfile
.I keyfile
.RB [ --decrypt | --encrypt ]
.RI [ inputfile ]
@end ifset
@mansect description
Sometimes simple encryption tools are already in use for a long time and
there might be a desire to integrate them into the GnuPG framework. The
protocols and encryption methods might be non-standard or not even
properly documented, so that a full-fledged encryption tool with an
interface like gpg is not doable. @command{symcryptrun} provides a
solution: It operates by calling the external encryption/decryption
module and provides a passphrase for a key using the standard
@command{pinentry} based mechanism through @command{gpg-agent}.
Note, that @command{symcryptrun} is only available if GnuPG has been
configured with @samp{--enable-symcryptrun} at build time.
@menu
* Invoking symcryptrun:: List of all commands and options.
@end menu
@manpause
@node Invoking symcryptrun
@subsection List of all commands and options.
@noindent
@command{symcryptrun} is invoked this way:
@example
symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE
[--decrypt | --encrypt] [inputfile]
@end example
@mancont
For encryption, the plain text must be provided on STDIN or as the
argument @var{inputfile}, and the ciphertext will be output to STDOUT.
For decryption vice versa.
@var{CLASS} describes the calling conventions of the external tool.
Currently it must be given as @samp{confucius}. @var{PROGRAM} is
the full filename of that external tool.
For the class @samp{confucius} the option @option{--keyfile} is
required; @var{keyfile} is the name of a file containing the secret key,
which may be protected by a passphrase. For detailed calling
conventions, see the source code.
@noindent
Note, that @command{gpg-agent} must be running before starting
@command{symcryptrun}.
@noindent
The following additional options may be used:
@table @gnupgtabopt
@item -v
@itemx --verbose
@opindex verbose
Output additional information while running.
@item -q
@item --quiet
@opindex q
@opindex quiet
Try to be as quiet as possible.
@include opt-homedir.texi
@item --log-file @var{file}
@opindex log-file
Append all logging output to @var{file}. Default is to write logging
information to STDERR.
@end table
@noindent
The possible exit status codes of @command{symcryptrun} are:
@table @code
@item 0
Success.
@item 1
Some error occured.
@item 2
No valid passphrase was provided.
@item 3
The operation was canceled by the user.
@end table
@mansect see also
@ifset isman
@command{gpg}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
@end ifset
@include see-also-note.texi
@c
@c GPG-ZIP
@c
@c The original manpage on which this section is based was written
@c by Colin Tuckley <colin@tuckley.org> and Daniel Leidert
@c <daniel.leidert@wgdd.de> for the Debian distribution (but may be used by
@c others).
@manpage gpg-zip.1
@node gpg-zip
@section Encrypt or sign files into an archive
@ifset manverb
.B gpg-zip \- Encrypt or sign files into an archive
@end ifset
@mansect synopsis
@ifset manverb
.B gpg-zip
.RI [ options ]
.I filename1
.I [ filename2, ... ]
.I directory1
.I [ directory2, ... ]
@end ifset
@mansect description
@command{gpg-zip} 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{gpg-zip} is invoked this way:
@example
gpg-zip [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
@end example
@mansect options
@noindent
@command{gpg-zip} understands these options:
@table @gnupgtabopt
@item --encrypt
@itemx -e
@opindex encrypt
Encrypt data. This option may be combined with @option{--symmetric} (for output that may be decrypted via a secret key or a passphrase).
@item --decrypt
@itemx -d
@opindex decrypt
Decrypt data.
@item --symmetric
@itemx -c
Encrypt with a symmetric cipher using a passphrase. The default
symmetric cipher used is CAST5, but may be chosen with the
@option{--cipher-algo} option to @command{gpg}.
@item --sign
@itemx -s
Make a signature. See @command{gpg}.
@item --recipient @var{user}
@itemx -r @var{user}
@opindex recipient
Encrypt for user id @var{user}. See @command{gpg}.
@item --local-user @var{user}
@itemx -u @var{user}
@opindex local-user
Use @var{user} as the key to sign with. See @command{gpg}.
@item --list-archive
@opindex list-archive
List the contents of the specified archive.
@item --output @var{file}
@itemx -o @var{file}
@opindex output
Write output to specified file @var{file}.
@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 options to @command{gpg}.
@item --tar @var{tarcmd}
@opindex tar
Use the specified command @var{tarcmd} instead of @command{tar}.
@item --tar-args @var{args}
@opindex tar-args
Pass the specified options to @command{tar}.
@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
gpg-zip --encrypt --output test1 --gpg-args -r Bob mydocs
@end example
@noindent
List the contents of archive @file{test1}:
@example
gpg-zip --list-archive test1
@end example
@mansect see also
@ifset isman
@command{gpg}(1),
@command{tar}(1),
@end ifset
@include see-also-note.texi
diff --git a/tools/gpgconf.c b/tools/gpgconf.c
index 2b177e233..ad61511d3 100644
--- a/tools/gpgconf.c
+++ b/tools/gpgconf.c
@@ -1,465 +1,487 @@
/* gpgconf.c - Configuration utility for GnuPG
* Copyright (C) 2003, 2007, 2009, 2011 Free Software Foundation, Inc.
*
* This file is part of GnuPG.
*
* GnuPG is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 3 of the License, or
* (at your option) any later version.
*
* GnuPG is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <http://www.gnu.org/licenses/>.
*/
#include <config.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include "gpgconf.h"
#include "i18n.h"
#include "sysutils.h"
#include "../common/init.h"
/* Constants to identify the commands and options. */
enum cmd_and_opt_values
{
aNull = 0,
oDryRun = 'n',
oOutput = 'o',
oQuiet = 'q',
oVerbose = 'v',
oRuntime = 'r',
oComponent = 'c',
oNoVerbose = 500,
oHomedir,
aListComponents,
aCheckPrograms,
aListOptions,
aChangeOptions,
aCheckOptions,
aApplyDefaults,
aListConfig,
aCheckConfig,
aListDirs,
aLaunch,
aKill,
aCreateSocketDir,
aRemoveSocketDir,
aReload
};
/* The list of commands and options. */
static ARGPARSE_OPTS opts[] =
{
{ 300, NULL, 0, N_("@Commands:\n ") },
{ aListComponents, "list-components", 256, N_("list all components") },
{ aCheckPrograms, "check-programs", 256, N_("check all programs") },
{ aListOptions, "list-options", 256, N_("|COMPONENT|list options") },
{ aChangeOptions, "change-options", 256, N_("|COMPONENT|change options") },
{ aCheckOptions, "check-options", 256, N_("|COMPONENT|check options") },
{ aApplyDefaults, "apply-defaults", 256,
N_("apply global default values") },
{ aListDirs, "list-dirs", 256,
N_("get the configuration directories for @GPGCONF@") },
{ aListConfig, "list-config", 256,
N_("list global configuration file") },
{ aCheckConfig, "check-config", 256,
N_("check global configuration file") },
{ aReload, "reload", 256, N_("reload all or a given component")},
{ aLaunch, "launch", 256, N_("launch a given component")},
{ aKill, "kill", 256, N_("kill a given component")},
{ aCreateSocketDir, "create-socketdir", 256, "@"},
{ aRemoveSocketDir, "remove-socketdir", 256, "@"},
{ 301, NULL, 0, N_("@\nOptions:\n ") },
{ oOutput, "output", 2, N_("use as output file") },
{ oVerbose, "verbose", 0, N_("verbose") },
{ oQuiet, "quiet", 0, N_("quiet") },
{ oDryRun, "dry-run", 0, N_("do not make any changes") },
{ oRuntime, "runtime", 0, N_("activate changes at runtime, if possible") },
/* hidden options */
{ oHomedir, "homedir", 2, "@" },
{ oNoVerbose, "no-verbose", 0, "@"},
{0}
};
/* Print usage information and and provide strings for help. */
static const char *
my_strusage( int level )
{
const char *p;
switch (level)
{
case 11: p = "@GPGCONF@ (@GNUPG@)";
break;
case 13: p = VERSION; break;
case 17: p = PRINTABLE_OS_NAME; break;
case 19: p = _("Please report bugs to <@EMAIL@>.\n"); break;
case 1:
case 40: p = _("Usage: @GPGCONF@ [options] (-h for help)");
break;
case 41:
p = _("Syntax: @GPGCONF@ [options]\n"
"Manage configuration options for tools of the @GNUPG@ system\n");
break;
default: p = NULL; break;
}
return p;
}
/* Return the fp for the output. This is usually stdout unless
--output has been used. In the latter case this function opens
that file. */
static estream_t
get_outfp (estream_t *fp)
{
if (!*fp)
{
if (opt.outfile)
{
*fp = es_fopen (opt.outfile, "w");
if (!*fp)
gc_error (1, errno, "can not open '%s'", opt.outfile);
}
else
*fp = es_stdout;
}
return *fp;
}
+static void
+list_dirs (estream_t fp, char **names)
+{
+ static struct {
+ const char *name;
+ const char *(*fnc)(void);
+ const char *extra;
+ int special;
+ } list[] = {
+ { "sysconfdir", gnupg_sysconfdir, NULL },
+ { "bindir", gnupg_bindir, NULL },
+ { "libexecdir", gnupg_libexecdir, NULL },
+ { "libdir", gnupg_libdir, NULL },
+ { "datadir", gnupg_datadir, NULL },
+ { "localedir", gnupg_localedir, NULL },
+ { "dirmngr-socket", dirmngr_user_socket_name, NULL, 1 },
+ { "dirmngr-socket", dirmngr_sys_socket_name, NULL, 2 },
+ { "dirmngr-sys-socket", dirmngr_sys_socket_name, NULL, 1 },
+ { "agent-ssh-socket", gnupg_socketdir, GPG_AGENT_SSH_SOCK_NAME },
+ { "agent-socket", gnupg_socketdir, GPG_AGENT_SOCK_NAME },
+ { "homedir", gnupg_homedir, NULL }
+ };
+ int idx, j;
+ char *tmp;
+ const char *s;
+
+
+ for (idx = 0; idx < DIM (list); idx++)
+ {
+ if (list[idx].special == 1 && dirmngr_user_socket_name ())
+ ;
+ else if (list[idx].special == 2 && !dirmngr_user_socket_name ())
+ ;
+ else if (list[idx].special == 1 || list[idx].special == 2)
+ continue;
+
+ s = list[idx].fnc ();
+ if (list[idx].extra)
+ {
+ tmp = make_filename (s, list[idx].extra, NULL);
+ s = tmp;
+ }
+ else
+ tmp = NULL;
+ if (!names)
+ es_fprintf (fp, "%s:%s\n", list[idx].name, gc_percent_escape (s));
+ else
+ {
+ for (j=0; names[j]; j++)
+ if (!strcmp (names[j], list[idx].name))
+ es_fprintf (fp, "%s\n", s);
+ }
+
+ xfree (tmp);
+ }
+}
+
+
/* gpgconf main. */
int
main (int argc, char **argv)
{
ARGPARSE_ARGS pargs;
const char *fname;
int no_more_options = 0;
enum cmd_and_opt_values cmd = 0;
estream_t outfp = NULL;
early_system_init ();
gnupg_reopen_std (GPGCONF_NAME);
set_strusage (my_strusage);
log_set_prefix (GPGCONF_NAME, 1);
/* Make sure that our subsystems are ready. */
i18n_init();
init_common_subsystems (&argc, &argv);
/* Parse the command line. */
pargs.argc = &argc;
pargs.argv = &argv;
pargs.flags = 1; /* Do not remove the args. */
while (!no_more_options && optfile_parse (NULL, NULL, NULL, &pargs, opts))
{
switch (pargs.r_opt)
{
case oOutput: opt.outfile = pargs.r.ret_str; break;
case oQuiet: opt.quiet = 1; break;
case oDryRun: opt.dry_run = 1; break;
case oRuntime:
opt.runtime = 1;
break;
case oVerbose: opt.verbose++; break;
case oNoVerbose: opt.verbose = 0; break;
case oHomedir: gnupg_set_homedir (pargs.r.ret_str); break;
case aListDirs:
case aListComponents:
case aCheckPrograms:
case aListOptions:
case aChangeOptions:
case aCheckOptions:
case aApplyDefaults:
case aListConfig:
case aCheckConfig:
case aReload:
case aLaunch:
case aKill:
case aCreateSocketDir:
case aRemoveSocketDir:
cmd = pargs.r_opt;
break;
default: pargs.err = 2; break;
}
}
if (log_get_errorcount (0))
exit (2);
/* Print a warning if an argument looks like an option. */
if (!opt.quiet && !(pargs.flags & ARGPARSE_FLAG_STOP_SEEN))
{
int i;
for (i=0; i < argc; i++)
if (argv[i][0] == '-' && argv[i][1] == '-')
log_info (_("Note: '%s' is not considered an option\n"), argv[i]);
}
fname = argc ? *argv : NULL;
switch (cmd)
{
case aListComponents:
default:
/* List all components. */
gc_component_list_components (get_outfp (&outfp));
break;
case aCheckPrograms:
/* Check all programs. */
gc_check_programs (get_outfp (&outfp));
break;
case aListOptions:
case aChangeOptions:
case aCheckOptions:
if (!fname)
{
es_fprintf (es_stderr, _("usage: %s [options] "), GPGCONF_NAME);
es_putc ('\n', es_stderr);
es_fputs (_("Need one component argument"), es_stderr);
es_putc ('\n', es_stderr);
exit (2);
}
else
{
int idx = gc_component_find (fname);
if (idx < 0)
{
es_fputs (_("Component not found"), es_stderr);
es_putc ('\n', es_stderr);
exit (1);
}
if (cmd == aCheckOptions)
gc_component_check_options (idx, get_outfp (&outfp), NULL);
else
{
gc_component_retrieve_options (idx);
if (gc_process_gpgconf_conf (NULL, 1, 0, NULL))
exit (1);
if (cmd == aListOptions)
gc_component_list_options (idx, get_outfp (&outfp));
else if (cmd == aChangeOptions)
gc_component_change_options (idx, es_stdin, get_outfp (&outfp));
}
}
break;
case aLaunch:
case aKill:
if (!fname)
{
es_fprintf (es_stderr, _("usage: %s [options] "), GPGCONF_NAME);
es_putc ('\n', es_stderr);
es_fputs (_("Need one component argument"), es_stderr);
es_putc ('\n', es_stderr);
exit (2);
}
else
{
/* Launch/Kill a given component. */
int idx;
idx = gc_component_find (fname);
if (idx < 0)
{
es_fputs (_("Component not found"), es_stderr);
es_putc ('\n', es_stderr);
exit (1);
}
else if (cmd == aLaunch)
{
if (gc_component_launch (idx))
exit (1);
}
else
{
/* We don't error out if the kill failed because this
command should do nothing if the component is not
running. */
gc_component_kill (idx);
}
}
break;
case aReload:
if (!fname)
{
/* Reload all. */
gc_component_reload (-1);
}
else
{
/* Reload given component. */
int idx;
idx = gc_component_find (fname);
if (idx < 0)
{
es_fputs (_("Component not found"), es_stderr);
es_putc ('\n', es_stderr);
exit (1);
}
else
{
gc_component_reload (idx);
}
}
break;
case aListConfig:
if (gc_process_gpgconf_conf (fname, 0, 0, get_outfp (&outfp)))
exit (1);
break;
case aCheckConfig:
if (gc_process_gpgconf_conf (fname, 0, 0, NULL))
exit (1);
break;
case aApplyDefaults:
if (fname)
{
es_fprintf (es_stderr, _("usage: %s [options] "), GPGCONF_NAME);
es_putc ('\n', es_stderr);
es_fputs (_("No argument allowed"), es_stderr);
es_putc ('\n', es_stderr);
exit (2);
}
gc_component_retrieve_options (-1);
if (gc_process_gpgconf_conf (NULL, 1, 1, NULL))
exit (1);
break;
case aListDirs:
/* Show the system configuration directories for gpgconf. */
get_outfp (&outfp);
- es_fprintf (outfp, "sysconfdir:%s\n",
- gc_percent_escape (gnupg_sysconfdir ()));
- es_fprintf (outfp, "bindir:%s\n",
- gc_percent_escape (gnupg_bindir ()));
- es_fprintf (outfp, "libexecdir:%s\n",
- gc_percent_escape (gnupg_libexecdir ()));
- es_fprintf (outfp, "libdir:%s\n",
- gc_percent_escape (gnupg_libdir ()));
- es_fprintf (outfp, "datadir:%s\n",
- gc_percent_escape (gnupg_datadir ()));
- es_fprintf (outfp, "localedir:%s\n",
- gc_percent_escape (gnupg_localedir ()));
-
- if (dirmngr_user_socket_name ())
- {
- es_fprintf (outfp, "dirmngr-socket:%s\n",
- gc_percent_escape (dirmngr_user_socket_name ()));
- es_fprintf (outfp, "dirmngr-sys-socket:%s\n",
- gc_percent_escape (dirmngr_sys_socket_name ()));
- }
- else
- {
- es_fprintf (outfp, "dirmngr-socket:%s\n",
- gc_percent_escape (dirmngr_sys_socket_name ()));
- }
-
- {
- char *tmp = make_filename (gnupg_socketdir (),
- GPG_AGENT_SOCK_NAME, NULL);
- es_fprintf (outfp, "agent-socket:%s\n", gc_percent_escape (tmp));
- xfree (tmp);
- }
- {
- char *tmp = xstrdup (gnupg_homedir ());
- es_fprintf (outfp, "homedir:%s\n", gc_percent_escape (tmp));
- xfree (tmp);
- }
+ list_dirs (outfp, argc? argv : NULL);
break;
case aCreateSocketDir:
{
char *socketdir;
unsigned int flags;
/* Make sure that the top /run/user/UID/gnupg dir has been
* created. */
gnupg_socketdir ();
/* Check the /var/run dir. */
socketdir = _gnupg_socketdir_internal (1, &flags);
if ((flags & 64) && !opt.dry_run)
{
/* No sub dir - create it. */
if (gnupg_mkdir (socketdir, "-rwx"))
gc_error (1, errno, "error creating '%s'", socketdir);
/* Try again. */
socketdir = _gnupg_socketdir_internal (1, &flags);
}
/* Give some info. */
if ( (flags & ~32) || opt.verbose || opt.dry_run)
{
log_info ("socketdir is '%s'\n", socketdir);
if ((flags & 1)) log_info ("\tgeneral error\n");
if ((flags & 2)) log_info ("\tno /run/user dir\n");
if ((flags & 4)) log_info ("\tbad permissions\n");
if ((flags & 8)) log_info ("\tbad permissions (subdir)\n");
if ((flags & 16)) log_info ("\tmkdir failed\n");
if ((flags & 32)) log_info ("\tnon-default homedir\n");
if ((flags & 64)) log_info ("\tno such subdir\n");
if ((flags & 128)) log_info ("\tusing homedir as fallback\n");
}
if ((flags & ~32) && !opt.dry_run)
gc_error (1, 0, "error creating socket directory");
xfree (socketdir);
}
break;
case aRemoveSocketDir:
{
char *socketdir;
unsigned int flags;
/* Check the /var/run dir. */
socketdir = _gnupg_socketdir_internal (1, &flags);
if ((flags & 128))
log_info ("ignoring request to remove non /run/user socket dir\n");
else if (opt.dry_run)
;
else if (rmdir (socketdir))
gc_error (1, errno, "error removing '%s'", socketdir);
xfree (socketdir);
}
break;
}
if (outfp != es_stdout)
if (es_fclose (outfp))
gc_error (1, errno, "error closing '%s'", opt.outfile);
return 0;
}

File Metadata

Mime Type
text/x-diff
Expires
Sun, Feb 23, 7:17 PM (20 m, 28 s)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
01/f8/03976828644ba1a74c2a1d1c03a0

Event Timeline