Taken from NewPG
[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 HAVEKEY::         Check whether a key is available
358 * Agent LEARN::           Register a smartcard
359 * Agent PASSWD::          Change a Passphrase
360 @end menu
361
362 @node Agent PKDECRYPT
363 @subsection Decrypting a session key
364
365 The client asks the server to decrypt a session key.  The encrypted
366 session key should have all information needed to select the
367 appropriate secret key or to delegate it to a smartcard.
368
369 @example
370   SETKEY <keyGrip>
371 @end example
372
373 Tell the server about the key to be used for decryption.  If this is
374 not used, gpg-agent may try to figure out the key by trying to
375 decrypt the message with each key available.
376
377 @example
378   PKDECRYPT
379 @end example
380
381 The agent checks whether this command is allowed and then does an
382 INQUIRY to get the ciphertext the client should then send the cipher
383 text.
384
385 @example
386     S: INQUIRE CIPHERTEXT
387     C: D (xxxxxx
388     C: D xxxx)
389     C: END
390 @end example
391     
392 Please note that the server may send status info lines while reading the
393 data lines from the client.  The data send is a SPKI like S-Exp with
394 this structure:
395
396 @example
397      (enc-val   
398        (<algo>
399          (<param_name1> <mpi>)
400            ...
401          (<param_namen> <mpi>)))
402 @end example
403
404 Where algo is a string with the name of the algorithm; see the libgcrypt
405 documentation for a list of valid algorithms.  The number and names of
406 the parameters depend on the algorithm.  The agent does return an error
407 if there is an inconsistency.
408
409 If the decryption was successful the decrypted data is returned by
410 means of "D" lines. 
411
412 Here is an example session:
413
414 @example
415    C: PKDECRYPT
416    S: INQUIRE CIPHERTEXT
417    C: D (enc-val elg (a 349324324) 
418    C: D    (b 3F444677CA)))
419    C: END
420    S: # session key follows
421    S: D 1234567890ABCDEF0
422    S: OK descryption successful
423 @end example         
424
425
426 @node Agent PKSIGN
427 @subsection Signing a Hash
428
429 The client ask the agent to sign a given hash value.  A default key
430 will be chosen if no key has been set.  To set a key a client first
431 uses:
432
433 @example
434    SIGKEY <keyGrip>
435 @end example
436
437 This can be used multiple times to create multiple signature, the list
438 of keys is reset with the next PKSIGN command or a RESET.  The server
439 test whether the key is a valid key to sign something and responds with
440 okay.
441
442 @example
443    SETHASH <hexstring>
444 @end example
445
446 The client can use this command to tell the server about the data
447 (which usually is a hash) to be signed.  
448
449 The actual signing is done using
450
451 @example
452    PKSIGN <options>
453 @end example
454
455 Options are not yet defined, but my later be used to choosen among
456 different algorithms (e.g. pkcs 1.5)
457
458 The agent does then some checks, asks for the passphrase and
459 if SETHASH has not been used asks the client for the data to sign:
460
461 @example
462    S: INQUIRE HASHVAL
463    C: D ABCDEF012345678901234
464    C: END
465 @end example
466
467 As a result the server returns the signature as an SPKI like S-Exp
468 in "D" lines:
469
470 @example  
471      (sig-val   
472        (<algo>
473          (<param_name1> <mpi>)
474            ...
475          (<param_namen> <mpi>)))
476 @end example
477
478
479 The operation is affected by the option
480
481 @example
482    OPTION use-cache-for-signing=0|1
483 @end example
484
485 The default of @code{1} uses the cache.  Setting this option to @code{0}
486 will lead gpg-agent to ignore the passphrase cache.  Note, that there is
487 also a global command line option for gpg-agent to globally disable the
488 caching.
489
490
491 Here is an example session:
492
493 @example
494    C: SIGKEY <keyGrip>
495    S: OK key available
496    C: SIGKEY <keyGrip>
497    S: OK key available
498    C: PKSIGN
499    S: # I did ask the user whether he really wants to sign
500    S: # I did ask the user for the passphrase
501    S: INQUIRE HASHVAL
502    C: D ABCDEF012345678901234
503    C: END
504    S: # signature follows
505    S: D (sig-val rsa (s 45435453654612121212))
506    S: OK
507 @end example
508
509
510 @node Agent GENKEY
511 @subsection Generating a Key
512
513 This is used to create a new keypair and store the secret key inside the
514 active PSE -w which is in most cases a Soft-PSE.  An not yet defined
515 option allows to choose the storage location.  To get the secret key out
516 of the PSE, a special export tool has to be used.
517
518 @example
519    GENKEY 
520 @end example
521
522 Invokes the key generation process and the server will then inquire
523 on the generation parameters, like:
524
525 @example
526    S: INQUIRE KEYPARM
527    C: D (genkey (rsa (nbits  1024)))
528    C: END
529 @end example
530
531 The format of the key parameters which depends on the algorithm is of
532 the form:
533
534 @example
535     (genkey
536       (algo
537         (parameter_name_1 ....)
538           ....
539         (parameter_name_n ....)))
540 @end example
541
542 If everything succeeds, the server returns the *public key* in a SPKI
543 like S-Expression like this:
544
545 @example
546      (public-key
547        (rsa
548          (n <mpi>)
549          (e <mpi>)))
550 @end example
551
552 Here is an example session:
553
554 @example
555    C: GENKEY
556    S: INQUIRE KEYPARM
557    C: D (genkey (rsa (nbits  1024)))
558    C: END
559    S: D (public-key
560    S: D   (rsa (n 326487324683264) (e 10001)))
561    S  OK key created
562 @end example
563
564 @node Agent IMPORT
565 @subsection Importing a Secret Key
566
567 This operation is not yet supportted by GpgAgent.  Specialized tools
568 are to be used for this.
569
570 There is no actual need because we can expect that secret keys
571 created by a 3rd party are stored on a smartcard.  If we have
572 generated the key ourself, we do not need to import it.
573
574 @node Agent EXPORT
575 @subsection Export a Secret Key
576
577 Not implemented.
578
579 Should be done by an extra tool.
580
581 @node Agent ISTRUSTED
582 @subsection Importing a Root Certificate
583
584 Actually we do not import a Root Cert but provide a way to validate
585 any piece of data by storing its Hash along with a description and
586 an identifier in the PSE.  Here is the interface desription:
587
588 @example
589     ISTRUSTED <fingerprint>
590 @end example
591
592 Check whether the OpenPGP primary key or the X.509 certificate with the
593 given fingerprint is an ultimately trusted key or a trusted Root CA
594 certificate.  The fingerprint should be given as a hexstring (without
595 any blanks or colons or whatever in between) and may be left padded with
596 00 in case of an MD5 fingerprint.  GPGAgent will answer with:
597
598 @example
599     OK
600 @end example
601
602 The key is in the table of trusted keys.
603
604 @example
605     ERR 304 (Not Trusted)
606 @end example
607
608 The key is not in this table.
609
610 Gpg needs the entire list of trusted keys to maintain the web of
611 trust; the following command is therefore quite helpful:
612
613 @example
614     LISTTRUSTED
615 @end example
616
617 GpgAgent returns a list of trusted keys line by line:
618
619 @example
620     S: D 000000001234454556565656677878AF2F1ECCFF P
621     S: D 340387563485634856435645634856438576457A P
622     S: D FEDC6532453745367FD83474357495743757435D S
623     S: OK
624 @end example
625
626 The first item on a line is the hexified fingerprint where MD5
627 ingerprints are @code{00} padded to the left and the second item is a
628 flag to indicate the type of key (so that gpg is able to only take care
629 of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
630 of the line, so that we can extend the format in the future.
631
632 Finally a client should be able to mark a key as trusted:
633
634 @example
635    MARKTRUSTED @var{fingerprint} "P"|"S"
636 @end example
637
638 The server will then pop up a window to ask the user whether she
639 really trusts this key. For this it will probably ask for a text to
640 be displayed like this:
641
642 @example
643    S: INQUIRE TRUSTDESC
644    C: D Do you trust the key with the fingerprint @@FPR@@
645    C: D bla fasel blurb.
646    C: END
647    S: OK
648 @end example
649
650 Known sequences with the pattern @@foo@@ are replaced according to this
651 table:
652
653 @table @code
654 @item @@FPR16@@ 
655 Format the fingerprint according to gpg rules for a v3 keys.
656 @item @@FPR20@@ 
657 Format the fingerprint according to gpg rules for a v4 keys.
658 @item @@FPR@@
659 Choose an appropriate format to format the fingerprint.
660 @item @@@@ 
661 Replaced by a single @code{@@}
662 @end table
663
664 @node Agent GET_PASSPHRASE
665 @subsection Ask for a passphrase
666
667 This function is usually used to ask for a passphrase to be used for
668 conventional encryption, but may also be used by programs which need
669 special handling of passphrases.  This command uses a syntax which helps
670 clients to use the agent with minimum effort.
671
672 @example
673   GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
674 @end example
675
676 @var{cache_id} is expected to be a hex string used for caching a
677 passphrase.  Use a @code{X} to bypass the cache.  With no other
678 arguments the agent returns a cached passphrase or an error.
679   
680 @var{error_message} is either a single @code{X} for no error message or
681 a string to be shown as an error message like (e.g. "invalid
682 passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
683
684 @var{prompt} is either a single @code{X} for a default prompt or the
685 text to be shown as the prompt.  Blanks must be percent escaped or
686 replaced by @code{+}.
687
688 @var{description} is a text shown above the entry field.  Blanks must be
689 percent escaped or replaced by @code{+}.
690
691 The agent either returns with an error or with a OK followed by the 
692 hex encoded passphrase.  Note that the length of the strings is
693 implicitly limited by the maximum length of a command.
694
695 @example
696   CLEAR_PASSPHRASE @var{cache_id}
697 @end example
698
699 may be used to invalidate the cache entry for a passphrase.  The
700 function returns with OK even when there is no cached passphrase.
701
702
703 @node Agent HAVEKEY
704 @subsection Check whether a key is available
705
706 This can be used to see whether a secret key is available.  It does
707 not return any information on whether the key is somehow protected.
708
709 @example
710   HAVEKEY @var{keygrip}
711 @end example
712
713 The Agent answers either with OK or @code{No_Secret_Key} (208).  The
714 caller may want to check for other error codes as well.
715
716
717 @node Agent LEARN
718 @subsection Register a smartcard
719
720 @example
721   LEARN [--send]
722 @end example
723
724 This command is used to register a smartcard.  With the --send
725 option given the certificates are send back.
726
727
728 @node Agent PASSWD
729 @subsection Change a Passphrase
730
731 @example
732   PASSWD @var{keygrip}
733 @end example
734
735 This command is used to interactively change the passphrase of the key
736 indentified by the hex string @var{keygrip}.
737
738
739