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