More man pages.
[gnupg.git] / doc / scdaemon.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 SCDAEMON
6 @chapter Invoking the SCDAEMON
7 @cindex SCDAEMON command options
8 @cindex command options
9 @cindex options, SCDAEMON command
10
11 @manpage scdaemon.1
12 @ifset manverb
13 .B scdaemon
14 .R \- Smartcard daemon for the GnuPG system
15 @end ifset
16
17 @mansect synopsis
18 @ifset manverb
19 .B  scdaemon
20 .RB [ \-\-homedir
21 .IR dir ]
22 .RB [ \-\-options
23 .IR file ]
24 .RI [ options ]  
25 .B  \-\-server 
26 .br
27 .B  scdaemon
28 .RB [ \-\-homedir
29 .IR dir ]
30 .RB [ \-\-options
31 .IR file ]
32 .RI [ options ]  
33 .B  \-\-daemon 
34 .RI [ command_line ]
35 @end ifset
36
37
38 @mansect description
39 The @command{scdaemon} is a daemon to manage smartcards.  It is usually
40 invoked by @command{gpg-agent} and in general not used directly.
41
42 @manpause
43 @xref{Option Index}, for an index to @command{scdaemon}'s commands and
44 options.
45 @mancont
46
47 @menu
48 * Scdaemon Commands::      List of all commands.
49 * Scdaemon Options::       List of all options.
50 * Card applications::      Description of card applications.
51 * Scdaemon Examples::      Some usage examples.
52 * Scdaemon Protocol::      The protocol the daemon uses.
53 @end menu
54
55 @mansect commands
56
57 @node Scdaemon Commands
58 @section Commands
59
60 Commands are not distinguished from options execpt for the fact that
61 only one one command is allowed.
62
63 @table @gnupgtabopt
64 @item --version
65 @opindex version
66 Print the program version and licensing information.  Not that you can
67 abbreviate this command.
68
69 @item --help, -h
70 @opindex help
71 Print a usage message summarizing the most usefule command-line options.
72 Not that you can abbreviate this command.
73
74 @item --dump-options
75 @opindex dump-options
76 Print a list of all available options and commands.  Not that you can
77 abbreviate this command.
78
79 @item --server
80 @opindex server
81 Run in server mode and wait for commands on the @code{stdin}.  This is
82 default mode is to create a socket and listen for commands there.
83
84 @item --multi-server
85 @opindex multi-server
86 Run in server mode and wait for commands on the @code{stdin} as well as
87 on an additional Unix Domain socket.  The server command @code{GETINFO}
88 may be used to get the name of that extra socket.
89
90 @item --daemon
91 @opindex daemon
92 Run the program in the background.  This option is required to prevent
93 it from being accidently running in the background.
94
95 @item --print-atr
96 @opindex print-atr
97 This is mainly a debugging command, used to print the ATR
98 (Answer-To-Reset) of a card and exit immediately. 
99
100 @end table
101
102
103 @mansect options
104
105 @node Scdaemon Options
106 @section Option Summary
107
108 @table @gnupgtabopt
109
110 @item --options @var{file}
111 @opindex options
112 Reads configuration from @var{file} instead of from the default
113 per-user configuration file.  The default configuration file is named
114 @file{scdaemon.conf} and expected in the @file{.gnupg} directory directly
115 below the home directory of the user.
116
117 @item --homedir @var{dir}
118 @opindex homedir
119 Set the name of the home directory to @var{dir}. If his option is not
120 used, the home directory defaults to @file{~/.gnupg}.  It is only
121 recognized when given on the command line.  It also overrides any home
122 directory stated through the environment variable @env{GNUPGHOME} or
123 (on W32 systems) by means on the Registry entry
124 @var{HKCU\Software\GNU\GnuPG:HomeDir}.
125
126 @item -v
127 @item --verbose
128 @opindex v
129 @opindex verbose
130 Outputs additional information while running.
131 You can increase the verbosity by giving several
132 verbose commands to @command{gpgsm}, such as @samp{-vv}.
133
134 @item --debug-level @var{level}
135 @opindex debug-level
136 Select the debug level for investigating problems. @var{level} may be
137 one of:
138
139 @table @code
140 @item none
141 no debugging at all.
142 @item basic  
143 some basic debug messages
144 @item advanced
145 more verbose debug messages
146 @item expert
147 even more detailed messages
148 @item guru
149 all of the debug messages you can get
150 @end table
151
152 How these messages are mapped to the actual debugging flags is not
153 specified and may change with newer releaes of this program. They are
154 however carefully selected to best aid in debugging.
155
156 @quotation Note
157 All debugging options are subject to change and thus should not be used
158 by any application program.  As the name says, they are only used as
159 helpers to debug problems.
160 @end quotation
161
162
163 @item --debug @var{flags}
164 @opindex debug
165 This option is only useful for debugging and the behaviour may change at
166 any time without notice.  FLAGS are bit encoded and may be given in
167 usual C-Syntax. The currently defined bits are:
168
169 @table @code
170 @item 0  (1)
171 command I/O
172 @item 1  (2)  
173 values of big number integers 
174 @item 2  (4)
175 low level crypto operations
176 @item 5  (32)
177 memory allocation
178 @item 6  (64)
179 caching
180 @item 7  (128)
181 show memory statistics.
182 @item 9  (512)
183 write hashed data to files named @code{dbgmd-000*}
184 @item 10 (1024)
185 trace Assuan protocol
186 @item 11 (2048)
187 trace APDU I/O to the card.  This may reveal sensitive data.
188 @end table
189
190 @item --debug-all
191 @opindex debug-all
192 Same as @code{--debug=0xffffffff}
193
194 @item --debug-wait @var{n}
195 @opindex debug-wait
196 When running in server mode, wait @var{n} seconds before entering the
197 actual processing loop and print the pid.  This gives time to attach a
198 debugger.
199
200 @item --debug-ccid-driver
201 @opindex debug-wait
202 Enable debug output from the included CCID driver for smartcards.
203 Using this option twice will also enable some tracing of the T=1
204 protocol.  Note that this option may reveal sensitive data.
205
206 @item --debug-disable-ticker
207 @opindex debug-disable-ticker
208 This option disables all ticker functions like checking for card
209 insertions.
210
211 @item --debug-allow-core-dump
212 @opindex debug-allow-core-dump
213 For security reasons we won't create a core dump when the process
214 aborts.  For debugging purposes it is sometimes better to allow core
215 dump.  This options enables it and also changes the working directory to
216 @file{/tmp} when running in @option{--server} mode.
217
218
219 @item --no-detach
220 @opindex no-detach
221 Don't detach the process from the console.  This is manly usefule for
222 debugging.
223
224 @item --log-file @var{file}
225 @opindex log-file
226 Append all logging output to @var{file}.  This is very helpful in
227 seeing what the agent actually does.
228
229
230 @item --pcsc-driver @var{library}
231 @opindex pcsc-driver
232 Use @var{library} to access the smartcard reader.  The current default
233 is @file{libpcsclite.so}.  Instead of using this option you might also
234 want to install a symbolic link to the default file name
235 (e.g. from @file{libpcsclite.so.1}).
236
237 @item --ctapi-driver @var{library}
238 @opindex ctapi-driver
239 Use @var{library} to access the smartcard reader.  The current default
240 is @file{libtowitoko.so}.  Note that the use of this interface is
241 deprecated; it may be removed in future releases.
242
243 @item --disable-ccid 
244 @opindex disable-ccid
245 Disable the integrated support for CCID compliant readers.  This
246 allows to fall back to one of the other drivers even if the internal
247 CCID driver can handle the reader.  Note, that CCID support is only
248 available if libusb was available at build time.
249
250 @item --reader-port @var{number_or_string}
251 @opindex reader-port
252 This option may be used to specify the port of the card terminal.  A
253 value of 0 refers to the first serial device; add 32768 to access USB
254 devices.  The default is 32768 (first USB device).  PC/SC or CCID
255 readers might need a string here; run the program in verbose mode to get
256 a list of available readers.  The default is then the first reader
257 found.
258
259 @item --disable-keypad
260 @opindex disable-keypad
261 Even if a card reader features a keypad, do not try to use it.
262
263
264 @item --allow-admin
265 @itemx --deny-admin
266 @opindex allow-admin
267 @opindex deny-admin
268 This enables the use of Admin class commands for card applications
269 where this is supported.  Currently we support it for the OpenPGP
270 card.  Deny is the default.  This commands is useful to inhibit
271 accidental access to admin class command which could ultimately lock
272 the card through worng PIN numbers.
273
274 @item --disable-application @var{name}
275 @opindex disable-application
276 This option disables the use of the card application named
277 @var{name}.  This is mainly useful for debugging or if a application
278 with lower priority should be used by default.
279
280 @end table
281
282 All the long options may also be given in the configuration file after
283 stripping off the two leading dashes.
284
285
286 @mansect card applications
287 @node Card applications
288 @section Description of card applications
289
290 @command{scdaemon} supports the card applications as described below.
291
292 @menu
293 * OpenPGP Card::          The OpenPGP card application
294 * NKS Card::              The Telesec NetKey card application
295 * DINSIG Card::           The DINSIG card application
296 * PKCS#15 Card::          The PKCS#15 card application
297 @end menu
298
299 @node OpenPGP Card
300 @subsection The OpenPGP card application ``openpgp''
301
302 This application is currently only used by @command{gpg} but may in
303 future also be useful with @command{gpgsm}. 
304
305 The specification for such a card is available at
306 @uref{http://g10code.com/docs/openpgp-card-1.0.pdf}.
307
308 @node NKS Card
309 @subsection The Telesec NetKey card ``nks''
310
311 This is the main application of the Telesec cards as available in
312 Germany.  It is a superset of the German DINSIG card.  The card is
313 used by @command{gpgsm}.
314
315 @node DINSIG Card
316 @subsection The DINSIG card application ``dinsig''
317
318 This is an application as described in the German draft standard
319 @emph{DIN V 66291-1}.  It is intended to be used by cards supporteing
320 the German signature law and its bylaws (SigG and SigV).
321
322 @node PKCS#15 Card
323 @subsection The PKCS#15 card application ``p15''
324
325 This is common fraqmework for smart card applications.  It is used by
326 @command{gpgsm}.
327
328
329
330 @c 
331 @c  Examples
332 @c
333 @mansect examples
334 @node Scdaemon Examples
335 @section Examples
336
337 @c man begin EXAMPLES
338
339 @example
340 $ scdaemon --server -v
341 @end example
342
343 @c man end
344
345 @c 
346 @c  Assuan Protocol
347 @c
348 @mansect assuan
349 @node Scdaemon Protocol
350 @section Scdaemon's Assuan Protocol
351
352 The SC-Daemon should be started by the system to provide access to
353 external tokens.  Using Smartcards on a multi-user system does not
354 make much sense expcet for system services, but in this case no
355 regular user accounts are hosted on the machine.
356
357 A client connects to the SC-Daemon by connecting to the socket named
358 @file{/var/run/scdaemon/socket}, configuration information is read from
359 @var{/etc/scdaemon.conf}
360
361 Each connection acts as one session, SC-Daemon takes care of
362 syncronizing access to a token between sessions.
363
364 @menu
365 * Scdaemon SERIALNO::     Return the serial number.
366 * Scdaemon LEARN::        Read all useful information from the card.
367 * Scdaemon READCERT::     Return a certificate.
368 * Scdaemon READKEY::      Return a public key.
369 * Scdaemon PKSIGN::       Signing data with a Smartcard.
370 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
371 * Scdaemon GETATTR::      Read an attribute's value.
372 * Scdaemon SETATTR::      Update an attribute's value.
373 * Scdaemon WRITEKEY::     Write a key to a card.
374 * Scdaemon GENKEY::       Generate a new key on-card.
375 * Scdaemon RANDOM::       Return random bytes generate on-card.
376 * Scdaemon PASSWD::       Change PINs.
377 * Scdaemon CHECKPIN::     Perform a VERIFY operation.
378 * Scdaemon RESTART::      Restart connection
379 * Scdaemon APDU::         Send a verbatim APDU to the card
380 @end menu
381
382 @node Scdaemon SERIALNO 
383 @subsection Return the serial number
384
385 This command should be used to check for the presence of a card.  It is
386 special in that it can be used to reset the card.  Most other commands
387 will return an error when a card change has been detected and the use of
388 this function is therefore required.
389
390 Background: We want to keep the client clear of handling card changes
391 between operations; i.e. the client can assume that all operations are
392 done on the same card unless he call this function.
393
394 @example
395   SERIALNO
396 @end example
397
398 Return the serial number of the card using a status reponse like:
399
400 @example
401   S SERIALNO D27600000000000000000000 0
402 @end example
403
404 The trailing 0 should be ignored for now, it is reserved for a future
405 extension.  The serial number is the hex encoded value identified by 
406 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
407
408
409
410 @node Scdaemon LEARN
411 @subsection Read all useful information from the card
412
413 @example
414   LEARN [--force]
415 @end example
416
417 Learn all useful information of the currently inserted card.  When
418 used without the force options, the command might do an INQUIRE
419 like this:
420
421 @example
422       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
423 @end example
424
425 The client should just send an @code{END} if the processing should go on
426 or a @code{CANCEL} to force the function to terminate with a cancel
427 error message.  The response of this command is a list of status lines
428 formatted as this:
429
430 @example
431      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
432 @end example
433
434 If there is no certificate yet stored on the card a single "X" is
435 returned in @var{hexstring_with_keygrip}.
436
437 @node Scdaemon READCERT
438 @subsection Return a certificate
439
440 @example
441  READCERT @var{hexified_certid}
442 @end example
443
444 This function is used to read a certificate identified by
445 @var{hexified_certid} from the card.
446
447
448 @node Scdaemon READKEY
449 @subsection Return a public key
450
451 @example
452 READKEY @var{hexified_certid}
453 @end example
454
455 Return the public key for the given cert or key ID as an standard
456 S-Expression. 
457
458
459
460 @node Scdaemon PKSIGN
461 @subsection Signing data with a Smartcard
462
463 To sign some data the caller should use the command
464
465 @example
466  SETDATA @var{hexstring}
467 @end example
468
469 to tell @command{scdaemon} about the data to be signed.  The data must be given in
470 hex notation.  The actual signing is done using the command
471
472 @example
473   PKSIGN @var{keyid}
474 @end example
475
476 where @var{keyid} is the hexified ID of the key to be used.  The key id
477 may have been retrieved using the command @code{LEARN}.  If another
478 hash algorithm than SHA-1 is used, that algorithm may be given like:
479
480 @example
481   PKSIGN --hash=@var{algoname} @var{keyid}
482 @end example
483
484 With @var{algoname} are one of @code{sha1}, @code{rmd160} or @code{md5}.
485
486
487 @node Scdaemon PKDECRYPT
488 @subsection Decrypting data with a Smartcard
489
490 To decrypt some data the caller should use the command
491
492 @example
493  SETDATA @var{hexstring}
494 @end example
495
496 to tell @command{scdaemon} about the data to be decrypted.  The data
497 must be given in hex notation.  The actual decryption is then done
498 using the command
499
500 @example
501   PKDECRYPT @var{keyid}
502 @end example
503
504 where @var{keyid} is the hexified ID of the key to be used.
505
506
507 @node Scdaemon GETATTR
508 @subsection Read an attribute's value.
509
510 TO BE WRITTEN.
511
512 @node Scdaemon SETATTR
513 @subsection Update an attribute's value.
514
515 TO BE WRITTEN.
516
517 @node Scdaemon WRITEKEY
518 @subsection Write a key to a card.
519
520 @example
521   WRITEKEY [--force] @var{keyid}
522 @end example
523
524 This command is used to store a secret key on a a smartcard.  The
525 allowed keyids depend on the currently selected smartcard
526 application. The actual keydata is requested using the inquiry
527 @code{KEYDATA} and need to be provided without any protection.  With
528 @option{--force} set an existing key under this @var{keyid} will get
529 overwritten.  The key data is expected to be the usual canonical encoded
530 S-expression.
531
532 A PIN will be requested in most saes.  This however depends on the
533 actual card application.
534
535
536 @node Scdaemon GENKEY
537 @subsection Generate a new key on-card.
538
539 TO BE WRITTEN.
540
541 @node Scdaemon RANDOM
542 @subsection Return random bytes generate on-card.
543
544 TO BE WRITTEN.
545
546
547 @node Scdaemon PASSWD
548 @subsection Change PINs.
549
550 @example
551    PASSWD [--reset] @var{chvno}
552 @end example
553   
554 Change the PIN or reset the retry counter of the card holder
555 verification vector number @var{chvno}.
556
557
558 @node Scdaemon CHECKPIN
559 @subsection Perform a VERIFY operation.
560
561 @example
562   CHECKPIN @var{idstr}
563 @end example
564
565 Perform a VERIFY operation without doing anything else.  This may be
566 used to initialize a the PIN cache earlier to long lasting
567 operations.  Its use is highly application dependent:
568
569 @table @strong
570 @item OpenPGP
571
572 Perform a simple verify operation for CHV1 and CHV2, so that further
573 operations won't ask for CHV2 and it is possible to do a cheap check on
574 the PIN: If there is something wrong with the PIN entry system, only the
575 regular CHV will get blocked and not the dangerous CHV3.  @var{idstr} is
576 the usual card's serial number in hex notation; an optional fingerprint
577 part will get ignored.
578
579 There is however a special mode if @var{idstr} is suffixed with the
580 literal string @code{[CHV3]}: In this case the Admin PIN is checked if
581 and only if the retry counter is still at 3.
582
583 @end table
584
585
586
587 @node Scdaemon RESTART
588 @subsection Perform a RESTART operation.
589
590 @example
591   RESTART
592 @end example
593
594 Restart the current connection; this is a kind of warm reset.  It
595 deletes the context used by this connection but does not actually
596 reset the card. 
597
598 This is used by gpg-agent to reuse a primary pipe connection and
599 may be used by clients to backup from a conflict in the serial
600 command; i.e. to select another application. 
601
602
603
604
605 @node Scdaemon APDU
606 @subsection Send a verbatim APDU to the card.
607
608 @example
609   APDU [--atr] [--more] [@var{hexstring}]
610 @end example
611
612
613 Send an APDU to the current reader.  This command bypasses the high
614 level functions and sends the data directly to the card.
615 @var{hexstring} is expected to be a proper APDU.  If @var{hexstring} is
616 not given no commands are send to the card; However the command will
617 implictly check whether the card is ready for use.
618
619 Using the option @code{--atr} returns the ATR of the card as a status
620 message before any data like this:
621 @example
622      S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1
623 @end example
624
625 Using the option @code{--more} handles the card status word MORE_DATA
626 (61xx) and concatenate all reponses to one block.
627
628
629