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