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