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