17bd59c7aa997b7419fc5ccb01339c7274d4d77a
[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 --enable-ssh-support
330 @opindex enable-ssh-support
331
332 Enable emulation of the OpenSSH Agent protocol.
333
334 In this mode of operation, the agent does not only implement the
335 gpg-agent protocol, but also the agent protocol used by OpenSSH
336 (through a seperate socket).  Consequently, it should possible to use
337 the gpg-agent as a drop-in replacement for the well known ssh-agent.
338
339 SSH Keys, which are to be used through the agent, need to be added to
340 the gpg-agent initially through the ssh-add utility.  When a key is
341 added, ssh-add will ask for the password of the provided key file and
342 send the unprotected key material to the agent; this causes the
343 gpg-agent to ask for a passphrase, which is to be used for encrypting
344 the newly received key and storing it in a gpg-agent specific
345 directory.
346
347 Once, a key has been added to the gpg-agent this way, the gpg-agent
348 will be ready to use the key.
349
350 Note: in case the gpg-agent receives a signature request, the user
351 might need to be prompted for a passphrase, which is necessary for
352 decrypting the stored key.  Since the ssh-agent protocol does not
353 contain a mechanism for telling the agent on which display/terminal it
354 is running, gpg-agent's ssh-support will use the TTY or X display where
355 gpg-agent has been started. 
356
357 @end table
358
359 All the long options may also be given in the configuration file after
360 stripping off the two leading dashes.
361
362 @c
363 @c Agent Signals
364 @c
365 @node Agent Signals
366 @section Use of some signals.
367 A running @command{gpg-agent} may be controlled by signals, i.e. using
368 the @command{kill} command to send a signal to the process. 
369
370 Here is a list of supported signals:
371
372 @table @gnupgtabopt
373
374 @item SIGHUP
375 @cpindex SIGHUP
376 This signals flushes all chached passphrases and when the program was
377 started with a configuration file, the configuration file is read again.
378 Only certain options are honored: @code{quiet}, @code{verbose},
379 @code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program},
380 @code{default-cache-ttl} and @code{ignore-cache-for-signing}.
381 @code{scdaemon-program} is also supported but due to the current
382 implementation, which calls the scdaemon only once, it is not of much
383 use.
384
385
386 @item SIGTERM
387 @cpindex SIGTERM
388 Shuts down the process but waits until all current requests are
389 fulfilled.  If the process has received 3 of these signals and requests
390 are still pending, a shutdown is forced.
391
392 @item SIGINT
393 @cpindex SIGINT
394 Shuts down the process immediately.
395
396
397 @item SIGUSR1
398 @itemx SIGUSR2
399 @cpindex SIGUSR1
400 @cpindex SIGUSR2
401 These signals are used for internal purposes.
402
403 @end table
404
405 @c 
406 @c  Examples
407 @c
408 @node Agent Examples
409 @section Examples
410
411 @c man begin EXAMPLES
412
413 @example
414 $ eval `gpg-agent --daemon`
415 @end example
416
417 @c man end
418
419
420 @c 
421 @c  Assuan Protocol
422 @c
423 @node Agent Protocol
424 @section Agent's Assuan Protocol
425
426 Note: this section does only document the protocol, which is used by
427 GnuPG components; it does not deal with the ssh-agent protocol.
428
429 The @command{gpg-agent} should be started by the login shell and set an
430 environment variable to tell clients about the socket to be used.
431 Clients should deny to access an agent with a socket name which does
432 not match its own configuration.  An application may choose to start
433 an instance of the gpgagent if it does not figure that any has been
434 started; it should not do this if a gpgagent is running but not
435 usable.  Because @command{gpg-agent} can only be used in background mode, no
436 special command line option is required to activate the use of the
437 protocol.
438
439 To identify a key we use a thing called keygrip which is the SHA-1 hash
440 of an canoncical encoded S-Expression of the the public key as used in
441 Libgcrypt.  For the purpose of this interface the keygrip is given as a
442 hex string.  The advantage of using this and not the hash of a
443 certificate is that it will be possible to use the same keypair for
444 different protocols, thereby saving space on the token used to keep the
445 secret keys.
446
447 @menu
448 * Agent PKDECRYPT::       Decrypting a session key
449 * Agent PKSIGN::          Signing a Hash
450 * Agent GENKEY::          Generating a Key
451 * Agent IMPORT::          Importing a Secret Key
452 * Agent EXPORT::          Exporting a Secret Key
453 * Agent ISTRUSTED::       Importing a Root Certificate
454 * Agent GET_PASSPHRASE::  Ask for a passphrase
455 * Agent GET_CONFIRMATION:: Ask for confirmation
456 * Agent HAVEKEY::         Check whether a key is available
457 * Agent LEARN::           Register a smartcard
458 * Agent PASSWD::          Change a Passphrase
459 @end menu
460
461 @node Agent PKDECRYPT
462 @subsection Decrypting a session key
463
464 The client asks the server to decrypt a session key.  The encrypted
465 session key should have all information needed to select the
466 appropriate secret key or to delegate it to a smartcard.
467
468 @example
469   SETKEY <keyGrip>
470 @end example
471
472 Tell the server about the key to be used for decryption.  If this is
473 not used, @command{gpg-agent} may try to figure out the key by trying to
474 decrypt the message with each key available.
475
476 @example
477   PKDECRYPT
478 @end example
479
480 The agent checks whether this command is allowed and then does an
481 INQUIRY to get the ciphertext the client should then send the cipher
482 text.
483
484 @example
485     S: INQUIRE CIPHERTEXT
486     C: D (xxxxxx
487     C: D xxxx)
488     C: END
489 @end example
490     
491 Please note that the server may send status info lines while reading the
492 data lines from the client.  The data send is a SPKI like S-Exp with
493 this structure:
494
495 @example
496      (enc-val   
497        (<algo>
498          (<param_name1> <mpi>)
499            ...
500          (<param_namen> <mpi>)))
501 @end example
502
503 Where algo is a string with the name of the algorithm; see the libgcrypt
504 documentation for a list of valid algorithms.  The number and names of
505 the parameters depend on the algorithm.  The agent does return an error
506 if there is an inconsistency.
507
508 If the decryption was successful the decrypted data is returned by
509 means of "D" lines. 
510
511 Here is an example session:
512
513 @example
514    C: PKDECRYPT
515    S: INQUIRE CIPHERTEXT
516    C: D (enc-val elg (a 349324324) 
517    C: D    (b 3F444677CA)))
518    C: END
519    S: # session key follows
520    S: D 1234567890ABCDEF0
521    S: OK descryption successful
522 @end example         
523
524
525 @node Agent PKSIGN
526 @subsection Signing a Hash
527
528 The client ask the agent to sign a given hash value.  A default key
529 will be chosen if no key has been set.  To set a key a client first
530 uses:
531
532 @example
533    SIGKEY <keyGrip>
534 @end example
535
536 This can be used multiple times to create multiple signature, the list
537 of keys is reset with the next PKSIGN command or a RESET.  The server
538 test whether the key is a valid key to sign something and responds with
539 okay.
540
541 @example
542    SETHASH <hexstring>
543 @end example
544
545 The client can use this command to tell the server about the data
546 (which usually is a hash) to be signed.  
547
548 The actual signing is done using
549
550 @example
551    PKSIGN <options>
552 @end example
553
554 Options are not yet defined, but my later be used to choosen among
555 different algorithms (e.g. pkcs 1.5)
556
557 The agent does then some checks, asks for the passphrase and
558 if SETHASH has not been used asks the client for the data to sign:
559
560 @example
561    S: INQUIRE HASHVAL
562    C: D ABCDEF012345678901234
563    C: END
564 @end example
565
566 As a result the server returns the signature as an SPKI like S-Exp
567 in "D" lines:
568
569 @example  
570      (sig-val   
571        (<algo>
572          (<param_name1> <mpi>)
573            ...
574          (<param_namen> <mpi>)))
575 @end example
576
577
578 The operation is affected by the option
579
580 @example
581    OPTION use-cache-for-signing=0|1
582 @end example
583
584 The default of @code{1} uses the cache.  Setting this option to @code{0}
585 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
586 also a global command line option for @command{gpg-agent} to globally disable the
587 caching.
588
589
590 Here is an example session:
591
592 @example
593    C: SIGKEY <keyGrip>
594    S: OK key available
595    C: SIGKEY <keyGrip>
596    S: OK key available
597    C: PKSIGN
598    S: # I did ask the user whether he really wants to sign
599    S: # I did ask the user for the passphrase
600    S: INQUIRE HASHVAL
601    C: D ABCDEF012345678901234
602    C: END
603    S: # signature follows
604    S: D (sig-val rsa (s 45435453654612121212))
605    S: OK
606 @end example
607
608
609 @node Agent GENKEY
610 @subsection Generating a Key
611
612 This is used to create a new keypair and store the secret key inside the
613 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
614 option allows to choose the storage location.  To get the secret key out
615 of the PSE, a special export tool has to be used.
616
617 @example
618    GENKEY 
619 @end example
620
621 Invokes the key generation process and the server will then inquire
622 on the generation parameters, like:
623
624 @example
625    S: INQUIRE KEYPARM
626    C: D (genkey (rsa (nbits  1024)))
627    C: END
628 @end example
629
630 The format of the key parameters which depends on the algorithm is of
631 the form:
632
633 @example
634     (genkey
635       (algo
636         (parameter_name_1 ....)
637           ....
638         (parameter_name_n ....)))
639 @end example
640
641 If everything succeeds, the server returns the *public key* in a SPKI
642 like S-Expression like this:
643
644 @example
645      (public-key
646        (rsa
647          (n <mpi>)
648          (e <mpi>)))
649 @end example
650
651 Here is an example session:
652
653 @example
654    C: GENKEY
655    S: INQUIRE KEYPARM
656    C: D (genkey (rsa (nbits  1024)))
657    C: END
658    S: D (public-key
659    S: D   (rsa (n 326487324683264) (e 10001)))
660    S  OK key created
661 @end example
662
663 @node Agent IMPORT
664 @subsection Importing a Secret Key
665
666 This operation is not yet supportted by GpgAgent.  Specialized tools
667 are to be used for this.
668
669 There is no actual need because we can expect that secret keys
670 created by a 3rd party are stored on a smartcard.  If we have
671 generated the key ourself, we do not need to import it.
672
673 @node Agent EXPORT
674 @subsection Export a Secret Key
675
676 Not implemented.
677
678 Should be done by an extra tool.
679
680 @node Agent ISTRUSTED
681 @subsection Importing a Root Certificate
682
683 Actually we do not import a Root Cert but provide a way to validate
684 any piece of data by storing its Hash along with a description and
685 an identifier in the PSE.  Here is the interface desription:
686
687 @example
688     ISTRUSTED <fingerprint>
689 @end example
690
691 Check whether the OpenPGP primary key or the X.509 certificate with the
692 given fingerprint is an ultimately trusted key or a trusted Root CA
693 certificate.  The fingerprint should be given as a hexstring (without
694 any blanks or colons or whatever in between) and may be left padded with
695 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
696
697 @example
698     OK
699 @end example
700
701 The key is in the table of trusted keys.
702
703 @example
704     ERR 304 (Not Trusted)
705 @end example
706
707 The key is not in this table.
708
709 Gpg needs the entire list of trusted keys to maintain the web of
710 trust; the following command is therefore quite helpful:
711
712 @example
713     LISTTRUSTED
714 @end example
715
716 GpgAgent returns a list of trusted keys line by line:
717
718 @example
719     S: D 000000001234454556565656677878AF2F1ECCFF P
720     S: D 340387563485634856435645634856438576457A P
721     S: D FEDC6532453745367FD83474357495743757435D S
722     S: OK
723 @end example
724
725 The first item on a line is the hexified fingerprint where MD5
726 ingerprints are @code{00} padded to the left and the second item is a
727 flag to indicate the type of key (so that gpg is able to only take care
728 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
729 of the line, so that we can extend the format in the future.
730
731 Finally a client should be able to mark a key as trusted:
732
733 @example
734    MARKTRUSTED @var{fingerprint} "P"|"S"
735 @end example
736
737 The server will then pop up a window to ask the user whether she
738 really trusts this key. For this it will probably ask for a text to
739 be displayed like this:
740
741 @example
742    S: INQUIRE TRUSTDESC
743    C: D Do you trust the key with the fingerprint @@FPR@@
744    C: D bla fasel blurb.
745    C: END
746    S: OK
747 @end example
748
749 Known sequences with the pattern @@foo@@ are replaced according to this
750 table:
751
752 @table @code
753 @item @@FPR16@@ 
754 Format the fingerprint according to gpg rules for a v3 keys.
755 @item @@FPR20@@ 
756 Format the fingerprint according to gpg rules for a v4 keys.
757 @item @@FPR@@
758 Choose an appropriate format to format the fingerprint.
759 @item @@@@ 
760 Replaced by a single @code{@@}
761 @end table
762
763 @node Agent GET_PASSPHRASE
764 @subsection Ask for a passphrase
765
766 This function is usually used to ask for a passphrase to be used for
767 conventional encryption, but may also be used by programs which need
768 special handling of passphrases.  This command uses a syntax which helps
769 clients to use the agent with minimum effort.
770
771 @example
772   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
773 @end example
774
775 @var{cache_id} is expected to be a hex string used for caching a
776 passphrase.  Use a @code{X} to bypass the cache.  With no other
777 arguments the agent returns a cached passphrase or an error.
778   
779 @var{error_message} is either a single @code{X} for no error message or
780 a string to be shown as an error message like (e.g. "invalid
781 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
782
783 @var{prompt} is either a single @code{X} for a default prompt or the
784 text to be shown as the prompt.  Blanks must be percent escaped or
785 replaced by @code{+}.
786
787 @var{description} is a text shown above the entry field.  Blanks must be
788 percent escaped or replaced by @code{+}.
789
790 The agent either returns with an error or with a OK followed by the 
791 hex encoded passphrase.  Note that the length of the strings is
792 implicitly limited by the maximum length of a command.
793
794 @example
795   CLEAR_PASSPHRASE @var{cache_id}
796 @end example
797
798 may be used to invalidate the cache entry for a passphrase.  The
799 function returns with OK even when there is no cached passphrase.
800
801
802 @node Agent GET_CONFIRMATION
803 @subsection Ask for confirmation
804
805 This command may be used to ask for a simple confirmation by
806 presenting a text and 2 bottonts: Okay and Cancel.
807
808 @example
809   GET_CONFIRMATION @var{description}
810 @end example
811
812 @var{description}is displayed along with a Okay and Cancel
813 button. Blanks must be percent escaped or replaced by @code{+}.  A
814 @code{X} may be used to display confirmation dialog with a default
815 text.
816
817 The agent either returns with an error or with a OK.  Note, that the
818 length of @var{description} is implicitly limited by the maximum
819 length of a command.
820
821
822
823 @node Agent HAVEKEY
824 @subsection Check whether a key is available
825
826 This can be used to see whether a secret key is available.  It does
827 not return any information on whether the key is somehow protected.
828
829 @example
830   HAVEKEY @var{keygrip}
831 @end example
832
833 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
834 caller may want to check for other error codes as well.
835
836
837 @node Agent LEARN
838 @subsection Register a smartcard
839
840 @example
841   LEARN [--send]
842 @end example
843
844 This command is used to register a smartcard.  With the --send
845 option given the certificates are send back.
846
847
848 @node Agent PASSWD
849 @subsection Change a Passphrase
850
851 @example
852   PASSWD @var{keygrip}
853 @end example
854
855 This command is used to interactively change the passphrase of the key
856 indentified by the hex string @var{keygrip}.
857
858
859