(Agent Configuration): New section.
[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 signals flushes all chached passphrases and when the program was
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{no-grab}, @code{pinentry-program},
472 @code{default-cache-ttl} and @code{ignore-cache-for-signing}.
473 @code{scdaemon-program} is also supported but due to the current
474 implementation, which calls the scdaemon only once, it is not of much
475 use.
476
477
478 @item SIGTERM
479 @cpindex SIGTERM
480 Shuts down the process but waits until all current requests are
481 fulfilled.  If the process has received 3 of these signals and requests
482 are still pending, a shutdown is forced.
483
484 @item SIGINT
485 @cpindex SIGINT
486 Shuts down the process immediately.
487
488
489 @item SIGUSR1
490 @itemx SIGUSR2
491 @cpindex SIGUSR1
492 @cpindex SIGUSR2
493 These signals are used for internal purposes.
494
495 @end table
496
497 @c 
498 @c  Examples
499 @c
500 @node Agent Examples
501 @section Examples
502
503 @c man begin EXAMPLES
504
505 @example
506 $ eval `gpg-agent --daemon`
507 @end example
508
509 @c man end
510
511
512 @c 
513 @c  Assuan Protocol
514 @c
515 @node Agent Protocol
516 @section Agent's Assuan Protocol
517
518 Note: this section does only document the protocol, which is used by
519 GnuPG components; it does not deal with the ssh-agent protocol.
520
521 The @command{gpg-agent} should be started by the login shell and set an
522 environment variable to tell clients about the socket to be used.
523 Clients should deny to access an agent with a socket name which does
524 not match its own configuration.  An application may choose to start
525 an instance of the gpgagent if it does not figure that any has been
526 started; it should not do this if a gpgagent is running but not
527 usable.  Because @command{gpg-agent} can only be used in background mode, no
528 special command line option is required to activate the use of the
529 protocol.
530
531 To identify a key we use a thing called keygrip which is the SHA-1 hash
532 of an canoncical encoded S-Expression of the the public key as used in
533 Libgcrypt.  For the purpose of this interface the keygrip is given as a
534 hex string.  The advantage of using this and not the hash of a
535 certificate is that it will be possible to use the same keypair for
536 different protocols, thereby saving space on the token used to keep the
537 secret keys.
538
539 @menu
540 * Agent PKDECRYPT::       Decrypting a session key
541 * Agent PKSIGN::          Signing a Hash
542 * Agent GENKEY::          Generating a Key
543 * Agent IMPORT::          Importing a Secret Key
544 * Agent EXPORT::          Exporting a Secret Key
545 * Agent ISTRUSTED::       Importing a Root Certificate
546 * Agent GET_PASSPHRASE::  Ask for a passphrase
547 * Agent GET_CONFIRMATION:: Ask for confirmation
548 * Agent HAVEKEY::         Check whether a key is available
549 * Agent LEARN::           Register a smartcard
550 * Agent PASSWD::          Change a Passphrase
551 @end menu
552
553 @node Agent PKDECRYPT
554 @subsection Decrypting a session key
555
556 The client asks the server to decrypt a session key.  The encrypted
557 session key should have all information needed to select the
558 appropriate secret key or to delegate it to a smartcard.
559
560 @example
561   SETKEY <keyGrip>
562 @end example
563
564 Tell the server about the key to be used for decryption.  If this is
565 not used, @command{gpg-agent} may try to figure out the key by trying to
566 decrypt the message with each key available.
567
568 @example
569   PKDECRYPT
570 @end example
571
572 The agent checks whether this command is allowed and then does an
573 INQUIRY to get the ciphertext the client should then send the cipher
574 text.
575
576 @example
577     S: INQUIRE CIPHERTEXT
578     C: D (xxxxxx
579     C: D xxxx)
580     C: END
581 @end example
582     
583 Please note that the server may send status info lines while reading the
584 data lines from the client.  The data send is a SPKI like S-Exp with
585 this structure:
586
587 @example
588      (enc-val   
589        (<algo>
590          (<param_name1> <mpi>)
591            ...
592          (<param_namen> <mpi>)))
593 @end example
594
595 Where algo is a string with the name of the algorithm; see the libgcrypt
596 documentation for a list of valid algorithms.  The number and names of
597 the parameters depend on the algorithm.  The agent does return an error
598 if there is an inconsistency.
599
600 If the decryption was successful the decrypted data is returned by
601 means of "D" lines. 
602
603 Here is an example session:
604
605 @example
606    C: PKDECRYPT
607    S: INQUIRE CIPHERTEXT
608    C: D (enc-val elg (a 349324324) 
609    C: D    (b 3F444677CA)))
610    C: END
611    S: # session key follows
612    S: D 1234567890ABCDEF0
613    S: OK descryption successful
614 @end example         
615
616
617 @node Agent PKSIGN
618 @subsection Signing a Hash
619
620 The client ask the agent to sign a given hash value.  A default key
621 will be chosen if no key has been set.  To set a key a client first
622 uses:
623
624 @example
625    SIGKEY <keyGrip>
626 @end example
627
628 This can be used multiple times to create multiple signature, the list
629 of keys is reset with the next PKSIGN command or a RESET.  The server
630 test whether the key is a valid key to sign something and responds with
631 okay.
632
633 @example
634    SETHASH <hexstring>
635 @end example
636
637 The client can use this command to tell the server about the data
638 (which usually is a hash) to be signed.  
639
640 The actual signing is done using
641
642 @example
643    PKSIGN <options>
644 @end example
645
646 Options are not yet defined, but my later be used to choosen among
647 different algorithms (e.g. pkcs 1.5)
648
649 The agent does then some checks, asks for the passphrase and
650 if SETHASH has not been used asks the client for the data to sign:
651
652 @example
653    S: INQUIRE HASHVAL
654    C: D ABCDEF012345678901234
655    C: END
656 @end example
657
658 As a result the server returns the signature as an SPKI like S-Exp
659 in "D" lines:
660
661 @example  
662      (sig-val   
663        (<algo>
664          (<param_name1> <mpi>)
665            ...
666          (<param_namen> <mpi>)))
667 @end example
668
669
670 The operation is affected by the option
671
672 @example
673    OPTION use-cache-for-signing=0|1
674 @end example
675
676 The default of @code{1} uses the cache.  Setting this option to @code{0}
677 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
678 also a global command line option for @command{gpg-agent} to globally disable the
679 caching.
680
681
682 Here is an example session:
683
684 @example
685    C: SIGKEY <keyGrip>
686    S: OK key available
687    C: SIGKEY <keyGrip>
688    S: OK key available
689    C: PKSIGN
690    S: # I did ask the user whether he really wants to sign
691    S: # I did ask the user for the passphrase
692    S: INQUIRE HASHVAL
693    C: D ABCDEF012345678901234
694    C: END
695    S: # signature follows
696    S: D (sig-val rsa (s 45435453654612121212))
697    S: OK
698 @end example
699
700
701 @node Agent GENKEY
702 @subsection Generating a Key
703
704 This is used to create a new keypair and store the secret key inside the
705 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
706 option allows to choose the storage location.  To get the secret key out
707 of the PSE, a special export tool has to be used.
708
709 @example
710    GENKEY 
711 @end example
712
713 Invokes the key generation process and the server will then inquire
714 on the generation parameters, like:
715
716 @example
717    S: INQUIRE KEYPARM
718    C: D (genkey (rsa (nbits  1024)))
719    C: END
720 @end example
721
722 The format of the key parameters which depends on the algorithm is of
723 the form:
724
725 @example
726     (genkey
727       (algo
728         (parameter_name_1 ....)
729           ....
730         (parameter_name_n ....)))
731 @end example
732
733 If everything succeeds, the server returns the *public key* in a SPKI
734 like S-Expression like this:
735
736 @example
737      (public-key
738        (rsa
739          (n <mpi>)
740          (e <mpi>)))
741 @end example
742
743 Here is an example session:
744
745 @example
746    C: GENKEY
747    S: INQUIRE KEYPARM
748    C: D (genkey (rsa (nbits  1024)))
749    C: END
750    S: D (public-key
751    S: D   (rsa (n 326487324683264) (e 10001)))
752    S  OK key created
753 @end example
754
755 @node Agent IMPORT
756 @subsection Importing a Secret Key
757
758 This operation is not yet supportted by GpgAgent.  Specialized tools
759 are to be used for this.
760
761 There is no actual need because we can expect that secret keys
762 created by a 3rd party are stored on a smartcard.  If we have
763 generated the key ourself, we do not need to import it.
764
765 @node Agent EXPORT
766 @subsection Export a Secret Key
767
768 Not implemented.
769
770 Should be done by an extra tool.
771
772 @node Agent ISTRUSTED
773 @subsection Importing a Root Certificate
774
775 Actually we do not import a Root Cert but provide a way to validate
776 any piece of data by storing its Hash along with a description and
777 an identifier in the PSE.  Here is the interface desription:
778
779 @example
780     ISTRUSTED <fingerprint>
781 @end example
782
783 Check whether the OpenPGP primary key or the X.509 certificate with the
784 given fingerprint is an ultimately trusted key or a trusted Root CA
785 certificate.  The fingerprint should be given as a hexstring (without
786 any blanks or colons or whatever in between) and may be left padded with
787 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
788
789 @example
790     OK
791 @end example
792
793 The key is in the table of trusted keys.
794
795 @example
796     ERR 304 (Not Trusted)
797 @end example
798
799 The key is not in this table.
800
801 Gpg needs the entire list of trusted keys to maintain the web of
802 trust; the following command is therefore quite helpful:
803
804 @example
805     LISTTRUSTED
806 @end example
807
808 GpgAgent returns a list of trusted keys line by line:
809
810 @example
811     S: D 000000001234454556565656677878AF2F1ECCFF P
812     S: D 340387563485634856435645634856438576457A P
813     S: D FEDC6532453745367FD83474357495743757435D S
814     S: OK
815 @end example
816
817 The first item on a line is the hexified fingerprint where MD5
818 ingerprints are @code{00} padded to the left and the second item is a
819 flag to indicate the type of key (so that gpg is able to only take care
820 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
821 of the line, so that we can extend the format in the future.
822
823 Finally a client should be able to mark a key as trusted:
824
825 @example
826    MARKTRUSTED @var{fingerprint} "P"|"S"
827 @end example
828
829 The server will then pop up a window to ask the user whether she
830 really trusts this key. For this it will probably ask for a text to
831 be displayed like this:
832
833 @example
834    S: INQUIRE TRUSTDESC
835    C: D Do you trust the key with the fingerprint @@FPR@@
836    C: D bla fasel blurb.
837    C: END
838    S: OK
839 @end example
840
841 Known sequences with the pattern @@foo@@ are replaced according to this
842 table:
843
844 @table @code
845 @item @@FPR16@@ 
846 Format the fingerprint according to gpg rules for a v3 keys.
847 @item @@FPR20@@ 
848 Format the fingerprint according to gpg rules for a v4 keys.
849 @item @@FPR@@
850 Choose an appropriate format to format the fingerprint.
851 @item @@@@ 
852 Replaced by a single @code{@@}
853 @end table
854
855 @node Agent GET_PASSPHRASE
856 @subsection Ask for a passphrase
857
858 This function is usually used to ask for a passphrase to be used for
859 conventional encryption, but may also be used by programs which need
860 special handling of passphrases.  This command uses a syntax which helps
861 clients to use the agent with minimum effort.
862
863 @example
864   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
865 @end example
866
867 @var{cache_id} is expected to be a hex string used for caching a
868 passphrase.  Use a @code{X} to bypass the cache.  With no other
869 arguments the agent returns a cached passphrase or an error.
870   
871 @var{error_message} is either a single @code{X} for no error message or
872 a string to be shown as an error message like (e.g. "invalid
873 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
874
875 @var{prompt} is either a single @code{X} for a default prompt or the
876 text to be shown as the prompt.  Blanks must be percent escaped or
877 replaced by @code{+}.
878
879 @var{description} is a text shown above the entry field.  Blanks must be
880 percent escaped or replaced by @code{+}.
881
882 The agent either returns with an error or with a OK followed by the 
883 hex encoded passphrase.  Note that the length of the strings is
884 implicitly limited by the maximum length of a command.
885
886 @example
887   CLEAR_PASSPHRASE @var{cache_id}
888 @end example
889
890 may be used to invalidate the cache entry for a passphrase.  The
891 function returns with OK even when there is no cached passphrase.
892
893
894 @node Agent GET_CONFIRMATION
895 @subsection Ask for confirmation
896
897 This command may be used to ask for a simple confirmation by
898 presenting a text and 2 bottonts: Okay and Cancel.
899
900 @example
901   GET_CONFIRMATION @var{description}
902 @end example
903
904 @var{description}is displayed along with a Okay and Cancel
905 button. Blanks must be percent escaped or replaced by @code{+}.  A
906 @code{X} may be used to display confirmation dialog with a default
907 text.
908
909 The agent either returns with an error or with a OK.  Note, that the
910 length of @var{description} is implicitly limited by the maximum
911 length of a command.
912
913
914
915 @node Agent HAVEKEY
916 @subsection Check whether a key is available
917
918 This can be used to see whether a secret key is available.  It does
919 not return any information on whether the key is somehow protected.
920
921 @example
922   HAVEKEY @var{keygrip}
923 @end example
924
925 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
926 caller may want to check for other error codes as well.
927
928
929 @node Agent LEARN
930 @subsection Register a smartcard
931
932 @example
933   LEARN [--send]
934 @end example
935
936 This command is used to register a smartcard.  With the --send
937 option given the certificates are send back.
938
939
940 @node Agent PASSWD
941 @subsection Change a Passphrase
942
943 @example
944   PASSWD @var{keygrip}
945 @end example
946
947 This command is used to interactively change the passphrase of the key
948 indentified by the hex string @var{keygrip}.
949
950
951