diff options
Diffstat (limited to 'doc/gpg-agent.texi')
| -rw-r--r-- | doc/gpg-agent.texi | 1672 |
1 files changed, 1672 insertions, 0 deletions
diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi new file mode 100644 index 0000000..8766250 --- /dev/null +++ b/doc/gpg-agent.texi @@ -0,0 +1,1672 @@ +@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 +This option is only useful for debugging and the behavior 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 --steal-socket +@opindex steal-socket +In @option{--daemon} mode, gpg-agent detects an already running +gpg-agent and does not allow to start a new instance. This option can +be used to override this check: the new gpg-agent process will try to +take over the communication sockets from the already running process +and start anyway. This option should in general not be used. + + +@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 --no-user-trustlist} +@item --no-user-trustlist +@opindex no-user-trustlist +Entirely ignore the user trust list and consider only the global +trustlist (@file{@value{SYSCONFDIR}/trustlist.txt}). This +implies the @ref{option --no-allow-mark-trusted}. + +@item --sys-trustlist-name @var{file} +@opindex sys-trustlist-name +Changes the default name for the global trustlist from "trustlist.txt" +to @var{file}. If @var{file} does not contain any slashes and does +not start with "~/" it is searched in the system configuration +directory (@file{@value{SYSCONFDIR}}). + +@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.2.22 keys are created in the extended private key +format by default. Changing the passphrase of a key will also convert +the key to that new format. This key format is supported since GnuPG +version 2.1.12 and thus there should be no need to disable it. +Anyway, the disable option still allows to revert to the old behavior +for new keys; be aware that keys are never migrated back to the old +format. 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. In extended +key format the OCB mode is used for key protection. + +@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; +the @ref{option --no-user-trustlist} enforces the use of only +this global list. + +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 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 @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 |