1SCDAEMON(1)                  GNU Privacy Guard 2.3                 SCDAEMON(1)
2
3
4

NAME

6       scdaemon - Smartcard daemon for the GnuPG system
7

SYNOPSIS

9       scdaemon [--homedir dir] [--options file] [options] --server
10       scdaemon  [--homedir  dir]  [--options  file]  [options] --daemon [com‐
11       mand_line]
12
13
14

DESCRIPTION

16       The scdaemon is a daemon to manage smartcards.  It is  usually  invoked
17       by gpg-agent and in general not used directly.
18
19
20
21

COMMANDS

23       Commands  are  not  distinguished from options except for the fact that
24       only one command is allowed.
25
26
27       --version
28              Print the program version and licensing information.  Note  that
29              you cannot abbreviate this command.
30
31
32       --help, -h
33              Print  a  usage message summarizing the most useful command-line
34              options.  Note that you cannot abbreviate this command.
35
36
37       --dump-options
38              Print a list of all available options and commands.   Note  that
39              you cannot abbreviate this command.
40
41
42       --server
43              Run  in server mode and wait for commands on the stdin.  The de‐
44              fault mode is to create a socket and listen for commands there.
45
46
47       --multi-server
48              Run in server mode and wait for commands on the stdin as well as
49              on an additional Unix Domain socket.  The server command GETINFO
50              may be used to get the name of that extra socket.
51
52
53       --daemon
54              Run the program in the background.  This option is  required  to
55              prevent it from being accidentally running in the background.
56
57

OPTIONS

