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