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