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