Changed the scdaemon to handle concurrent sessions. Adjusted
[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 --daemon
58 @opindex daemon
59 Run the program in the background.  This option is required to prevent
60 it from being accidently running in the background.
61
62 @item --print-atr
63 @opindex print-atr
64 This is mainly a debugging command, used to print the ATR
65 (Answer-To-Reset) of a card and exit immediately. 
66
67 @end table
68
69
70 @c man begin OPTIONS
71
72 @node Scdaemon Options
73 @section Option Summary
74
75 @table @gnupgtabopt
76
77 @item --options @var{file}
78 @opindex options
79 Reads configuration from @var{file} instead of from the default
80 per-user configuration file.  The default configuration file is named
81 @file{scdaemon.conf} and expected in the @file{.gnupg} directory directly
82 below the home directory of the user.
83
84 @item --homedir @var{dir}
85 @opindex homedir
86 Set the name of the home directory to @var{dir}. If his option is not
87 used, the home directory defaults to @file{~/.gnupg}.  It is only
88 recognized when given on the command line.  It also overrides any home
89 directory stated through the environment variable @env{GNUPGHOME} or
90 (on W32 systems) by means on the Registry entry
91 @var{HKCU\Software\GNU\GnuPG:HomeDir}.
92
93 @item -v
94 @item --verbose
95 @opindex v
96 @opindex verbose
97 Outputs additional information while running.
98 You can increase the verbosity by giving several
99 verbose commands to @command{gpgsm}, such as @samp{-vv}.
100
101 @item --debug-level @var{level}
102 @opindex debug-level
103 Select the debug level for investigating problems. @var{level} may be
104 one of:
105
106    @table @code
107    @item none
108    no debugging at all.
109    @item basic  
110    some basic debug messages
111    @item advanced
112    more verbose debug messages
113    @item expert
114    even more detailed messages
115    @item guru
116    all of the debug messages you can get
117    @end table
118
119 How these messages are mapped to the actual debugging flags is not
120 specified and may change with newer releaes of this program. They are
121 however carefully selected to best aid in debugging.
122
123 @item --debug @var{flags}
124 @opindex debug
125 This option is only useful for debugging and the behaviour may change at
126 any time without notice.  FLAGS are bit encoded and may be given in
127 usual C-Syntax. The currently defined bits are:
128
129    @table @code
130    @item 0  (1)
131    X.509 or OpenPGP protocol related data
132    @item 1  (2)  
133    values of big number integers 
134    @item 2  (4)
135    low level crypto operations
136    @item 5  (32)
137    memory allocation
138    @item 6  (64)
139    caching
140    @item 7  (128)
141    show memory statistics.
142    @item 9  (512)
143    write hashed data to files named @code{dbgmd-000*}
144    @item 10 (1024)
145    trace Assuan protocol
146    @item 12 (4096)
147    bypass all certificate validation
148    @end table
149
150 @item --debug-all
151 @opindex debug-all
152 Same as @code{--debug=0xffffffff}
153
154 @item --debug-wait @var{n}
155 @opindex debug-wait
156 When running in server mode, wait @var{n} seconds before entering the
157 actual processing loop and print the pid.  This gives time to attach a
158 debugger.
159
160 @item --no-detach
161 @opindex no-detach
162 Don't detach the process from the console.  This is manly usefule for
163 debugging.
164
165 @item --log-file @var{file}
166 @opindex log-file
167 Append all logging output to @var{file}.  This is very helpful in
168 seeing what the agent actually does.
169
170 @item --reader-port @var{number}
171 This option may be used to specify the port of the card terminal.  A
172 value of 0 refers to the first serial device; add 32768 to access USB
173 devices.  The default is 32768 (first USB device).
174
175 @item --ctapi-driver @var{library}
176 Use @var{library} to access the smartcard reader.  The current default
177 is @code{libtowitoko.so}.  Note that the use of this interface is
178 deprecated; it may be removed in future releases.
179
180
181 @item --allow-admin
182 @itemx --deny-admin
183 @opindex allow-admin
184 @opindex deny-admin
185 This enables the use of Admin class commands for card applications
186 where this is supported.  Currently we support it for the OpenPGP
187 card.  Deny is the default.  This commands is useful to inhibit
188 accidental access to admin class command which could ultimately lock
189 the card through worng PIN numbers.
190
191 @item --disable-application @var{name}
192 @opindex disable-application
193 This option disables the use of the card application named
194 @var{name}.  This is mainly useful for debugging or if a application
195 with lower priority should be used by default.
196
197 @end table
198
199 All the long options may also be given in the configuration file after
200 stripping off the two leading dashes.
201
202
203 @c man begin CARD APPLICATIONS
204
205 @node Card applications
206 @section Description of card applications
207
208 @command{scdaemon} supports the card applications as described below.
209
210 @menu
211 * OpenPGP Card::          The OpenPGP card application
212 * NKS Card::              The Telesec NetKey card application
213 * DINSIG Card::           The DINSIG card application
214 * PKCS#15 Card::          The PKCS#15 card application
215 @end menu
216
217 @node OpenPGP Card
218 @subsection The OpenPGP card application ``openpgp''
219
220 This application is currently only used by @command{gpg} but may in
221 future also be useful with @command{gpgsm}. 
222
223 The specification for such a card is available at
224 @uref{http://g10code.com/docs/openpgp-card-1.0.pdf}.
225
226 @node NKS Card
227 @subsection The Telesec NetKey card ``nks''
228
229 This is the main application of the Telesec cards as available in
230 Germany.  It is a superset of the German DINSIG card.  The card is
231 used by @command{gpgsm}.
232
233 @node DINSIG Card
234 @subsection The DINSIG card application ``dinsig''
235
236 This is an application as described in the German draft standard
237 @emph{DIN V 66291-1}.  It is intended to be used by cards supporteing
238 the German signature law and its bylaws (SigG and SigV).
239
240 @node PKCS#15 Card
241 @subsection The PKCS#15 card application ``p15''
242
243 This is common fraqmework for smart card applications.  It is used by
244 @command{gpgsm}.
245
246
247
248 @c 
249 @c  Examples
250 @c
251 @node Scdaemon Examples
252 @section Examples
253
254 @c man begin EXAMPLES
255
256 @example
257 $ scdaemon --server -v
258 @end example
259
260 @c man end
261
262 @c 
263 @c  Assuan Protocol
264 @c
265 @node Scdaemon Protocol
266 @section Scdaemon's Assuan Protocol
267
268 The SC-Daemon should be started by the system to provide access to
269 external tokens.  Using Smartcards on a multi-user system does not
270 make much sense expcet for system services, but in this case no
271 regular user accounts are hosted on the machine.
272
273 A client connects to the SC-Daemon by connecting to the socket named
274 @file{/var/run/scdaemon/socket}, configuration information is read from
275 @var{/etc/scdaemon.conf}
276
277 Each connection acts as one session, SC-Daemon takes care of
278 syncronizing access to a token between sessions.
279
280 @menu
281 * Scdaemon SERIALNO::     Return the serial number.
282 * Scdaemon LEARN::        Read all useful information from the card.
283 * Scdaemon READCERT::     Return a certificate.
284 * Scdaemon READKEY::      Return a public key.
285 * Scdaemon PKSIGN::       Signing data with a Smartcard.
286 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
287 * Scdaemon GETATTR::      Read an attribute's value.
288 * Scdaemon SETATTR::      Update an attribute's value.
289 * Scdaemon GENKEY::       Generate a new key on-card.
290 * Scdaemon RANDOM::       Return random bytes generate on-card.
291 * Scdaemon PASSWD::       Change PINs.
292 * Scdaemon CHECKPIN::     Perform a VERIFY operation.
293 @end menu
294
295 @node Scdaemon SERIALNO 
296 @subsection Return the serial number
297
298 This command should be used to check for the presence of a card.  It is
299 special in that it can be used to reset the card.  Most other commands
300 will return an error when a card change has been detected and the use of
301 this function is therefore required.
302
303 Background: We want to keep the client clear of handling card changes
304 between operations; i.e. the client can assume that all operations are
305 done on the same card unless he call this function.
306
307 @example
308   SERIALNO
309 @end example
310
311 Return the serial number of the card using a status reponse like:
312
313 @example
314   S SERIALNO D27600000000000000000000 0
315 @end example
316
317 The trailing 0 should be ignored for now, it is reserved for a future
318 extension.  The serial number is the hex encoded value identified by 
319 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
320
321
322
323 @node Scdaemon LEARN
324 @subsection Read all useful information from the card
325
326 @example
327   LEARN [--force]
328 @end example
329
330 Learn all useful information of the currently inserted card.  When
331 used without the force options, the command might do an INQUIRE
332 like this:
333
334 @example
335       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
336 @end example
337
338 The client should just send an @code{END} if the processing should go on
339 or a @code{CANCEL} to force the function to terminate with a cancel
340 error message.  The response of this command is a list of status lines
341 formatted as this:
342
343 @example
344      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
345 @end example
346
347 If there is no certificate yet stored on the card a single "X" is
348 returned in @var{hexstring_with_keygrip}.
349
350 @node Scdaemon READCERT
351 @subsection Return a certificate
352
353 @example
354  READCERT @var{hexified_certid}
355 @end example
356
357 This function is used to read a certificate identified by
358 @var{hexified_certid} from the card.
359
360
361 @node Scdaemon READKEY
362 @subsection Return a public key
363
364 @example
365 READKEY @var{hexified_certid}
366 @end example
367
368 Return the public key for the given cert or key ID as an standard
369 S-Expression. 
370
371
372
373 @node Scdaemon PKSIGN
374 @subsection Signing data with a Smartcard
375
376 To sign some data the caller should use the command
377
378 @example
379  SETDATA @var{hexstring}
380 @end example
381
382 to tell @command{scdaemon} about the data to be signed.  The data must be given in
383 hex notation.  The actual signing is done using the command
384
385 @example
386   PKSIGN @var{keyid}
387 @end example
388
389 where @var{keyid} is the hexified ID of the key to be used.  The key id
390 may have been retrieved using the command @code{LEARN}.
391
392
393 @node Scdaemon PKDECRYPT
394 @subsection Decrypting data with a Smartcard
395
396 To decrypt some data the caller should use the command
397
398 @example
399  SETDATA @var{hexstring}
400 @end example
401
402 to tell @command{scdaemon} about the data to be decrypted.  The data
403 must be given in hex notation.  The actual decryption is then done
404 using the command
405
406 @example
407   PKDECRYPT @var{keyid}
408 @end example
409
410 where @var{keyid} is the hexified ID of the key to be used.
411
412
413 @node Scdaemon GETATTR
414 @subsection Read an attribute's value.
415
416 TO BE WRITTEN.
417
418 @node Scdaemon SETATTR
419 @subsection Update an attribute's value.
420
421 TO BE WRITTEN.
422
423 @node Scdaemon GENKEY
424 @subsection Generate a new key on-card.
425
426 TO BE WRITTEN.
427
428 @node Scdaemon RANDOM
429 @subsection Return random bytes generate on-card.
430
431 TO BE WRITTEN.
432
433
434 @node Scdaemon PASSWD
435 @subsection Change PINs.
436
437 TO BE WRITTEN.
438
439
440 @node Scdaemon CHECKPIN
441 @subsection Perform a VERIFY operation.
442
443 TO BE WRITTEN.
444
445