Changed the scdaemon to handle concurrent sessions. Adjusted
[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 @anchor{option --allow-mark-trusted}
257 @item --allow-mark-trusted
258 @opindex allow-mark-trusted
259 Allow clients to mark keys as trusted, i.e. put them into the
260 @file{trustlist.txt} file.  This is by default not allowed to make it
261 harder for users to inadvertly accept Root-CA keys.
262
263 @item --ignore-cache-for-signing
264 @opindex ignore-cache-for-signing
265 This option will let @command{gpg-agent} bypass the passphrase cache for all
266 signing operation.  Note that there is also a per-session option to
267 control this behaviour but this command line option takes precedence.
268
269 @item --default-cache-ttl @var{n}
270 @opindex default-cache-ttl
271 Set the time a cache entry is valid to @var{n} seconds.  The default are
272 600 seconds.
273
274 @item --max-cache-ttl @var{n}
275 @opindex max-cache-ttl
276 Set the maximum time a cache entry is valid to @var{n} seconds.  After
277 this time a cache entry will get expired even if it has been accessed
278 recently.  The default are 2 hours (7200 seconds).
279
280 @item --pinentry-program @var{filename}
281 @opindex pinentry-program
282 Use program @var{filename} as the PIN entry.  The default is installation
283 dependend and can be shown with the @code{--version} command.
284
285 @item --scdaemon-program @var{filename}
286 @opindex scdaemon-program
287 Use program @var{filename} as the Smartcard daemon.  The default is
288 installation dependend and can be shown with the @code{--version}
289 command.
290
291 @item --disable-scdaemon
292 @opindex disable-scdaemon
293 Do not make use of the scdaemon tool.  This option has the effect of
294 disabling the ability to do smartcard operations.  Note, that enabling
295 this option at runtime does not kill an already forked scdaemon.
296
297 @item --use-standard-socket
298 @itemx --no-use-standard-socket
299 @opindex use-standard-socket
300 @opindex no-use-standard-socket
301 By enabling this option @command{gpg-agent} will listen on the socket
302 named @file{S.gpg-agent}, located in the home directory, and not create
303 a random socket below a temporary directory.  Tools connecting to
304 @command{gpg-agent} should first try to connect to the socket given in
305 environment variable @var{GPG_AGENT_INFO} and the fall back to this
306 socket.  This option may not be used if the home directory is mounted as
307 a remote file system.  
308
309 @noindent
310 Note, that as of now, W32 systems default to this option.
311
312
313 @item --display @var{string}
314 @itemx --ttyname @var{string}
315 @itemx --ttytype @var{string}
316 @itemx --lc-type @var{string}
317 @itemx --lc-messages @var{string}
318 @opindex display 
319 @opindex ttyname 
320 @opindex ttytype 
321 @opindex lc-type 
322 @opindex lc-messages
323 These options are used with the server mode to pass localization
324 information.
325
326 @item --keep-tty
327 @itemx --keep-display
328 @opindex keep-tty
329 @opindex keep-display
330 Ignore requests to change change the current @sc{tty} respective the X
331 window system's @code{DISPLAY} variable.  This is useful to lock the
332 pinentry to pop up at the @sc{tty} or display you started the agent.
333
334 @anchor{option --enable-ssh-support}
335 @item --enable-ssh-support
336 @opindex enable-ssh-support
337
338 Enable emulation of the OpenSSH Agent protocol.
339
340 In this mode of operation, the agent does not only implement the
341 gpg-agent protocol, but also the agent protocol used by OpenSSH
342 (through a seperate socket).  Consequently, it should possible to use
343 the gpg-agent as a drop-in replacement for the well known ssh-agent.
344
345 SSH Keys, which are to be used through the agent, need to be added to
346 the gpg-agent initially through the ssh-add utility.  When a key is
347 added, ssh-add will ask for the password of the provided key file and
348 send the unprotected key material to the agent; this causes the
349 gpg-agent to ask for a passphrase, which is to be used for encrypting
350 the newly received key and storing it in a gpg-agent specific
351 directory.
352
353 Once, a key has been added to the gpg-agent this way, the gpg-agent
354 will be ready to use the key.
355
356 Note: in case the gpg-agent receives a signature request, the user
357 might need to be prompted for a passphrase, which is necessary for
358 decrypting the stored key.  Since the ssh-agent protocol does not
359 contain a mechanism for telling the agent on which display/terminal it
360 is running, gpg-agent's ssh-support will use the TTY or X display where
361 gpg-agent has been started. 
362
363 @end table
364
365 All the long options may also be given in the configuration file after
366 stripping off the two leading dashes.
367
368
369 @c man begin FILES
370
371 @node Agent Configuration
372 @section Configuration
373
374 There are a few configuration files needed for the operation of the
375 agent. By default they may all be found in the current home directory
376 (@pxref{option --homedir}).
377
378 @table @file
379
380 @item gpg-agent.conf
381 @cindex gpg-agent.conf
382   This is the standard configuration file read by @command{gpg-agent} on
383   startup.  It may contain any valid long option; the leading
384   two dashes may not be entered and the option may not be abbreviated.
385   This file is also read after a @code{SIGHUP} however only a few
386   options will actually have an effect.  This default name may be
387   changed on the command line (@pxref{option --options}).
388
389 @item trustlist.txt
390   This is the list of trusted keys.  Comment lines, indicated by a leading
391   hash mark, as well as empty lines are ignored.  To mark a key as trusted
392   you need to enter its fingerprint followed by a space and a capital
393   letter @code{S}.  Colons may optionally be used to separate the bytes of
394   a fingerprint; this allows to cut and paste the fingeperint from a key
395   listing output.
396   
397   Here is an example where two keys are marked as ultimately trusted:
398   
399   @example
400   # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
401   A6935DD34EF3087973C706FC311AA2CCF733765B S
402   
403   # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
404   DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S 
405   @end example
406   
407   Before entering a key into this file, you need to ensure its
408   authenticity.  How to do this depends on your organisation; your
409   administrator might have already entered those keys which are deemed
410   trustworthy enough into this file.  Places where to look for the
411   fingerprint of a root certificate are letters received from the CA or
412   the website of the CA (after making 100% sure that this is indeed the
413   website of that CA).  You may want to consider allowing interactive
414   updates of this file by using the @xref{option --allow-mark-trusted}.
415   This is however not as secure as maintaining this file manually.  It is
416   even advisable to change the permissions to read-only so that this file
417   can't be changed inadvertently.
418   
419   @item sshcontrol
420
421   This file is used when support for the secure shell agent protocol has
422   been enabled (@pxref{option --enable-ssh-support}). Only keys present in
423   this file are used in the SSH protocol.  The @command{ssh-add} tool y be
424   used to add new entries to this file; you may also add them manually.
425   Comment lines, indicated by a leading hash mark, as well as empty lines
426   are ignored.  An entry starts with optional white spaces, followed by
427   the keygrip of the key given as 40 hex digits, optionally followed by
428   the caching TTL in seconds and another optional field for arbitrary
429   flags.  A @code{!} may be prepended to the keygrip to disable this
430   entry.
431     
432   The follwoing example lists exactly one key.  Note that keys available
433   through a OpenPGP smartcard in the active smartcard reader are implictly
434   added to this list; i.e. there is no need to list them.
435   
436   @example
437   # Key added on 2005-02-25 15:08:29
438   5A6592BF45DC73BD876874A28FD4639282E29B52 0
439   @end example
440 @end table
441
442 Note that on larger installations, it is useful to put predefined
443 files into the directory @file{/etc/skel/.gnupg/} so that newly created
444 users start up with a working configuration.  For existing users the
445 a small helper script is provied to create these files (@pxref{addgnupghome}).
446
447
448
449 @c
450 @c Agent Signals
451 @c
452 @node Agent Signals
453 @section Use of some signals.
454 A running @command{gpg-agent} may be controlled by signals, i.e. using
455 the @command{kill} command to send a signal to the process. 
456
457 Here is a list of supported signals:
458
459 @table @gnupgtabopt
460
461 @item SIGHUP
462 @cpindex SIGHUP
463 This signal flushes all chached passphrases and if the program has been
464 started with a configuration file, the configuration file is read again.
465 Only certain options are honored: @code{quiet}, @code{verbose},
466 @code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
467 @code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
468 @code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
469 @code{disable-scdaemon}.  @code{scdaemon-program} is also supported but
470 due to the current implementation, which calls the scdaemon only once,
471 it is not of much use unless you manually kill the scdaemon.
472
473
474 @item SIGTERM
475 @cpindex SIGTERM
476 Shuts down the process but waits until all current requests are
477 fulfilled.  If the process has received 3 of these signals and requests
478 are still pending, a shutdown is forced.
479
480 @item SIGINT
481 @cpindex SIGINT
482 Shuts down the process immediately.
483
484
485 @item SIGUSR1
486 @itemx SIGUSR2
487 @cpindex SIGUSR1
488 @cpindex SIGUSR2
489 These signals are used for internal purposes.
490
491 @end table
492
493 @c 
494 @c  Examples
495 @c
496 @node Agent Examples
497 @section Examples
498
499 @c man begin EXAMPLES
500
501 @example
502 $ eval `gpg-agent --daemon`
503 @end example
504
505 @c man end
506
507
508 @c 
509 @c  Assuan Protocol
510 @c
511 @node Agent Protocol
512 @section Agent's Assuan Protocol
513
514 Note: this section does only document the protocol, which is used by
515 GnuPG components; it does not deal with the ssh-agent protocol.
516
517 The @command{gpg-agent} should be started by the login shell and set an
518 environment variable to tell clients about the socket to be used.
519 Clients should deny to access an agent with a socket name which does
520 not match its own configuration.  An application may choose to start
521 an instance of the gpgagent if it does not figure that any has been
522 started; it should not do this if a gpgagent is running but not
523 usable.  Because @command{gpg-agent} can only be used in background mode, no
524 special command line option is required to activate the use of the
525 protocol.
526
527 To identify a key we use a thing called keygrip which is the SHA-1 hash
528 of an canoncical encoded S-Expression of the the public key as used in
529 Libgcrypt.  For the purpose of this interface the keygrip is given as a
530 hex string.  The advantage of using this and not the hash of a
531 certificate is that it will be possible to use the same keypair for
532 different protocols, thereby saving space on the token used to keep the
533 secret keys.
534
535 @menu
536 * Agent PKDECRYPT::       Decrypting a session key
537 * Agent PKSIGN::          Signing a Hash
538 * Agent GENKEY::          Generating a Key
539 * Agent IMPORT::          Importing a Secret Key
540 * Agent EXPORT::          Exporting a Secret Key
541 * Agent ISTRUSTED::       Importing a Root Certificate
542 * Agent GET_PASSPHRASE::  Ask for a passphrase
543 * Agent GET_CONFIRMATION:: Ask for confirmation
544 * Agent HAVEKEY::         Check whether a key is available
545 * Agent LEARN::           Register a smartcard
546 * Agent PASSWD::          Change a Passphrase
547 @end menu
548
549 @node Agent PKDECRYPT
550 @subsection Decrypting a session key
551
552 The client asks the server to decrypt a session key.  The encrypted
553 session key should have all information needed to select the
554 appropriate secret key or to delegate it to a smartcard.
555
556 @example
557   SETKEY <keyGrip>
558 @end example
559
560 Tell the server about the key to be used for decryption.  If this is
561 not used, @command{gpg-agent} may try to figure out the key by trying to
562 decrypt the message with each key available.
563
564 @example
565   PKDECRYPT
566 @end example
567
568 The agent checks whether this command is allowed and then does an
569 INQUIRY to get the ciphertext the client should then send the cipher
570 text.
571
572 @example
573     S: INQUIRE CIPHERTEXT
574     C: D (xxxxxx
575     C: D xxxx)
576     C: END
577 @end example
578     
579 Please note that the server may send status info lines while reading the
580 data lines from the client.  The data send is a SPKI like S-Exp with
581 this structure:
582
583 @example
584      (enc-val   
585        (<algo>
586          (<param_name1> <mpi>)
587            ...
588          (<param_namen> <mpi>)))
589 @end example
590
591 Where algo is a string with the name of the algorithm; see the libgcrypt
592 documentation for a list of valid algorithms.  The number and names of
593 the parameters depend on the algorithm.  The agent does return an error
594 if there is an inconsistency.
595
596 If the decryption was successful the decrypted data is returned by
597 means of "D" lines. 
598
599 Here is an example session:
600
601 @example
602    C: PKDECRYPT
603    S: INQUIRE CIPHERTEXT
604    C: D (enc-val elg (a 349324324) 
605    C: D    (b 3F444677CA)))
606    C: END
607    S: # session key follows
608    S: D 1234567890ABCDEF0
609    S: OK descryption successful
610 @end example         
611
612
613 @node Agent PKSIGN
614 @subsection Signing a Hash
615
616 The client ask the agent to sign a given hash value.  A default key
617 will be chosen if no key has been set.  To set a key a client first
618 uses:
619
620 @example
621    SIGKEY <keyGrip>
622 @end example
623
624 This can be used multiple times to create multiple signature, the list
625 of keys is reset with the next PKSIGN command or a RESET.  The server
626 test whether the key is a valid key to sign something and responds with
627 okay.
628
629 @example
630    SETHASH <hexstring>
631 @end example
632
633 The client can use this command to tell the server about the data
634 (which usually is a hash) to be signed.  
635
636 The actual signing is done using
637
638 @example
639    PKSIGN <options>
640 @end example
641
642 Options are not yet defined, but my later be used to choosen among
643 different algorithms (e.g. pkcs 1.5)
644
645 The agent does then some checks, asks for the passphrase and
646 if SETHASH has not been used asks the client for the data to sign:
647
648 @example
649    S: INQUIRE HASHVAL
650    C: D ABCDEF012345678901234
651    C: END
652 @end example
653
654 As a result the server returns the signature as an SPKI like S-Exp
655 in "D" lines:
656
657 @example  
658      (sig-val   
659        (<algo>
660          (<param_name1> <mpi>)
661            ...
662          (<param_namen> <mpi>)))
663 @end example
664
665
666 The operation is affected by the option
667
668 @example
669    OPTION use-cache-for-signing=0|1
670 @end example
671
672 The default of @code{1} uses the cache.  Setting this option to @code{0}
673 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
674 also a global command line option for @command{gpg-agent} to globally disable the
675 caching.
676
677
678 Here is an example session:
679
680 @example
681    C: SIGKEY <keyGrip>
682    S: OK key available
683    C: SIGKEY <keyGrip>
684    S: OK key available
685    C: PKSIGN
686    S: # I did ask the user whether he really wants to sign
687    S: # I did ask the user for the passphrase
688    S: INQUIRE HASHVAL
689    C: D ABCDEF012345678901234
690    C: END
691    S: # signature follows
692    S: D (sig-val rsa (s 45435453654612121212))
693    S: OK
694 @end example
695
696
697 @node Agent GENKEY
698 @subsection Generating a Key
699
700 This is used to create a new keypair and store the secret key inside the
701 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
702 option allows to choose the storage location.  To get the secret key out
703 of the PSE, a special export tool has to be used.
704
705 @example
706    GENKEY 
707 @end example
708
709 Invokes the key generation process and the server will then inquire
710 on the generation parameters, like:
711
712 @example
713    S: INQUIRE KEYPARM
714    C: D (genkey (rsa (nbits  1024)))
715    C: END
716 @end example
717
718 The format of the key parameters which depends on the algorithm is of
719 the form:
720
721 @example
722     (genkey
723       (algo
724         (parameter_name_1 ....)
725           ....
726         (parameter_name_n ....)))
727 @end example
728
729 If everything succeeds, the server returns the *public key* in a SPKI
730 like S-Expression like this:
731
732 @example
733      (public-key
734        (rsa
735          (n <mpi>)
736          (e <mpi>)))
737 @end example
738
739 Here is an example session:
740
741 @example
742    C: GENKEY
743    S: INQUIRE KEYPARM
744    C: D (genkey (rsa (nbits  1024)))
745    C: END
746    S: D (public-key
747    S: D   (rsa (n 326487324683264) (e 10001)))
748    S  OK key created
749 @end example
750
751 @node Agent IMPORT
752 @subsection Importing a Secret Key
753
754 This operation is not yet supportted by GpgAgent.  Specialized tools
755 are to be used for this.
756
757 There is no actual need because we can expect that secret keys
758 created by a 3rd party are stored on a smartcard.  If we have
759 generated the key ourself, we do not need to import it.
760
761 @node Agent EXPORT
762 @subsection Export a Secret Key
763
764 Not implemented.
765
766 Should be done by an extra tool.
767
768 @node Agent ISTRUSTED
769 @subsection Importing a Root Certificate
770
771 Actually we do not import a Root Cert but provide a way to validate
772 any piece of data by storing its Hash along with a description and
773 an identifier in the PSE.  Here is the interface desription:
774
775 @example
776     ISTRUSTED <fingerprint>
777 @end example
778
779 Check whether the OpenPGP primary key or the X.509 certificate with the
780 given fingerprint is an ultimately trusted key or a trusted Root CA
781 certificate.  The fingerprint should be given as a hexstring (without
782 any blanks or colons or whatever in between) and may be left padded with
783 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
784
785 @example
786     OK
787 @end example
788
789 The key is in the table of trusted keys.
790
791 @example
792     ERR 304 (Not Trusted)
793 @end example
794
795 The key is not in this table.
796
797 Gpg needs the entire list of trusted keys to maintain the web of
798 trust; the following command is therefore quite helpful:
799
800 @example
801     LISTTRUSTED
802 @end example
803
804 GpgAgent returns a list of trusted keys line by line:
805
806 @example
807     S: D 000000001234454556565656677878AF2F1ECCFF P
808     S: D 340387563485634856435645634856438576457A P
809     S: D FEDC6532453745367FD83474357495743757435D S
810     S: OK
811 @end example
812
813 The first item on a line is the hexified fingerprint where MD5
814 ingerprints are @code{00} padded to the left and the second item is a
815 flag to indicate the type of key (so that gpg is able to only take care
816 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
817 of the line, so that we can extend the format in the future.
818
819 Finally a client should be able to mark a key as trusted:
820
821 @example
822    MARKTRUSTED @var{fingerprint} "P"|"S"
823 @end example
824
825 The server will then pop up a window to ask the user whether she
826 really trusts this key. For this it will probably ask for a text to
827 be displayed like this:
828
829 @example
830    S: INQUIRE TRUSTDESC
831    C: D Do you trust the key with the fingerprint @@FPR@@
832    C: D bla fasel blurb.
833    C: END
834    S: OK
835 @end example
836
837 Known sequences with the pattern @@foo@@ are replaced according to this
838 table:
839
840 @table @code
841 @item @@FPR16@@ 
842 Format the fingerprint according to gpg rules for a v3 keys.
843 @item @@FPR20@@ 
844 Format the fingerprint according to gpg rules for a v4 keys.
845 @item @@FPR@@
846 Choose an appropriate format to format the fingerprint.
847 @item @@@@ 
848 Replaced by a single @code{@@}
849 @end table
850
851 @node Agent GET_PASSPHRASE
852 @subsection Ask for a passphrase
853
854 This function is usually used to ask for a passphrase to be used for
855 conventional encryption, but may also be used by programs which need
856 special handling of passphrases.  This command uses a syntax which helps
857 clients to use the agent with minimum effort.
858
859 @example
860   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
861 @end example
862
863 @var{cache_id} is expected to be a hex string used for caching a
864 passphrase.  Use a @code{X} to bypass the cache.  With no other
865 arguments the agent returns a cached passphrase or an error.
866   
867 @var{error_message} is either a single @code{X} for no error message or
868 a string to be shown as an error message like (e.g. "invalid
869 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
870
871 @var{prompt} is either a single @code{X} for a default prompt or the
872 text to be shown as the prompt.  Blanks must be percent escaped or
873 replaced by @code{+}.
874
875 @var{description} is a text shown above the entry field.  Blanks must be
876 percent escaped or replaced by @code{+}.
877
878 The agent either returns with an error or with a OK followed by the 
879 hex encoded passphrase.  Note that the length of the strings is
880 implicitly limited by the maximum length of a command.
881
882 @example
883   CLEAR_PASSPHRASE @var{cache_id}
884 @end example
885
886 may be used to invalidate the cache entry for a passphrase.  The
887 function returns with OK even when there is no cached passphrase.
888
889
890 @node Agent GET_CONFIRMATION
891 @subsection Ask for confirmation
892
893 This command may be used to ask for a simple confirmation by
894 presenting a text and 2 bottonts: Okay and Cancel.
895
896 @example
897   GET_CONFIRMATION @var{description}
898 @end example
899
900 @var{description}is displayed along with a Okay and Cancel
901 button. Blanks must be percent escaped or replaced by @code{+}.  A
902 @code{X} may be used to display confirmation dialog with a default
903 text.
904
905 The agent either returns with an error or with a OK.  Note, that the
906 length of @var{description} is implicitly limited by the maximum
907 length of a command.
908
909
910
911 @node Agent HAVEKEY
912 @subsection Check whether a key is available
913
914 This can be used to see whether a secret key is available.  It does
915 not return any information on whether the key is somehow protected.
916
917 @example
918   HAVEKEY @var{keygrip}
919 @end example
920
921 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
922 caller may want to check for other error codes as well.
923
924
925 @node Agent LEARN
926 @subsection Register a smartcard
927
928 @example
929   LEARN [--send]
930 @end example
931
932 This command is used to register a smartcard.  With the --send
933 option given the certificates are send back.
934
935
936 @node Agent PASSWD
937 @subsection Change a Passphrase
938
939 @example
940   PASSWD @var{keygrip}
941 @end example
942
943 This command is used to interactively change the passphrase of the key
944 indentified by the hex string @var{keygrip}.
945
946
947