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