1@c Copyright (C) 2002 Free Software Foundation, Inc. 2@c This is part of the GnuPG manual. 3@c For copying conditions, see the file gnupg.texi. 4 5@include defs.inc 6 7@node Invoking GPG-AGENT 8@chapter Invoking GPG-AGENT 9@cindex GPG-AGENT command options 10@cindex command options 11@cindex options, GPG-AGENT command 12 13@manpage gpg-agent.1 14@ifset manverb 15.B gpg-agent 16\- Secret key management for GnuPG 17@end ifset 18 19@mansect synopsis 20@ifset manverb 21.B gpg-agent 22.RB [ \-\-homedir 23.IR dir ] 24.RB [ \-\-options 25.IR file ] 26.RI [ options ] 27.br 28.B gpg-agent 29.RB [ \-\-homedir 30.IR dir ] 31.RB [ \-\-options 32.IR file ] 33.RI [ options ] 34.B \-\-server 35.br 36.B gpg-agent 37.RB [ \-\-homedir 38.IR dir ] 39.RB [ \-\-options 40.IR file ] 41.RI [ options ] 42.B \-\-daemon 43.RI [ command_line ] 44@end ifset 45 46@mansect description 47@command{gpg-agent} is a daemon to manage secret (private) keys 48independently from any protocol. It is used as a backend for 49@command{gpg} and @command{gpgsm} as well as for a couple of other 50utilities. 51 52The agent is automatically started on demand by @command{gpg}, 53@command{gpgsm}, @command{gpgconf}, or @command{gpg-connect-agent}. 54Thus there is no reason to start it manually. In case you want to use 55the included Secure Shell Agent you may start the agent using: 56 57@c From dkg on gnupg-devel on 2016-04-21: 58@c 59@c Here's an attempt at writing a short description of the goals of an 60@c isolated cryptographic agent: 61@c 62@c A cryptographic agent should control access to secret key material. 63@c The agent permits use of the secret key material by a supplicant 64@c without providing a copy of the secret key material to the supplicant. 65@c 66@c An isolated cryptographic agent separates the request for use of 67@c secret key material from permission for use of secret key material. 68@c That is, the system or process requesting use of the key (the 69@c "supplicant") can be denied use of the key by the owner/operator of 70@c the agent (the "owner"), which the supplicant has no control over. 71@c 72@c One way of enforcing this split is a per-key or per-session 73@c passphrase, known only by the owner, which must be supplied to the 74@c agent to permit the use of the secret key material. Another way is 75@c with an out-of-band permission mechanism (e.g. a button or GUI 76@c interface that the owner has access to, but the supplicant does not). 77@c 78@c The rationale for this separation is that it allows access to the 79@c secret key to be tightly controlled and audited, and it doesn't permit 80@c the supplicant to either copy the key or to override the owner's 81@c intentions. 82 83@example 84gpg-connect-agent /bye 85@end example 86 87@noindent 88If you want to manually terminate the currently-running agent, you can 89safely do so with: 90 91@example 92gpgconf --kill gpg-agent 93@end example 94 95@noindent 96@efindex GPG_TTY 97You should always add the following lines to your @code{.bashrc} or 98whatever initialization file is used for all shell invocations: 99 100@smallexample 101GPG_TTY=$(tty) 102export GPG_TTY 103@end smallexample 104 105@noindent 106It is important that this environment variable always reflects the 107output of the @code{tty} command. For W32 systems this option is not 108required. 109 110Please make sure that a proper pinentry program has been installed 111under the default filename (which is system dependent) or use the 112option @option{pinentry-program} to specify the full name of that program. 113It is often useful to install a symbolic link from the actual used 114pinentry (e.g. @file{@value{BINDIR}/pinentry-gtk}) to the expected 115one (e.g. @file{@value{BINDIR}/pinentry}). 116 117@manpause 118@noindent 119@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options. 120@mancont 121 122@menu 123* Agent Commands:: List of all commands. 124* Agent Options:: List of all options. 125* Agent Configuration:: Configuration files. 126* Agent Signals:: Use of some signals. 127* Agent Examples:: Some usage examples. 128* Agent Protocol:: The protocol the agent uses. 129@end menu 130 131@mansect commands 132@node Agent Commands 133@section Commands 134 135Commands are not distinguished from options except for the fact that 136only one command is allowed. 137 138@table @gnupgtabopt 139@item --version 140@opindex version 141Print the program version and licensing information. Note that you cannot 142abbreviate this command. 143 144@item --help 145@itemx -h 146@opindex help 147Print a usage message summarizing the most useful command-line options. 148Note that you cannot abbreviate this command. 149 150@item --dump-options 151@opindex dump-options 152Print a list of all available options and commands. Note that you cannot 153abbreviate this command. 154 155@item --server 156@opindex server 157Run in server mode and wait for commands on the @code{stdin}. The 158default mode is to create a socket and listen for commands there. 159 160@item --daemon [@var{command line}] 161@opindex daemon 162Start the gpg-agent as a daemon; that is, detach it from the console 163and run it in the background. 164 165As an alternative you may create a new process as a child of 166gpg-agent: @code{gpg-agent --daemon /bin/sh}. This way you get a new 167shell with the environment setup properly; after you exit from this 168shell, gpg-agent terminates within a few seconds. 169 170@item --supervised 171@opindex supervised 172Run in the foreground, sending logs by default to stderr, and 173listening on provided file descriptors, which must already be bound to 174listening sockets. This command is useful when running under systemd 175or other similar process supervision schemes. This option is not 176supported on Windows. 177 178In --supervised mode, different file descriptors can be provided for 179use as different socket types (e.g. ssh, extra) as long as they are 180identified in the environment variable @code{LISTEN_FDNAMES} (see 181sd_listen_fds(3) on some Linux distributions for more information on 182this convention). 183@end table 184 185@mansect options 186@node Agent Options 187@section Option Summary 188 189Options may either be used on the command line or, after stripping off 190the two leading dashes, in the configuration file. 191 192@table @gnupgtabopt 193 194@anchor{option --options} 195@item --options @var{file} 196@opindex options 197Reads configuration from @var{file} instead of from the default 198per-user configuration file. The default configuration file is named 199@file{gpg-agent.conf} and expected in the @file{.gnupg} directory 200directly below the home directory of the user. This option is ignored 201if used in an options file. 202 203@anchor{option --homedir} 204@include opt-homedir.texi 205 206 207@item -v 208@itemx --verbose 209@opindex verbose 210Outputs additional information while running. 211You can increase the verbosity by giving several 212verbose commands to @command{gpg-agent}, such as @samp{-vv}. 213 214@item -q 215@itemx --quiet 216@opindex quiet 217Try to be as quiet as possible. 218 219@item --batch 220@opindex batch 221Don't invoke a pinentry or do any other thing requiring human interaction. 222 223@item --faked-system-time @var{epoch} 224@opindex faked-system-time 225This option is only useful for testing; it sets the system time back or 226forth to @var{epoch} which is the number of seconds elapsed since the year 2271970. 228 229@item --debug-level @var{level} 230@opindex debug-level 231Select the debug level for investigating problems. @var{level} may be 232a numeric value or a keyword: 233 234@table @code 235@item none 236No debugging at all. A value of less than 1 may be used instead of 237the keyword. 238@item basic 239Some basic debug messages. A value between 1 and 2 may be used 240instead of the keyword. 241@item advanced 242More verbose debug messages. A value between 3 and 5 may be used 243instead of the keyword. 244@item expert 245Even more detailed messages. A value between 6 and 8 may be used 246instead of the keyword. 247@item guru 248All of the debug messages you can get. A value greater than 8 may be 249used instead of the keyword. The creation of hash tracing files is 250only enabled if the keyword is used. 251@end table 252 253How these messages are mapped to the actual debugging flags is not 254specified and may change with newer releases of this program. They are 255however carefully selected to best aid in debugging. 256 257@item --debug @var{flags} 258@opindex debug 259Set debug flags. All flags are or-ed and @var{flags} may be given 260in C syntax (e.g. 0x0042) or as a comma separated list of flag names. 261To get a list of all supported flags the single word "help" can be 262used. This option is only useful for debugging and the behavior may 263change at any time without notice. 264 265@item --debug-all 266@opindex debug-all 267Same as @code{--debug=0xffffffff} 268 269@item --debug-wait @var{n} 270@opindex debug-wait 271When running in server mode, wait @var{n} seconds before entering the 272actual processing loop and print the pid. This gives time to attach a 273debugger. 274 275@item --debug-quick-random 276@opindex debug-quick-random 277This option inhibits the use of the very secure random quality level 278(Libgcrypt’s @code{GCRY_VERY_STRONG_RANDOM}) and degrades all request 279down to standard random quality. It is only used for testing and 280should not be used for any production quality keys. This option is 281only effective when given on the command line. 282 283On GNU/Linux, another way to quickly generate insecure keys is to use 284@command{rngd} to fill the kernel's entropy pool with lower quality 285random data. @command{rngd} is typically provided by the 286@command{rng-tools} package. It can be run as follows: @samp{sudo 287rngd -f -r /dev/urandom}. 288 289@item --debug-pinentry 290@opindex debug-pinentry 291This option enables extra debug information pertaining to the 292Pinentry. As of now it is only useful when used along with 293@code{--debug 1024}. 294 295@item --no-detach 296@opindex no-detach 297Don't detach the process from the console. This is mainly useful for 298debugging. 299 300@item -s 301@itemx --sh 302@itemx -c 303@itemx --csh 304@opindex sh 305@opindex csh 306@efindex SHELL 307Format the info output in daemon mode for use with the standard Bourne 308shell or the C-shell respectively. The default is to guess it based on 309the environment variable @code{SHELL} which is correct in almost all 310cases. 311 312 313@item --grab 314@itemx --no-grab 315@opindex grab 316@opindex no-grab 317Tell the pinentry to grab the keyboard and mouse. This option should 318be used on X-Servers to avoid X-sniffing attacks. Any use of the 319option @option{--grab} overrides an used option @option{--no-grab}. 320The default is @option{--no-grab}. 321 322@anchor{option --log-file} 323@item --log-file @var{file} 324@opindex log-file 325@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile 326Append all logging output to @var{file}. This is very helpful in 327seeing what the agent actually does. Use @file{socket://} to log to 328socket. If neither a log file nor a log file descriptor has been set 329on a Windows platform, the Registry entry 330@code{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to 331specify the logging output. 332 333 334@anchor{option --no-allow-mark-trusted} 335@item --no-allow-mark-trusted 336@opindex no-allow-mark-trusted 337Do not allow clients to mark keys as trusted, i.e. put them into the 338@file{trustlist.txt} file. This makes it harder for users to inadvertently 339accept Root-CA keys. 340 341@anchor{option --allow-preset-passphrase} 342@item --allow-preset-passphrase 343@opindex allow-preset-passphrase 344This option allows the use of @command{gpg-preset-passphrase} to seed the 345internal cache of @command{gpg-agent} with passphrases. 346 347@anchor{option --no-allow-loopback-pinentry} 348@item --no-allow-loopback-pinentry 349@item --allow-loopback-pinentry 350@opindex no-allow-loopback-pinentry 351@opindex allow-loopback-pinentry 352Disallow or allow clients to use the loopback pinentry features; see 353the option @option{pinentry-mode} for details. Allow is the default. 354 355The @option{--force} option of the Assuan command @command{DELETE_KEY} 356is also controlled by this option: The option is ignored if a loopback 357pinentry is disallowed. 358 359@item --no-allow-external-cache 360@opindex no-allow-external-cache 361Tell Pinentry not to enable features which use an external cache for 362passphrases. 363 364Some desktop environments prefer to unlock all 365credentials with one master password and may have installed a Pinentry 366which employs an additional external cache to implement such a policy. 367By using this option the Pinentry is advised not to make use of such a 368cache and instead always ask the user for the requested passphrase. 369 370@item --allow-emacs-pinentry 371@opindex allow-emacs-pinentry 372Tell Pinentry to allow features to divert the passphrase entry to a 373running Emacs instance. How this is exactly handled depends on the 374version of the used Pinentry. 375 376@item --ignore-cache-for-signing 377@opindex ignore-cache-for-signing 378This option will let @command{gpg-agent} bypass the passphrase cache for all 379signing operation. Note that there is also a per-session option to 380control this behavior but this command line option takes precedence. 381 382@item --default-cache-ttl @var{n} 383@opindex default-cache-ttl 384Set the time a cache entry is valid to @var{n} seconds. The default 385is 600 seconds. Each time a cache entry is accessed, the entry's 386timer is reset. To set an entry's maximum lifetime, use 387@command{max-cache-ttl}. Note that a cached passphrase may not be 388evicted immediately from memory if no client requests a cache 389operation. This is due to an internal housekeeping function which is 390only run every few seconds. 391 392@item --default-cache-ttl-ssh @var{n} 393@opindex default-cache-ttl 394Set the time a cache entry used for SSH keys is valid to @var{n} 395seconds. The default is 1800 seconds. Each time a cache entry is 396accessed, the entry's timer is reset. To set an entry's maximum 397lifetime, use @command{max-cache-ttl-ssh}. 398 399@item --max-cache-ttl @var{n} 400@opindex max-cache-ttl 401Set the maximum time a cache entry is valid to @var{n} seconds. After 402this time a cache entry will be expired even if it has been accessed 403recently or has been set using @command{gpg-preset-passphrase}. The 404default is 2 hours (7200 seconds). 405 406@item --max-cache-ttl-ssh @var{n} 407@opindex max-cache-ttl-ssh 408Set the maximum time a cache entry used for SSH keys is valid to 409@var{n} seconds. After this time a cache entry will be expired even 410if it has been accessed recently or has been set using 411@command{gpg-preset-passphrase}. The default is 2 hours (7200 412seconds). 413 414@item --enforce-passphrase-constraints 415@opindex enforce-passphrase-constraints 416Enforce the passphrase constraints by not allowing the user to bypass 417them using the ``Take it anyway'' button. 418 419@item --min-passphrase-len @var{n} 420@opindex min-passphrase-len 421Set the minimal length of a passphrase. When entering a new passphrase 422shorter than this value a warning will be displayed. Defaults to 8. 423 424@item --min-passphrase-nonalpha @var{n} 425@opindex min-passphrase-nonalpha 426Set the minimal number of digits or special characters required in a 427passphrase. When entering a new passphrase with less than this number 428of digits or special characters a warning will be displayed. Defaults 429to 1. 430 431@item --check-passphrase-pattern @var{file} 432@itemx --check-sym-passphrase-pattern @var{file} 433@opindex check-passphrase-pattern 434@opindex check-sym-passphrase-pattern 435Check the passphrase against the pattern given in @var{file}. When 436entering a new passphrase matching one of these pattern a warning will 437be displayed. If @var{file} does not contain any slashes and does not 438start with "~/" it is searched in the system configuration directory 439(@file{@value{SYSCONFDIR}}). The default is not to use any 440pattern file. The second version of this option is only used when 441creating a new symmetric key to allow the use of different patterns 442for such passphrases. 443 444Security note: It is known that checking a passphrase against a list of 445pattern or even against a complete dictionary is not very effective to 446enforce good passphrases. Users will soon figure up ways to bypass such 447a policy. A better policy is to educate users on good security 448behavior and optionally to run a passphrase cracker regularly on all 449users passphrases to catch the very simple ones. 450 451@item --max-passphrase-days @var{n} 452@opindex max-passphrase-days 453Ask the user to change the passphrase if @var{n} days have passed since 454the last change. With @option{--enforce-passphrase-constraints} set the 455user may not bypass this check. 456 457@item --enable-passphrase-history 458@opindex enable-passphrase-history 459This option does nothing yet. 460 461@item --pinentry-invisible-char @var{char} 462@opindex pinentry-invisible-char 463This option asks the Pinentry to use @var{char} for displaying hidden 464characters. @var{char} must be one character UTF-8 string. A 465Pinentry may or may not honor this request. 466 467@item --pinentry-timeout @var{n} 468@opindex pinentry-timeout 469This option asks the Pinentry to timeout after @var{n} seconds with no 470user input. The default value of 0 does not ask the pinentry to 471timeout, however a Pinentry may use its own default timeout value in 472this case. A Pinentry may or may not honor this request. 473 474@item --pinentry-formatted-passphrase 475@opindex pinentry-formatted-passphrase 476This option asks the Pinentry to enable passphrase formatting when asking the 477user for a new passphrase and masking of the passphrase is turned off. 478 479If passphrase formatting is enabled, then all non-breaking space characters 480are stripped from the entered passphrase. Passphrase formatting is mostly 481useful in combination with passphrases generated with the GENPIN 482feature of some Pinentries. Note that such a generated 483passphrase, if not modified by the user, skips all passphrase 484constraints checking because such constraints would actually weaken 485the generated passphrase. 486 487@item --pinentry-program @var{filename} 488@opindex pinentry-program 489Use program @var{filename} as the PIN entry. The default is 490installation dependent. With the default configuration the name of 491the default pinentry is @file{pinentry}; if that file does not exist 492but a @file{pinentry-basic} exist the latter is used. 493 494On a Windows platform the default is to use the first existing program 495from this list: 496@file{bin\pinentry.exe}, 497@file{..\Gpg4win\bin\pinentry.exe}, 498@file{..\Gpg4win\pinentry.exe}, 499@file{..\GNU\GnuPG\pinentry.exe}, 500@file{..\GNU\bin\pinentry.exe}, 501@file{bin\pinentry-basic.exe} 502where the file names are relative to the GnuPG installation directory. 503 504 505@item --pinentry-touch-file @var{filename} 506@opindex pinentry-touch-file 507By default the filename of the socket gpg-agent is listening for 508requests is passed to Pinentry, so that it can touch that file before 509exiting (it does this only in curses mode). This option changes the 510file passed to Pinentry to @var{filename}. The special name 511@code{/dev/null} may be used to completely disable this feature. Note 512that Pinentry will not create that file, it will only change the 513modification and access time. 514 515 516@item --scdaemon-program @var{filename} 517@opindex scdaemon-program 518Use program @var{filename} as the Smartcard daemon. The default is 519installation dependent and can be shown with the @command{gpgconf} 520command. 521 522@item --disable-scdaemon 523@opindex disable-scdaemon 524Do not make use of the scdaemon tool. This option has the effect of 525disabling the ability to do smartcard operations. Note, that enabling 526this option at runtime does not kill an already forked scdaemon. 527 528@item --disable-check-own-socket 529@opindex disable-check-own-socket 530@command{gpg-agent} employs a periodic self-test to detect a stolen 531socket. This usually means a second instance of @command{gpg-agent} 532has taken over the socket and @command{gpg-agent} will then terminate 533itself. This option may be used to disable this self-test for 534debugging purposes. 535 536@item --use-standard-socket 537@itemx --no-use-standard-socket 538@itemx --use-standard-socket-p 539@opindex use-standard-socket 540@opindex no-use-standard-socket 541@opindex use-standard-socket-p 542Since GnuPG 2.1 the standard socket is always used. These options 543have no more effect. The command @code{gpg-agent 544--use-standard-socket-p} will thus always return success. 545 546@item --display @var{string} 547@itemx --ttyname @var{string} 548@itemx --ttytype @var{string} 549@itemx --lc-ctype @var{string} 550@itemx --lc-messages @var{string} 551@itemx --xauthority @var{string} 552@opindex display 553@opindex ttyname 554@opindex ttytype 555@opindex lc-ctype 556@opindex lc-messages 557@opindex xauthority 558These options are used with the server mode to pass localization 559information. 560 561@item --keep-tty 562@itemx --keep-display 563@opindex keep-tty 564@opindex keep-display 565Ignore requests to change the current @code{tty} or X window system's 566@code{DISPLAY} variable respectively. This is useful to lock the 567pinentry to pop up at the @code{tty} or display you started the agent. 568 569@item --listen-backlog @var{n} 570@opindex listen-backlog 571Set the size of the queue for pending connections. The default is 64. 572 573@anchor{option --extra-socket} 574@item --extra-socket @var{name} 575@opindex extra-socket 576The extra socket is created by default, you may use this option to 577change the name of the socket. To disable the creation of the socket 578use ``none'' or ``/dev/null'' for @var{name}. 579 580Also listen on native gpg-agent connections on the given socket. The 581intended use for this extra socket is to setup a Unix domain socket 582forwarding from a remote machine to this socket on the local machine. 583A @command{gpg} running on the remote machine may then connect to the 584local gpg-agent and use its private keys. This enables decrypting or 585signing data on a remote machine without exposing the private keys to the 586remote machine. 587 588@item --enable-extended-key-format 589@itemx --disable-extended-key-format 590@opindex enable-extended-key-format 591@opindex disable-extended-key-format 592Since version 2.3 keys are created in the extended private key format. 593Changing the passphrase of a key will also convert the key to that new 594format. This new key format is supported since GnuPG version 2.1.12 595and thus there should be no need to disable it. The disable option 596allows to revert to the old behavior for new keys; be aware that keys 597are never migrated back to the old format. However if the enable 598option has been used the disable option won't have an effect. The 599advantage of the extended private key format is that it is text based 600and can carry additional meta data. 601 602@anchor{option --enable-ssh-support} 603@item --enable-ssh-support 604@itemx --enable-putty-support 605@opindex enable-ssh-support 606@opindex enable-putty-support 607 608The OpenSSH Agent protocol is always enabled, but @command{gpg-agent} 609will only set the @code{SSH_AUTH_SOCK} variable if this flag is given. 610 611In this mode of operation, the agent does not only implement the 612gpg-agent protocol, but also the agent protocol used by OpenSSH 613(through a separate socket). Consequently, it should be possible to use 614the gpg-agent as a drop-in replacement for the well known ssh-agent. 615 616SSH Keys, which are to be used through the agent, need to be added to 617the gpg-agent initially through the ssh-add utility. When a key is 618added, ssh-add will ask for the password of the provided key file and 619send the unprotected key material to the agent; this causes the 620gpg-agent to ask for a passphrase, which is to be used for encrypting 621the newly received key and storing it in a gpg-agent specific 622directory. 623 624Once a key has been added to the gpg-agent this way, the gpg-agent 625will be ready to use the key. 626 627Note: in case the gpg-agent receives a signature request, the user might 628need to be prompted for a passphrase, which is necessary for decrypting 629the stored key. Since the ssh-agent protocol does not contain a 630mechanism for telling the agent on which display/terminal it is running, 631gpg-agent's ssh-support will use the TTY or X display where gpg-agent 632has been started. To switch this display to the current one, the 633following command may be used: 634 635@smallexample 636gpg-connect-agent updatestartuptty /bye 637@end smallexample 638 639Although all GnuPG components try to start the gpg-agent as needed, this 640is not possible for the ssh support because ssh does not know about it. 641Thus if no GnuPG tool which accesses the agent has been run, there is no 642guarantee that ssh is able to use gpg-agent for authentication. To fix 643this you may start gpg-agent if needed using this simple command: 644 645@smallexample 646gpg-connect-agent /bye 647@end smallexample 648 649Adding the @option{--verbose} shows the progress of starting the agent. 650 651The @option{--enable-putty-support} is only available under Windows 652and allows the use of gpg-agent with the ssh implementation 653@command{putty}. This is similar to the regular ssh-agent support but 654makes use of Windows message queue as required by @command{putty}. 655 656@anchor{option --ssh-fingerprint-digest} 657@item --ssh-fingerprint-digest 658@opindex ssh-fingerprint-digest 659 660Select the digest algorithm used to compute ssh fingerprints that are 661communicated to the user, e.g. in pinentry dialogs. OpenSSH has 662transitioned from using MD5 to the more secure SHA256. 663 664 665@item --auto-expand-secmem @var{n} 666@opindex auto-expand-secmem 667Allow Libgcrypt to expand its secure memory area as required. The 668optional value @var{n} is a non-negative integer with a suggested size 669in bytes of each additionally allocated secure memory area. The value 670is rounded up to the next 32 KiB; usual C style prefixes are allowed. 671For an heavy loaded gpg-agent with many concurrent connection this 672option avoids sign or decrypt errors due to out of secure memory error 673returns. 674 675@item --s2k-calibration @var{milliseconds} 676@opindex s2k-calibration 677Change the default calibration time to @var{milliseconds}. The given 678value is capped at 60 seconds; a value of 0 resets to the compiled-in 679default. This option is re-read on a SIGHUP (or @code{gpgconf 680--reload gpg-agent}) and the S2K count is then re-calibrated. 681 682@item --s2k-count @var{n} 683@opindex s2k-count 684Specify the iteration count used to protect the passphrase. This 685option can be used to override the auto-calibration done by default. 686The auto-calibration computes a count which requires by default 100ms 687to mangle a given passphrase. See also @option{--s2k-calibration}. 688 689To view the actually used iteration count and the milliseconds 690required for an S2K operation use: 691 692@example 693gpg-connect-agent 'GETINFO s2k_count' /bye 694gpg-connect-agent 'GETINFO s2k_time' /bye 695@end example 696 697To view the auto-calibrated count use: 698 699@example 700gpg-connect-agent 'GETINFO s2k_count_cal' /bye 701@end example 702 703 704@end table 705 706 707@mansect files 708@node Agent Configuration 709@section Configuration 710 711There are a few configuration files needed for the operation of the 712agent. By default they may all be found in the current home directory 713(@pxref{option --homedir}). 714 715@table @file 716 717@item gpg-agent.conf 718@efindex gpg-agent.conf 719 This is the standard configuration file read by @command{gpg-agent} on 720 startup. It may contain any valid long option; the leading 721 two dashes may not be entered and the option may not be abbreviated. 722 This file is also read after a @code{SIGHUP} however only a few 723 options will actually have an effect. This default name may be 724 changed on the command line (@pxref{option --options}). 725 You should backup this file. 726 727@item trustlist.txt 728@efindex trustlist.txt 729 This is the list of trusted keys. You should backup this file. 730 731 Comment lines, indicated by a leading hash mark, as well as empty 732 lines are ignored. To mark a key as trusted you need to enter its 733 fingerprint followed by a space and a capital letter @code{S}. Colons 734 may optionally be used to separate the bytes of a fingerprint; this 735 enables cutting and pasting the fingerprint from a key listing output. If 736 the line is prefixed with a @code{!} the key is explicitly marked as 737 not trusted. 738 739 Here is an example where two keys are marked as ultimately trusted 740 and one as not trusted: 741 742 @cartouche 743 @smallexample 744 # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE 745 A6935DD34EF3087973C706FC311AA2CCF733765B S 746 747 # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE 748 DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S 749 750 # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE 751 !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S 752 @end smallexample 753 @end cartouche 754 755Before entering a key into this file, you need to ensure its 756authenticity. How to do this depends on your organisation; your 757administrator might have already entered those keys which are deemed 758trustworthy enough into this file. Places where to look for the 759fingerprint of a root certificate are letters received from the CA or 760the website of the CA (after making 100% sure that this is indeed the 761website of that CA). You may want to consider disallowing interactive 762updates of this file by using the @ref{option --no-allow-mark-trusted}. 763It might even be advisable to change the permissions to read-only so 764that this file can't be changed inadvertently. 765 766As a special feature a line @code{include-default} will include a global 767list of trusted certificates (e.g. @file{@value{SYSCONFDIR}/trustlist.txt}). 768This global list is also used if the local list is not available. 769 770It is possible to add further flags after the @code{S} for use by the 771caller: 772 773@table @code 774 775@item relax 776@cindex relax 777Relax checking of some root certificate requirements. As of now this 778flag allows the use of root certificates with a missing basicConstraints 779attribute (despite that it is a MUST for CA certificates) and disables 780CRL checking for the root certificate. 781 782@item cm 783If validation of a certificate finally issued by a CA with this flag set 784fails, try again using the chain validation model. 785 786@end table 787 788 789@item sshcontrol 790@efindex sshcontrol 791This file is used when support for the secure shell agent protocol has 792been enabled (@pxref{option --enable-ssh-support}). Only keys present in 793this file are used in the SSH protocol. You should backup this file. 794 795The @command{ssh-add} tool may be used to add new entries to this file; 796you may also add them manually. Comment lines, indicated by a leading 797hash mark, as well as empty lines are ignored. An entry starts with 798optional whitespace, followed by the keygrip of the key given as 40 hex 799digits, optionally followed by the caching TTL in seconds and another 800optional field for arbitrary flags. A non-zero TTL overrides the global 801default as set by @option{--default-cache-ttl-ssh}. 802 803The only flag support is @code{confirm}. If this flag is found for a 804key, each use of the key will pop up a pinentry to confirm the use of 805that key. The flag is automatically set if a new key was loaded into 806@code{gpg-agent} using the option @option{-c} of the @code{ssh-add} 807command. 808 809The keygrip may be prefixed with a @code{!} to disable an entry. 810 811The following example lists exactly one key. Note that keys available 812through a OpenPGP smartcard in the active smartcard reader are 813implicitly added to this list; i.e. there is no need to list them. 814 815@cartouche 816@smallexample 817 # Key added on: 2011-07-20 20:38:46 818 # Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81 819 34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm 820@end smallexample 821@end cartouche 822 823@item private-keys-v1.d/ 824@efindex private-keys-v1.d 825 826 This is the directory where gpg-agent stores the private keys. Each 827 key is stored in a file with the name made up of the keygrip and the 828 suffix @file{key}. You should backup all files in this directory 829 and take great care to keep this backup closed away. 830 831 832@end table 833 834Note that on larger installations, it is useful to put predefined 835files into the directory @file{@value{SYSCONFSKELDIR}} so that newly created 836users start up with a working configuration. For existing users the 837a small helper script is provided to create these files (@pxref{addgnupghome}). 838 839 840 841@c 842@c Agent Signals 843@c 844@mansect signals 845@node Agent Signals 846@section Use of some signals 847A running @command{gpg-agent} may be controlled by signals, i.e. using 848the @command{kill} command to send a signal to the process. 849 850Here is a list of supported signals: 851 852@table @gnupgtabopt 853 854@item SIGHUP 855@cpindex SIGHUP 856This signal flushes all cached passphrases and if the program has been 857started with a configuration file, the configuration file is read 858again. Only certain options are honored: @code{quiet}, 859@code{verbose}, @code{debug}, @code{debug-all}, @code{debug-level}, 860@code{debug-pinentry}, 861@code{no-grab}, 862@code{pinentry-program}, 863@code{pinentry-invisible-char}, 864@code{default-cache-ttl}, 865@code{max-cache-ttl}, @code{ignore-cache-for-signing}, 866@code{s2k-count}, 867@code{no-allow-external-cache}, @code{allow-emacs-pinentry}, 868@code{no-allow-mark-trusted}, @code{disable-scdaemon}, and 869@code{disable-check-own-socket}. @code{scdaemon-program} is also 870supported but due to the current implementation, which calls the 871scdaemon only once, it is not of much use unless you manually kill the 872scdaemon. 873 874 875@item SIGTERM 876@cpindex SIGTERM 877Shuts down the process but waits until all current requests are 878fulfilled. If the process has received 3 of these signals and requests 879are still pending, a shutdown is forced. 880 881@item SIGINT 882@cpindex SIGINT 883Shuts down the process immediately. 884 885@item SIGUSR1 886@cpindex SIGUSR1 887Dump internal information to the log file. 888 889@item SIGUSR2 890@cpindex SIGUSR2 891This signal is used for internal purposes. 892 893@end table 894 895@c 896@c Examples 897@c 898@mansect examples 899@node Agent Examples 900@section Examples 901 902It is important to set the environment variable @code{GPG_TTY} in 903your login shell, for example in the @file{~/.bashrc} init script: 904 905@cartouche 906@example 907 export GPG_TTY=$(tty) 908@end example 909@end cartouche 910 911If you enabled the Ssh Agent Support, you also need to tell ssh about 912it by adding this to your init script: 913 914@cartouche 915@example 916unset SSH_AGENT_PID 917if [ "$@{gnupg_SSH_AUTH_SOCK_by:-0@}" -ne $$ ]; then 918 export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" 919fi 920@end example 921@end cartouche 922 923 924@c 925@c Assuan Protocol 926@c 927@manpause 928@node Agent Protocol 929@section Agent's Assuan Protocol 930 931Note: this section does only document the protocol, which is used by 932GnuPG components; it does not deal with the ssh-agent protocol. To 933see the full specification of each command, use 934 935@example 936 gpg-connect-agent 'help COMMAND' /bye 937@end example 938 939@noindent 940or just 'help' to list all available commands. 941 942@noindent 943The @command{gpg-agent} daemon is started on demand by the GnuPG 944components. 945 946To identify a key we use a thing called keygrip which is the SHA-1 hash 947of an canonical encoded S-Expression of the public key as used in 948Libgcrypt. For the purpose of this interface the keygrip is given as a 949hex string. The advantage of using this and not the hash of a 950certificate is that it will be possible to use the same keypair for 951different protocols, thereby saving space on the token used to keep the 952secret keys. 953 954The @command{gpg-agent} may send status messages during a command or when 955returning from a command to inform a client about the progress or result of an 956operation. For example, the @var{INQUIRE_MAXLEN} status message may be sent 957during a server inquire to inform the client of the maximum usable length of 958the inquired data (which should not be exceeded). 959 960@menu 961* Agent PKDECRYPT:: Decrypting a session key 962* Agent PKSIGN:: Signing a Hash 963* Agent GENKEY:: Generating a Key 964* Agent IMPORT:: Importing a Secret Key 965* Agent EXPORT:: Exporting a Secret Key 966* Agent ISTRUSTED:: Importing a Root Certificate 967* Agent GET_PASSPHRASE:: Ask for a passphrase 968* Agent CLEAR_PASSPHRASE:: Expire a cached passphrase 969* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip 970* Agent GET_CONFIRMATION:: Ask for confirmation 971* Agent HAVEKEY:: Check whether a key is available 972* Agent LEARN:: Register a smartcard 973* Agent PASSWD:: Change a Passphrase 974* Agent UPDATESTARTUPTTY:: Change the Standard Display 975* Agent GETEVENTCOUNTER:: Get the Event Counters 976* Agent GETINFO:: Return information about the process 977* Agent OPTION:: Set options for the session 978@end menu 979 980@node Agent PKDECRYPT 981@subsection Decrypting a session key 982 983The client asks the server to decrypt a session key. The encrypted 984session key should have all information needed to select the 985appropriate secret key or to delegate it to a smartcard. 986 987@example 988 SETKEY <keyGrip> 989@end example 990 991Tell the server about the key to be used for decryption. If this is 992not used, @command{gpg-agent} may try to figure out the key by trying to 993decrypt the message with each key available. 994 995@example 996 PKDECRYPT 997@end example 998 999The agent checks whether this command is allowed and then does an 1000INQUIRY to get the ciphertext the client should then send the cipher 1001text. 1002 1003@example 1004 S: INQUIRE CIPHERTEXT 1005 C: D (xxxxxx 1006 C: D xxxx) 1007 C: END 1008@end example 1009 1010Please note that the server may send status info lines while reading the 1011data lines from the client. The data send is a SPKI like S-Exp with 1012this structure: 1013 1014@example 1015 (enc-val 1016 (<algo> 1017 (<param_name1> <mpi>) 1018 ... 1019 (<param_namen> <mpi>))) 1020@end example 1021 1022Where algo is a string with the name of the algorithm; see the libgcrypt 1023documentation for a list of valid algorithms. The number and names of 1024the parameters depend on the algorithm. The agent does return an error 1025if there is an inconsistency. 1026 1027If the decryption was successful the decrypted data is returned by 1028means of "D" lines. 1029 1030Here is an example session: 1031@cartouche 1032@smallexample 1033 C: PKDECRYPT 1034 S: INQUIRE CIPHERTEXT 1035 C: D (enc-val elg (a 349324324) 1036 C: D (b 3F444677CA))) 1037 C: END 1038 S: # session key follows 1039 S: S PADDING 0 1040 S: D (value 1234567890ABCDEF0) 1041 S: OK decryption successful 1042@end smallexample 1043@end cartouche 1044 1045The “PADDING” status line is only send if gpg-agent can tell what kind 1046of padding is used. As of now only the value 0 is used to indicate 1047that the padding has been removed. 1048 1049 1050@node Agent PKSIGN 1051@subsection Signing a Hash 1052 1053The client asks the agent to sign a given hash value. A default key 1054will be chosen if no key has been set. To set a key a client first 1055uses: 1056 1057@example 1058 SIGKEY <keyGrip> 1059@end example 1060 1061This can be used multiple times to create multiple signature, the list 1062of keys is reset with the next PKSIGN command or a RESET. The server 1063tests whether the key is a valid key to sign something and responds with 1064okay. 1065 1066@example 1067 SETHASH --hash=<name>|<algo> <hexstring> 1068@end example 1069 1070The client can use this command to tell the server about the data <hexstring> 1071(which usually is a hash) to be signed. <algo> is the decimal encoded hash 1072algorithm number as used by Libgcrypt. Either <algo> or --hash=<name> 1073must be given. Valid names for <name> are: 1074 1075@table @code 1076@item sha1 1077The SHA-1 hash algorithm 1078@item sha256 1079The SHA-256 hash algorithm 1080@item rmd160 1081The RIPE-MD160 hash algorithm 1082@item md5 1083The old and broken MD5 hash algorithm 1084@item tls-md5sha1 1085A combined hash algorithm as used by the TLS protocol. 1086@end table 1087 1088@noindent 1089The actual signing is done using 1090 1091@example 1092 PKSIGN <options> 1093@end example 1094 1095Options are not yet defined, but may later be used to choose among 1096different algorithms. The agent does then some checks, asks for the 1097passphrase and as a result the server returns the signature as an SPKI 1098like S-expression in "D" lines: 1099 1100@example 1101 (sig-val 1102 (<algo> 1103 (<param_name1> <mpi>) 1104 ... 1105 (<param_namen> <mpi>))) 1106@end example 1107 1108 1109The operation is affected by the option 1110 1111@example 1112 OPTION use-cache-for-signing=0|1 1113@end example 1114 1115The default of @code{1} uses the cache. Setting this option to @code{0} 1116will lead @command{gpg-agent} to ignore the passphrase cache. Note, that there is 1117also a global command line option for @command{gpg-agent} to globally disable the 1118caching. 1119 1120 1121Here is an example session: 1122@cartouche 1123@smallexample 1124 C: SIGKEY <keyGrip> 1125 S: OK key available 1126 C: SIGKEY <keyGrip> 1127 S: OK key available 1128 C: PKSIGN 1129 S: # I did ask the user whether he really wants to sign 1130 S: # I did ask the user for the passphrase 1131 S: INQUIRE HASHVAL 1132 C: D ABCDEF012345678901234 1133 C: END 1134 S: # signature follows 1135 S: D (sig-val rsa (s 45435453654612121212)) 1136 S: OK 1137@end smallexample 1138@end cartouche 1139 1140@node Agent GENKEY 1141@subsection Generating a Key 1142 1143This is used to create a new keypair and store the secret key inside the 1144active PSE --- which is in most cases a Soft-PSE. A not-yet-defined 1145option allows choosing the storage location. To get the secret key out 1146of the PSE, a special export tool has to be used. 1147 1148@example 1149 GENKEY [--no-protection] [--preset] [<cache_nonce>] 1150@end example 1151 1152Invokes the key generation process and the server will then inquire 1153on the generation parameters, like: 1154 1155@example 1156 S: INQUIRE KEYPARM 1157 C: D (genkey (rsa (nbits 1024))) 1158 C: END 1159@end example 1160 1161The format of the key parameters which depends on the algorithm is of 1162the form: 1163 1164@example 1165 (genkey 1166 (algo 1167 (parameter_name_1 ....) 1168 .... 1169 (parameter_name_n ....))) 1170@end example 1171 1172If everything succeeds, the server returns the *public key* in a SPKI 1173like S-Expression like this: 1174 1175@example 1176 (public-key 1177 (rsa 1178 (n <mpi>) 1179 (e <mpi>))) 1180@end example 1181 1182Here is an example session: 1183@cartouche 1184@smallexample 1185 C: GENKEY 1186 S: INQUIRE KEYPARM 1187 C: D (genkey (rsa (nbits 1024))) 1188 C: END 1189 S: D (public-key 1190 S: D (rsa (n 326487324683264) (e 10001))) 1191 S OK key created 1192@end smallexample 1193@end cartouche 1194 1195The @option{--no-protection} option may be used to prevent prompting for a 1196passphrase to protect the secret key while leaving the secret key unprotected. 1197The @option{--preset} option may be used to add the passphrase to the cache 1198using the default cache parameters. 1199 1200The @option{--inq-passwd} option may be used to create the key with a 1201supplied passphrase. When used the agent does an inquiry with the 1202keyword @code{NEWPASSWD} to retrieve that passphrase. This option 1203takes precedence over @option{--no-protection}; however if the client 1204sends a empty (zero-length) passphrase, this is identical to 1205@option{--no-protection}. 1206 1207@node Agent IMPORT 1208@subsection Importing a Secret Key 1209 1210This operation is not yet supported by GpgAgent. Specialized tools 1211are to be used for this. 1212 1213There is no actual need because we can expect that secret keys 1214created by a 3rd party are stored on a smartcard. If we have 1215generated the key ourselves, we do not need to import it. 1216 1217@node Agent EXPORT 1218@subsection Export a Secret Key 1219 1220Not implemented. 1221 1222Should be done by an extra tool. 1223 1224@node Agent ISTRUSTED 1225@subsection Importing a Root Certificate 1226 1227Actually we do not import a Root Cert but provide a way to validate 1228any piece of data by storing its Hash along with a description and 1229an identifier in the PSE. Here is the interface description: 1230 1231@example 1232 ISTRUSTED <fingerprint> 1233@end example 1234 1235Check whether the OpenPGP primary key or the X.509 certificate with the 1236given fingerprint is an ultimately trusted key or a trusted Root CA 1237certificate. The fingerprint should be given as a hexstring (without 1238any blanks or colons or whatever in between) and may be left padded with 123900 in case of an MD5 fingerprint. GPGAgent will answer with: 1240 1241@example 1242 OK 1243@end example 1244 1245The key is in the table of trusted keys. 1246 1247@example 1248 ERR 304 (Not Trusted) 1249@end example 1250 1251The key is not in this table. 1252 1253Gpg needs the entire list of trusted keys to maintain the web of 1254trust; the following command is therefore quite helpful: 1255 1256@example 1257 LISTTRUSTED 1258@end example 1259 1260GpgAgent returns a list of trusted keys line by line: 1261 1262@example 1263 S: D 000000001234454556565656677878AF2F1ECCFF P 1264 S: D 340387563485634856435645634856438576457A P 1265 S: D FEDC6532453745367FD83474357495743757435D S 1266 S: OK 1267@end example 1268 1269The first item on a line is the hexified fingerprint where MD5 1270fingerprints are @code{00} padded to the left and the second item is a 1271flag to indicate the type of key (so that gpg is able to only take care 1272of PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest 1273of the line, so that we can extend the format in the future. 1274 1275Finally a client should be able to mark a key as trusted: 1276 1277@example 1278 MARKTRUSTED @var{fingerprint} "P"|"S" 1279@end example 1280 1281The server will then pop up a window to ask the user whether she 1282really trusts this key. For this it will probably ask for a text to 1283be displayed like this: 1284 1285@example 1286 S: INQUIRE TRUSTDESC 1287 C: D Do you trust the key with the fingerprint @@FPR@@ 1288 C: D bla fasel blurb. 1289 C: END 1290 S: OK 1291@end example 1292 1293Known sequences with the pattern @@foo@@ are replaced according to this 1294table: 1295 1296@table @code 1297@item @@FPR16@@ 1298Format the fingerprint according to gpg rules for a v3 keys. 1299@item @@FPR20@@ 1300Format the fingerprint according to gpg rules for a v4 keys. 1301@item @@FPR@@ 1302Choose an appropriate format to format the fingerprint. 1303@item @@@@ 1304Replaced by a single @code{@@}. 1305@end table 1306 1307@node Agent GET_PASSPHRASE 1308@subsection Ask for a passphrase 1309 1310This function is usually used to ask for a passphrase to be used for 1311symmetric encryption, but may also be used by programs which need 1312special handling of passphrases. This command uses a syntax which helps 1313clients to use the agent with minimum effort. 1314 1315@example 1316 GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \ 1317 [--qualitybar] @var{cache_id} \ 1318 [@var{error_message} @var{prompt} @var{description}] 1319@end example 1320 1321@var{cache_id} is expected to be a string used to identify a cached 1322passphrase. Use a @code{X} to bypass the cache. With no other 1323arguments the agent returns a cached passphrase or an error. By 1324convention either the hexified fingerprint of the key shall be used for 1325@var{cache_id} or an arbitrary string prefixed with the name of the 1326calling application and a colon: Like @code{gpg:somestring}. 1327 1328@var{error_message} is either a single @code{X} for no error message or 1329a string to be shown as an error message like (e.g. "invalid 1330passphrase"). Blanks must be percent escaped or replaced by @code{+}'. 1331 1332@var{prompt} is either a single @code{X} for a default prompt or the 1333text to be shown as the prompt. Blanks must be percent escaped or 1334replaced by @code{+}. 1335 1336@var{description} is a text shown above the entry field. Blanks must be 1337percent escaped or replaced by @code{+}. 1338 1339The agent either returns with an error or with a OK followed by the hex 1340encoded passphrase. Note that the length of the strings is implicitly 1341limited by the maximum length of a command. If the option 1342@option{--data} is used, the passphrase is not returned on the OK line 1343but by regular data lines; this is the preferred method. 1344 1345If the option @option{--check} is used, the standard passphrase 1346constraints checks are applied. A check is not done if the passphrase 1347has been found in the cache. 1348 1349If the option @option{--no-ask} is used and the passphrase is not in the 1350cache the user will not be asked to enter a passphrase but the error 1351code @code{GPG_ERR_NO_DATA} is returned. 1352 1353If the option @option{--qualitybar} is used and a minimum passphrase 1354length has been configured, a visual indication of the entered 1355passphrase quality is shown. 1356 1357@example 1358 CLEAR_PASSPHRASE @var{cache_id} 1359@end example 1360 1361may be used to invalidate the cache entry for a passphrase. The 1362function returns with OK even when there is no cached passphrase. 1363 1364 1365 1366@node Agent CLEAR_PASSPHRASE 1367@subsection Remove a cached passphrase 1368 1369Use this command to remove a cached passphrase. 1370 1371@example 1372 CLEAR_PASSPHRASE [--mode=normal] <cache_id> 1373@end example 1374 1375The @option{--mode=normal} option can be used to clear a @var{cache_id} that 1376was set by gpg-agent. 1377 1378 1379@node Agent PRESET_PASSPHRASE 1380@subsection Set a passphrase for a keygrip 1381 1382This command adds a passphrase to the cache for the specified @var{keygrip}. 1383 1384@example 1385 PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>] 1386@end example 1387 1388The passphrase is a hexadecimal string when specified. When not specified, the 1389passphrase will be retrieved from the pinentry module unless the 1390@option{--inquire} option was specified in which case the passphrase will be 1391retrieved from the client. 1392 1393The @var{timeout} parameter keeps the passphrase cached for the specified 1394number of seconds. A value of @code{-1} means infinite while @code{0} means 1395the default (currently only a timeout of -1 is allowed, which means to never 1396expire it). 1397 1398 1399@node Agent GET_CONFIRMATION 1400@subsection Ask for confirmation 1401 1402This command may be used to ask for a simple confirmation by 1403presenting a text and 2 buttons: Okay and Cancel. 1404 1405@example 1406 GET_CONFIRMATION @var{description} 1407@end example 1408 1409@var{description}is displayed along with a Okay and Cancel 1410button. Blanks must be percent escaped or replaced by @code{+}. A 1411@code{X} may be used to display confirmation dialog with a default 1412text. 1413 1414The agent either returns with an error or with a OK. Note, that the 1415length of @var{description} is implicitly limited by the maximum 1416length of a command. 1417 1418 1419 1420@node Agent HAVEKEY 1421@subsection Check whether a key is available 1422 1423This can be used to see whether a secret key is available. It does 1424not return any information on whether the key is somehow protected. 1425 1426@example 1427 HAVEKEY @var{keygrips} 1428@end example 1429 1430The agent answers either with OK or @code{No_Secret_Key} (208). The 1431caller may want to check for other error codes as well. More than one 1432keygrip may be given. In this case the command returns success if at 1433least one of the keygrips corresponds to an available secret key. 1434 1435 1436@node Agent LEARN 1437@subsection Register a smartcard 1438 1439@example 1440 LEARN [--send] 1441@end example 1442 1443This command is used to register a smartcard. With the @option{--send} 1444option given the certificates are sent back. 1445 1446 1447@node Agent PASSWD 1448@subsection Change a Passphrase 1449 1450@example 1451 PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] @var{keygrip} 1452@end example 1453 1454This command is used to interactively change the passphrase of the key 1455identified by the hex string @var{keygrip}. The @option{--preset} 1456option may be used to add the new passphrase to the cache using the 1457default cache parameters. 1458 1459 1460@node Agent UPDATESTARTUPTTY 1461@subsection Change the standard display 1462 1463@example 1464 UPDATESTARTUPTTY 1465@end example 1466 1467Set the startup TTY and X-DISPLAY variables to the values of this 1468session. This command is useful to direct future pinentry invocations 1469to another screen. It is only required because there is no way in the 1470ssh-agent protocol to convey this information. 1471 1472 1473@node Agent GETEVENTCOUNTER 1474@subsection Get the Event Counters 1475 1476@example 1477 GETEVENTCOUNTER 1478@end example 1479 1480This function return one status line with the current values of the 1481event counters. The event counters are useful to avoid polling by 1482delaying a poll until something has changed. The values are decimal 1483numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to 14840. The actual values should not be relied upon; they shall only be used 1485to detect a change. 1486 1487The currently defined counters are: 1488@table @code 1489@item ANY 1490Incremented with any change of any of the other counters. 1491@item KEY 1492Incremented for added or removed private keys. 1493@item CARD 1494Incremented for each change of the card reader's status. 1495@end table 1496 1497@node Agent GETINFO 1498@subsection Return information about the process 1499 1500This is a multipurpose function to return a variety of information. 1501 1502@example 1503GETINFO @var{what} 1504@end example 1505 1506The value of @var{what} specifies the kind of information returned: 1507@table @code 1508@item version 1509Return the version of the program. 1510@item pid 1511Return the process id of the process. 1512@item socket_name 1513Return the name of the socket used to connect the agent. 1514@item ssh_socket_name 1515Return the name of the socket used for SSH connections. If SSH support 1516has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned. 1517@end table 1518 1519@node Agent OPTION 1520@subsection Set options for the session 1521 1522Here is a list of session options which are not yet described with 1523other commands. The general syntax for an Assuan option is: 1524 1525@smallexample 1526OPTION @var{key}=@var{value} 1527@end smallexample 1528 1529@noindent 1530Supported @var{key}s are: 1531 1532@table @code 1533@item agent-awareness 1534This may be used to tell gpg-agent of which gpg-agent version the 1535client is aware of. gpg-agent uses this information to enable 1536features which might break older clients. 1537 1538@item putenv 1539Change the session's environment to be used for the 1540Pinentry. Valid values are: 1541 1542 @table @code 1543 @item @var{name} 1544 Delete envvar @var{name} 1545 @item @var{name}= 1546 Set envvar @var{name} to the empty string 1547 @item @var{name}=@var{value} 1548 Set envvar @var{name} to the string @var{value}. 1549 @end table 1550 1551@item use-cache-for-signing 1552See Assuan command @code{PKSIGN}. 1553 1554@item allow-pinentry-notify 1555This does not need any value. It is used to enable the 1556PINENTRY_LAUNCHED inquiry. 1557 1558@item pinentry-mode 1559This option is used to change the operation mode of the pinentry. The 1560following values are defined: 1561 1562 @table @code 1563 @item ask 1564 This is the default mode which pops up a pinentry as needed. 1565 1566 @item cancel 1567 Instead of popping up a pinentry, return the error code 1568 @code{GPG_ERR_CANCELED}. 1569 1570 @item error 1571 Instead of popping up a pinentry, return the error code 1572 @code{GPG_ERR_NO_PIN_ENTRY}. 1573 1574 @item loopback 1575 Use a loopback pinentry. This fakes a pinentry by using inquiries 1576 back to the caller to ask for a passphrase. This option may only be 1577 set if the agent has been configured for that. 1578 To disable this feature use @ref{option --no-allow-loopback-pinentry}. 1579 @end table 1580 1581@item cache-ttl-opt-preset 1582This option sets the cache TTL for new entries created by GENKEY and 1583PASSWD commands when using the @option{--preset} option. It is not 1584used a default value is used. 1585 1586@item s2k-count 1587Instead of using the standard S2K count (which is computed on the 1588fly), the given S2K count is used for new keys or when changing the 1589passphrase of a key. Values below 65536 are considered to be 0. This 1590option is valid for the entire session or until reset to 0. This 1591option is useful if the key is later used on boxes which are either 1592much slower or faster than the actual box. 1593 1594@item pretend-request-origin 1595This option switches the connection into a restricted mode which 1596handles all further commands in the same way as they would be handled 1597when originating from the extra or browser socket. Note that this 1598option is not available in the restricted mode. Valid values for this 1599option are: 1600 1601 @table @code 1602 @item none 1603 @itemx local 1604 This is a NOP and leaves the connection in the standard way. 1605 1606 @item remote 1607 Pretend to come from a remote origin in the same way as connections 1608 from the @option{--extra-socket}. 1609 1610 @item browser 1611 Pretend to come from a local web browser in the same way as connections 1612 from the @option{--browser-socket}. 1613 @end table 1614 1615@end table 1616 1617 1618@mansect see also 1619@ifset isman 1620@command{@gpgname}(1), 1621@command{gpgsm}(1), 1622@command{gpgconf}(1), 1623@command{gpg-connect-agent}(1), 1624@command{scdaemon}(1) 1625@end ifset 1626@include see-also-note.texi 1627