Don't set SSH_AGENTPID_INFO.
[gnupg.git] / doc / gpg-agent.texi
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 @node Invoking GPG-AGENT
6 @chapter Invoking GPG-AGENT
7 @cindex GPG-AGENT command options
8 @cindex command options
9 @cindex options, GPG-AGENT command
10
11 @manpage gpg-agent.1
12 @ifset manverb
13 .B gpg-agent
14 \- Secret key management for GnuPG
15 @end ifset
16
17 @mansect synopsis
18 @ifset manverb
19 .B  gpg-agent
20 .RB [ \-\-homedir
21 .IR dir ]
22 .RB [ \-\-options
23 .IR file ]
24 .RI [ options ]  
25 .br
26 .B  gpg-agent
27 .RB [ \-\-homedir
28 .IR dir ]
29 .RB [ \-\-options
30 .IR file ]
31 .RI [ options ]  
32 .B  \-\-server 
33 .br
34 .B  gpg-agent
35 .RB [ \-\-homedir
36 .IR dir ]
37 .RB [ \-\-options
38 .IR file ]
39 .RI [ options ]  
40 .B  \-\-daemon 
41 .RI [ command_line ]
42 @end ifset
43
44 @mansect description
45 @command{gpg-agent} is a daemon to manage secret (private) keys
46 independently from any protocol.  It is used as a backend for
47 @command{gpg} and @command{gpgsm} as well as for a couple of other
48 utilities.
49
50 @noindent
51 The usual way to run the agent is from the @code{~/.xsession} file:
52
53 @example
54 eval $(gpg-agent --daemon)
55 @end example
56
57 @noindent
58 If you don't use an X server, you can also put this into your regular
59 startup file @code{~/.profile} or @code{.bash_profile}.  It is best not
60 to run multiple instance of the @command{gpg-agent}, so you should make
61 sure that only one is running: @command{gpg-agent} uses an environment
62 variable to inform clients about the communication parameters. You can
63 write the content of this environment variable to a file so that you can
64 test for a running agent.  Here is an example using Bourne shell syntax:
65
66 @smallexample
67 gpg-agent --daemon --enable-ssh-support \
68           --write-env-file "$@{HOME@}/.gpg-agent-info"
69 @end smallexample
70
71 This code should only be run once per user session to initially fire up
72 the agent.  In the example the optional support for the included Secure
73 Shell agent is enabled and the information about the agent is written to
74 a file in the HOME directory.  Note that by running gpg-agent without
75 arguments you may test whether an agent is already running; however such
76 a test may lead to a race condition, thus it is not suggested.
77
78 @noindent
79 The second script needs to be run for each interactive session:
80
81 @smallexample
82 if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
83   . "$@{HOME@}/.gpg-agent-info"
84   export GPG_AGENT_INFO
85   export SSH_AUTH_SOCK
86 fi
87 @end smallexample
88
89 @noindent
90 It reads the data out of the file and exports the variables.  If you
91 don't use Secure Shell, you don't need the last two export statements.
92  
93 @noindent
94 You should always add the following lines to your @code{.bashrc} or
95 whatever initialization file is used for all shell invocations:
96
97 @smallexample
98 GPG_TTY=$(tty)
99 export GPG_TTY
100 @end smallexample
101
102 @noindent
103 It is important that this environment variable always reflects the
104 output of the @code{tty} command.  For W32 systems this option is not
105 required.
106
107 Please make sure that a proper pinentry program has been installed
108 under the default filename (which is system dependant) or use the
109 option @option{pinentry-program} to specify the full name of that program.
110 It is often useful to install a symbolic link from the actual used
111 pinentry (e.g. @file{/usr/bin/pinentry-gtk}) to the expected
112 one (e.g. @file{/usr/bin/pinentry}).
113
114 @manpause
115 @noindent
116 @xref{Option Index},for an index to @command{GPG-AGENT}'s commands and options.
117 @mancont
118
119 @menu
120 * Agent Commands::      List of all commands.
121 * Agent Options::       List of all options.
122 * Agent Configuration:: Configuration files.
123 * Agent Signals::       Use of some signals.
124 * Agent Examples::      Some usage examples.
125 * Agent Protocol::      The protocol the agent uses.
126 @end menu
127
128 @mansect commands
129 @node Agent Commands
130 @section Commands
131
132 Commands are not distinguished from options except for the fact that
133 only one command is allowed.
134
135 @table @gnupgtabopt
136 @item --version
137 @opindex version
138 Print the program version and licensing information.  Note that you cannot
139 abbreviate this command.
140
141 @item --help
142 @itemx -h
143 @opindex help
144 Print a usage message summarizing the most useful command-line options.
145 Note that you cannot abbreviate this command.
146
147 @item --dump-options
148 @opindex dump-options
149 Print a list of all available options and commands.  Note that you cannot
150 abbreviate this command.
151
152 @item --server
153 @opindex server
154 Run in server mode and wait for commands on the @code{stdin}.  The
155 default mode is to create a socket and listen for commands there.
156
157 @item --daemon [@var{command line}]
158 @opindex daemon
159 Start the gpg-agent as a daemon; that is, detach it from the console
160 and run it in the background.  Because @command{gpg-agent} prints out
161 important information required for further use, a common way of
162 invoking gpg-agent is: @code{eval $(gpg-agent --daemon)} to setup the
163 environment variables.  The option @option{--write-env-file} is
164 another way commonly used to do this.  Yet another way is creating
165 a new process as a child of gpg-agent: @code{gpg-agent --daemon
166 /bin/sh}.  This way you get a new shell with the environment setup
167 properly; if you exit from this shell, gpg-agent terminates as well.
168 @end table
169
170 @mansect options
171 @node Agent Options
172 @section Option Summary
173
174 @table @gnupgtabopt
175
176 @anchor{option --options}
177 @item --options @var{file}
178 @opindex options
179 Reads configuration from @var{file} instead of from the default
180 per-user configuration file.  The default configuration file is named
181 @file{gpg-agent.conf} and expected in the @file{.gnupg} directory directly
182 below the home directory of the user.
183
184 @anchor{option --homedir}
185 @include opt-homedir.texi
186
187
188 @item -v
189 @item --verbose
190 @opindex v
191 @opindex verbose
192 Outputs additional information while running.
193 You can increase the verbosity by giving several
194 verbose commands to @command{gpgsm}, such as @samp{-vv}.
195
196 @item -q
197 @item --quiet
198 @opindex q
199 @opindex quiet
200 Try to be as quiet as possible.
201
202 @item --batch
203 @opindex batch
204 Don't invoke a pinentry or do any other thing requiring human interaction.
205
206 @item --faked-system-time @var{epoch}
207 @opindex faked-system-time
208 This option is only useful for testing; it sets the system time back or
209 forth to @var{epoch} which is the number of seconds elapsed since the year
210 1970.
211
212 @item --debug-level @var{level}
213 @opindex debug-level
214 Select the debug level for investigating problems. @var{level} may be
215 a numeric value or a keyword:
216
217 @table @code
218 @item none
219 No debugging at all.  A value of less than 1 may be used instead of
220 the keyword.
221 @item basic  
222 Some basic debug messages.  A value between 1 and 2 may be used
223 instead of the keyword.
224 @item advanced
225 More verbose debug messages.  A value between 3 and 5 may be used
226 instead of the keyword.
227 @item expert
228 Even more detailed messages.  A value between 6 and 8 may be used
229 instead of the keyword.
230 @item guru
231 All of the debug messages you can get. A value greater than 8 may be
232 used instead of the keyword.  The creation of hash tracing files is
233 only enabled if the keyword is used.
234 @end table
235
236 How these messages are mapped to the actual debugging flags is not
237 specified and may change with newer releases of this program. They are
238 however carefully selected to best aid in debugging.
239
240 @item --debug @var{flags}
241 @opindex debug
242 This option is only useful for debugging and the behaviour may change at
243 any time without notice.  FLAGS are bit encoded and may be given in
244 usual C-Syntax. The currently defined bits are:
245
246 @table @code
247 @item 0  (1)
248 X.509 or OpenPGP protocol related data
249 @item 1  (2)  
250 values of big number integers 
251 @item 2  (4)
252 low level crypto operations
253 @item 5  (32)
254 memory allocation
255 @item 6  (64)
256 caching
257 @item 7  (128)
258 show memory statistics.
259 @item 9  (512)
260 write hashed data to files named @code{dbgmd-000*}
261 @item 10 (1024)
262 trace Assuan protocol
263 @item 12 (4096)
264 bypass all certificate validation
265 @end table
266
267 @item --debug-all
268 @opindex debug-all
269 Same as @code{--debug=0xffffffff}
270
271 @item --debug-wait @var{n}
272 @opindex debug-wait
273 When running in server mode, wait @var{n} seconds before entering the
274 actual processing loop and print the pid.  This gives time to attach a
275 debugger.
276
277 @item --no-detach
278 @opindex no-detach
279 Don't detach the process from the console.  This is mainly useful for
280 debugging.
281
282 @item -s
283 @itemx --sh
284 @itemx -c
285 @itemx --csh
286 @opindex s
287 @opindex sh
288 @opindex c
289 @opindex csh
290 Format the info output in daemon mode for use with the standard Bourne
291 shell or the C-shell respectively.  The default is to guess it based on
292 the environment variable @code{SHELL} which is correct in almost all
293 cases.
294
295 @item --write-env-file @var{file}
296 @opindex write-env-file
297 Often it is required to connect to the agent from a process not being an
298 inferior of @command{gpg-agent} and thus the environment variable with
299 the socket name is not available.  To help setting up those variables in
300 other sessions, this option may be used to write the information into
301 @var{file}.  If @var{file} is not specified the default name
302 @file{$@{HOME@}/.gpg-agent-info} will be used.  The format is suitable
303 to be evaluated by a Bourne shell like in this simple example:
304
305 @example
306 eval $(cat @var{file})
307 eval $(cut -d= -f 1 < @var{file} | xargs echo export)
308 @end example
309
310
311
312 @item --no-grab
313 @opindex no-grab
314 Tell the pinentry not to grab the keyboard and mouse.  This option
315 should in general not be used to avoid X-sniffing attacks.
316
317 @item --log-file @var{file}
318 @opindex log-file
319 Append all logging output to @var{file}.  This is very helpful in seeing
320 what the agent actually does.  If neither a log file nor a log file
321 descriptor has been set on a Windows platform, the Registry entry
322 @var{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to specify
323 the logging output.
324
325
326 @anchor{option --allow-mark-trusted}
327 @item --allow-mark-trusted
328 @opindex allow-mark-trusted
329 Allow clients to mark keys as trusted, i.e. put them into the
330 @file{trustlist.txt} file.  This is by default not allowed to make it
331 harder for users to inadvertently accept Root-CA keys.
332
333 @item --ignore-cache-for-signing
334 @opindex ignore-cache-for-signing
335 This option will let @command{gpg-agent} bypass the passphrase cache for all
336 signing operation.  Note that there is also a per-session option to
337 control this behaviour but this command line option takes precedence.
338
339 @item --default-cache-ttl @var{n}
340 @opindex default-cache-ttl
341 Set the time a cache entry is valid to @var{n} seconds.  The default is
342 600 seconds.
343
344 @item --default-cache-ttl-ssh @var{n}
345 @opindex default-cache-ttl
346 Set the time a cache entry used for SSH keys is valid to @var{n}
347 seconds.  The default is 1800 seconds.
348
349 @item --max-cache-ttl @var{n}
350 @opindex max-cache-ttl
351 Set the maximum time a cache entry is valid to @var{n} seconds.  After
352 this time a cache entry will be expired even if it has been accessed
353 recently.  The default is 2 hours (7200 seconds).
354
355 @item --max-cache-ttl-ssh @var{n}
356 @opindex max-cache-ttl-ssh
357 Set the maximum time a cache entry used for SSH keys is valid to @var{n}
358 seconds.  After this time a cache entry will be expired even if it has
359 been accessed recently.  The default is 2 hours (7200 seconds).
360
361 @item --enforce-passphrase-constraints
362 @opindex enforce-passphrase-constraints
363 Enforce the passphrase constraints by not allowing the user to bypass
364 them using the ``Take it anyway'' button.
365
366 @item --min-passphrase-len @var{n}
367 @opindex min-passphrase-len
368 Set the minimal length of a passphrase.  When entering a new passphrase
369 shorter than this value a warning will be displayed.  Defaults to 8.
370
371 @item --min-passphrase-nonalpha @var{n}
372 @opindex min-passphrase-nonalpha
373 Set the minimal number of digits or special characters required in a
374 passphrase.  When entering a new passphrase with less than this number
375 of digits or special characters a warning will be displayed.  Defaults
376 to 1.
377
378 @item --check-passphrase-pattern @var{file}
379 @opindex check-passphrase-pattern
380 Check the passphrase against the pattern given in @var{file}.  When
381 entering a new passphrase matching one of these pattern a warning will
382 be displayed. @var{file} should be an absolute filename.  The default is
383 not to use any pattern file. 
384
385 Security note: It is known that checking a passphrase against a list of
386 pattern or even against a complete dictionary is not very effective to
387 enforce good passphrases.  Users will soon figure up ways to bypass such
388 a policy.  A better policy is to educate users on good security
389 behavior and optionally to run a passphrase cracker regularly on all
390 users passphrases to catch the very simple ones.
391
392 @item --max-passphrase-days @var{n}
393 @opindex max-passphrase-days 
394 Ask the user to change the passphrase if @var{n} days have passed since
395 the last change.  With @option{--enforce-passphrase-constraints} set the
396 user may not bypass this check.
397
398 @item --enable-passphrase-history
399 @opindex enable-passphrase-history
400 This option does nothing yet.
401
402 @item --pinentry-program @var{filename}
403 @opindex pinentry-program
404 Use program @var{filename} as the PIN entry.  The default is installation
405 dependent.
406
407 @item --pinentry-touch-file @var{filename}
408 @opindex pinentry-touch-file
409 By default the filename of the socket gpg-agent is listening for
410 requests is passed to Pinentry, so that it can touch that file before
411 exiting (it does this only in curses mode).  This option changes the
412 file passed to Pinentry to @var{filename}.  The special name
413 @code{/dev/null} may be used to completely disable this feature.  Note
414 that Pinentry will not create that file, it will only change the
415 modification and access time.
416
417
418 @item --scdaemon-program @var{filename}
419 @opindex scdaemon-program
420 Use program @var{filename} as the Smartcard daemon.  The default is
421 installation dependent and can be shown with the @command{gpgconf}
422 command.
423
424 @item --disable-scdaemon
425 @opindex disable-scdaemon
426 Do not make use of the scdaemon tool.  This option has the effect of
427 disabling the ability to do smartcard operations.  Note, that enabling
428 this option at runtime does not kill an already forked scdaemon.
429
430 @item --use-standard-socket
431 @itemx --no-use-standard-socket
432 @opindex use-standard-socket
433 @opindex no-use-standard-socket
434 By enabling this option @command{gpg-agent} will listen on the socket
435 named @file{S.gpg-agent}, located in the home directory, and not create
436 a random socket below a temporary directory.  Tools connecting to
437 @command{gpg-agent} should first try to connect to the socket given in
438 environment variable @var{GPG_AGENT_INFO} and then fall back to this
439 socket.  This option may not be used if the home directory is mounted on
440 a remote file system which does not support special files like fifos or
441 sockets.  Note, that @option{--use-standard-socket} is the default on
442 Windows systems.  The default may be changed at build time.  It is
443 possible to test at runtime whether the agent has been configured for
444 use with the standard socket by issuing the command @command{gpg-agent
445 --use-standard-socket-p} which returns success if the standard socket
446 option has been enabled.
447
448 @item --display @var{string}
449 @itemx --ttyname @var{string}
450 @itemx --ttytype @var{string}
451 @itemx --lc-ctype @var{string}
452 @itemx --lc-messages @var{string}
453 @itemx --xauthority @var{string}
454 @opindex display 
455 @opindex ttyname 
456 @opindex ttytype 
457 @opindex lc-ctype 
458 @opindex lc-messages
459 @opindex xauthority
460 These options are used with the server mode to pass localization
461 information.
462
463 @item --keep-tty
464 @itemx --keep-display
465 @opindex keep-tty
466 @opindex keep-display
467 Ignore requests to change the current @code{tty} or X window system's
468 @code{DISPLAY} variable respectively.  This is useful to lock the
469 pinentry to pop up at the @code{tty} or display you started the agent.
470
471 @anchor{option --enable-ssh-support}
472 @item --enable-ssh-support
473 @opindex enable-ssh-support
474
475 Enable emulation of the OpenSSH Agent protocol.
476
477 In this mode of operation, the agent does not only implement the
478 gpg-agent protocol, but also the agent protocol used by OpenSSH
479 (through a separate socket).  Consequently, it should be possible to use
480 the gpg-agent as a drop-in replacement for the well known ssh-agent.
481
482 SSH Keys, which are to be used through the agent, need to be added to
483 the gpg-agent initially through the ssh-add utility.  When a key is
484 added, ssh-add will ask for the password of the provided key file and
485 send the unprotected key material to the agent; this causes the
486 gpg-agent to ask for a passphrase, which is to be used for encrypting
487 the newly received key and storing it in a gpg-agent specific
488 directory.
489
490 Once a key has been added to the gpg-agent this way, the gpg-agent
491 will be ready to use the key.
492
493 Note: in case the gpg-agent receives a signature request, the user might
494 need to be prompted for a passphrase, which is necessary for decrypting
495 the stored key.  Since the ssh-agent protocol does not contain a
496 mechanism for telling the agent on which display/terminal it is running,
497 gpg-agent's ssh-support will use the TTY or X display where gpg-agent
498 has been started.  To switch this display to the current one, the
499 following command may be used:
500
501 @smallexample
502 echo UPDATESTARTUPTTY | gpg-connect-agent
503 @end smallexample
504
505
506
507 @end table
508
509 All the long options may also be given in the configuration file after
510 stripping off the two leading dashes.
511
512
513 @mansect files
514 @node Agent Configuration
515 @section Configuration
516
517 There are a few configuration files needed for the operation of the
518 agent. By default they may all be found in the current home directory
519 (@pxref{option --homedir}).
520
521 @table @file
522
523 @item gpg-agent.conf
524 @cindex gpg-agent.conf
525   This is the standard configuration file read by @command{gpg-agent} on
526   startup.  It may contain any valid long option; the leading
527   two dashes may not be entered and the option may not be abbreviated.
528   This file is also read after a @code{SIGHUP} however only a few
529   options will actually have an effect.  This default name may be
530   changed on the command line (@pxref{option --options}).  
531   You should backup this file.
532
533 @item trustlist.txt
534   This is the list of trusted keys.  You should backup this file.
535
536   Comment lines, indicated by a leading hash mark, as well as empty
537   lines are ignored.  To mark a key as trusted you need to enter its
538   fingerprint followed by a space and a capital letter @code{S}.  Colons
539   may optionally be used to separate the bytes of a fingerprint; this
540   allows to cut and paste the fingerprint from a key listing output.  If
541   the line is prefixed with a @code{!} the key is explicitly marked as
542   not trusted.
543   
544   Here is an example where two keys are marked as ultimately trusted
545   and one as not trusted:
546   
547   @example
548   # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
549   A6935DD34EF3087973C706FC311AA2CCF733765B S
550   
551   # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
552   DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S 
553
554   # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
555   !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
556   @end example
557   
558 Before entering a key into this file, you need to ensure its
559 authenticity.  How to do this depends on your organisation; your
560 administrator might have already entered those keys which are deemed
561 trustworthy enough into this file.  Places where to look for the
562 fingerprint of a root certificate are letters received from the CA or
563 the website of the CA (after making 100% sure that this is indeed the
564 website of that CA).  You may want to consider allowing interactive
565 updates of this file by using the @xref{option --allow-mark-trusted}.
566 This is however not as secure as maintaining this file manually.  It is
567 even advisable to change the permissions to read-only so that this file
568 can't be changed inadvertently.
569
570 As a special feature a line @code{include-default} will include a global
571 list of trusted certificates (e.g. @file{/etc/gnupg/trustlist.txt}).
572 This global list is also used if the local list is not available.
573
574 It is possible to add further flags after the @code{S} for use by the
575 caller:
576
577 @table @code
578
579 @item relax
580 @cindex relax
581 Relax checking of some root certificate requirements.  As of now this
582 flag allows the use of root certificates with a missing basicConstraints
583 attribute (despite that it is a MUST for CA certificates) and disables
584 CRL checking for the root certificate.
585
586 @item cm
587 If validation of a certificate finally issued by a CA with this flag set
588 fails, try again using the chain validation model.
589
590 @end table
591
592   
593 @item sshcontrol
594 @cindex sshcontrol
595 This file is used when support for the secure shell agent protocol has
596 been enabled (@pxref{option --enable-ssh-support}). Only keys present in
597 this file are used in the SSH protocol.  You should backup this file.
598
599 The @command{ssh-add} tool may be used to add new entries to this file;
600 you may also add them manually.  Comment lines, indicated by a leading
601 hash mark, as well as empty lines are ignored.  An entry starts with
602 optional whitespace, followed by the keygrip of the key given as 40 hex
603 digits, optionally followed by the caching TTL in seconds and another
604 optional field for arbitrary flags.  A non-zero TTL overrides the global
605 default as set by @option{--default-cache-ttl-ssh}.
606
607 The keygrip may be prefixed with a @code{!} to disable an entry entry.
608     
609 The following example lists exactly one key.  Note that keys available
610 through a OpenPGP smartcard in the active smartcard reader are
611 implicitly added to this list; i.e. there is no need to list them.
612   
613   @example
614   # Key added on 2005-02-25 15:08:29
615   5A6592BF45DC73BD876874A28FD4639282E29B52 0
616   @end example
617
618 @item private-keys-v1.d/
619
620   This is the directory where gpg-agent stores the private keys.  Each
621   key is stored in a file with the name made up of the keygrip and the
622   suffix @file{key}.  You should backup all files in this directory
623   and take great care to keep this backup closed away.
624
625
626 @end table
627
628 Note that on larger installations, it is useful to put predefined
629 files into the directory @file{/etc/skel/.gnupg/} so that newly created
630 users start up with a working configuration.  For existing users the
631 a small helper script is provided to create these files (@pxref{addgnupghome}).
632
633
634
635 @c
636 @c Agent Signals
637 @c
638 @mansect signals
639 @node Agent Signals
640 @section Use of some signals.
641 A running @command{gpg-agent} may be controlled by signals, i.e. using
642 the @command{kill} command to send a signal to the process. 
643
644 Here is a list of supported signals:
645
646 @table @gnupgtabopt
647
648 @item SIGHUP
649 @cpindex SIGHUP
650 This signal flushes all cached passphrases and if the program has been
651 started with a configuration file, the configuration file is read again.
652 Only certain options are honored: @code{quiet}, @code{verbose},
653 @code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
654 @code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
655 @code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
656 @code{disable-scdaemon}.  @code{scdaemon-program} is also supported but
657 due to the current implementation, which calls the scdaemon only once,
658 it is not of much use unless you manually kill the scdaemon.
659
660
661 @item SIGTERM
662 @cpindex SIGTERM
663 Shuts down the process but waits until all current requests are
664 fulfilled.  If the process has received 3 of these signals and requests
665 are still pending, a shutdown is forced.
666
667 @item SIGINT
668 @cpindex SIGINT
669 Shuts down the process immediately.
670
671 @item SIGUSR1
672 @cpindex SIGUSR1
673 Dump internal information to the log file.
674
675 @item SIGUSR2
676 @cpindex SIGUSR2
677 This signal is used for internal purposes.
678
679 @end table
680
681 @c 
682 @c  Examples
683 @c
684 @mansect examples
685 @node Agent Examples
686 @section Examples
687
688 The usual way to invoke @command{gpg-agent} is
689
690 @example
691 $ eval $(gpg-agent --daemon)
692 @end example
693
694 An alternative way is by replacing @command{ssh-agent} with
695 @command{gpg-agent}.  If for example @command{ssh-agent} is started as
696 part of the Xsession initialization, you may simply replace
697 @command{ssh-agent} by a script like:
698
699 @cartouche
700 @example
701 #!/bin/sh
702
703 exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
704       --write-env-file $@{HOME@}/.gpg-agent-info "$@@"
705 @end example
706 @end cartouche
707
708 @noindent
709 and add something like (for Bourne shells)
710
711 @cartouche
712 @example
713   if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
714     . "$@{HOME@}/.gpg-agent-info"
715     export GPG_AGENT_INFO
716     export SSH_AUTH_SOCK
717   fi
718 @end example
719 @end cartouche
720
721 @noindent
722 to your shell initialization file (e.g. @file{~/.bashrc}).
723
724 @c 
725 @c  Assuan Protocol
726 @c
727 @manpause
728 @node Agent Protocol
729 @section Agent's Assuan Protocol
730
731 Note: this section does only document the protocol, which is used by
732 GnuPG components; it does not deal with the ssh-agent protocol.
733
734 The @command{gpg-agent} should be started by the login shell and set an
735 environment variable to tell clients about the socket to be used.
736 Clients should deny to access an agent with a socket name which does
737 not match its own configuration.  An application may choose to start
738 an instance of the gpgagent if it does not figure that any has been
739 started; it should not do this if a gpgagent is running but not
740 usable.  Because @command{gpg-agent} can only be used in background mode, no
741 special command line option is required to activate the use of the
742 protocol.
743
744 To identify a key we use a thing called keygrip which is the SHA-1 hash
745 of an canonical encoded S-Expression of the public key as used in
746 Libgcrypt.  For the purpose of this interface the keygrip is given as a
747 hex string.  The advantage of using this and not the hash of a
748 certificate is that it will be possible to use the same keypair for
749 different protocols, thereby saving space on the token used to keep the
750 secret keys.
751
752 @menu
753 * Agent PKDECRYPT::       Decrypting a session key
754 * Agent PKSIGN::          Signing a Hash
755 * Agent GENKEY::          Generating a Key
756 * Agent IMPORT::          Importing a Secret Key
757 * Agent EXPORT::          Exporting a Secret Key
758 * Agent ISTRUSTED::       Importing a Root Certificate
759 * Agent GET_PASSPHRASE::  Ask for a passphrase
760 * Agent GET_CONFIRMATION:: Ask for confirmation
761 * Agent HAVEKEY::         Check whether a key is available
762 * Agent LEARN::           Register a smartcard
763 * Agent PASSWD::          Change a Passphrase
764 * Agent UPDATESTARTUPTTY:: Change the Standard Display
765 * Agent GETEVENTCOUNTER:: Get the Event Counters
766 * Agent GETINFO::         Return information about the process
767 @end menu
768
769 @node Agent PKDECRYPT
770 @subsection Decrypting a session key
771
772 The client asks the server to decrypt a session key.  The encrypted
773 session key should have all information needed to select the
774 appropriate secret key or to delegate it to a smartcard.
775
776 @example
777   SETKEY <keyGrip>
778 @end example
779
780 Tell the server about the key to be used for decryption.  If this is
781 not used, @command{gpg-agent} may try to figure out the key by trying to
782 decrypt the message with each key available.
783
784 @example
785   PKDECRYPT
786 @end example
787
788 The agent checks whether this command is allowed and then does an
789 INQUIRY to get the ciphertext the client should then send the cipher
790 text.
791
792 @example
793     S: INQUIRE CIPHERTEXT
794     C: D (xxxxxx
795     C: D xxxx)
796     C: END
797 @end example
798     
799 Please note that the server may send status info lines while reading the
800 data lines from the client.  The data send is a SPKI like S-Exp with
801 this structure:
802
803 @example
804      (enc-val   
805        (<algo>
806          (<param_name1> <mpi>)
807            ...
808          (<param_namen> <mpi>)))
809 @end example
810
811 Where algo is a string with the name of the algorithm; see the libgcrypt
812 documentation for a list of valid algorithms.  The number and names of
813 the parameters depend on the algorithm.  The agent does return an error
814 if there is an inconsistency.
815
816 If the decryption was successful the decrypted data is returned by
817 means of "D" lines. 
818
819 Here is an example session:
820
821 @example
822    C: PKDECRYPT
823    S: INQUIRE CIPHERTEXT
824    C: D (enc-val elg (a 349324324) 
825    C: D    (b 3F444677CA)))
826    C: END
827    S: # session key follows
828    S: D (value 1234567890ABCDEF0)
829    S: OK descryption successful
830 @end example         
831
832
833 @node Agent PKSIGN
834 @subsection Signing a Hash
835
836 The client ask the agent to sign a given hash value.  A default key
837 will be chosen if no key has been set.  To set a key a client first
838 uses:
839
840 @example
841    SIGKEY <keyGrip>
842 @end example
843
844 This can be used multiple times to create multiple signature, the list
845 of keys is reset with the next PKSIGN command or a RESET.  The server
846 test whether the key is a valid key to sign something and responds with
847 okay.
848
849 @example
850    SETHASH --hash=<name>|<algo> <hexstring>
851 @end example
852
853 The client can use this command to tell the server about the data <hexstring>
854 (which usually is a hash) to be signed. <algo> is the decimal encoded hash
855 algorithm number as used by Libgcrypt.  Either <algo> or --hash=<name>
856 must be given.  Valid names for <name> are:
857
858 @table @code
859 @item sha1
860 @item sha256
861 @item rmd160
862 @item md5
863 @item tls-md5sha1
864 @end table
865
866 @noindent
867 The actual signing is done using
868
869 @example
870    PKSIGN <options>
871 @end example
872
873 Options are not yet defined, but my later be used to choose among
874 different algorithms.  The agent does then some checks, asks for the
875 passphrase and as a result the server returns the signature as an SPKI
876 like S-expression in "D" lines:
877
878 @example  
879      (sig-val   
880        (<algo>
881          (<param_name1> <mpi>)
882            ...
883          (<param_namen> <mpi>)))
884 @end example
885
886
887 The operation is affected by the option
888
889 @example
890    OPTION use-cache-for-signing=0|1
891 @end example
892
893 The default of @code{1} uses the cache.  Setting this option to @code{0}
894 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
895 also a global command line option for @command{gpg-agent} to globally disable the
896 caching.
897
898
899 Here is an example session:
900
901 @example
902    C: SIGKEY <keyGrip>
903    S: OK key available
904    C: SIGKEY <keyGrip>
905    S: OK key available
906    C: PKSIGN
907    S: # I did ask the user whether he really wants to sign
908    S: # I did ask the user for the passphrase
909    S: INQUIRE HASHVAL
910    C: D ABCDEF012345678901234
911    C: END
912    S: # signature follows
913    S: D (sig-val rsa (s 45435453654612121212))
914    S: OK
915 @end example
916
917
918 @node Agent GENKEY
919 @subsection Generating a Key
920
921 This is used to create a new keypair and store the secret key inside the
922 active PSE --- which is in most cases a Soft-PSE.  An not yet defined
923 option allows to choose the storage location.  To get the secret key out
924 of the PSE, a special export tool has to be used.
925
926 @example
927    GENKEY 
928 @end example
929
930 Invokes the key generation process and the server will then inquire
931 on the generation parameters, like:
932
933 @example
934    S: INQUIRE KEYPARM
935    C: D (genkey (rsa (nbits  1024)))
936    C: END
937 @end example
938
939 The format of the key parameters which depends on the algorithm is of
940 the form:
941
942 @example
943     (genkey
944       (algo
945         (parameter_name_1 ....)
946           ....
947         (parameter_name_n ....)))
948 @end example
949
950 If everything succeeds, the server returns the *public key* in a SPKI
951 like S-Expression like this:
952
953 @example
954      (public-key
955        (rsa
956          (n <mpi>)
957          (e <mpi>)))
958 @end example
959
960 Here is an example session:
961
962 @example
963    C: GENKEY
964    S: INQUIRE KEYPARM
965    C: D (genkey (rsa (nbits  1024)))
966    C: END
967    S: D (public-key
968    S: D   (rsa (n 326487324683264) (e 10001)))
969    S  OK key created
970 @end example
971
972 @node Agent IMPORT
973 @subsection Importing a Secret Key
974
975 This operation is not yet supported by GpgAgent.  Specialized tools
976 are to be used for this.
977
978 There is no actual need because we can expect that secret keys
979 created by a 3rd party are stored on a smartcard.  If we have
980 generated the key ourself, we do not need to import it.
981
982 @node Agent EXPORT
983 @subsection Export a Secret Key
984
985 Not implemented.
986
987 Should be done by an extra tool.
988
989 @node Agent ISTRUSTED
990 @subsection Importing a Root Certificate
991
992 Actually we do not import a Root Cert but provide a way to validate
993 any piece of data by storing its Hash along with a description and
994 an identifier in the PSE.  Here is the interface description:
995
996 @example
997     ISTRUSTED <fingerprint>
998 @end example
999
1000 Check whether the OpenPGP primary key or the X.509 certificate with the
1001 given fingerprint is an ultimately trusted key or a trusted Root CA
1002 certificate.  The fingerprint should be given as a hexstring (without
1003 any blanks or colons or whatever in between) and may be left padded with
1004 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
1005
1006 @example
1007     OK
1008 @end example
1009
1010 The key is in the table of trusted keys.
1011
1012 @example
1013     ERR 304 (Not Trusted)
1014 @end example
1015
1016 The key is not in this table.
1017
1018 Gpg needs the entire list of trusted keys to maintain the web of
1019 trust; the following command is therefore quite helpful:
1020
1021 @example
1022     LISTTRUSTED
1023 @end example
1024
1025 GpgAgent returns a list of trusted keys line by line:
1026
1027 @example
1028     S: D 000000001234454556565656677878AF2F1ECCFF P
1029     S: D 340387563485634856435645634856438576457A P
1030     S: D FEDC6532453745367FD83474357495743757435D S
1031     S: OK
1032 @end example
1033
1034 The first item on a line is the hexified fingerprint where MD5
1035 fingerprints are @code{00} padded to the left and the second item is a
1036 flag to indicate the type of key (so that gpg is able to only take care
1037 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
1038 of the line, so that we can extend the format in the future.
1039
1040 Finally a client should be able to mark a key as trusted:
1041
1042 @example
1043    MARKTRUSTED @var{fingerprint} "P"|"S"
1044 @end example
1045
1046 The server will then pop up a window to ask the user whether she
1047 really trusts this key. For this it will probably ask for a text to
1048 be displayed like this:
1049
1050 @example
1051    S: INQUIRE TRUSTDESC
1052    C: D Do you trust the key with the fingerprint @@FPR@@
1053    C: D bla fasel blurb.
1054    C: END
1055    S: OK
1056 @end example
1057
1058 Known sequences with the pattern @@foo@@ are replaced according to this
1059 table:
1060
1061 @table @code
1062 @item @@FPR16@@ 
1063 Format the fingerprint according to gpg rules for a v3 keys.
1064 @item @@FPR20@@ 
1065 Format the fingerprint according to gpg rules for a v4 keys.
1066 @item @@FPR@@
1067 Choose an appropriate format to format the fingerprint.
1068 @item @@@@ 
1069 Replaced by a single @code{@@}
1070 @end table
1071
1072 @node Agent GET_PASSPHRASE
1073 @subsection Ask for a passphrase
1074
1075 This function is usually used to ask for a passphrase to be used for
1076 conventional encryption, but may also be used by programs which need
1077 special handling of passphrases.  This command uses a syntax which helps
1078 clients to use the agent with minimum effort.
1079
1080 @example
1081   GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] [--qualitybar] @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
1082 @end example
1083
1084 @var{cache_id} is expected to be a string used to identify a cached
1085 passphrase.  Use a @code{X} to bypass the cache.  With no other
1086 arguments the agent returns a cached passphrase or an error.  By
1087 convention either the hexified fingerprint of the key shall be used for
1088 @var{cache_id} or an arbitrary string prefixed with the name of the
1089 calling application and a colon: Like @code{gpg:somestring}.
1090   
1091 @var{error_message} is either a single @code{X} for no error message or
1092 a string to be shown as an error message like (e.g. "invalid
1093 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
1094
1095 @var{prompt} is either a single @code{X} for a default prompt or the
1096 text to be shown as the prompt.  Blanks must be percent escaped or
1097 replaced by @code{+}.
1098
1099 @var{description} is a text shown above the entry field.  Blanks must be
1100 percent escaped or replaced by @code{+}.
1101
1102 The agent either returns with an error or with a OK followed by the hex
1103 encoded passphrase.  Note that the length of the strings is implicitly
1104 limited by the maximum length of a command.  If the option
1105 @option{--data} is used, the passphrase is not returned on the OK line
1106 but by regular data lines; this is the preferred method.
1107
1108 If the option @option{--check} is used, the standard passphrase
1109 constraints checks are applied.  A check is not done if the passphrase
1110 has been found in the cache.
1111
1112 If the option @option{--no-ask} is used and the passphrase is not in the
1113 cache the user will not be asked to enter a passphrase but the error
1114 code @code{GPG_ERR_NO_DATA} is returned.  
1115
1116 If the option @option{--qualitybar} is used and a minimum passphrase
1117 length has been configured, a visual indication of the entered
1118 passphrase quality is shown.
1119
1120 @example
1121   CLEAR_PASSPHRASE @var{cache_id}
1122 @end example
1123
1124 may be used to invalidate the cache entry for a passphrase.  The
1125 function returns with OK even when there is no cached passphrase.
1126
1127
1128 @node Agent GET_CONFIRMATION
1129 @subsection Ask for confirmation
1130
1131 This command may be used to ask for a simple confirmation by
1132 presenting a text and 2 buttons: Okay and Cancel.
1133
1134 @example
1135   GET_CONFIRMATION @var{description}
1136 @end example
1137
1138 @var{description}is displayed along with a Okay and Cancel
1139 button. Blanks must be percent escaped or replaced by @code{+}.  A
1140 @code{X} may be used to display confirmation dialog with a default
1141 text.
1142
1143 The agent either returns with an error or with a OK.  Note, that the
1144 length of @var{description} is implicitly limited by the maximum
1145 length of a command.
1146
1147
1148
1149 @node Agent HAVEKEY
1150 @subsection Check whether a key is available
1151
1152 This can be used to see whether a secret key is available.  It does
1153 not return any information on whether the key is somehow protected.
1154
1155 @example
1156   HAVEKEY @var{keygrips}
1157 @end example
1158
1159 The agent answers either with OK or @code{No_Secret_Key} (208).  The
1160 caller may want to check for other error codes as well.  More than one
1161 keygrip may be given.  In this case the command returns success if at
1162 least one of the keygrips corresponds to an available secret key.
1163
1164
1165 @node Agent LEARN
1166 @subsection Register a smartcard
1167
1168 @example
1169   LEARN [--send]
1170 @end example
1171
1172 This command is used to register a smartcard.  With the --send
1173 option given the certificates are send back.
1174
1175
1176 @node Agent PASSWD
1177 @subsection Change a Passphrase
1178
1179 @example
1180   PASSWD @var{keygrip}
1181 @end example
1182
1183 This command is used to interactively change the passphrase of the key
1184 identified by the hex string @var{keygrip}.
1185
1186
1187 @node Agent UPDATESTARTUPTTY
1188 @subsection Change the standard display
1189
1190 @example
1191   UPDATESTARTUPTTY
1192 @end example
1193
1194 Set the startup TTY and X-DISPLAY variables to the values of this
1195 session.  This command is useful to direct future pinentry invocations
1196 to another screen.  It is only required because there is no way in the
1197 ssh-agent protocol to convey this information.
1198
1199
1200 @node Agent GETEVENTCOUNTER
1201 @subsection Get the Event Counters
1202
1203 @example
1204   GETEVENTCOUNTER
1205 @end example
1206
1207 This function return one status line with the current values of the
1208 event counters.  The event counters are useful to avoid polling by
1209 delaying a poll until something has changed.  The values are decimal
1210 numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to
1211 0.  The actual values should not be relied upon; they shall only be used
1212 to detect a change.
1213
1214 The currently defined counters are are:
1215 @table @code
1216 @item ANY
1217 Incremented with any change of any of the other counters.
1218 @item KEY
1219 Incremented for added or removed private keys.
1220 @item CARD
1221 Incremented for changes of the card readers stati.
1222 @end table
1223
1224 @node Agent GETINFO
1225 @subsection  Return information about the process
1226
1227 This is a multipurpose function to return a variety of information.
1228
1229 @example
1230 GETINFO @var{what}
1231 @end example
1232
1233 The value of @var{what} specifies the kind of information returned:
1234 @table @code
1235 @item version
1236 Return the version of the program.
1237 @item pid
1238 Return the process id of the process.
1239 @item socket_name
1240 Return the name of the socket used to connect the agent.
1241 @item ssh_socket_name
1242 Return the name of the socket used for SSH connections.  If SSH support
1243 has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned.
1244 @end table
1245
1246
1247 @mansect see also
1248 @ifset isman
1249 @command{gpg2}(1), 
1250 @command{gpgsm}(1), 
1251 @command{gpg-connect-agent}(1),
1252 @command{scdaemon}(1)
1253 @end ifset
1254 @include see-also-note.texi