26
26
If you don't use an X server, you can also put this into your regular
27
27
startup file @code{~/.profile} or @code{.bash_profile}. It is best not
28
to run multiple instance of the @command{gpg-agent}, so you should make sure that
29
only is running: @command{gpg-agent} uses an environment variable to inform
30
clients about the communication parameters. You can write the
31
content of this environment variable to a file so that you can test for
32
a running agent. This short script may do the job:
28
to run multiple instance of the @command{gpg-agent}, so you should make
29
sure that only one is running: @command{gpg-agent} uses an environment
30
variable to inform clients about the communication parameters. You can
31
write the content of this environment variable to a file so that you can
32
test for a running agent. This short script may do the job:
35
35
if test -f $HOME/.gpg-agent-info && \
272
292
Set the time a cache entry is valid to @var{n} seconds. The default are
295
@item --default-cache-ttl-ssh @var{n}
296
@opindex default-cache-ttl
297
Set the time a cache entry used for SSH keys is valid to @var{n}
298
seconds. The default are 1800 seconds.
275
300
@item --max-cache-ttl @var{n}
276
301
@opindex max-cache-ttl
277
302
Set the maximum time a cache entry is valid to @var{n} seconds. After
278
303
this time a cache entry will get expired even if it has been accessed
279
304
recently. The default are 2 hours (7200 seconds).
306
@item --max-cache-ttl-ssh @var{n}
307
@opindex max-cache-ttl-ssh
308
Set the maximum time a cache entry used for SSH keys is valid to @var{n}
309
seconds. After this time a cache entry will get expired even if it has
310
been accessed recently. The default are 2 hours (7200 seconds).
281
312
@item --pinentry-program @var{filename}
282
313
@opindex pinentry-program
283
314
Use program @var{filename} as the PIN entry. The default is installation
326
363
window system's @code{DISPLAY} variable. This is useful to lock the
327
364
pinentry to pop up at the @sc{tty} or display you started the agent.
366
@anchor{option --enable-ssh-support}
367
@item --enable-ssh-support
368
@opindex enable-ssh-support
370
Enable emulation of the OpenSSH Agent protocol.
372
In this mode of operation, the agent does not only implement the
373
gpg-agent protocol, but also the agent protocol used by OpenSSH
374
(through a seperate socket). Consequently, it should possible to use
375
the gpg-agent as a drop-in replacement for the well known ssh-agent.
377
SSH Keys, which are to be used through the agent, need to be added to
378
the gpg-agent initially through the ssh-add utility. When a key is
379
added, ssh-add will ask for the password of the provided key file and
380
send the unprotected key material to the agent; this causes the
381
gpg-agent to ask for a passphrase, which is to be used for encrypting
382
the newly received key and storing it in a gpg-agent specific
385
Once, a key has been added to the gpg-agent this way, the gpg-agent
386
will be ready to use the key.
388
Note: in case the gpg-agent receives a signature request, the user might
389
need to be prompted for a passphrase, which is necessary for decrypting
390
the stored key. Since the ssh-agent protocol does not contain a
391
mechanism for telling the agent on which display/terminal it is running,
392
gpg-agent's ssh-support will use the TTY or X display where gpg-agent
393
has been started. To switch this display to the current one, the
394
follwing command may be used:
397
echo UPDATESTARTUPTTY | gpg-connect-agent
332
404
All the long options may also be given in the configuration file after
333
405
stripping off the two leading dashes.
410
@node Agent Configuration
411
@section Configuration
413
There are a few configuration files needed for the operation of the
414
agent. By default they may all be found in the current home directory
415
(@pxref{option --homedir}).
420
@cindex gpg-agent.conf
421
This is the standard configuration file read by @command{gpg-agent} on
422
startup. It may contain any valid long option; the leading
423
two dashes may not be entered and the option may not be abbreviated.
424
This file is also read after a @code{SIGHUP} however only a few
425
options will actually have an effect. This default name may be
426
changed on the command line (@pxref{option --options}).
429
This is the list of trusted keys. Comment lines, indicated by a leading
430
hash mark, as well as empty lines are ignored. To mark a key as trusted
431
you need to enter its fingerprint followed by a space and a capital
432
letter @code{S}. Colons may optionally be used to separate the bytes of
433
a fingerprint; this allows to cut and paste the fingeperint from a key
436
Here is an example where two keys are marked as ultimately trusted:
439
# CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
440
A6935DD34EF3087973C706FC311AA2CCF733765B S
442
# CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
443
DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
446
Before entering a key into this file, you need to ensure its
447
authenticity. How to do this depends on your organisation; your
448
administrator might have already entered those keys which are deemed
449
trustworthy enough into this file. Places where to look for the
450
fingerprint of a root certificate are letters received from the CA or
451
the website of the CA (after making 100% sure that this is indeed the
452
website of that CA). You may want to consider allowing interactive
453
updates of this file by using the @xref{option --allow-mark-trusted}.
454
This is however not as secure as maintaining this file manually. It is
455
even advisable to change the permissions to read-only so that this file
456
can't be changed inadvertently.
460
This file is used when support for the secure shell agent protocol has
461
been enabled (@pxref{option --enable-ssh-support}). Only keys present in
462
this file are used in the SSH protocol. The @command{ssh-add} tool y be
463
used to add new entries to this file; you may also add them manually.
464
Comment lines, indicated by a leading hash mark, as well as empty lines
465
are ignored. An entry starts with optional white spaces, followed by
466
the keygrip of the key given as 40 hex digits, optionally followed by
467
the caching TTL in seconds and another optional field for arbitrary
468
flags. A @code{!} may be prepended to the keygrip to disable this
471
The follwoing example lists exactly one key. Note that keys available
472
through a OpenPGP smartcard in the active smartcard reader are implictly
473
added to this list; i.e. there is no need to list them.
476
# Key added on 2005-02-25 15:08:29
477
5A6592BF45DC73BD876874A28FD4639282E29B52 0
481
Note that on larger installations, it is useful to put predefined
482
files into the directory @file{/etc/skel/.gnupg/} so that newly created
483
users start up with a working configuration. For existing users the
484
a small helper script is provied to create these files (@pxref{addgnupghome}).
349
This signals flushes all chached passphrases and when the program was
502
This signal flushes all chached passphrases and if the program has been
350
503
started with a configuration file, the configuration file is read again.
351
504
Only certain options are honored: @code{quiet}, @code{verbose},
352
@code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program},
353
@code{default-cache-ttl} and @code{ignore-cache-for-signing}.
354
@code{scdaemon-program} is also supported but due to the current
355
implementation, which calls the scdaemon only once, it is not of much
505
@code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
506
@code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
507
@code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
508
@code{disable-scdaemon}. @code{scdaemon-program} is also supported but
509
due to the current implementation, which calls the scdaemon only once,
510
it is not of much use unless you manually kill the scdaemon.
added
removed
doc/gpg-agent.texi
