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