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