1GPG-AGENT(1) GNU Privacy Guard GPG-AGENT(1)
2
6 gpg-agent - Secret key management for GnuPG
7
9 gpg-agent [--homedir dir] [--options file] [options]
10 gpg-agent [--homedir dir] [--options file] [options] --server
11 gpg-agent [--homedir dir] [--options file] [options] --daemon [com‐
12 mand_line]
13
16 gpg-agent is a daemon to manage secret (private) keys independently
17 from any protocol. It is used as a backend for gpg and gpgsm as well
18 as for a couple of other utilities.
19 The usual way to run the agent is from the ~/.xsession file:
22 eval `gpg-agent --daemon`
24 If you don't use an X server, you can also put this into your regular
27 startup file ~/.profile or .bash_profile. It is best not to run multi‐
28 ple instance of the gpg-agent, so you should make sure that only one is
29 running: gpg-agent uses an environment variable to inform clients about
30 the communication parameters. You can write the content of this envi‐
31 ronment variable to a file so that you can test for a running agent.
32 This short script may do the job:
33 if test -f $HOME/.gpg-agent-info && kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
35 GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
36 export GPG_AGENT_INFO
37 else
38 eval `gpg-agent --daemon`
39 echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
40 fi
41 Note that the new option --write-env-file may be used instead.
44 You should always add the following lines to your .bashrc or whatever
48 initialization file is used for all shell invocations:
49 GPG_TTY=`tty`
51 export GPG_TTY
52 It is important that this environment variable always reflects the out‐
55 put of the tty command. For W32 systems this option is not required.
56 Please make sure that a proper pinentry program has been installed
58 under the default filename (which is system dependant) or use the
59 option pinentry-program to specify the full name of that program. It
60 is often useful to install a symbolic link from the actual used pinen‐
61 try (e.g. `/usr/bin/pinentry-gtk') to the expected one (e.g.
62 `/usr/bin/pinentry').
63
68 Commands are not distinguished from options execpt for the fact that
69 only one one command is allowed.
70 --version
73 Print the program version and licensing information. Not that
74 you can abbreviate this command.
75 --help
78 -h Print a usage message summarizing the most useful command-line
80 options. Not that you can abbreviate this command.
81 --dump-options
84 Print a list of all available options and commands. Not that
85 you can abbreviate this command.
86 --server
89 Run in server mode and wait for commands on the stdin. The
90 default mode is to create a socket and listen for commands
91 there.
92 --daemon [command line]
95 Run the program in the background. This option is required to
96 prevent it from being accidently running in the background. A
97 common way to do this is:
98 $ eval `gpg-agent --daemon`
99
103 --options file
104 Reads configuration from file instead of from the default per-
105 user configuration file. The default configuration file is
106 named `gpg-agent.conf' and expected in the `.gnupg' directory
107 directly below the home directory of the user.
108 --homedir dir
112 Set the name of the home directory to dir. If his option is not
113 used, the home directory defaults to `~/.gnupg'. It is only
114 recognized when given on the command line. It also overrides
115 any home directory stated through the environment variable
116 `GNUPGHOME' or (on W32 systems) by means on the Registry entry
117 HKCU\Software\GNU\GnuPG:HomeDir.
118 -v
122 --verbose
124 Outputs additional information while running. You can increase
125 the verbosity by giving several verbose commands to gpgsm, such
126 as '-vv'.
127 -q
130 --quiet
132 Try to be as quiet as possible.
133 --batch
136 Don't invoke a pinentry or do any other thing requiring human
137 interaction.
138 --faked-system-time epoch
141 This option is only useful for testing; it sets the system time
142 back or forth to epoch which is the number of seconds elapsed
143 since the year 1970.
144 --debug-level level
147 Select the debug level for investigating problems. level may be
148 one of:
149 .RS
151 .TP none
152 no debugging at all.
153 .TP basic
154 some basic debug messages
155 .TP advanced
156 more verbose debug messages
157 .TP expert
158 even more detailed messages
159 .TP guru
160 all of the debug messages you can get
161 .RE
162 How these messages are mapped to the actual debugging flags is
164 not specified and may change with newer releaes of this program.
165 They are however carefully selected to best aid in debugging.
166 --debug flags
169 This option is only useful for debugging and the behaviour may
170 change at any time without notice. FLAGS are bit encoded and
171 may be given in usual C-Syntax. The currently defined bits are:
172 0 (1) X.509 or OpenPGP protocol related data
175 1 (2) values of big number integers
177 2 (4) low level crypto operations
179 5 (32) memory allocation
181 6 (64) caching
183 7 (128)
185 show memory statistics.
186 9 (512)
188 write hashed data to files named dbgmd-000*
189 10 (1024)
191 trace Assuan protocol
192 12 (4096)
194 bypass all certificate validation
195 --debug-all
198 Same as --debug=0xffffffff
199 --debug-wait n
202 When running in server mode, wait n seconds before entering the
203 actual processing loop and print the pid. This gives time to
204 attach a debugger.
205 --no-detach
208 Don't detach the process from the console. This is manly use‐
209 fule for debugging.
210 -s
213 --sh
215 -c
217 --csh Format the info output in daemon mode for use with the standard
219 Bourne shell respective the C-shell . The default is to guess it
220 based on the environment variable SHELL which is in almost all
221 cases sufficient.
222 --write-env-file file
225 Often it is required to connect to the agent from a process not
226 being an inferior of gpg-agent and thus the environment variable
227 with the socket name is not available. To help setting up those
228 variables in other sessions, this option may be used to write
229 the information into file. If file is not specified the default
230 name `${HOME}/.gpg-agent-info' will be used. The format is
231 suitable to be evaluated by a Bourne shell like in this simple
232 example:
233 eval `cat file`
235 eval `cut -d= -f 1 < file | xargs echo export`
236 --no-grab
241 Tell the pinentry not to grab the keyboard and mouse. This
242 option should in general not be used to avoid X-sniffing
243 attacks.
244 --log-file file
247 Append all logging output to file. This is very helpful in see‐
248 ing what the agent actually does.
249 --allow-mark-trusted
253 Allow clients to mark keys as trusted, i.e. put them into the
254 `trustlist.txt' file. This is by default not allowed to make it
255 harder for users to inadvertly accept Root-CA keys.
256 --ignore-cache-for-signing
259 This option will let gpg-agent bypass the passphrase cache for
260 all signing operation. Note that there is also a per-session
261 option to control this behaviour but this command line option
262 takes precedence.
263 --default-cache-ttl n
266 Set the time a cache entry is valid to n seconds. The default
267 are 600 seconds.
268 --default-cache-ttl-ssh n
271 Set the time a cache entry used for SSH keys is valid to n sec‐
272 onds. The default are 1800 seconds.
273 --max-cache-ttl n
276 Set the maximum time a cache entry is valid to n seconds. After
277 this time a cache entry will get expired even if it has been
278 accessed recently. The default are 2 hours (7200 seconds).
279 --max-cache-ttl-ssh n
282 Set the maximum time a cache entry used for SSH keys is valid to
283 n seconds. After this time a cache entry will get expired even
284 if it has been accessed recently. The default are 2 hours (7200
285 seconds).
286 --enforce-passphrase-constraints
289 Enforce the passphrase constraints by not allowing the user to
290 bypass them using the ``Take it anyway'' button.
291 --min-passphrase-len n
294 Set the minimal length of a passphrase. When entering a new
295 passphrase shorter than this value a warning will be displayed.
296 Defaults to 8.
297 --min-passphrase-nonalpha n
300 Set the minimal number of digits or special characters required
301 in a passphrase. When entering a new passphrase with less than
302 this number of digits or special characters a warning will be
303 displayed. Defaults to 1.
304 --check-passphrase-pattern file
307 Check the passphrase against the pattern given in file. When
308 entering a new passphrase matching one of these pattern a warn‐
309 ing will be displayed. file should be an absolute filename. The
310 default is not to use any pattern file.
311 Security note: It is known that checking a passphrase against a
313 list of pattern or even against a complete dictionary is not
314 very effective to enforce good passphrases. Users will soon
315 figure up ways to bypass such a policy. A better policy is to
316 educate users on good security behavior and optional to run a
317 passphrase cracker regularly on all users passphrases t catch
318 the very simple ones.
319 --max-passphrase-days n
322 Ask the user to change the passphrase if n days have passed
323 since the last change. With --enforce-passphrase-constraints
324 set the user may not bypass this check.
325 --enable-passphrase-history
328 This option does nothing yet.
329 --pinentry-program filename
332 Use program filename as the PIN entry. The default is installa‐
333 tion dependend and can be shown with the --version command.
334 --pinentry-touch-file filename
337 By default the file name of the socket gpg-agent is listening
338 for requests is passed to Pinentry, so that it can touch that
339 file before exiting (it does this only in curses mode). This
340 option changes the file passed to Pinentry to filename. The
341 special name /dev/null may be used to completely disable this
342 feature. Note that Pinentry will not create that file, it will
343 only change the modification and access time.
344 --scdaemon-program filename
348 Use program filename as the Smartcard daemon. The default is
349 installation dependend and can be shown with the --version com‐
350 mand.
351 --disable-scdaemon
354 Do not make use of the scdaemon tool. This option has the
355 effect of disabling the ability to do smartcard operations.
356 Note, that enabling this option at runtime does not kill an
357 already forked scdaemon.
358 --use-standard-socket
361 --no-use-standard-socket
363 By enabling this option gpg-agent will listen on the socket
364 named `S.gpg-agent', located in the home directory, and not cre‐
365 ate a random socket below a temporary directory. Tools connect‐
366 ing to gpg-agent should first try to connect to the socket given
367 in environment variable GPG_AGENT_INFO and the fall back to this
368 socket. This option may not be used if the home directory is
369 mounted as a remote file system. Note, that --use-standard-
370 socket is the default on Windows systems.
371 --display string
375 --ttyname string
377 --ttytype string
379 --lc-type string
381 --lc-messages string
383 --xauthority string
385 These options are used with the server mode to pass localization
386 information.
387 --keep-tty
390 --keep-display
392 Ignore requests to change change the current tty respective the
393 X window system's DISPLAY variable. This is useful to lock the
394 pinentry to pop up at the tty or display you started the agent.
395 --enable-ssh-support
399 Enable emulation of the OpenSSH Agent protocol.
401 In this mode of operation, the agent does not only implement the
403 gpg-agent protocol, but also the agent protocol used by OpenSSH
404 (through a seperate socket). Consequently, it should possible
405 to use the gpg-agent as a drop-in replacement for the well known
406 ssh-agent.
407 SSH Keys, which are to be used through the agent, need to be
409 added to the gpg-agent initially through the ssh-add utility.
410 When a key is added, ssh-add will ask for the password of the
411 provided key file and send the unprotected key material to the
412 agent; this causes the gpg-agent to ask for a passphrase, which
413 is to be used for encrypting the newly received key and storing
414 it in a gpg-agent specific directory.
415 Once, a key has been added to the gpg-agent this way, the gpg-
417 agent will be ready to use the key.
418 Note: in case the gpg-agent receives a signature request, the
420 user might need to be prompted for a passphrase, which is neces‐
421 sary for decrypting the stored key. Since the ssh-agent proto‐
422 col does not contain a mechanism for telling the agent on which
423 display/terminal it is running, gpg-agent's ssh-support will use
424 the TTY or X display where gpg-agent has been started. To
425 switch this display to the current one, the follwing command may
426 be used:
427 echo UPDATESTARTUPTTY | gpg-connect-agent
429 All the long options may also be given in the configuration file after
434 stripping off the two leading dashes.
435
439 The usual way to invoke gpg-agent is
440 $ eval `gpg-agent --daemon`
442 An alternative way is by replacing ssh-agent with gpg-agent. If for
444 example ssh-agent is started as part of the Xsession intialization you
445 may simply replace ssh-agent by a script like:
446 #!/bin/sh
448 exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon --write-env-file ${HOME}/.gpg-agent-info "$@"
450 and add something like (for Bourne shells)
453 if [ -f "${HOME}/.gpg-agent-info" ]; then
455 . "${HOME}/.gpg-agent-info"
456 export GPG_AGENT_INFO
457 export SSH_AUTH_SOCK
458 export SSH_AGENT_PID
459 fi
460 to your shell initialization file (e.g. `~/.bashrc').
463
467 There are a few configuration files needed for the operation of the
468 agent. By default they may all be found in the current home directory
469 (see: [option --homedir]).
470 gpg-agent.conf
474 This is the standard configuration file read by gpg-agent on
475 startup. It may contain any valid long option; the leading
476 two dashes may not be entered and the option may not be abbre‐
477 viated.
478 This file is also read after a SIGHUP however only a few
479 options will actually have an effect. This default name may
480 be
481 changed on the command line (see: [option --options]).
482 trustlist.txt
485 This is the list of trusted keys. Comment lines, indicated by
486 a leading
487 hash mark, as well as empty lines are ignored. To mark a key
488 as trusted
489 you need to enter its fingerprint followed by a space and a
490 capital
491 letter S. Colons may optionally be used to separate the bytes
492 of
493 a fingerprint; this allows to cut and paste the fingerprint
494 from a key
495 listing output.
496 Here is an example where two keys are marked as ultimately
498 trusted:
499 .RS 2
501 # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
502 A6935DD34EF3087973C706FC311AA2CCF733765B S
503 # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
505 DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
506 .fi
507 Before entering a key into this file, you need to ensure its
509 authenticity. How to do this depends on your organisation; your
510 administrator might have already entered those keys which are deemed
511 trustworthy enough into this file. Places where to look for the
512 fingerprint of a root certificate are letters received from the CA or
513 the website of the CA (after making 100% sure that this is indeed the
514 website of that CA). You may want to consider allowing interactive
515 updates of this file by using the see: [option --allow-mark-trusted].
516 This is however not as secure as maintaining this file manually. It is
517 even advisable to change the permissions to read-only so that this file
518 can't be changed inadvertently.
519 As a special feature a line include-default will include a global
521 list of trusted certificates (e.g. `/etc/gnupg/trustlist.txt').
522 This global list is also used if the local list is not available.
523 It is possible to add further flags after the S for use by the
525 caller:
526 relax Relax checking of some root certificate requirements. This is for
529 example required if the certificate is missing the basicConstraints
530 attribute (despite that it is a MUST for CA certificates).
531 cm If validation of a certificate finally issued by a CA with this flag set
534 fails, try again using the chain validation model.
535 sshcontrol
540 This file is used when support for the secure shell agent protocol has
542 been enabled (see: [option --enable-ssh-support]). Only keys present
543 in this file are used in the SSH protocol. The ssh-add tool
544 y be used to add new entries to this file; you may also add them
545 manually. Comment lines, indicated by a leading hash mark, as well as
546 empty lines are ignored. An entry starts with optional white spaces,
547 followed by the keygrip of the key given as 40 hex digits, optionally
548 followed by the caching TTL in seconds and another optional field for
549 arbitrary flags. A ! may be prepended to the keygrip to
550 disable this entry.
551 The follwoing example lists exactly one key. Note that keys available
553 through a OpenPGP smartcard in the active smartcard reader are
554 implictly added to this list; i.e. there is no need to list them.
555 .RS 2
557 # Key added on 2005-02-25 15:08:29
558 5A6592BF45DC73BD876874A28FD4639282E29B52 0
559 .fi
560 private-keys-v1.d/
563 This is the directory where gpg-agent stores the private keys. Each
565 key is stored in a file with the name made up of the keygrip and the
566 suffix `key'.
567 Note that on larger installations, it is useful to put predefined
571 files into the directory `/etc/skel/.gnupg/' so that newly created
572 users start up with a working configuration. For existing users the
573 a small helper script is provied to create these files (see: [addgnupghome]).
574
580 A running gpg-agent may be controlled by signals, i.e. using the kill
581 command to send a signal to the process.
582 Here is a list of supported signals:
584 SIGHUP This signal flushes all chached passphrases and if the program
588 has been started with a configuration file, the configuration
589 file is read again. Only certain options are honored: quiet,
590 verbose, debug, debug-all, debug-level, no-grab, pinentry-pro‐
591 gram, default-cache-ttl, max-cache-ttl, ignore-cache-for-sign‐
592 ing, allow-mark-trusted and disable-scdaemon. scdaemon-program
593 is also supported but due to the current implementation, which
594 calls the scdaemon only once, it is not of much use unless you
595 manually kill the scdaemon.
596 SIGTERM
600 Shuts down the process but waits until all current requests are
601 fulfilled. If the process has received 3 of these signals and
602 requests are still pending, a shutdown is forced.
603 SIGINT Shuts down the process immediately.
606 SIGUSR1
609 Dump internal information to the log file.
610 SIGUSR2
613 This signal is used for internal purposes.
614
619 gpg2(1), gpgsm(1), gpg-connect-agent(1), scdaemon(1)
620 The full documentation for this tool is maintained as a Texinfo manual.
622 If GnuPG and the info program are properly installed at your site, the
623 command
624 info gnupg
626 should give you access to the complete manual including a menu struc‐
628 ture and an index.
629GnuPG 2.0.8 2008-01-24 GPG-AGENT(1)