59       --options file
60              Reads  configuration  from file instead of from the default per-
61              user configuration file.   The  default  configuration  file  is
62              named ‘scdaemon.conf’ and expected in the ‘.gnupg’ directory di‐
63              rectly below the home directory of the user.
64
65
66       --homedir dir
67              Set the name of the home directory to dir. If this option is not
68              used,  the  home  directory  defaults to ‘~/.gnupg’.  It is only
69              recognized when given on the command line.   It  also  overrides
70              any  home  directory  stated  through  the  environment variable
71GNUPGHOME’ or (on Windows systems) by means of the Registry en‐
72              try HKCU\Software\GNU\GnuPG:HomeDir.
73
74              On Windows systems it is possible to install GnuPG as a portable
75              application.  In this case only this command line option is con‐
76              sidered, all other ways to set a home directory are ignored.
77
78              To install GnuPG as a portable application under Windows, create
79              an empty file named ‘gpgconf.ctl’ in the same directory  as  the
80              tool  ‘gpgconf.exe’.   The root of the installation is then that
81              directory; or, if ‘gpgconf.exe’ has been installed directly  be‐
82              low  a  directory  named  ‘bin’, its parent directory.  You also
83              need to make sure that the following directories exist  and  are
84              writable:     ‘ROOT/home’     for    the    GnuPG    home    and
85ROOT/var/cache/gnupg’ for internal cache files.
86
87
88
89       -v
90
91       --verbose
92              Outputs additional information while running.  You can  increase
93              the  verbosity by giving several verbose commands to gpgsm, such
94              as ‘-vv’.
95
96
97       --debug-level level
98              Select the debug level for investigating problems.  level may be
99              a numeric value or a keyword:
100
101
102              none   No  debugging at all.  A value of less than 1 may be used
103                     instead of the keyword.
104
105              basic  Some basic debug messages.  A value between 1 and  2  may
106                     be used instead of the keyword.
107
108              advanced
109                     More verbose debug messages.  A value between 3 and 5 may
110                     be used instead of the keyword.
111
112              expert Even more detailed messages.  A value between 6 and 8 may
113                     be used instead of the keyword.
114
115              guru   All  of  the  debug messages you can get. A value greater
116                     than 8 may be used instead of the keyword.  The  creation
117                     of  hash  tracing files is only enabled if the keyword is
118                     used.
119
120       How these messages are mapped to the  actual  debugging  flags  is  not
121       specified  and may change with newer releases of this program. They are
122       however carefully selected to best aid in debugging.
123
124              All debugging options are subject to change and thus should  not
125              be  used by any application program.  As the name says, they are
126              only used as helpers to debug problems.
127
128
129
130       --debug flags
131              Set debug flags.  All flags are or-ed and flags may be given  in
132              C  syntax  (e.g.  0x0042)  or  as a comma separated list of flag
133              names.  To get a list of all supported  flags  the  single  word
134              "help" can be used. This option is only useful for debugging and
135              the behavior may change at any time without notice.
136
137
138       --debug-all
139              Same as --debug=0xffffffff
140
141
142       --debug-wait n
143              When running in server mode, wait n seconds before entering  the
144              actual  processing  loop  and print the pid.  This gives time to
145              attach a debugger.
146
147
148       --debug-ccid-driver
149              Enable debug output from the included  CCID  driver  for  smart‐
150              cards.  Using this option twice will also enable some tracing of
151              the T=1 protocol.  Note that this option  may  reveal  sensitive
152              data.
153
154
155       --debug-disable-ticker
156              This option disables all ticker functions like checking for card
157              insertions.
158
159
160       --debug-allow-core-dump
161              For security reasons we  won't  create  a  core  dump  when  the
162              process  aborts.   For debugging purposes it is sometimes better
163              to allow core dump.  This option enables it and also changes the
164              working directory to ‘/tmp’ when running in --server mode.
165
166
167       --debug-log-tid
168              This option appends a thread ID to the PID in the log output.
169
170
171       --debug-assuan-log-cats cats
172              Changes  the  active  Libassuan logging categories to cats.  The
173              value for cats is an unsigned integer given in  usual  C-Syntax.
174              A  value of 0 switches to a default category.  If this option is
175              not used the categories are taken from the environment  variable
176              ASSUAN_DEBUG.   Note  that this option has only an effect if the
177              Assuan debug flag has also been with the option --debug.  For  a
178              list of categories see the Libassuan manual.
179
180
181       --no-detach
182              Don't  detach the process from the console.  This is mainly use‐
183              ful for debugging.
184
185
186       --listen-backlog n
187              Set the size of the queue for pending connections.  The  default
188              is 64.  This option has an effect only if --multi-server is also
189              used.
190
191
192       --log-file file
193              Append all logging output to file.  This is very helpful in see‐
194              ing  what  the  agent  actually does.  Use ‘socket://’ to log to
195              socket.
196
197
198       --pcsc-shared
199              Use shared mode to access the card via PC/SC.  This is  a  some‐
200              what  dangerous option because Scdaemon assumes exclusive access
201              to the card and for example caches certain information from  the
202              card.  Use this option only if you know what you are doing.
203
204
205       --pcsc-driver library
206              Use library to access the smartcard reader.  The current default
207              on Unix is ‘libpcsclite.so’ and on Windows ‘winscard.dll’.   In‐
208              stead of using this option you might also want to install a sym‐
209              bolic  link  to  the  default  file  name  (e.g.  from   ‘libpc‐
210              sclite.so.1’).  A Unicode file name may not be used on Windows.
211
212
213       --ctapi-driver library
214              Use library to access the smartcard reader.  The current default
215              is ‘libtowitoko.so’.  Note that the use  of  this  interface  is
216              deprecated; it may be removed in future releases.
217
218
219       --disable-ccid
220              Disable the integrated support for CCID compliant readers.  This
221              allows falling back to one of the other drivers even if the  in‐
222              ternal  CCID driver can handle the reader.  Note, that CCID sup‐
223              port is only available if libusb was available at build time.
224
225
226       --reader-port number_or_string
227              This option may be used to specify the port of the  card  termi‐
228              nal.   A value of 0 refers to the first serial device; add 32768
229              to access USB devices.  The default is 32768 (first USB device).
230              PC/SC  or CCID readers might need a string here; run the program
231              in verbose mode to get a list of available readers.  The default
232              is then the first reader found.
233
234              To  get  a  list of available CCID readers you may use this com‐
235              mand:
236           echo scd getinfo reader_list \
237             | gpg-connect-agent --decode | awk '/^D/ {print $2}'
238
239
240       --card-timeout n
241              This option is deprecated.  In GnuPG 2.0, it used to be used for
242              DISCONNECT  command  to  control timing issue.  Since DISCONNECT
243              command works synchronously, it has no effect.
244
245
246       --enable-pinpad-varlen
247              Please specify this option when the card reader  supports  vari‐
248              able length input for pinpad (default is no).  For known readers
249              (listed in ccid-driver.c and apdu.c), this option is not needed.
250              Note  that  if your card reader doesn't supports variable length
251              input but you want to use it, you need to  specify  your  pinpad
252              request on your card.
253
254
255
256       --disable-pinpad
257              Even if a card reader features a pinpad, do not try to use it.
258
259
260
261       --deny-admin
262              This  option  disables  the use of admin class commands for card
263              applications where this is supported.  Currently we  support  it
264              for  the OpenPGP card. This option is useful to inhibit acciden‐
265              tal access to admin class command which  could  ultimately  lock
266              the  card  through  wrong PIN numbers.  Note that GnuPG versions
267              older than 2.0.11 featured an --allow-admin option which was re‐
268              quired  to use such admin commands.  This option has no more ef‐
269              fect today because the default is now to allow admin commands.
270
271
272       --disable-application name
273              This option disables the use of the card application named name.
274              This  is  mainly  useful  for debugging or if a application with
275              lower priority should be used by default.
276
277
278       --application-priority namelist
279              This option allows to change the order in which applications  of
280              a  card  a  tried  if  no  specific  application  was requested.
281              namelist is a space  or  comma  delimited  list  of  application
282              names.  Unknown names are simply skipped.  Applications not men‐
283              tioned in the list are put in the former order at the end of the
284              new priority list.
285
286              To get the list of current active applications, use
287             gpg-connect-agent 'scd getinfo app_list' /bye
288
289
290       All  the long options may also be given in the configuration file after
291       stripping off the two leading dashes.
292
293
294

