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