2003-11-16 Moritz Schulte <mo@g10code.com>
[gnupg.git] / doc / gpg-agent.texi
1 @c Copyright (C) 2002 Free Software Foundation, Inc.
2 @c This is part of the GnuPG manual.
3 @c For copying conditions, see the file gnupg.texi.
4
5 @node Invoking GPG-AGENT
6 @chapter Invoking GPG-AGENT
7 @cindex GPG-AGENT command options
8 @cindex command options
9 @cindex options, GPG-AGENT command
10
11 @c man begin DESCRIPTION
12
13 @sc{gpg-agent} is a daemon to manage secret (private) keys independelty
14 from any protocol.  It is used as a backend for @sc{gpg} and @sc{gpgsm}
15 as well as for a couple of other utilities.
16
17 @noindent
18 The usual way to run the agent is from the @code{~/.xsession} file:
19
20 @example
21 eval `gpg-agent --daemon`
22 @end example
23
24 @noindent
25 If you don't use an X server, you can also put this into your regular
26 startup file @code{~/.profile} or @code{.bash_profile}.  It is best not
27 to run multiple instance of the gpg-agent, so you should make sure that
28 only is running:  @sc{gpg-agent} uses an environment variable to inform
29 clients about the communication parameters. You can write the
30 content of this environment variable to a file so that you can test for
31 a running agent.  This short script may do the job:
32
33 @smallexample
34 if test -f $HOME/.gpg-agent-info && \
35    kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
36      GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
37      export GPG_AGENT_INFO   
38 else
39      eval `gpg-agent --daemon`
40      echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
41 fi
42 @end smallexample
43
44 @noindent
45 If you want to use a curses based pinentry (which is usually also the
46 fallback mode for a GUI based pinentry), you should add these lines to
47 your @code{.bashrc} or whatever initialization file is used for all shell
48 invocations:
49
50 @smallexample
51 GPG_TTY=`tty`
52 export GPG_TTY
53 @end smallexample
54
55 It is important that this environment variable always reflects the
56 output of the @code{tty} command.
57
58 @c man end
59
60 @noindent
61 @xref{Option Index}, for an index to GPG-AGENTS's commands and options.
62
63 @menu
64 * Agent Commands::      List of all commands.
65 * Agent Options::       List of all options.
66 * Agent Signals::       Use of some signals.
67 * Agent Examples::      Some usage examples.
68 * Agent Protocol::      The protocol the agent uses.
69 @end menu
70
71 @c man begin COMMANDS
72
73 @node Agent Commands
74 @section Commands
75
76 Commands are not distinguished from options execpt for the fact that
77 only one one command is allowed.
78
79 @table @gnupgtabopt
80 @item --version
81 @opindex version
82 Print the program version and licensing information.  Not that you can
83 abbreviate this command.
84
85 @item --help, -h
86 @opindex help
87 Print a usage message summarizing the most usefule command-line options.
88 Not that you can abbreviate this command.
89
90 @item --dump-options
91 @opindex dump-options
92 Print a list of all available options and commands.  Not that you can
93 abbreviate this command.
94
95 @item --server
96 @opindex server
97 Run in server mode and wait for commands on the @code{stdin}.  The
98 default mode is to create a socket and listen for commands there.
99
100 @item --daemon
101 @opindex daemon
102 Run the program in the background.  This option is required to prevent
103 it from being accidently running in the background.  A common way to do
104 this is:
105 @example
106 @end example
107 $ eval `gpg-agent --daemon`
108 @end table
109
110
111 @c man begin OPTIONS
112
113 @node Agent Options
114 @section Option Summary
115
116 @table @gnupgtabopt
117
118 @item --options @var{file}
119 @opindex options
120 Reads configuration from @var{file} instead of from the default
121 per-user configuration file.
122
123 @item -v
124 @item --verbose
125 @opindex v
126 @opindex verbose
127 Outputs additional information while running.
128 You can increase the verbosity by giving several
129 verbose commands to @sc{gpgsm}, such as @samp{-vv}.
130
131 @item -q
132 @item --quiet
133 @opindex q
134 @opindex quiet
135 Try to be as quiet as possible.
136
137 @item --batch
138 @opindex batch
139 Don't invoke a pinentry or do any other thing requiring human interaction.
140
141 @item --faked-system-time @var{epoch}
142 @opindex faked-system-time
143 This option is only useful for testing; it sets the system time back or
144 forth to @var{epoch} which is the number of seconds elapsed since the year
145 1970.
146
147 @item --debug @var{flags}
148 @opindex debug
149 This option is only useful for debugging and the behaviour may change at
150 any time without notice.  FLAGS are bit encoded and may be given in
151 usual C-Syntax. The currently defined bits are:
152    @table @code
153    @item 0  (1)
154    X.509 or OpenPGP protocol related data
155    @item 1  (2)  
156    values of big number integers 
157    @item 2  (4)
158    low level crypto operations
159    @item 5  (32)
160    memory allocation
161    @item 6  (64)
162    caching
163    @item 7  (128)
164    show memory statistics.
165    @item 9  (512)
166    write hashed data to files named @code{dbgmd-000*}
167    @item 10 (1024)
168    trace Assuan protocol
169    @item 12 (4096)
170    bypass all certificate validation
171    @end table
172
173 @item --debug-all
174 @opindex debug-all
175 Same as @code{--debug=0xffffffff}
176
177 @item --debug-wait @var{n}
178 @opindex debug-wait
179 When running in server mode, wait @var{n} seconds before entering the
180 actual processing loop and print the pid.  This gives time to attach a
181 debugger.
182
183 @item --no-detach
184 @opindex no-detach
185 Don't detach the process from the console.  This is manly usefule for
186 debugging.
187
188 @item -s
189 @itemx --sh
190 @itemx -c
191 @itemx --csh
192 @opindex s
193 @opindex sh
194 @opindex c
195 @opindex csh
196 Format the info output in daemon mode for use with the standard Bourne
197 shell respective the C-shell . The default ist to guess it based on the
198 environment variable @code{SHELL} which is in almost all cases
199 sufficient.
200
201 @item --no-grab
202 @opindex no-grab
203 Tell the pinentryo not to grab the keyboard and mouse.  This option
204 should in general not be used to avaoid X-sniffing attacks.
205
206 @item --log-file @var{file}
207 @opindex log-file
208 Append all logging output to @var{file}.  This is very helpful in
209 seeing what the agent actually does.
210
211 @item --disable-pth
212 @opindex disable-pth
213 Don't allow multiple connections.  This option is in general not very
214 useful. 
215
216 @item --ignore-cache-for-signing
217 @opindex ignore-cache-for-signing
218 This option will let gpg-agent bypass the passphrase cache for all
219 signing operation.  Note that there is also a per-session option to
220 control this behaviour but this command line option takes precedence.
221
222 @item --default-cache-ttl @var{n}
223 @opindex default-cache-ttl
224 Set the time a cache entry is valid to @var{n} seconds.  The default are
225 600 seconds.
226
227 @item --pinentry-program @var{path}
228 @opindex pinentry-program
229 Use program @var{path} as the PIN entry.  The default is installation
230 dependend and can be shown with the @code{--version} command.
231
232 @item --scdaemon-program @var{path}
233 @opindex scdaemon-program
234 Use program @var{path} as the Smartcard daemon.  The default is installation
235 dependend and can be shown with the @code{--version} command.
236
237
238 @item --display @var{string}
239 @itemx --ttyname @var{string}
240 @itemx --ttytype @var{string}
241 @itemx --lc-type @var{string}
242 @itemx --lc-messages @var{string}
243 @opindex display 
244 @opindex ttyname 
245 @opindex ttytype 
246 @opindex lc-type 
247 @opindex lc-messa
248 These options are used with the server mode to pass localization
249 information.
250
251 @item --keep-tty
252 @itemx --keep-display
253 @opindex keep-tty
254 @opindex keep-display
255 Ignore requests to change change the current @sc{tty} respective the X
256 window system's @code{DISPLAY} variable.  This is useful to lock the
257 pinentry to pop up at the @sc{tty} or display you started the agent.
258
259
260 @end table
261
262 All the long options may also be given in the configuration file after
263 stripping off the two leading dashes.
264
265 @c
266 @c Agent Signals
267 @c
268 @node Agent Signals
269 @section Use of some signals.
270 A running @command{gpg-agent} may be controlled by signals, i.e. using
271 the @command{kill} command to send a signal to the process. 
272
273 Here is a list of supported signals:
274
275 @table @gnupgtabopt
276
277 @item SIGHUP
278 @cpindex SIGHUP
279 This signals flushes all chached passphrases and when the program was
280 started with a configuration file, the configuration file is read again.
281 Only certain options are honored: @code{quiet}, @code{verbose},
282 @code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program},
283 @code{default-cache-ttl} and @code{ignore-cache-for-signing}.
284 @code{scdaemon-program} is also supported but due to the current
285 implementation, which calls the scdaemon only once, it is not of much
286 use.
287
288
289 @item SIGUSR1
290 @cpindex SIGUSR1
291 This signal increases the verbosity of the logging by one up to a value
292 of 5.
293
294 @item SIGUSR2
295 @cpindex SIGUSR2
296 This signal decreases the verbosity of the logging by one.
297
298 @item SIGTERM
299 @cpindex SIGTERM
300 Shuts down the process but waits until all current requests are
301 fulfilled.  If the process has received 3 of these signals and requests
302 are still pending, a shutdown is forced.
303
304 @item SIGINT
305 @cpindex SIGINT
306 Shuts down the process immediately.
307
308 @end table
309
310 @c 
311 @c  Examples
312 @c
313 @node Agent Examples
314 @section Examples
315
316 @c man begin EXAMPLES
317
318 @example
319 $ eval `gpg-agent --daemon`
320 @end example
321
322 @c man end
323
324
325 @c 
326 @c  Assuan Protocol
327 @c
328 @node Agent Protocol
329 @section Agent's Assuan Protocol
330
331 The gpg-agent should be started by the login shell and set an
332 environment variable to tell clients about the socket to be used.
333 Clients should deny to access an agent with a socket name which does
334 not match its own configuration.  An application may choose to start
335 an instance of the gpgagent if it does not figure that any has been
336 started; it should not do this if a gpgagent is running but not
337 usable.  Because gpg-agent can only be used in background mode, no
338 special command line option is required to activate the use of the
339 protocol.
340
341 To identify a key we use a thing called keygrip which is the SHA-1 hash
342 of an canoncical encoded S-Expression of the the public key as used in
343 Libgcrypt.  For the purpose of this interface the keygrip is given as a
344 hex string.  The advantage of using this and not the hash of a
345 certificate is that it will be possible to use the same keypair for
346 different protocols, thereby saving space on the token used to keep the
347 secret keys.
348
349 @menu
350 * Agent PKDECRYPT::       Decrypting a session key
351 * Agent PKSIGN::          Signing a Hash
352 * Agent GENKEY::          Generating a Key
353 * Agent IMPORT::          Importing a Secret Key
354 * Agent EXPORT::          Exporting a Secret Key
355 * Agent ISTRUSTED::       Importing a Root Certificate
356 * Agent GET_PASSPHRASE::  Ask for a passphrase
357 * Agent GET_CONFIRMATION:: Ask for confirmation
358 * Agent HAVEKEY::         Check whether a key is available
359 * Agent LEARN::           Register a smartcard
360 * Agent PASSWD::          Change a Passphrase
361 @end menu
362
363 @node Agent PKDECRYPT
364 @subsection Decrypting a session key
365
366 The client asks the server to decrypt a session key.  The encrypted
367 session key should have all information needed to select the
368 appropriate secret key or to delegate it to a smartcard.
369
370 @example
371   SETKEY <keyGrip>
372 @end example
373
374 Tell the server about the key to be used for decryption.  If this is
375 not used, gpg-agent may try to figure out the key by trying to
376 decrypt the message with each key available.
377
378 @example
379   PKDECRYPT
380 @end example
381
382 The agent checks whether this command is allowed and then does an
383 INQUIRY to get the ciphertext the client should then send the cipher
384 text.
385
386 @example
387     S: INQUIRE CIPHERTEXT
388     C: D (xxxxxx
389     C: D xxxx)
390     C: END
391 @end example
392     
393 Please note that the server may send status info lines while reading the
394 data lines from the client.  The data send is a SPKI like S-Exp with
395 this structure:
396
397 @example
398      (enc-val   
399        (<algo>
400          (<param_name1> <mpi>)
401            ...
402          (<param_namen> <mpi>)))
403 @end example
404
405 Where algo is a string with the name of the algorithm; see the libgcrypt
406 documentation for a list of valid algorithms.  The number and names of
407 the parameters depend on the algorithm.  The agent does return an error
408 if there is an inconsistency.
409
410 If the decryption was successful the decrypted data is returned by
411 means of "D" lines. 
412
413 Here is an example session:
414
415 @example
416    C: PKDECRYPT
417    S: INQUIRE CIPHERTEXT
418    C: D (enc-val elg (a 349324324) 
419    C: D    (b 3F444677CA)))
420    C: END
421    S: # session key follows
422    S: D 1234567890ABCDEF0
423    S: OK descryption successful
424 @end example         
425
426
427 @node Agent PKSIGN
428 @subsection Signing a Hash
429
430 The client ask the agent to sign a given hash value.  A default key
431 will be chosen if no key has been set.  To set a key a client first
432 uses:
433
434 @example
435    SIGKEY <keyGrip>
436 @end example
437
438 This can be used multiple times to create multiple signature, the list
439 of keys is reset with the next PKSIGN command or a RESET.  The server
440 test whether the key is a valid key to sign something and responds with
441 okay.
442
443 @example
444    SETHASH <hexstring>
445 @end example
446
447 The client can use this command to tell the server about the data
448 (which usually is a hash) to be signed.  
449
450 The actual signing is done using
451
452 @example
453    PKSIGN <options>
454 @end example
455
456 Options are not yet defined, but my later be used to choosen among
457 different algorithms (e.g. pkcs 1.5)
458
459 The agent does then some checks, asks for the passphrase and
460 if SETHASH has not been used asks the client for the data to sign:
461
462 @example
463    S: INQUIRE HASHVAL
464    C: D ABCDEF012345678901234
465    C: END
466 @end example
467
468 As a result the server returns the signature as an SPKI like S-Exp
469 in "D" lines:
470
471 @example  
472      (sig-val   
473        (<algo>
474          (<param_name1> <mpi>)
475            ...
476          (<param_namen> <mpi>)))
477 @end example
478
479
480 The operation is affected by the option
481
482 @example
483    OPTION use-cache-for-signing=0|1
484 @end example
485
486 The default of @code{1} uses the cache.  Setting this option to @code{0}
487 will lead gpg-agent to ignore the passphrase cache.  Note, that there is
488 also a global command line option for gpg-agent to globally disable the
489 caching.
490
491
492 Here is an example session:
493
494 @example
495    C: SIGKEY <keyGrip>
496    S: OK key available
497    C: SIGKEY <keyGrip>
498    S: OK key available
499    C: PKSIGN
500    S: # I did ask the user whether he really wants to sign
501    S: # I did ask the user for the passphrase
502    S: INQUIRE HASHVAL
503    C: D ABCDEF012345678901234
504    C: END
505    S: # signature follows
506    S: D (sig-val rsa (s 45435453654612121212))
507    S: OK
508 @end example
509
510
511 @node Agent GENKEY
512 @subsection Generating a Key
513
514 This is used to create a new keypair and store the secret key inside the
515 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
516 option allows to choose the storage location.  To get the secret key out
517 of the PSE, a special export tool has to be used.
518
519 @example
520    GENKEY 
521 @end example
522
523 Invokes the key generation process and the server will then inquire
524 on the generation parameters, like:
525
526 @example
527    S: INQUIRE KEYPARM
528    C: D (genkey (rsa (nbits  1024)))
529    C: END
530 @end example
531
532 The format of the key parameters which depends on the algorithm is of
533 the form:
534
535 @example
536     (genkey
537       (algo
538         (parameter_name_1 ....)
539           ....
540         (parameter_name_n ....)))
541 @end example
542
543 If everything succeeds, the server returns the *public key* in a SPKI
544 like S-Expression like this:
545
546 @example
547      (public-key
548        (rsa
549          (n <mpi>)
550          (e <mpi>)))
551 @end example
552
553 Here is an example session:
554
555 @example
556    C: GENKEY
557    S: INQUIRE KEYPARM
558    C: D (genkey (rsa (nbits  1024)))
559    C: END
560    S: D (public-key
561    S: D   (rsa (n 326487324683264) (e 10001)))
562    S  OK key created
563 @end example
564
565 @node Agent IMPORT
566 @subsection Importing a Secret Key
567
568 This operation is not yet supportted by GpgAgent.  Specialized tools
569 are to be used for this.
570
571 There is no actual need because we can expect that secret keys
572 created by a 3rd party are stored on a smartcard.  If we have
573 generated the key ourself, we do not need to import it.
574
575 @node Agent EXPORT
576 @subsection Export a Secret Key
577
578 Not implemented.
579
580 Should be done by an extra tool.
581
582 @node Agent ISTRUSTED
583 @subsection Importing a Root Certificate
584
585 Actually we do not import a Root Cert but provide a way to validate
586 any piece of data by storing its Hash along with a description and
587 an identifier in the PSE.  Here is the interface desription:
588
589 @example
590     ISTRUSTED <fingerprint>
591 @end example
592
593 Check whether the OpenPGP primary key or the X.509 certificate with the
594 given fingerprint is an ultimately trusted key or a trusted Root CA
595 certificate.  The fingerprint should be given as a hexstring (without
596 any blanks or colons or whatever in between) and may be left padded with
597 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
598
599 @example
600     OK
601 @end example
602
603 The key is in the table of trusted keys.
604
605 @example
606     ERR 304 (Not Trusted)
607 @end example
608
609 The key is not in this table.
610
611 Gpg needs the entire list of trusted keys to maintain the web of
612 trust; the following command is therefore quite helpful:
613
614 @example
615     LISTTRUSTED
616 @end example
617
618 GpgAgent returns a list of trusted keys line by line:
619
620 @example
621     S: D 000000001234454556565656677878AF2F1ECCFF P
622     S: D 340387563485634856435645634856438576457A P
623     S: D FEDC6532453745367FD83474357495743757435D S
624     S: OK
625 @end example
626
627 The first item on a line is the hexified fingerprint where MD5
628 ingerprints are @code{00} padded to the left and the second item is a
629 flag to indicate the type of key (so that gpg is able to only take care
630 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
631 of the line, so that we can extend the format in the future.
632
633 Finally a client should be able to mark a key as trusted:
634
635 @example
636    MARKTRUSTED @var{fingerprint} "P"|"S"
637 @end example
638
639 The server will then pop up a window to ask the user whether she
640 really trusts this key. For this it will probably ask for a text to
641 be displayed like this:
642
643 @example
644    S: INQUIRE TRUSTDESC
645    C: D Do you trust the key with the fingerprint @@FPR@@
646    C: D bla fasel blurb.
647    C: END
648    S: OK
649 @end example
650
651 Known sequences with the pattern @@foo@@ are replaced according to this
652 table:
653
654 @table @code
655 @item @@FPR16@@ 
656 Format the fingerprint according to gpg rules for a v3 keys.
657 @item @@FPR20@@ 
658 Format the fingerprint according to gpg rules for a v4 keys.
659 @item @@FPR@@
660 Choose an appropriate format to format the fingerprint.
661 @item @@@@ 
662 Replaced by a single @code{@@}
663 @end table
664
665 @node Agent GET_PASSPHRASE
666 @subsection Ask for a passphrase
667
668 This function is usually used to ask for a passphrase to be used for
669 conventional encryption, but may also be used by programs which need
670 special handling of passphrases.  This command uses a syntax which helps
671 clients to use the agent with minimum effort.
672
673 @example
674   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
675 @end example
676
677 @var{cache_id} is expected to be a hex string used for caching a
678 passphrase.  Use a @code{X} to bypass the cache.  With no other
679 arguments the agent returns a cached passphrase or an error.
680   
681 @var{error_message} is either a single @code{X} for no error message or
682 a string to be shown as an error message like (e.g. "invalid
683 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
684
685 @var{prompt} is either a single @code{X} for a default prompt or the
686 text to be shown as the prompt.  Blanks must be percent escaped or
687 replaced by @code{+}.
688
689 @var{description} is a text shown above the entry field.  Blanks must be
690 percent escaped or replaced by @code{+}.
691
692 The agent either returns with an error or with a OK followed by the 
693 hex encoded passphrase.  Note that the length of the strings is
694 implicitly limited by the maximum length of a command.
695
696 @example
697   CLEAR_PASSPHRASE @var{cache_id}
698 @end example
699
700 may be used to invalidate the cache entry for a passphrase.  The
701 function returns with OK even when there is no cached passphrase.
702
703
704 @node Agent GET_CONFIRMATION
705 @subsection Ask for confirmation
706
707 This command may be used to ask for a simple confirmation by
708 presenting a text and 2 bottonts: Okay and Cancel.
709
710 @example
711   GET_CONFIRMATION @var{description}
712 @end example
713
714 @var{description}is displayed along with a Okay and Cancel
715 button. Blanks must be percent escaped or replaced by @code{+}.  A
716 @code{X} may be used to display confirmation dialog with a default
717 text.
718
719 The agent either returns with an error or with a OK.  Note, that the
720 length of @var{description} is implicitly limited by the maximum
721 length of a command.
722
723
724
725 @node Agent HAVEKEY
726 @subsection Check whether a key is available
727
728 This can be used to see whether a secret key is available.  It does
729 not return any information on whether the key is somehow protected.
730
731 @example
732   HAVEKEY @var{keygrip}
733 @end example
734
735 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
736 caller may want to check for other error codes as well.
737
738
739 @node Agent LEARN
740 @subsection Register a smartcard
741
742 @example
743   LEARN [--send]
744 @end example
745
746 This command is used to register a smartcard.  With the --send
747 option given the certificates are send back.
748
749
750 @node Agent PASSWD
751 @subsection Change a Passphrase
752
753 @example
754   PASSWD @var{keygrip}
755 @end example
756
757 This command is used to interactively change the passphrase of the key
758 indentified by the hex string @var{keygrip}.
759
760
761