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