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