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