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