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