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