CARD APPLICATIONS

296       scdaemon supports the card applications as described below.
297
298
299
300
301   The OpenPGP card application ``openpgp''
302
303
304       This application is currently only used by gpg but may in  future  also
305       be  useful  with  gpgsm.   Version  1 and version 2 of the card is sup‐
306       ported.
307
308
309       The specifications for these cards are available at
310       (http://g10code.com/docs/openpgp-card-1.0.pdf) and
311       (http://g10code.com/docs/openpgp-card-2.0.pdf).
312
313
314
315   The Telesec NetKey card ``nks''
316
317
318       This is the main application of the Telesec cards as available in  Ger‐
319       many.  It is a superset of the German DINSIG card.  The card is used by
320       gpgsm.
321
322
323
324   The DINSIG card application ``dinsig''
325
326
327       This is an application as described in the German draft standard DIN  V
328       66291-1.  It is intended to be used by cards supporting the German sig‐
329       nature law and its bylaws (SigG and SigV).
330
331
332
333   The PKCS#15 card application ``p15''
334
335
336       This is common framework for smart card applications.  It  is  used  by
337       gpgsm.
338
339
340
341   The Geldkarte card application ``geldkarte''
342
343
344       This  is  a simple application to display information of a German Geld‐
345       karte.  The Geldkarte is a small amount debit  card  application  which
346       comes with almost all German banking cards.
347
348
349
350   The SmartCard-HSM card application ``sc-hsm''
351
352
353       This  application  adds  read-only  support  for  keys and certificates
354       stored on a (http://www.smartcard-hsm.com, SmartCard-HSM).
355
356       To   generate   keys   and   store    certificates    you    may    use
357       (https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM,   OpenSC)  or  the
358       tools from (http://www.openscdp.org, OpenSCDP).
359
360       The SmartCard-HSM cards requires a card reader that  supports  Extended
361       Length APDUs.
362
363
364
365   The Undefined card application ``undefined''
366
367
368       This is a stub application to allow the use of the APDU command even if
369       no supported application is found on the card.  This application is not
370       used  automatically but must be explicitly requested using the SERIALNO
371       command.
372
373
374
375

EXAMPLES

377         $ scdaemon --server -v
378
379
380
381

FILES

383       There are a few configuration files to control certain aspects  of  sc‐
384       daemons's  operation.  Unless  noted,  they are expected in the current
385       home directory (see: [option --homedir]).
386
387
388
389       scdaemon.conf
390              This is the standard configuration  file  read  by  scdaemon  on
391              startup.   It may contain any valid long option; the leading two
392              dashes may not be entered and the option may not be abbreviated.
393              This  default name may be changed on the command line (see: [op‐
394              tion --options]).
395
396
397       scd-event
398              If this file is present and executable, it will be called on ev‐
399              ery  card  reader's status change.  An example of this script is
400              provided with the distribution
401
402
403       reader_n.status
404              This file is created by scdaemon to let other  applications  now
405              about reader status changes.  Its use is now deprecated in favor
406              of ‘scd-event’.
407
408

SEE ALSO

410       gpg-agent(1), gpgsm(1), gpg2(1)
411
412       The full documentation for this tool is maintained as a Texinfo manual.
413       If  GnuPG and the info program are properly installed at your site, the
414       command
415
416         info gnupg
417
418       should give you access to the complete manual including a  menu  struc‐
419       ture and an index.
420
421
422
423GnuPG 2.3.7                       2022-06-27                       SCDAEMON(1)
Impressum