35dca4780938ba058b24e51c82c1af0ff6cbb932
[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
233 @item --allow-admin
234 @itemx --deny-admin
235 @opindex allow-admin
236 @opindex deny-admin
237 This enables the use of Admin class commands for card applications
238 where this is supported.  Currently we support it for the OpenPGP
239 card.  Deny is the default.  This commands is useful to inhibit
240 accidental access to admin class command which could ultimately lock
241 the card through worng PIN numbers.
242
243 @item --disable-application @var{name}
244 @opindex disable-application
245 This option disables the use of the card application named
246 @var{name}.  This is mainly useful for debugging or if a application
247 with lower priority should be used by default.
248
249 @end table
250
251 All the long options may also be given in the configuration file after
252 stripping off the two leading dashes.
253
254
255 @c man begin CARD APPLICATIONS
256
257 @node Card applications
258 @section Description of card applications
259
260 @command{scdaemon} supports the card applications as described below.
261
262 @menu
263 * OpenPGP Card::          The OpenPGP card application
264 * NKS Card::              The Telesec NetKey card application
265 * DINSIG Card::           The DINSIG card application
266 * PKCS#15 Card::          The PKCS#15 card application
267 @end menu
268
269 @node OpenPGP Card
270 @subsection The OpenPGP card application ``openpgp''
271
272 This application is currently only used by @command{gpg} but may in
273 future also be useful with @command{gpgsm}. 
274
275 The specification for such a card is available at
276 @uref{http://g10code.com/docs/openpgp-card-1.0.pdf}.
277
278 @node NKS Card
279 @subsection The Telesec NetKey card ``nks''
280
281 This is the main application of the Telesec cards as available in
282 Germany.  It is a superset of the German DINSIG card.  The card is
283 used by @command{gpgsm}.
284
285 @node DINSIG Card
286 @subsection The DINSIG card application ``dinsig''
287
288 This is an application as described in the German draft standard
289 @emph{DIN V 66291-1}.  It is intended to be used by cards supporteing
290 the German signature law and its bylaws (SigG and SigV).
291
292 @node PKCS#15 Card
293 @subsection The PKCS#15 card application ``p15''
294
295 This is common fraqmework for smart card applications.  It is used by
296 @command{gpgsm}.
297
298
299
300 @c 
301 @c  Examples
302 @c
303 @node Scdaemon Examples
304 @section Examples
305
306 @c man begin EXAMPLES
307
308 @example
309 $ scdaemon --server -v
310 @end example
311
312 @c man end
313
314 @c 
315 @c  Assuan Protocol
316 @c
317 @node Scdaemon Protocol
318 @section Scdaemon's Assuan Protocol
319
320 The SC-Daemon should be started by the system to provide access to
321 external tokens.  Using Smartcards on a multi-user system does not
322 make much sense expcet for system services, but in this case no
323 regular user accounts are hosted on the machine.
324
325 A client connects to the SC-Daemon by connecting to the socket named
326 @file{/var/run/scdaemon/socket}, configuration information is read from
327 @var{/etc/scdaemon.conf}
328
329 Each connection acts as one session, SC-Daemon takes care of
330 syncronizing access to a token between sessions.
331
332 @menu
333 * Scdaemon SERIALNO::     Return the serial number.
334 * Scdaemon LEARN::        Read all useful information from the card.
335 * Scdaemon READCERT::     Return a certificate.
336 * Scdaemon READKEY::      Return a public key.
337 * Scdaemon PKSIGN::       Signing data with a Smartcard.
338 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
339 * Scdaemon GETATTR::      Read an attribute's value.
340 * Scdaemon SETATTR::      Update an attribute's value.
341 * Scdaemon WRITEKEY::     Write a key to a card.
342 * Scdaemon GENKEY::       Generate a new key on-card.
343 * Scdaemon RANDOM::       Return random bytes generate on-card.
344 * Scdaemon PASSWD::       Change PINs.
345 * Scdaemon CHECKPIN::     Perform a VERIFY operation.
346 @end menu
347
348 @node Scdaemon SERIALNO 
349 @subsection Return the serial number
350
351 This command should be used to check for the presence of a card.  It is
352 special in that it can be used to reset the card.  Most other commands
353 will return an error when a card change has been detected and the use of
354 this function is therefore required.
355
356 Background: We want to keep the client clear of handling card changes
357 between operations; i.e. the client can assume that all operations are
358 done on the same card unless he call this function.
359
360 @example
361   SERIALNO
362 @end example
363
364 Return the serial number of the card using a status reponse like:
365
366 @example
367   S SERIALNO D27600000000000000000000 0
368 @end example
369
370 The trailing 0 should be ignored for now, it is reserved for a future
371 extension.  The serial number is the hex encoded value identified by 
372 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
373
374
375
376 @node Scdaemon LEARN
377 @subsection Read all useful information from the card
378
379 @example
380   LEARN [--force]
381 @end example
382
383 Learn all useful information of the currently inserted card.  When
384 used without the force options, the command might do an INQUIRE
385 like this:
386
387 @example
388       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
389 @end example
390
391 The client should just send an @code{END} if the processing should go on
392 or a @code{CANCEL} to force the function to terminate with a cancel
393 error message.  The response of this command is a list of status lines
394 formatted as this:
395
396 @example
397      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
398 @end example
399
400 If there is no certificate yet stored on the card a single "X" is
401 returned in @var{hexstring_with_keygrip}.
402
403 @node Scdaemon READCERT
404 @subsection Return a certificate
405
406 @example
407  READCERT @var{hexified_certid}
408 @end example
409
410 This function is used to read a certificate identified by
411 @var{hexified_certid} from the card.
412
413
414 @node Scdaemon READKEY
415 @subsection Return a public key
416
417 @example
418 READKEY @var{hexified_certid}
419 @end example
420
421 Return the public key for the given cert or key ID as an standard
422 S-Expression. 
423
424
425
426 @node Scdaemon PKSIGN
427 @subsection Signing data with a Smartcard
428
429 To sign some data the caller should use the command
430
431 @example
432  SETDATA @var{hexstring}
433 @end example
434
435 to tell @command{scdaemon} about the data to be signed.  The data must be given in
436 hex notation.  The actual signing is done using the command
437
438 @example
439   PKSIGN @var{keyid}
440 @end example
441
442 where @var{keyid} is the hexified ID of the key to be used.  The key id
443 may have been retrieved using the command @code{LEARN}.
444
445
446 @node Scdaemon PKDECRYPT
447 @subsection Decrypting data with a Smartcard
448
449 To decrypt some data the caller should use the command
450
451 @example
452  SETDATA @var{hexstring}
453 @end example
454
455 to tell @command{scdaemon} about the data to be decrypted.  The data
456 must be given in hex notation.  The actual decryption is then done
457 using the command
458
459 @example
460   PKDECRYPT @var{keyid}
461 @end example
462
463 where @var{keyid} is the hexified ID of the key to be used.
464
465
466 @node Scdaemon GETATTR
467 @subsection Read an attribute's value.
468
469 TO BE WRITTEN.
470
471 @node Scdaemon SETATTR
472 @subsection Update an attribute's value.
473
474 TO BE WRITTEN.
475
476 @node Scdaemon WRITEKEY
477 @subsection Write a key to a card.
478
479 @example
480   WRITEKEY [--force] @var{keyid}
481 @end example
482
483 This command is used to store a secret key on a a smartcard.  The
484 allowed keyids depend on the currently selected smartcard
485 application. The actual keydata is requested using the inquiry
486 @code{KEYDATA} and need to be provided without any protection.  With
487 @option{--force} set an existing key under this @var{keyid} will get
488 overwritten.  The key data is expected to be the usual canonical encoded
489 S-expression.
490
491 A PIN will be requested in most saes.  This however depends on the
492 actual card application.
493
494
495 @node Scdaemon GENKEY
496 @subsection Generate a new key on-card.
497
498 TO BE WRITTEN.
499
500 @node Scdaemon RANDOM
501 @subsection Return random bytes generate on-card.
502
503 TO BE WRITTEN.
504
505
506 @node Scdaemon PASSWD
507 @subsection Change PINs.
508
509 @example
510    PASSWD [--reset] @var{chvno}
511 @end example
512   
513 Change the PIN or reset the retry counter of the card holder
514 verification vector number @var{chvno}.
515
516
517 @node Scdaemon CHECKPIN
518 @subsection Perform a VERIFY operation.
519
520 @example
521   CHECKPIN @var{idstr}
522 @end example
523
524 Perform a VERIFY operation without doing anything else.  This may be
525 used to initialize a the PIN cache earlier to long lasting
526 operations.  Its use is highly application dependent:
527
528 @table @strong
529 @item OpenPGP
530
531 Perform a simple verify operation for CHV1 and CHV2, so that further
532 operations won't ask for CHV2 and it is possible to do a cheap check on
533 the PIN: If there is something wrong with the PIN entry system, only the
534 regular CHV will get blocked and not the dangerous CHV3.  @var{idstr} is
535 the usual card's serial number in hex notation; an optional fingerprint
536 part will get ignored.
537
538 There is however a special mode if @var{idstr} is suffixed with the
539 literal string @code{[CHV3]}: In this case the Admin PIN is checked if
540 and only if the retry counter is still at 3.
541
542 @end table
543
544