24a22355e04b50d796f1b1dd3c688953d2a82361
[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 @end menu
351
352 @node Scdaemon SERIALNO 
353 @subsection Return the serial number
354
355 This command should be used to check for the presence of a card.  It is
356 special in that it can be used to reset the card.  Most other commands
357 will return an error when a card change has been detected and the use of
358 this function is therefore required.
359
360 Background: We want to keep the client clear of handling card changes
361 between operations; i.e. the client can assume that all operations are
362 done on the same card unless he call this function.
363
364 @example
365   SERIALNO
366 @end example
367
368 Return the serial number of the card using a status reponse like:
369
370 @example
371   S SERIALNO D27600000000000000000000 0
372 @end example
373
374 The trailing 0 should be ignored for now, it is reserved for a future
375 extension.  The serial number is the hex encoded value identified by 
376 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
377
378
379
380 @node Scdaemon LEARN
381 @subsection Read all useful information from the card
382
383 @example
384   LEARN [--force]
385 @end example
386
387 Learn all useful information of the currently inserted card.  When
388 used without the force options, the command might do an INQUIRE
389 like this:
390
391 @example
392       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
393 @end example
394
395 The client should just send an @code{END} if the processing should go on
396 or a @code{CANCEL} to force the function to terminate with a cancel
397 error message.  The response of this command is a list of status lines
398 formatted as this:
399
400 @example
401      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
402 @end example
403
404 If there is no certificate yet stored on the card a single "X" is
405 returned in @var{hexstring_with_keygrip}.
406
407 @node Scdaemon READCERT
408 @subsection Return a certificate
409
410 @example
411  READCERT @var{hexified_certid}
412 @end example
413
414 This function is used to read a certificate identified by
415 @var{hexified_certid} from the card.
416
417
418 @node Scdaemon READKEY
419 @subsection Return a public key
420
421 @example
422 READKEY @var{hexified_certid}
423 @end example
424
425 Return the public key for the given cert or key ID as an standard
426 S-Expression. 
427
428
429
430 @node Scdaemon PKSIGN
431 @subsection Signing data with a Smartcard
432
433 To sign some data the caller should use the command
434
435 @example
436  SETDATA @var{hexstring}
437 @end example
438
439 to tell @command{scdaemon} about the data to be signed.  The data must be given in
440 hex notation.  The actual signing is done using the command
441
442 @example
443   PKSIGN @var{keyid}
444 @end example
445
446 where @var{keyid} is the hexified ID of the key to be used.  The key id
447 may have been retrieved using the command @code{LEARN}.  If another
448 hash algorithm than SHA-1 is used, that algorithm may be given like:
449
450 @example
451   PKSIGN --hash=@var{algoname} @var{keyid}
452 @end example
453
454 With @var{algoname} are one of @code{sha1}, @code{rmd160} or @code{md5}.
455
456
457 @node Scdaemon PKDECRYPT
458 @subsection Decrypting data with a Smartcard
459
460 To decrypt some data the caller should use the command
461
462 @example
463  SETDATA @var{hexstring}
464 @end example
465
466 to tell @command{scdaemon} about the data to be decrypted.  The data
467 must be given in hex notation.  The actual decryption is then done
468 using the command
469
470 @example
471   PKDECRYPT @var{keyid}
472 @end example
473
474 where @var{keyid} is the hexified ID of the key to be used.
475
476
477 @node Scdaemon GETATTR
478 @subsection Read an attribute's value.
479
480 TO BE WRITTEN.
481
482 @node Scdaemon SETATTR
483 @subsection Update an attribute's value.
484
485 TO BE WRITTEN.
486
487 @node Scdaemon WRITEKEY
488 @subsection Write a key to a card.
489
490 @example
491   WRITEKEY [--force] @var{keyid}
492 @end example
493
494 This command is used to store a secret key on a a smartcard.  The
495 allowed keyids depend on the currently selected smartcard
496 application. The actual keydata is requested using the inquiry
497 @code{KEYDATA} and need to be provided without any protection.  With
498 @option{--force} set an existing key under this @var{keyid} will get
499 overwritten.  The key data is expected to be the usual canonical encoded
500 S-expression.
501
502 A PIN will be requested in most saes.  This however depends on the
503 actual card application.
504
505
506 @node Scdaemon GENKEY
507 @subsection Generate a new key on-card.
508
509 TO BE WRITTEN.
510
511 @node Scdaemon RANDOM
512 @subsection Return random bytes generate on-card.
513
514 TO BE WRITTEN.
515
516
517 @node Scdaemon PASSWD
518 @subsection Change PINs.
519
520 @example
521    PASSWD [--reset] @var{chvno}
522 @end example
523   
524 Change the PIN or reset the retry counter of the card holder
525 verification vector number @var{chvno}.
526
527
528 @node Scdaemon CHECKPIN
529 @subsection Perform a VERIFY operation.
530
531 @example
532   CHECKPIN @var{idstr}
533 @end example
534
535 Perform a VERIFY operation without doing anything else.  This may be
536 used to initialize a the PIN cache earlier to long lasting
537 operations.  Its use is highly application dependent:
538
539 @table @strong
540 @item OpenPGP
541
542 Perform a simple verify operation for CHV1 and CHV2, so that further
543 operations won't ask for CHV2 and it is possible to do a cheap check on
544 the PIN: If there is something wrong with the PIN entry system, only the
545 regular CHV will get blocked and not the dangerous CHV3.  @var{idstr} is
546 the usual card's serial number in hex notation; an optional fingerprint
547 part will get ignored.
548
549 There is however a special mode if @var{idstr} is suffixed with the
550 literal string @code{[CHV3]}: In this case the Admin PIN is checked if
551 and only if the retry counter is still at 3.
552
553 @end table
554
555