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