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