mirror of
git://git.gnupg.org/gnupg.git
synced 2024-09-07 12:56:21 +02:00
1627 lines
53 KiB
Plaintext
1627 lines
53 KiB
Plaintext
@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 controlled and audited, and it doesn't permit
|
||
@c the supplicant to either copy the key or to override the owner's
|
||
@c intentions.
|
||
|
||
@example
|
||
gpg-connect-agent /bye
|
||
@end example
|
||
|
||
@noindent
|
||
If you want to manually terminate the currently-running agent, you can
|
||
safely do so with:
|
||
|
||
@example
|
||
gpgconf --kill gpg-agent
|
||
@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.
|
||
|
||
@item --supervised
|
||
@opindex supervised
|
||
Run in the foreground, sending logs by default to stderr, and
|
||
listening on provided file descriptors, which must already be bound to
|
||
listening sockets. This command is useful when running under systemd
|
||
or other similar process supervision schemes. This option is not
|
||
supported on Windows.
|
||
|
||
In --supervised mode, different file descriptors can be provided for
|
||
use as different socket types (e.g. ssh, extra) as long as they are
|
||
identified in the environment variable @code{LISTEN_FDNAMES} (see
|
||
sd_listen_fds(3) on some Linux distributions for more information on
|
||
this convention).
|
||
@end table
|
||
|
||
@mansect options
|
||
@node Agent Options
|
||
@section Option Summary
|
||
|
||
Options may either be used on the command line or, after stripping off
|
||
the two leading dashes, in the configuration file.
|
||
|
||
@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. This option is ignored
|
||
if used in an options file.
|
||
|
||
@anchor{option --homedir}
|
||
@include opt-homedir.texi
|
||
|
||
|
||
@item -v
|
||
@itemx --verbose
|
||
@opindex verbose
|
||
Outputs additional information while running.
|
||
You can increase the verbosity by giving several
|
||
verbose commands to @command{gpg-agent}, such as @samp{-vv}.
|
||
|
||
@item -q
|
||
@itemx --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
|
||
Set debug flags. All flags are or-ed and @var{flags} may be given
|
||
in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
|
||
To get a list of all supported flags the single word "help" can be
|
||
used. This option is only useful for debugging and the behavior may
|
||
change at any time without notice.
|
||
|
||
@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 --grab
|
||
@itemx --no-grab
|
||
@opindex grab
|
||
@opindex no-grab
|
||
Tell the pinentry to grab the keyboard and mouse. This option should
|
||
be used on X-Servers to avoid X-sniffing attacks. Any use of the
|
||
option @option{--grab} overrides an used option @option{--no-grab}.
|
||
The default is @option{--no-grab}.
|
||
|
||
@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. Use @file{socket://} to log to
|
||
socket. 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 behavior 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}. Note that a cached passphrase may not be
|
||
evicted immediately from memory if no client requests a cache
|
||
operation. This is due to an internal housekeeping function which is
|
||
only run every few seconds.
|
||
|
||
@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}
|
||
@itemx --check-sym-passphrase-pattern @var{file}
|
||
@opindex check-passphrase-pattern
|
||
@opindex check-sym-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. If @var{file} does not contain any slashes and does not
|
||
start with "~/" it is searched in the system configuration directory
|
||
(@file{@value{SYSCONFDIR}}). The default is not to use any
|
||
pattern file. The second version of this option is only used when
|
||
creating a new symmetric key to allow the use of different patterns
|
||
for such passphrases.
|
||
|
||
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-formatted-passphrase
|
||
@opindex pinentry-formatted-passphrase
|
||
This option asks the Pinentry to enable passphrase formatting when asking the
|
||
user for a new passphrase and masking of the passphrase is turned off.
|
||
|
||
If passphrase formatting is enabled, then all non-breaking space characters
|
||
are stripped from the entered passphrase. Passphrase formatting is mostly
|
||
useful in combination with passphrases generated with the GENPIN
|
||
feature of some Pinentries. Note that such a generated
|
||
passphrase, if not modified by the user, skips all passphrase
|
||
constraints checking because such constraints would actually weaken
|
||
the generated passphrase.
|
||
|
||
@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.
|
||
|
||
@item --listen-backlog @var{n}
|
||
@opindex listen-backlog
|
||
Set the size of the queue for pending connections. The default is 64.
|
||
|
||
@anchor{option --extra-socket}
|
||
@item --extra-socket @var{name}
|
||
@opindex extra-socket
|
||
The extra socket is created by default, you may use this option to
|
||
change the name of the socket. To disable the creation of the socket
|
||
use ``none'' or ``/dev/null'' for @var{name}.
|
||
|
||
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 enables decrypting or
|
||
signing data on a remote machine without exposing the private keys to the
|
||
remote machine.
|
||
|
||
@item --enable-extended-key-format
|
||
@itemx --disable-extended-key-format
|
||
@opindex enable-extended-key-format
|
||
@opindex disable-extended-key-format
|
||
Since version 2.3 keys are created in the extended private key format.
|
||
Changing the passphrase of a key will also convert the key to that new
|
||
format. This new key format is supported since GnuPG version 2.1.12
|
||
and thus there should be no need to disable it. The disable option
|
||
allows to revert to the old behavior for new keys; be aware that keys
|
||
are never migrated back to the old format. However if the enable
|
||
option has been used the disable option won't have an effect. The
|
||
advantage of the extended private key format is that it is text based
|
||
and can carry additional meta data.
|
||
|
||
@anchor{option --enable-ssh-support}
|
||
@item --enable-ssh-support
|
||
@itemx --enable-putty-support
|
||
@opindex enable-ssh-support
|
||
@opindex enable-putty-support
|
||
|
||
The OpenSSH Agent protocol is always enabled, but @command{gpg-agent}
|
||
will only set the @code{SSH_AUTH_SOCK} variable if this flag is given.
|
||
|
||
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}.
|
||
|
||
@anchor{option --ssh-fingerprint-digest}
|
||
@item --ssh-fingerprint-digest
|
||
@opindex ssh-fingerprint-digest
|
||
|
||
Select the digest algorithm used to compute ssh fingerprints that are
|
||
communicated to the user, e.g. in pinentry dialogs. OpenSSH has
|
||
transitioned from using MD5 to the more secure SHA256.
|
||
|
||
|
||
@item --auto-expand-secmem @var{n}
|
||
@opindex auto-expand-secmem
|
||
Allow Libgcrypt to expand its secure memory area as required. The
|
||
optional value @var{n} is a non-negative integer with a suggested size
|
||
in bytes of each additionally allocated secure memory area. The value
|
||
is rounded up to the next 32 KiB; usual C style prefixes are allowed.
|
||
For an heavy loaded gpg-agent with many concurrent connection this
|
||
option avoids sign or decrypt errors due to out of secure memory error
|
||
returns.
|
||
|
||
@item --s2k-calibration @var{milliseconds}
|
||
@opindex s2k-calibration
|
||
Change the default calibration time to @var{milliseconds}. The given
|
||
value is capped at 60 seconds; a value of 0 resets to the compiled-in
|
||
default. This option is re-read on a SIGHUP (or @code{gpgconf
|
||
--reload gpg-agent}) and the S2K count is then re-calibrated.
|
||
|
||
@item --s2k-count @var{n}
|
||
@opindex s2k-count
|
||
Specify the iteration count used to protect the passphrase. This
|
||
option can be used to override the auto-calibration done by default.
|
||
The auto-calibration computes a count which requires by default 100ms
|
||
to mangle a given passphrase. See also @option{--s2k-calibration}.
|
||
|
||
To view the actually used iteration count and the milliseconds
|
||
required for an S2K operation use:
|
||
|
||
@example
|
||
gpg-connect-agent 'GETINFO s2k_count' /bye
|
||
gpg-connect-agent 'GETINFO s2k_time' /bye
|
||
@end example
|
||
|
||
To view the auto-calibrated count use:
|
||
|
||
@example
|
||
gpg-connect-agent 'GETINFO s2k_count_cal' /bye
|
||
@end example
|
||
|
||
|
||
@end table
|
||
|
||
|
||
@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
|
||
enables cutting and pasting 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 @ref{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.
|
||
|
||
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{s2k-count},
|
||
@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="$(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 decryption 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 asks 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
|
||
tests 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 may 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. A not-yet-defined
|
||
option allows choosing 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 ourselves, 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 hexadecimal 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 infinite 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 @option{--send}
|
||
option given the certificates are sent 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:
|
||
@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 each change of the card reader's status.
|
||
@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 @ref{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 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.
|
||
|
||
@item pretend-request-origin
|
||
This option switches the connection into a restricted mode which
|
||
handles all further commands in the same way as they would be handled
|
||
when originating from the extra or browser socket. Note that this
|
||
option is not available in the restricted mode. Valid values for this
|
||
option are:
|
||
|
||
@table @code
|
||
@item none
|
||
@itemx local
|
||
This is a NOP and leaves the connection in the standard way.
|
||
|
||
@item remote
|
||
Pretend to come from a remote origin in the same way as connections
|
||
from the @option{--extra-socket}.
|
||
|
||
@item browser
|
||
Pretend to come from a local web browser in the same way as connections
|
||
from the @option{--browser-socket}.
|
||
@end table
|
||
|
||
@end table
|
||
|
||
|
||
@mansect see also
|
||
@ifset isman
|
||
@command{@gpgname}(1),
|
||
@command{gpgsm}(1),
|
||
@command{gpgconf}(1),
|
||
@command{gpg-connect-agent}(1),
|
||
@command{scdaemon}(1)
|
||
@end ifset
|
||
@include see-also-note.texi
|