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