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