Taken from NewPG
[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 @end table
62
63
64 @c man begin OPTIONS
65
66 @node Scdaemon Options
67 @section Option Summary
68
69 @table @gnupgtabopt
70
71 @item --options @var{file}
72 @opindex options
73 Reads configuration from @var{file} instead of from the default
74 per-user configuration file.
75
76 @item -v
77 @item --verbose
78 @opindex v
79 @opindex verbose
80 Outputs additional information while running.
81 You can increase the verbosity by giving several
82 verbose commands to @sc{gpgsm}, such as @samp{-vv}.
83
84 @item --debug @var{flags}
85 @opindex debug
86 This option is only useful for debugging and the behaviour may change at
87 any time without notice.  FLAGS are bit encoded and may be given in
88 usual C-Syntax. The currently defined bits are:
89    @table @code
90    @item 0  (1)
91    X.509 or OpenPGP protocol related data
92    @item 1  (2)  
93    values of big number integers 
94    @item 2  (4)
95    low level crypto operations
96    @item 5  (32)
97    memory allocation
98    @item 6  (64)
99    caching
100    @item 7  (128)
101    show memory statistics.
102    @item 9  (512)
103    write hashed data to files named @code{dbgmd-000*}
104    @item 10 (1024)
105    trace Assuan protocol
106    @item 12 (4096)
107    bypass all certificate validation
108    @end table
109
110 @item --debug-all
111 @opindex debug-all
112 Same as @code{--debug=0xffffffff}
113
114 @item --debug-wait @var{n}
115 @opindex debug-wait
116 When running in server mode, wait @var{n} seconds before entering the
117 actual processing loop and print the pid.  This gives time to attach a
118 debugger.
119
120 @item --debug-sc @var{n}
121 @opindex debug-sc
122 Set the debug level of the OpenSC library to @var{n}.
123
124 @item --no-detach
125 @opindex no-detach
126 Don't detach the process from the console.  This is manly usefule for
127 debugging.
128
129 @item --log-file @var{file}
130 @opindex log-file
131 Append all logging output to @var{file}.  This is very helpful in
132 seeing what the agent actually does.
133
134
135 @end table
136
137 All the long options may also be given in the configuration file after
138 stripping off the two leading dashes.
139
140
141 @c 
142 @c  Examples
143 @c
144 @node Scdaemon Examples
145 @section Examples
146
147 @c man begin EXAMPLES
148
149 @example
150 $ scdaemon --server -v
151 @end example
152
153 @c man end
154
155 @c 
156 @c  Assuan Protocol
157 @c
158 @node Scdaemon Protocol
159 @section Scdaemon's Assuan Protocol
160
161 The SC-Daemon should be started by the system to provide access to
162 external tokens.  Using Smartcards on a multi-user system does not
163 make much sense expcet for system services, but in this case no
164 regular user accounts are hosted on the machine.
165
166 A client connects to the SC-Daemon by connecting to the socket named
167 @file{/var/run/scdaemon/socket}, configuration information is read from
168 @var{/etc/scdaemon.conf}
169
170 Each connection acts as one session, SC-Daemon takes care of
171 syncronizing access to a token between sessions.
172
173 @menu
174 * Scdaemon SERIALNO::     Return the serial number.
175 * Scdaemon LEARN::        Read all useful information from the card.
176 * Scdaemon READCERT::     Return a certificate.
177 * Scdaemon READKEY::      Return a public key.
178 * Scdaemon PKSIGN::       Signing data with a Smartcard.
179 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
180 @end menu
181
182 @node Scdaemon SERIALNO 
183 @subsection Return the serial number
184
185 This command should be used to check for the presence of a card.  It is
186 special in that it can be used to reset the card.  Most other commands
187 will return an error when a card change has been detected and the use of
188 this function is therefore required.
189
190 Background: We want to keep the client clear of handling card changes
191 between operations; i.e. the client can assume that all operations are
192 done on the same card unless he call this function.
193
194 @example
195   SERIALNO
196 @end example
197
198 Return the serial number of the card using a status reponse like:
199
200 @example
201   S SERIALNO D27600000000000000000000 0
202 @end example
203
204 The trailing 0 should be ignored for now, it is reserved for a future
205 extension.  The serial number is the hex encoded value identified by 
206 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
207
208
209
210 @node Scdaemon LEARN
211 @subsection Read all useful information from the card
212
213 @example
214   LEARN [--force]
215 @end example
216
217 Learn all useful information of the currently inserted card.  When
218 used without the force options, the command might do an INQUIRE
219 like this:
220
221 @example
222       INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
223 @end example
224
225 The client should just send an @code{END} if the processing should go on
226 or a @code{CANCEL} to force the function to terminate with a cancel
227 error message.  The response of this command is a list of status lines
228 formatted as this:
229
230 @example
231      S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
232 @end example
233
234 If there is no certificate yet stored on the card a single "X" is
235 returned in @var{hexstring_with_keygrip}.
236
237 @node Scdaemon READCERT
238 @subsection Return a certificate
239
240 @example
241  READCERT @var{hexified_certid}
242 @end example
243
244 This function is used to read a certificate identified by
245 @var{hexified_certid} from the card.
246
247
248 @node Scdaemon READKEY
249 @subsection Return a public key
250
251 @example
252 READKEY @var{hexified_certid}
253 @end example
254
255 Return the public key for the given cert or key ID as an standard
256 S-Expression. 
257
258
259
260 @node Scdaemon PKSIGN
261 @subsection Signing data with a Smartcard
262
263 To sign some data the caller should use the command
264
265 @example
266  SETDATA @var{hexstring}
267 @end example
268
269 to tell scdaemon about the data to be signed.  The data must be given in
270 hex notation.  The actual signing is done using the command
271
272 @example
273   PKSIGN @var{keyid}
274 @end example
275
276 where @var{keyid} is the hexified ID of the key to be used.  The key id
277 may have been retrieved using the command @code{LEARN}.
278
279
280 @node Scdaemon PKDECRYPT
281 @subsection Decrypting data with a Smartcard
282
283 To decrypt some data the caller should use the command
284
285 @example
286  SETDATA @var{hexstring}
287 @end example
288
289 to tell scdaemon about the data to be decrypted.  The data must be given in
290 hex notation.  The actual decryption is then done using the command
291
292 @example
293   PKDECRYPT @var{keyid}
294 @end example
295
296 where @var{keyid} is the hexified ID of the key to be used.
297