New debugging optionhs, updates to the manual.
[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 @c man begin DESCRIPTION
12
13 @command{gpg-agent} is a daemon to manage secret (private) keys
14 independently from any protocol.  It is used as a backend for
15 @command{gpg} and @command{gpgsm} as well as for a couple of other
16 utilities.
17
18 @noindent
19 The usual way to run the agent is from the @code{~/.xsession} file:
20
21 @example
22 eval `gpg-agent --daemon`
23 @end example
24
25 @noindent
26 If you don't use an X server, you can also put this into your regular
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
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:
33
34 @smallexample
35 if test -f $HOME/.gpg-agent-info && \
36    kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
37      GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
38      export GPG_AGENT_INFO   
39 else
40      eval `gpg-agent --daemon`
41      echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
42 fi
43 @end smallexample
44
45 @noindent
46 Note that the new option @option{--write-env-file} may be used instead.
47  
48
49 @noindent
50 You should always add the following lines to your @code{.bashrc} or
51 whatever initialization file is used for all shell invocations:
52
53 @smallexample
54 GPG_TTY=`tty`
55 export GPG_TTY
56 @end smallexample
57
58 @noindent
59 It is important that this environment variable always reflects the
60 output of the @code{tty} command.  For W32 systems this option is not
61 required.
62
63 Please make sure that a proper pinentry program has been installed
64 under the default filename (which is system dependant) or use the
65 option @code{pinentry-pgm} to specify the full name of that program.
66 It is often useful to install a symbolic link from the actual used
67 pinentry (e.g. @file{/usr/bin/pinentry-gtk}) to the expected
68 one (e.g. @file{/usr/bin/pinentry}).
69
70 @c man end
71
72 @noindent
73 @xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options.
74
75 @menu
76 * Agent Commands::      List of all commands.
77 * Agent Options::       List of all options.
78 * Agent Configuration:: Configuration files.
79 * Agent Signals::       Use of some signals.
80 * Agent Examples::      Some usage examples.
81 * Agent Protocol::      The protocol the agent uses.
82 @end menu
83
84 @c man begin COMMANDS
85
86 @node Agent Commands
87 @section Commands
88
89 Commands are not distinguished from options execpt for the fact that
90 only one one command is allowed.
91
92 @table @gnupgtabopt
93 @item --version
94 @opindex version
95 Print the program version and licensing information.  Not that you can
96 abbreviate this command.
97
98 @item --help, -h
99 @opindex help
100 Print a usage message summarizing the most usefule command-line options.
101 Not that you can abbreviate this command.
102
103 @item --dump-options
104 @opindex dump-options
105 Print a list of all available options and commands.  Not that you can
106 abbreviate this command.
107
108 @item --server
109 @opindex server
110 Run in server mode and wait for commands on the @code{stdin}.  The
111 default mode is to create a socket and listen for commands there.
112
113 @item --daemon
114 @opindex daemon
115 Run the program in the background.  This option is required to prevent
116 it from being accidently running in the background.  A common way to do
117 this is:
118 @example
119 @end example
120 $ eval `gpg-agent --daemon`
121 @end table
122
123
124 @c man begin OPTIONS
125
126 @node Agent Options
127 @section Option Summary
128
129 @table @gnupgtabopt
130
131 @anchor{option --options}
132 @item --options @var{file}
133 @opindex options
134 Reads configuration from @var{file} instead of from the default
135 per-user configuration file.  The default configuration file is named
136 @file{gpg-agent.conf} and expected in the @file{.gnupg} directory directly
137 below the home directory of the user.
138
139 @anchor{option --homedir}
140 @item --homedir @var{dir}
141 @opindex homedir
142 Set the name of the home directory to @var{dir}. If his option is not
143 used, the home directory defaults to @file{~/.gnupg}.  It is only
144 recognized when given on the command line.  It also overrides any home
145 directory stated through the environment variable @env{GNUPGHOME} or
146 (on W32 systems) by means on the Registry entry
147 @var{HKCU\Software\GNU\GnuPG:HomeDir}.
148
149 @item -v
150 @item --verbose
151 @opindex v
152 @opindex verbose
153 Outputs additional information while running.
154 You can increase the verbosity by giving several
155 verbose commands to @sc{gpgsm}, such as @samp{-vv}.
156
157 @item -q
158 @item --quiet
159 @opindex q
160 @opindex quiet
161 Try to be as quiet as possible.
162
163 @item --batch
164 @opindex batch
165 Don't invoke a pinentry or do any other thing requiring human interaction.
166
167 @item --faked-system-time @var{epoch}
168 @opindex faked-system-time
169 This option is only useful for testing; it sets the system time back or
170 forth to @var{epoch} which is the number of seconds elapsed since the year
171 1970.
172
173 @item --debug-level @var{level}
174 @opindex debug-level
175 Select the debug level for investigating problems. @var{level} may be
176 one of:
177
178    @table @code
179    @item none
180    no debugging at all.
181    @item basic  
182    some basic debug messages
183    @item advanced
184    more verbose debug messages
185    @item expert
186    even more detailed messages
187    @item guru
188    all of the debug messages you can get
189    @end table
190
191 How these messages are mapped to the actual debugging flags is not
192 specified and may change with newer releaes of this program. They are
193 however carefully selected to best aid in debugging.
194
195 @item --debug @var{flags}
196 @opindex debug
197 This option is only useful for debugging and the behaviour may change at
198 any time without notice.  FLAGS are bit encoded and may be given in
199 usual C-Syntax. The currently defined bits are:
200
201    @table @code
202    @item 0  (1)
203    X.509 or OpenPGP protocol related data
204    @item 1  (2)  
205    values of big number integers 
206    @item 2  (4)
207    low level crypto operations
208    @item 5  (32)
209    memory allocation
210    @item 6  (64)
211    caching
212    @item 7  (128)
213    show memory statistics.
214    @item 9  (512)
215    write hashed data to files named @code{dbgmd-000*}
216    @item 10 (1024)
217    trace Assuan protocol
218    @item 12 (4096)
219    bypass all certificate validation
220    @end table
221
222 @item --debug-all
223 @opindex debug-all
224 Same as @code{--debug=0xffffffff}
225
226 @item --debug-wait @var{n}
227 @opindex debug-wait
228 When running in server mode, wait @var{n} seconds before entering the
229 actual processing loop and print the pid.  This gives time to attach a
230 debugger.
231
232 @item --no-detach
233 @opindex no-detach
234 Don't detach the process from the console.  This is manly usefule for
235 debugging.
236
237 @item -s
238 @itemx --sh
239 @itemx -c
240 @itemx --csh
241 @opindex s
242 @opindex sh
243 @opindex c
244 @opindex csh
245 Format the info output in daemon mode for use with the standard Bourne
246 shell respective the C-shell . The default ist to guess it based on the
247 environment variable @code{SHELL} which is in almost all cases
248 sufficient.
249
250 @item --write-env-file @var{file}
251 @opindex write-env-file
252 Often it is required to connect to the agent from a process not being an
253 inferior of @command{gpg-agent} and thus the environment variable with
254 the socket name is not available.  To help setting up those variables in
255 other sessions, this option may be used to write the information into
256 @var{file}.  The format is suitable to be evaluated by a Bourne shell
257 like in this simple example:
258
259 @example
260 eval `cat @var{file}`
261 eval `cut -d= -f 1 < @var{file} | xargs echo export`
262 @end example
263
264
265 @item --no-grab
266 @opindex no-grab
267 Tell the pinentryo not to grab the keyboard and mouse.  This option
268 should in general not be used to avaoid X-sniffing attacks.
269
270 @item --log-file @var{file}
271 @opindex log-file
272 Append all logging output to @var{file}.  This is very helpful in
273 seeing what the agent actually does.
274
275 @anchor{option --allow-mark-trusted}
276 @item --allow-mark-trusted
277 @opindex allow-mark-trusted
278 Allow clients to mark keys as trusted, i.e. put them into the
279 @file{trustlist.txt} file.  This is by default not allowed to make it
280 harder for users to inadvertly accept Root-CA keys.
281
282 @item --ignore-cache-for-signing
283 @opindex ignore-cache-for-signing
284 This option will let @command{gpg-agent} bypass the passphrase cache for all
285 signing operation.  Note that there is also a per-session option to
286 control this behaviour but this command line option takes precedence.
287
288 @item --default-cache-ttl @var{n}
289 @opindex default-cache-ttl
290 Set the time a cache entry is valid to @var{n} seconds.  The default are
291 600 seconds.
292
293 @item --default-cache-ttl-ssh @var{n}
294 @opindex default-cache-ttl
295 Set the time a cache entry used for SSH keys is valid to @var{n}
296 seconds.  The default are 600 seconds.
297
298 @item --max-cache-ttl @var{n}
299 @opindex max-cache-ttl
300 Set the maximum time a cache entry is valid to @var{n} seconds.  After
301 this time a cache entry will get expired even if it has been accessed
302 recently.  The default are 2 hours (7200 seconds).
303
304 @item --pinentry-program @var{filename}
305 @opindex pinentry-program
306 Use program @var{filename} as the PIN entry.  The default is installation
307 dependend and can be shown with the @code{--version} command.
308
309 @item --scdaemon-program @var{filename}
310 @opindex scdaemon-program
311 Use program @var{filename} as the Smartcard daemon.  The default is
312 installation dependend and can be shown with the @code{--version}
313 command.
314
315 @item --disable-scdaemon
316 @opindex disable-scdaemon
317 Do not make use of the scdaemon tool.  This option has the effect of
318 disabling the ability to do smartcard operations.  Note, that enabling
319 this option at runtime does not kill an already forked scdaemon.
320
321 @item --use-standard-socket
322 @itemx --no-use-standard-socket
323 @opindex use-standard-socket
324 @opindex no-use-standard-socket
325 By enabling this option @command{gpg-agent} will listen on the socket
326 named @file{S.gpg-agent}, located in the home directory, and not create
327 a random socket below a temporary directory.  Tools connecting to
328 @command{gpg-agent} should first try to connect to the socket given in
329 environment variable @var{GPG_AGENT_INFO} and the fall back to this
330 socket.  This option may not be used if the home directory is mounted as
331 a remote file system.  
332
333 @noindent
334 Note, that as of now, W32 systems default to this option.
335
336
337 @item --display @var{string}
338 @itemx --ttyname @var{string}
339 @itemx --ttytype @var{string}
340 @itemx --lc-type @var{string}
341 @itemx --lc-messages @var{string}
342 @opindex display 
343 @opindex ttyname 
344 @opindex ttytype 
345 @opindex lc-type 
346 @opindex lc-messages
347 These options are used with the server mode to pass localization
348 information.
349
350 @item --keep-tty
351 @itemx --keep-display
352 @opindex keep-tty
353 @opindex keep-display
354 Ignore requests to change change the current @sc{tty} respective the X
355 window system's @code{DISPLAY} variable.  This is useful to lock the
356 pinentry to pop up at the @sc{tty} or display you started the agent.
357
358 @anchor{option --enable-ssh-support}
359 @item --enable-ssh-support
360 @opindex enable-ssh-support
361
362 Enable emulation of the OpenSSH Agent protocol.
363
364 In this mode of operation, the agent does not only implement the
365 gpg-agent protocol, but also the agent protocol used by OpenSSH
366 (through a seperate socket).  Consequently, it should possible to use
367 the gpg-agent as a drop-in replacement for the well known ssh-agent.
368
369 SSH Keys, which are to be used through the agent, need to be added to
370 the gpg-agent initially through the ssh-add utility.  When a key is
371 added, ssh-add will ask for the password of the provided key file and
372 send the unprotected key material to the agent; this causes the
373 gpg-agent to ask for a passphrase, which is to be used for encrypting
374 the newly received key and storing it in a gpg-agent specific
375 directory.
376
377 Once, a key has been added to the gpg-agent this way, the gpg-agent
378 will be ready to use the key.
379
380 Note: in case the gpg-agent receives a signature request, the user might
381 need to be prompted for a passphrase, which is necessary for decrypting
382 the stored key.  Since the ssh-agent protocol does not contain a
383 mechanism for telling the agent on which display/terminal it is running,
384 gpg-agent's ssh-support will use the TTY or X display where gpg-agent
385 has been started.  To switch this display to the current one, the
386 follwing command may be used:
387
388 @smallexample
389 echo UPDATESTARTUPTTY | gpg-connect-agent
390 @end smallexample
391
392
393
394 @end table
395
396 All the long options may also be given in the configuration file after
397 stripping off the two leading dashes.
398
399
400 @c man begin FILES
401
402 @node Agent Configuration
403 @section Configuration
404
405 There are a few configuration files needed for the operation of the
406 agent. By default they may all be found in the current home directory
407 (@pxref{option --homedir}).
408
409 @table @file
410
411 @item gpg-agent.conf
412 @cindex gpg-agent.conf
413   This is the standard configuration file read by @command{gpg-agent} on
414   startup.  It may contain any valid long option; the leading
415   two dashes may not be entered and the option may not be abbreviated.
416   This file is also read after a @code{SIGHUP} however only a few
417   options will actually have an effect.  This default name may be
418   changed on the command line (@pxref{option --options}).
419
420 @item trustlist.txt
421   This is the list of trusted keys.  Comment lines, indicated by a leading
422   hash mark, as well as empty lines are ignored.  To mark a key as trusted
423   you need to enter its fingerprint followed by a space and a capital
424   letter @code{S}.  Colons may optionally be used to separate the bytes of
425   a fingerprint; this allows to cut and paste the fingeperint from a key
426   listing output.
427   
428   Here is an example where two keys are marked as ultimately trusted:
429   
430   @example
431   # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
432   A6935DD34EF3087973C706FC311AA2CCF733765B S
433   
434   # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
435   DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S 
436   @end example
437   
438   Before entering a key into this file, you need to ensure its
439   authenticity.  How to do this depends on your organisation; your
440   administrator might have already entered those keys which are deemed
441   trustworthy enough into this file.  Places where to look for the
442   fingerprint of a root certificate are letters received from the CA or
443   the website of the CA (after making 100% sure that this is indeed the
444   website of that CA).  You may want to consider allowing interactive
445   updates of this file by using the @xref{option --allow-mark-trusted}.
446   This is however not as secure as maintaining this file manually.  It is
447   even advisable to change the permissions to read-only so that this file
448   can't be changed inadvertently.
449   
450   @item sshcontrol
451
452   This file is used when support for the secure shell agent protocol has
453   been enabled (@pxref{option --enable-ssh-support}). Only keys present in
454   this file are used in the SSH protocol.  The @command{ssh-add} tool y be
455   used to add new entries to this file; you may also add them manually.
456   Comment lines, indicated by a leading hash mark, as well as empty lines
457   are ignored.  An entry starts with optional white spaces, followed by
458   the keygrip of the key given as 40 hex digits, optionally followed by
459   the caching TTL in seconds and another optional field for arbitrary
460   flags.  A @code{!} may be prepended to the keygrip to disable this
461   entry.
462     
463   The follwoing example lists exactly one key.  Note that keys available
464   through a OpenPGP smartcard in the active smartcard reader are implictly
465   added to this list; i.e. there is no need to list them.
466   
467   @example
468   # Key added on 2005-02-25 15:08:29
469   5A6592BF45DC73BD876874A28FD4639282E29B52 0
470   @end example
471 @end table
472
473 Note that on larger installations, it is useful to put predefined
474 files into the directory @file{/etc/skel/.gnupg/} so that newly created
475 users start up with a working configuration.  For existing users the
476 a small helper script is provied to create these files (@pxref{addgnupghome}).
477
478
479
480 @c
481 @c Agent Signals
482 @c
483 @node Agent Signals
484 @section Use of some signals.
485 A running @command{gpg-agent} may be controlled by signals, i.e. using
486 the @command{kill} command to send a signal to the process. 
487
488 Here is a list of supported signals:
489
490 @table @gnupgtabopt
491
492 @item SIGHUP
493 @cpindex SIGHUP
494 This signal flushes all chached passphrases and if the program has been
495 started with a configuration file, the configuration file is read again.
496 Only certain options are honored: @code{quiet}, @code{verbose},
497 @code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
498 @code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
499 @code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
500 @code{disable-scdaemon}.  @code{scdaemon-program} is also supported but
501 due to the current implementation, which calls the scdaemon only once,
502 it is not of much use unless you manually kill the scdaemon.
503
504
505 @item SIGTERM
506 @cpindex SIGTERM
507 Shuts down the process but waits until all current requests are
508 fulfilled.  If the process has received 3 of these signals and requests
509 are still pending, a shutdown is forced.
510
511 @item SIGINT
512 @cpindex SIGINT
513 Shuts down the process immediately.
514
515 @item SIGUSR1
516 @cpindex SIGUSR1
517 Dump internal information to the log file.
518
519 @item SIGUSR2
520 @cpindex SIGUSR2
521 This signal is used for internal purposes.
522
523 @end table
524
525 @c 
526 @c  Examples
527 @c
528 @node Agent Examples
529 @section Examples
530
531 @c man begin EXAMPLES
532
533 The usual way to invoke @command{gpg-agent} is
534
535 @example
536 $ eval `gpg-agent --daemon`
537 @end example
538
539 @c man end
540
541 An alternative way is by replacing @command{ssh-agent} with
542 @command{gpg-agent}.  If for example @command{ssh-agent} is started as
543 part of the Xsession intialization you may simply replace
544 @command{ssh-agent} by a script like:
545
546 @cartouche
547 @example
548 #!/bin/sh
549
550 exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
551       --write-env-file $@{HOME@}/.gpg-agent-info "$@@"
552 @end example
553 @end cartouche
554
555 @noindent
556 and add something like (for Bourne shells)
557
558 @cartouche
559 @example
560   if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
561     . "$@{HOME@}/.gpg-agent-info"
562     export GPG_AGENT_INFO
563     export SSH_AUTH_SOCK
564     export SSH_AGENT_PID
565   fi
566 @end example
567 @end cartouche
568
569 @noindent
570 to your shell initialization file (e.g. @file{~/.bashrc}).
571
572 @c 
573 @c  Assuan Protocol
574 @c
575 @node Agent Protocol
576 @section Agent's Assuan Protocol
577
578 Note: this section does only document the protocol, which is used by
579 GnuPG components; it does not deal with the ssh-agent protocol.
580
581 The @command{gpg-agent} should be started by the login shell and set an
582 environment variable to tell clients about the socket to be used.
583 Clients should deny to access an agent with a socket name which does
584 not match its own configuration.  An application may choose to start
585 an instance of the gpgagent if it does not figure that any has been
586 started; it should not do this if a gpgagent is running but not
587 usable.  Because @command{gpg-agent} can only be used in background mode, no
588 special command line option is required to activate the use of the
589 protocol.
590
591 To identify a key we use a thing called keygrip which is the SHA-1 hash
592 of an canoncical encoded S-Expression of the the public key as used in
593 Libgcrypt.  For the purpose of this interface the keygrip is given as a
594 hex string.  The advantage of using this and not the hash of a
595 certificate is that it will be possible to use the same keypair for
596 different protocols, thereby saving space on the token used to keep the
597 secret keys.
598
599 @menu
600 * Agent PKDECRYPT::       Decrypting a session key
601 * Agent PKSIGN::          Signing a Hash
602 * Agent GENKEY::          Generating a Key
603 * Agent IMPORT::          Importing a Secret Key
604 * Agent EXPORT::          Exporting a Secret Key
605 * Agent ISTRUSTED::       Importing a Root Certificate
606 * Agent GET_PASSPHRASE::  Ask for a passphrase
607 * Agent GET_CONFIRMATION:: Ask for confirmation
608 * Agent HAVEKEY::         Check whether a key is available
609 * Agent LEARN::           Register a smartcard
610 * Agent PASSWD::          Change a Passphrase
611 * Agent UPDATESTARTUPTTY:: Change the Standard Display
612 @end menu
613
614 @node Agent PKDECRYPT
615 @subsection Decrypting a session key
616
617 The client asks the server to decrypt a session key.  The encrypted
618 session key should have all information needed to select the
619 appropriate secret key or to delegate it to a smartcard.
620
621 @example
622   SETKEY <keyGrip>
623 @end example
624
625 Tell the server about the key to be used for decryption.  If this is
626 not used, @command{gpg-agent} may try to figure out the key by trying to
627 decrypt the message with each key available.
628
629 @example
630   PKDECRYPT
631 @end example
632
633 The agent checks whether this command is allowed and then does an
634 INQUIRY to get the ciphertext the client should then send the cipher
635 text.
636
637 @example
638     S: INQUIRE CIPHERTEXT
639     C: D (xxxxxx
640     C: D xxxx)
641     C: END
642 @end example
643     
644 Please note that the server may send status info lines while reading the
645 data lines from the client.  The data send is a SPKI like S-Exp with
646 this structure:
647
648 @example
649      (enc-val   
650        (<algo>
651          (<param_name1> <mpi>)
652            ...
653          (<param_namen> <mpi>)))
654 @end example
655
656 Where algo is a string with the name of the algorithm; see the libgcrypt
657 documentation for a list of valid algorithms.  The number and names of
658 the parameters depend on the algorithm.  The agent does return an error
659 if there is an inconsistency.
660
661 If the decryption was successful the decrypted data is returned by
662 means of "D" lines. 
663
664 Here is an example session:
665
666 @example
667    C: PKDECRYPT
668    S: INQUIRE CIPHERTEXT
669    C: D (enc-val elg (a 349324324) 
670    C: D    (b 3F444677CA)))
671    C: END
672    S: # session key follows
673    S: D 1234567890ABCDEF0
674    S: OK descryption successful
675 @end example         
676
677
678 @node Agent PKSIGN
679 @subsection Signing a Hash
680
681 The client ask the agent to sign a given hash value.  A default key
682 will be chosen if no key has been set.  To set a key a client first
683 uses:
684
685 @example
686    SIGKEY <keyGrip>
687 @end example
688
689 This can be used multiple times to create multiple signature, the list
690 of keys is reset with the next PKSIGN command or a RESET.  The server
691 test whether the key is a valid key to sign something and responds with
692 okay.
693
694 @example
695    SETHASH <hexstring>
696 @end example
697
698 The client can use this command to tell the server about the data
699 (which usually is a hash) to be signed.  
700
701 The actual signing is done using
702
703 @example
704    PKSIGN <options>
705 @end example
706
707 Options are not yet defined, but my later be used to choosen among
708 different algorithms (e.g. pkcs 1.5)
709
710 The agent does then some checks, asks for the passphrase and
711 if SETHASH has not been used asks the client for the data to sign:
712
713 @example
714    S: INQUIRE HASHVAL
715    C: D ABCDEF012345678901234
716    C: END
717 @end example
718
719 As a result the server returns the signature as an SPKI like S-Exp
720 in "D" lines:
721
722 @example  
723      (sig-val   
724        (<algo>
725          (<param_name1> <mpi>)
726            ...
727          (<param_namen> <mpi>)))
728 @end example
729
730
731 The operation is affected by the option
732
733 @example
734    OPTION use-cache-for-signing=0|1
735 @end example
736
737 The default of @code{1} uses the cache.  Setting this option to @code{0}
738 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
739 also a global command line option for @command{gpg-agent} to globally disable the
740 caching.
741
742
743 Here is an example session:
744
745 @example
746    C: SIGKEY <keyGrip>
747    S: OK key available
748    C: SIGKEY <keyGrip>
749    S: OK key available
750    C: PKSIGN
751    S: # I did ask the user whether he really wants to sign
752    S: # I did ask the user for the passphrase
753    S: INQUIRE HASHVAL
754    C: D ABCDEF012345678901234
755    C: END
756    S: # signature follows
757    S: D (sig-val rsa (s 45435453654612121212))
758    S: OK
759 @end example
760
761
762 @node Agent GENKEY
763 @subsection Generating a Key
764
765 This is used to create a new keypair and store the secret key inside the
766 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
767 option allows to choose the storage location.  To get the secret key out
768 of the PSE, a special export tool has to be used.
769
770 @example
771    GENKEY 
772 @end example
773
774 Invokes the key generation process and the server will then inquire
775 on the generation parameters, like:
776
777 @example
778    S: INQUIRE KEYPARM
779    C: D (genkey (rsa (nbits  1024)))
780    C: END
781 @end example
782
783 The format of the key parameters which depends on the algorithm is of
784 the form:
785
786 @example
787     (genkey
788       (algo
789         (parameter_name_1 ....)
790           ....
791         (parameter_name_n ....)))
792 @end example
793
794 If everything succeeds, the server returns the *public key* in a SPKI
795 like S-Expression like this:
796
797 @example
798      (public-key
799        (rsa
800          (n <mpi>)
801          (e <mpi>)))
802 @end example
803
804 Here is an example session:
805
806 @example
807    C: GENKEY
808    S: INQUIRE KEYPARM
809    C: D (genkey (rsa (nbits  1024)))
810    C: END
811    S: D (public-key
812    S: D   (rsa (n 326487324683264) (e 10001)))
813    S  OK key created
814 @end example
815
816 @node Agent IMPORT
817 @subsection Importing a Secret Key
818
819 This operation is not yet supportted by GpgAgent.  Specialized tools
820 are to be used for this.
821
822 There is no actual need because we can expect that secret keys
823 created by a 3rd party are stored on a smartcard.  If we have
824 generated the key ourself, we do not need to import it.
825
826 @node Agent EXPORT
827 @subsection Export a Secret Key
828
829 Not implemented.
830
831 Should be done by an extra tool.
832
833 @node Agent ISTRUSTED
834 @subsection Importing a Root Certificate
835
836 Actually we do not import a Root Cert but provide a way to validate
837 any piece of data by storing its Hash along with a description and
838 an identifier in the PSE.  Here is the interface desription:
839
840 @example
841     ISTRUSTED <fingerprint>
842 @end example
843
844 Check whether the OpenPGP primary key or the X.509 certificate with the
845 given fingerprint is an ultimately trusted key or a trusted Root CA
846 certificate.  The fingerprint should be given as a hexstring (without
847 any blanks or colons or whatever in between) and may be left padded with
848 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
849
850 @example
851     OK
852 @end example
853
854 The key is in the table of trusted keys.
855
856 @example
857     ERR 304 (Not Trusted)
858 @end example
859
860 The key is not in this table.
861
862 Gpg needs the entire list of trusted keys to maintain the web of
863 trust; the following command is therefore quite helpful:
864
865 @example
866     LISTTRUSTED
867 @end example
868
869 GpgAgent returns a list of trusted keys line by line:
870
871 @example
872     S: D 000000001234454556565656677878AF2F1ECCFF P
873     S: D 340387563485634856435645634856438576457A P
874     S: D FEDC6532453745367FD83474357495743757435D S
875     S: OK
876 @end example
877
878 The first item on a line is the hexified fingerprint where MD5
879 ingerprints are @code{00} padded to the left and the second item is a
880 flag to indicate the type of key (so that gpg is able to only take care
881 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
882 of the line, so that we can extend the format in the future.
883
884 Finally a client should be able to mark a key as trusted:
885
886 @example
887    MARKTRUSTED @var{fingerprint} "P"|"S"
888 @end example
889
890 The server will then pop up a window to ask the user whether she
891 really trusts this key. For this it will probably ask for a text to
892 be displayed like this:
893
894 @example
895    S: INQUIRE TRUSTDESC
896    C: D Do you trust the key with the fingerprint @@FPR@@
897    C: D bla fasel blurb.
898    C: END
899    S: OK
900 @end example
901
902 Known sequences with the pattern @@foo@@ are replaced according to this
903 table:
904
905 @table @code
906 @item @@FPR16@@ 
907 Format the fingerprint according to gpg rules for a v3 keys.
908 @item @@FPR20@@ 
909 Format the fingerprint according to gpg rules for a v4 keys.
910 @item @@FPR@@
911 Choose an appropriate format to format the fingerprint.
912 @item @@@@ 
913 Replaced by a single @code{@@}
914 @end table
915
916 @node Agent GET_PASSPHRASE
917 @subsection Ask for a passphrase
918
919 This function is usually used to ask for a passphrase to be used for
920 conventional encryption, but may also be used by programs which need
921 special handling of passphrases.  This command uses a syntax which helps
922 clients to use the agent with minimum effort.
923
924 @example
925   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
926 @end example
927
928 @var{cache_id} is expected to be a hex string used for caching a
929 passphrase.  Use a @code{X} to bypass the cache.  With no other
930 arguments the agent returns a cached passphrase or an error.
931   
932 @var{error_message} is either a single @code{X} for no error message or
933 a string to be shown as an error message like (e.g. "invalid
934 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
935
936 @var{prompt} is either a single @code{X} for a default prompt or the
937 text to be shown as the prompt.  Blanks must be percent escaped or
938 replaced by @code{+}.
939
940 @var{description} is a text shown above the entry field.  Blanks must be
941 percent escaped or replaced by @code{+}.
942
943 The agent either returns with an error or with a OK followed by the 
944 hex encoded passphrase.  Note that the length of the strings is
945 implicitly limited by the maximum length of a command.
946
947 @example
948   CLEAR_PASSPHRASE @var{cache_id}
949 @end example
950
951 may be used to invalidate the cache entry for a passphrase.  The
952 function returns with OK even when there is no cached passphrase.
953
954
955 @node Agent GET_CONFIRMATION
956 @subsection Ask for confirmation
957
958 This command may be used to ask for a simple confirmation by
959 presenting a text and 2 bottonts: Okay and Cancel.
960
961 @example
962   GET_CONFIRMATION @var{description}
963 @end example
964
965 @var{description}is displayed along with a Okay and Cancel
966 button. Blanks must be percent escaped or replaced by @code{+}.  A
967 @code{X} may be used to display confirmation dialog with a default
968 text.
969
970 The agent either returns with an error or with a OK.  Note, that the
971 length of @var{description} is implicitly limited by the maximum
972 length of a command.
973
974
975
976 @node Agent HAVEKEY
977 @subsection Check whether a key is available
978
979 This can be used to see whether a secret key is available.  It does
980 not return any information on whether the key is somehow protected.
981
982 @example
983   HAVEKEY @var{keygrip}
984 @end example
985
986 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
987 caller may want to check for other error codes as well.
988
989
990 @node Agent LEARN
991 @subsection Register a smartcard
992
993 @example
994   LEARN [--send]
995 @end example
996
997 This command is used to register a smartcard.  With the --send
998 option given the certificates are send back.
999
1000
1001 @node Agent PASSWD
1002 @subsection Change a Passphrase
1003
1004 @example
1005   PASSWD @var{keygrip}
1006 @end example
1007
1008 This command is used to interactively change the passphrase of the key
1009 indentified by the hex string @var{keygrip}.
1010
1011
1012 @node Agent UPDATESTARTUPTTY
1013 @subsection Change the standard display
1014
1015 @example
1016   UPDATESTARTUPTTY
1017 @end example
1018
1019 Set the startup TTY and X-DISPLAY variables to the values of this
1020 session.  This command is useful to direct future pinentry invocations
1021 to another screen.  It is only required because there is no way in the
1022 ssh-agent protocol to convey this information.
1023
1024