Made card key generate with backup key work for 2048 bit.
[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.  If the line is prefixed with a @code{!} the key is
524   explicitly marked as not trusted.
525   
526   Here is an example where two keys are marked as ultimately trusted
527   and one as not trusted:
528   
529   @example
530   # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
531   A6935DD34EF3087973C706FC311AA2CCF733765B S
532   
533   # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
534   DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S 
535
536   # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
537   !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
538   @end example
539   
540 Before entering a key into this file, you need to ensure its
541 authenticity.  How to do this depends on your organisation; your
542 administrator might have already entered those keys which are deemed
543 trustworthy enough into this file.  Places where to look for the
544 fingerprint of a root certificate are letters received from the CA or
545 the website of the CA (after making 100% sure that this is indeed the
546 website of that CA).  You may want to consider allowing interactive
547 updates of this file by using the @xref{option --allow-mark-trusted}.
548 This is however not as secure as maintaining this file manually.  It is
549 even advisable to change the permissions to read-only so that this file
550 can't be changed inadvertently.
551
552 As a special feature a line @code{include-default} will include a global
553 list of trusted certificates (e.g. @file{/etc/gnupg/trustlist.txt}).
554 This global list is also used if the local list is not available.
555
556 It is possible to add further flags after the @code{S} for use by the
557 caller:
558
559 @table @code
560 @item relax
561 Relax checking of some root certificate requirements.  This is for
562 example required if the certificate is missing the basicConstraints
563 attribute (despite that it is a MUST for CA certificates).
564
565 @item cm
566 If validation of a certificate finally issued by a CA with this flag set
567 fails, try again using the chain validation model.
568
569 @end table
570
571   
572 @item sshcontrol
573
574 This file is used when support for the secure shell agent protocol has
575 been enabled (@pxref{option --enable-ssh-support}). Only keys present
576 in this file are used in the SSH protocol.  The @command{ssh-add} tool
577 may be used to add new entries to this file; you may also add them
578 manually.  Comment lines, indicated by a leading hash mark, as well as
579 empty lines are ignored.  An entry starts with optional whitespace,
580 followed by the keygrip of the key given as 40 hex digits, optionally
581 followed by the caching TTL in seconds and another optional field for
582 arbitrary flags.  A non-zero TTL overrides the global default as
583 set by @option{--default-cache-ttl-ssh}.
584
585 The keygrip may be prefixed with a @code{!} to disable an entry entry.
586     
587 The following example lists exactly one key.  Note that keys available
588 through a OpenPGP smartcard in the active smartcard reader are
589 implicitly added to this list; i.e. there is no need to list them.
590   
591   @example
592   # Key added on 2005-02-25 15:08:29
593   5A6592BF45DC73BD876874A28FD4639282E29B52 0
594   @end example
595
596 @item private-keys-v1.d/
597
598   This is the directory where gpg-agent stores the private keys.  Each
599   key is stored in a file with the name made up of the keygrip and the
600   suffix @file{key}.
601
602
603 @end table
604
605 Note that on larger installations, it is useful to put predefined
606 files into the directory @file{/etc/skel/.gnupg/} so that newly created
607 users start up with a working configuration.  For existing users the
608 a small helper script is provided to create these files (@pxref{addgnupghome}).
609
610
611
612 @c
613 @c Agent Signals
614 @c
615 @mansect signals
616 @node Agent Signals
617 @section Use of some signals.
618 A running @command{gpg-agent} may be controlled by signals, i.e. using
619 the @command{kill} command to send a signal to the process. 
620
621 Here is a list of supported signals:
622
623 @table @gnupgtabopt
624
625 @item SIGHUP
626 @cpindex SIGHUP
627 This signal flushes all cached passphrases and if the program has been
628 started with a configuration file, the configuration file is read again.
629 Only certain options are honored: @code{quiet}, @code{verbose},
630 @code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
631 @code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
632 @code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
633 @code{disable-scdaemon}.  @code{scdaemon-program} is also supported but
634 due to the current implementation, which calls the scdaemon only once,
635 it is not of much use unless you manually kill the scdaemon.
636
637
638 @item SIGTERM
639 @cpindex SIGTERM
640 Shuts down the process but waits until all current requests are
641 fulfilled.  If the process has received 3 of these signals and requests
642 are still pending, a shutdown is forced.
643
644 @item SIGINT
645 @cpindex SIGINT
646 Shuts down the process immediately.
647
648 @item SIGUSR1
649 @cpindex SIGUSR1
650 Dump internal information to the log file.
651
652 @item SIGUSR2
653 @cpindex SIGUSR2
654 This signal is used for internal purposes.
655
656 @end table
657
658 @c 
659 @c  Examples
660 @c
661 @mansect examples
662 @node Agent Examples
663 @section Examples
664
665 The usual way to invoke @command{gpg-agent} is
666
667 @example
668 $ eval $(gpg-agent --daemon)
669 @end example
670
671 An alternative way is by replacing @command{ssh-agent} with
672 @command{gpg-agent}.  If for example @command{ssh-agent} is started as
673 part of the Xsession initialization, you may simply replace
674 @command{ssh-agent} by a script like:
675
676 @cartouche
677 @example
678 #!/bin/sh
679
680 exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
681       --write-env-file $@{HOME@}/.gpg-agent-info "$@@"
682 @end example
683 @end cartouche
684
685 @noindent
686 and add something like (for Bourne shells)
687
688 @cartouche
689 @example
690   if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
691     . "$@{HOME@}/.gpg-agent-info"
692     export GPG_AGENT_INFO
693     export SSH_AUTH_SOCK
694     export SSH_AGENT_PID
695   fi
696 @end example
697 @end cartouche
698
699 @noindent
700 to your shell initialization file (e.g. @file{~/.bashrc}).
701
702 @c 
703 @c  Assuan Protocol
704 @c
705 @manpause
706 @node Agent Protocol
707 @section Agent's Assuan Protocol
708
709 Note: this section does only document the protocol, which is used by
710 GnuPG components; it does not deal with the ssh-agent protocol.
711
712 The @command{gpg-agent} should be started by the login shell and set an
713 environment variable to tell clients about the socket to be used.
714 Clients should deny to access an agent with a socket name which does
715 not match its own configuration.  An application may choose to start
716 an instance of the gpgagent if it does not figure that any has been
717 started; it should not do this if a gpgagent is running but not
718 usable.  Because @command{gpg-agent} can only be used in background mode, no
719 special command line option is required to activate the use of the
720 protocol.
721
722 To identify a key we use a thing called keygrip which is the SHA-1 hash
723 of an canoncical encoded S-Expression of the the public key as used in
724 Libgcrypt.  For the purpose of this interface the keygrip is given as a
725 hex string.  The advantage of using this and not the hash of a
726 certificate is that it will be possible to use the same keypair for
727 different protocols, thereby saving space on the token used to keep the
728 secret keys.
729
730 @menu
731 * Agent PKDECRYPT::       Decrypting a session key
732 * Agent PKSIGN::          Signing a Hash
733 * Agent GENKEY::          Generating a Key
734 * Agent IMPORT::          Importing a Secret Key
735 * Agent EXPORT::          Exporting a Secret Key
736 * Agent ISTRUSTED::       Importing a Root Certificate
737 * Agent GET_PASSPHRASE::  Ask for a passphrase
738 * Agent GET_CONFIRMATION:: Ask for confirmation
739 * Agent HAVEKEY::         Check whether a key is available
740 * Agent LEARN::           Register a smartcard
741 * Agent PASSWD::          Change a Passphrase
742 * Agent UPDATESTARTUPTTY:: Change the Standard Display
743 * Agent GETEVENTCOUNTER:: Get the Event Counters
744 * Agent GETINFO::         Return information about the process
745 @end menu
746
747 @node Agent PKDECRYPT
748 @subsection Decrypting a session key
749
750 The client asks the server to decrypt a session key.  The encrypted
751 session key should have all information needed to select the
752 appropriate secret key or to delegate it to a smartcard.
753
754 @example
755   SETKEY <keyGrip>
756 @end example
757
758 Tell the server about the key to be used for decryption.  If this is
759 not used, @command{gpg-agent} may try to figure out the key by trying to
760 decrypt the message with each key available.
761
762 @example
763   PKDECRYPT
764 @end example
765
766 The agent checks whether this command is allowed and then does an
767 INQUIRY to get the ciphertext the client should then send the cipher
768 text.
769
770 @example
771     S: INQUIRE CIPHERTEXT
772     C: D (xxxxxx
773     C: D xxxx)
774     C: END
775 @end example
776     
777 Please note that the server may send status info lines while reading the
778 data lines from the client.  The data send is a SPKI like S-Exp with
779 this structure:
780
781 @example
782      (enc-val   
783        (<algo>
784          (<param_name1> <mpi>)
785            ...
786          (<param_namen> <mpi>)))
787 @end example
788
789 Where algo is a string with the name of the algorithm; see the libgcrypt
790 documentation for a list of valid algorithms.  The number and names of
791 the parameters depend on the algorithm.  The agent does return an error
792 if there is an inconsistency.
793
794 If the decryption was successful the decrypted data is returned by
795 means of "D" lines. 
796
797 Here is an example session:
798
799 @example
800    C: PKDECRYPT
801    S: INQUIRE CIPHERTEXT
802    C: D (enc-val elg (a 349324324) 
803    C: D    (b 3F444677CA)))
804    C: END
805    S: # session key follows
806    S: D (value 1234567890ABCDEF0)
807    S: OK descryption successful
808 @end example         
809
810
811 @node Agent PKSIGN
812 @subsection Signing a Hash
813
814 The client ask the agent to sign a given hash value.  A default key
815 will be chosen if no key has been set.  To set a key a client first
816 uses:
817
818 @example
819    SIGKEY <keyGrip>
820 @end example
821
822 This can be used multiple times to create multiple signature, the list
823 of keys is reset with the next PKSIGN command or a RESET.  The server
824 test whether the key is a valid key to sign something and responds with
825 okay.
826
827 @example
828    SETHASH --hash=<name>|<algo> <hexstring>
829 @end example
830
831 The client can use this command to tell the server about the data <hexstring>
832 (which usually is a hash) to be signed. <algo> is the decimal encoded hash
833 algorithm number as used by Libgcrypt.  Either <algo> or --hash=<name>
834 must be given.  Valid names for <name> are:
835
836 @table @code
837 @item sha1
838 @item sha256
839 @item rmd160
840 @item md5
841 @item tls-md5sha1
842 @end table
843
844 @noindent
845 The actual signing is done using
846
847 @example
848    PKSIGN <options>
849 @end example
850
851 Options are not yet defined, but my later be used to choosen among
852 different algorithms.  The agent does then some checks, asks for the
853 passphrase and as a result the server returns the signature as an SPKI
854 like S-expression in "D" lines:
855
856 @example  
857      (sig-val   
858        (<algo>
859          (<param_name1> <mpi>)
860            ...
861          (<param_namen> <mpi>)))
862 @end example
863
864
865 The operation is affected by the option
866
867 @example
868    OPTION use-cache-for-signing=0|1
869 @end example
870
871 The default of @code{1} uses the cache.  Setting this option to @code{0}
872 will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
873 also a global command line option for @command{gpg-agent} to globally disable the
874 caching.
875
876
877 Here is an example session:
878
879 @example
880    C: SIGKEY <keyGrip>
881    S: OK key available
882    C: SIGKEY <keyGrip>
883    S: OK key available
884    C: PKSIGN
885    S: # I did ask the user whether he really wants to sign
886    S: # I did ask the user for the passphrase
887    S: INQUIRE HASHVAL
888    C: D ABCDEF012345678901234
889    C: END
890    S: # signature follows
891    S: D (sig-val rsa (s 45435453654612121212))
892    S: OK
893 @end example
894
895
896 @node Agent GENKEY
897 @subsection Generating a Key
898
899 This is used to create a new keypair and store the secret key inside the
900 active PSE --- which is in most cases a Soft-PSE.  An not yet defined
901 option allows to choose the storage location.  To get the secret key out
902 of the PSE, a special export tool has to be used.
903
904 @example
905    GENKEY 
906 @end example
907
908 Invokes the key generation process and the server will then inquire
909 on the generation parameters, like:
910
911 @example
912    S: INQUIRE KEYPARM
913    C: D (genkey (rsa (nbits  1024)))
914    C: END
915 @end example
916
917 The format of the key parameters which depends on the algorithm is of
918 the form:
919
920 @example
921     (genkey
922       (algo
923         (parameter_name_1 ....)
924           ....
925         (parameter_name_n ....)))
926 @end example
927
928 If everything succeeds, the server returns the *public key* in a SPKI
929 like S-Expression like this:
930
931 @example
932      (public-key
933        (rsa
934          (n <mpi>)
935          (e <mpi>)))
936 @end example
937
938 Here is an example session:
939
940 @example
941    C: GENKEY
942    S: INQUIRE KEYPARM
943    C: D (genkey (rsa (nbits  1024)))
944    C: END
945    S: D (public-key
946    S: D   (rsa (n 326487324683264) (e 10001)))
947    S  OK key created
948 @end example
949
950 @node Agent IMPORT
951 @subsection Importing a Secret Key
952
953 This operation is not yet supportted by GpgAgent.  Specialized tools
954 are to be used for this.
955
956 There is no actual need because we can expect that secret keys
957 created by a 3rd party are stored on a smartcard.  If we have
958 generated the key ourself, we do not need to import it.
959
960 @node Agent EXPORT
961 @subsection Export a Secret Key
962
963 Not implemented.
964
965 Should be done by an extra tool.
966
967 @node Agent ISTRUSTED
968 @subsection Importing a Root Certificate
969
970 Actually we do not import a Root Cert but provide a way to validate
971 any piece of data by storing its Hash along with a description and
972 an identifier in the PSE.  Here is the interface desription:
973
974 @example
975     ISTRUSTED <fingerprint>
976 @end example
977
978 Check whether the OpenPGP primary key or the X.509 certificate with the
979 given fingerprint is an ultimately trusted key or a trusted Root CA
980 certificate.  The fingerprint should be given as a hexstring (without
981 any blanks or colons or whatever in between) and may be left padded with
982 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
983
984 @example
985     OK
986 @end example
987
988 The key is in the table of trusted keys.
989
990 @example
991     ERR 304 (Not Trusted)
992 @end example
993
994 The key is not in this table.
995
996 Gpg needs the entire list of trusted keys to maintain the web of
997 trust; the following command is therefore quite helpful:
998
999 @example
1000     LISTTRUSTED
1001 @end example
1002
1003 GpgAgent returns a list of trusted keys line by line:
1004
1005 @example
1006     S: D 000000001234454556565656677878AF2F1ECCFF P
1007     S: D 340387563485634856435645634856438576457A P
1008     S: D FEDC6532453745367FD83474357495743757435D S
1009     S: OK
1010 @end example
1011
1012 The first item on a line is the hexified fingerprint where MD5
1013 ingerprints are @code{00} padded to the left and the second item is a
1014 flag to indicate the type of key (so that gpg is able to only take care
1015 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
1016 of the line, so that we can extend the format in the future.
1017
1018 Finally a client should be able to mark a key as trusted:
1019
1020 @example
1021    MARKTRUSTED @var{fingerprint} "P"|"S"
1022 @end example
1023
1024 The server will then pop up a window to ask the user whether she
1025 really trusts this key. For this it will probably ask for a text to
1026 be displayed like this:
1027
1028 @example
1029    S: INQUIRE TRUSTDESC
1030    C: D Do you trust the key with the fingerprint @@FPR@@
1031    C: D bla fasel blurb.
1032    C: END
1033    S: OK
1034 @end example
1035
1036 Known sequences with the pattern @@foo@@ are replaced according to this
1037 table:
1038
1039 @table @code
1040 @item @@FPR16@@ 
1041 Format the fingerprint according to gpg rules for a v3 keys.
1042 @item @@FPR20@@ 
1043 Format the fingerprint according to gpg rules for a v4 keys.
1044 @item @@FPR@@
1045 Choose an appropriate format to format the fingerprint.
1046 @item @@@@ 
1047 Replaced by a single @code{@@}
1048 @end table
1049
1050 @node Agent GET_PASSPHRASE
1051 @subsection Ask for a passphrase
1052
1053 This function is usually used to ask for a passphrase to be used for
1054 conventional encryption, but may also be used by programs which need
1055 special handling of passphrases.  This command uses a syntax which helps
1056 clients to use the agent with minimum effort.
1057
1058 @example
1059   GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] [--qualitybar] @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
1060 @end example
1061
1062 @var{cache_id} is expected to be a string used to identify a cached
1063 passphrase.  Use a @code{X} to bypass the cache.  With no other
1064 arguments the agent returns a cached passphrase or an error.  By
1065 convention either the hexified fingerprint of the key shall be used for
1066 @var{cache_id} or an arbitrary string prefixed with the name of the
1067 calling application and a colon: Like @code{gpg:somestring}.
1068   
1069 @var{error_message} is either a single @code{X} for no error message or
1070 a string to be shown as an error message like (e.g. "invalid
1071 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
1072
1073 @var{prompt} is either a single @code{X} for a default prompt or the
1074 text to be shown as the prompt.  Blanks must be percent escaped or
1075 replaced by @code{+}.
1076
1077 @var{description} is a text shown above the entry field.  Blanks must be
1078 percent escaped or replaced by @code{+}.
1079
1080 The agent either returns with an error or with a OK followed by the hex
1081 encoded passphrase.  Note that the length of the strings is implicitly
1082 limited by the maximum length of a command.  If the option
1083 @option{--data} is used, the passphrase is not returned on the OK line
1084 but by regular data lines; this is the preferred method.
1085
1086 If the option @option{--check} is used, the standard passphrase
1087 constraints checks are applied.  A check is not done if the passphrase
1088 has been found in the cache.
1089
1090 If the option @option{--no-ask} is used and the passphrase is not in the
1091 cache the user will not be asked to enter a passphrase but the error
1092 code @code{GPG_ERR_NO_DATA} is returned.  
1093
1094 If the option @option{--qualitybar} is used and a minimum passphrase
1095 length has been configured, a visual indication of the entered
1096 passphrase quality is shown.
1097
1098 @example
1099   CLEAR_PASSPHRASE @var{cache_id}
1100 @end example
1101
1102 may be used to invalidate the cache entry for a passphrase.  The
1103 function returns with OK even when there is no cached passphrase.
1104
1105
1106 @node Agent GET_CONFIRMATION
1107 @subsection Ask for confirmation
1108
1109 This command may be used to ask for a simple confirmation by
1110 presenting a text and 2 bottonts: Okay and Cancel.
1111
1112 @example
1113   GET_CONFIRMATION @var{description}
1114 @end example
1115
1116 @var{description}is displayed along with a Okay and Cancel
1117 button. Blanks must be percent escaped or replaced by @code{+}.  A
1118 @code{X} may be used to display confirmation dialog with a default
1119 text.
1120
1121 The agent either returns with an error or with a OK.  Note, that the
1122 length of @var{description} is implicitly limited by the maximum
1123 length of a command.
1124
1125
1126
1127 @node Agent HAVEKEY
1128 @subsection Check whether a key is available
1129
1130 This can be used to see whether a secret key is available.  It does
1131 not return any information on whether the key is somehow protected.
1132
1133 @example
1134   HAVEKEY @var{keygrip}
1135 @end example
1136
1137 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
1138 caller may want to check for other error codes as well.
1139
1140
1141 @node Agent LEARN
1142 @subsection Register a smartcard
1143
1144 @example
1145   LEARN [--send]
1146 @end example
1147
1148 This command is used to register a smartcard.  With the --send
1149 option given the certificates are send back.
1150
1151
1152 @node Agent PASSWD
1153 @subsection Change a Passphrase
1154
1155 @example
1156   PASSWD @var{keygrip}
1157 @end example
1158
1159 This command is used to interactively change the passphrase of the key
1160 indentified by the hex string @var{keygrip}.
1161
1162
1163 @node Agent UPDATESTARTUPTTY
1164 @subsection Change the standard display
1165
1166 @example
1167   UPDATESTARTUPTTY
1168 @end example
1169
1170 Set the startup TTY and X-DISPLAY variables to the values of this
1171 session.  This command is useful to direct future pinentry invocations
1172 to another screen.  It is only required because there is no way in the
1173 ssh-agent protocol to convey this information.
1174
1175
1176 @node Agent GETEVENTCOUNTER
1177 @subsection Get the Event Counters
1178
1179 @example
1180   GETEVENTCOUNTER
1181 @end example
1182
1183 This function return one status line with the current values of the
1184 event counters.  The event counters are useful to avoid polling by
1185 delaying a poll until something has changed.  The values are decimal
1186 numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to
1187 0.  The actual values should not be relied upon; they shall only be used
1188 to detect a change.
1189
1190 The currently defined counters are are:
1191 @table @code
1192 @item ANY
1193 Incremented with any change of any of the other counters.
1194 @item KEY
1195 Incremented for added or removed private keys.
1196 @item CARD
1197 Incremented for changes of the card readers stati.
1198 @end table
1199
1200 @node Agent GETINFO
1201 @subsection  Return information about the process
1202
1203 This is a multipurpose function to return a variety of information.
1204
1205 @example
1206 GETINFO @var{what}
1207 @end example
1208
1209 The value of @var{what} specifies the kind of information returned:
1210 @table @code
1211 @item version
1212 Return the version of the program.
1213 @item pid
1214 Return the process id of the process.
1215 @item socket_name
1216 Return the name of the socket used to connect the agent.
1217 @item ssh_socket_name
1218 Return the name of the socket used for SSH connections.  If SSH support
1219 has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned.
1220 @end table
1221
1222
1223 @mansect see also
1224 @ifset isman
1225 @command{gpg2}(1), 
1226 @command{gpgsm}(1), 
1227 @command{gpg-connect-agent}(1),
1228 @command{scdaemon}(1)
1229 @end ifset
1230 @include see-also-note.texi