Fixed a build bug (straw letter in sm/import.c) and updated the documentation.
[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 @var{flags}
92 @opindex debug
93 This option is only useful for debugging and the behaviour may change at
94 any time without notice.  FLAGS are bit encoded and may be given in
95 usual C-Syntax. The currently defined bits are:
96    @table @code
97    @item 0  (1)
98    X.509 or OpenPGP protocol related data
99    @item 1  (2)  
100    values of big number integers 
101    @item 2  (4)
102    low level crypto operations
103    @item 5  (32)
104    memory allocation
105    @item 6  (64)
106    caching
107    @item 7  (128)
108    show memory statistics.
109    @item 9  (512)
110    write hashed data to files named @code{dbgmd-000*}
111    @item 10 (1024)
112    trace Assuan protocol
113    @item 12 (4096)
114    bypass all certificate validation
115    @end table
116
117 @item --debug-all
118 @opindex debug-all
119 Same as @code{--debug=0xffffffff}
120
121 @item --debug-wait @var{n}
122 @opindex debug-wait
123 When running in server mode, wait @var{n} seconds before entering the
124 actual processing loop and print the pid.  This gives time to attach a
125 debugger.
126
127 @item --debug-sc @var{n}
128 @opindex debug-sc
129 Set the debug level of the OpenSC library to @var{n}.
130
131 @item --no-detach
132 @opindex no-detach
133 Don't detach the process from the console.  This is manly usefule for
134 debugging.
135
136 @item --log-file @var{file}
137 @opindex log-file
138 Append all logging output to @var{file}.  This is very helpful in
139 seeing what the agent actually does.
140
141 @item --reader-port @var{number}
142 When the program has been build without OpenSC support, this option must
143 be used to specify the port of the card terminal.  A value of 0 refers
144 to the first serial device; add 32768 to access USB devices.  The
145 default is 32768 (first USB device).
146
147 @item --ctapi-driver @var{library}
148 Use @var{library} to access the smartcard reader.  The current default
149 is @code{libtowitoko.so}.
150
151
152 @item --allow-admin
153 @itemx --deny-admin
154 @opindex allow-admin
155 @opindex deny-admin
156 This enables the use of Admin class commands for card application
157 where this is supported.  Currently we support it for the OpenPGP
158 card.  Deny is the default.  This commands is useful to inhibit
159 accidental access to admin class command which could ultimately lock
160 the card through worng PIN numbers.
161
162 @end table
163
164 All the long options may also be given in the configuration file after
165 stripping off the two leading dashes.
166
167
168 @c 
169 @c  Examples
170 @c
171 @node Scdaemon Examples
172 @section Examples
173
174 @c man begin EXAMPLES
175
176 @example
177 $ scdaemon --server -v
178 @end example
179
180 @c man end
181
182 @c 
183 @c  Assuan Protocol
184 @c
185 @node Scdaemon Protocol
186 @section Scdaemon's Assuan Protocol
187
188 The SC-Daemon should be started by the system to provide access to
189 external tokens.  Using Smartcards on a multi-user system does not
190 make much sense expcet for system services, but in this case no
191 regular user accounts are hosted on the machine.
192
193 A client connects to the SC-Daemon by connecting to the socket named
194 @file{/var/run/scdaemon/socket}, configuration information is read from
195 @var{/etc/scdaemon.conf}
196
197 Each connection acts as one session, SC-Daemon takes care of
198 syncronizing access to a token between sessions.
199
200 @menu
201 * Scdaemon SERIALNO::     Return the serial number.
202 * Scdaemon LEARN::        Read all useful information from the card.
203 * Scdaemon READCERT::     Return a certificate.
204 * Scdaemon READKEY::      Return a public key.
205 * Scdaemon PKSIGN::       Signing data with a Smartcard.
206 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
207 * Scdaemon GETATTR::      Read an attribute's value.
208 * Scdaemon SETATTR::      Update an attribute's value.
209 * Scdaemon GENKEY::       Generate a new key on-card.
210 * Scdaemon RANDOM::       Return random bytes generate on-card.
211 * Scdaemon PASSWD::       Change PINs.
212 * Scdaemon CHECKPIN::     Perform a VERIFY operation.
213 @end menu
214
215 @node Scdaemon SERIALNO 
216 @subsection Return the serial number
217
218 This command should be used to check for the presence of a card.  It is
219 special in that it can be used to reset the card.  Most other commands
220 will return an error when a card change has been detected and the use of
221 this function is therefore required.
222
223 Background: We want to keep the client clear of handling card changes
224 between operations; i.e. the client can assume that all operations are
225 done on the same card unless he call this function.
226
227 @example
228   SERIALNO
229 @end example
230
231 Return the serial number of the card using a status reponse like:
232
233 @example
234   S SERIALNO D27600000000000000000000 0
235 @end example
236
237 The trailing 0 should be ignored for now, it is reserved for a future
238 extension.  The serial number is the hex encoded value identified by 
239 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
240
241
242
243 @node Scdaemon LEARN
244 @subsection Read all useful information from the card
245
246 @example
247   LEARN [--force]
248 @end example
249
250 Learn all useful information of the currently inserted card.  When
251 used without the force options, the command might do an INQUIRE
252 like this:
253
254 @example
255       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
256 @end example
257
258 The client should just send an @code{END} if the processing should go on
259 or a @code{CANCEL} to force the function to terminate with a cancel
260 error message.  The response of this command is a list of status lines
261 formatted as this:
262
263 @example
264      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
265 @end example
266
267 If there is no certificate yet stored on the card a single "X" is
268 returned in @var{hexstring_with_keygrip}.
269
270 @node Scdaemon READCERT
271 @subsection Return a certificate
272
273 @example
274  READCERT @var{hexified_certid}
275 @end example
276
277 This function is used to read a certificate identified by
278 @var{hexified_certid} from the card.
279
280
281 @node Scdaemon READKEY
282 @subsection Return a public key
283
284 @example
285 READKEY @var{hexified_certid}
286 @end example
287
288 Return the public key for the given cert or key ID as an standard
289 S-Expression. 
290
291
292
293 @node Scdaemon PKSIGN
294 @subsection Signing data with a Smartcard
295
296 To sign some data the caller should use the command
297
298 @example
299  SETDATA @var{hexstring}
300 @end example
301
302 to tell scdaemon about the data to be signed.  The data must be given in
303 hex notation.  The actual signing is done using the command
304
305 @example
306   PKSIGN @var{keyid}
307 @end example
308
309 where @var{keyid} is the hexified ID of the key to be used.  The key id
310 may have been retrieved using the command @code{LEARN}.
311
312
313 @node Scdaemon PKDECRYPT
314 @subsection Decrypting data with a Smartcard
315
316 To decrypt some data the caller should use the command
317
318 @example
319  SETDATA @var{hexstring}
320 @end example
321
322 to tell scdaemon about the data to be decrypted.  The data must be given in
323 hex notation.  The actual decryption is then done using the command
324
325 @example
326   PKDECRYPT @var{keyid}
327 @end example
328
329 where @var{keyid} is the hexified ID of the key to be used.
330
331
332 @node Scdaemon GETATTR
333 @subsection Read an attribute's value.
334
335 TO BE WRITTEN.
336
337 @node Scdaemon SETATTR
338 @subsection Update an attribute's value.
339
340 TO BE WRITTEN.
341
342 @node Scdaemon GENKEY
343 @subsection Generate a new key on-card.
344
345 TO BE WRITTEN.
346
347 @node Scdaemon RANDOM
348 @subsection Return random bytes generate on-card.
349
350 TO BE WRITTEN.
351
352
353 @node Scdaemon PASSWD
354 @subsection Change PINs.
355
356 TO BE WRITTEN.
357
358
359 @node Scdaemon CHECKPIN
360 @subsection Perform a VERIFY operation.
361
362 TO BE WRITTEN.
363
364