1OPENSC.CONF(5)                OpenSC File Formats               OPENSC.CONF(5)
2
3
4

NAME

6       opensc.conf - configuration file for OpenSC
7

DESCRIPTION

9       OpenSC obtains configuration data from the following sources in the
10       following order
11
12        1. command-line options
13
14        2. environment variables
15
16        3. Windows registry key in HKEY_CURRENT_USER (if available)
17
18        4. Windows registry key in HKEY_LOCAL_MACHINE (if available)
19
20        5. system-wide configuration file (/etc/opensc.conf)
21
22       The configuration file, opensc.conf, is composed of blocks, which, in
23       general, have the following format:
24
25           key [, name...] {
26                block_contents
27           }
28
29
30
31       block_contents is one or more block_items where a block_item is one of
32
33       ·   # comment string
34
35       ·   key[, name...]  = value;
36
37       ·   block
38
39       At the root level, opensc.conf should contain one or more application
40       specific configuration blocks:
41
42           app application {
43                block_contents
44           }
45
46
47
48       application specifies one of:
49
50       ·   default: The fall-back configuration block for all applications
51
52       ·   opensc-pkcs11: Configuration block for the PKCS#11 module
53           (opensc-pkcs11.so)
54
55       ·   onepin-opensc-pkcs11: Configuration block for the PKCS#11
56           one-PIN-module (onepin-opensc-pkcs11.so)
57
58       ·   cardmod: Configuration block for Windows' minidriver
59           (opensc-minidriver.dll)
60
61       ·   tokend: Configuration block for macOS' tokend (OpenSC.tokend)
62
63       ·   cardos-tool, cryptoflex-tool, dnie-tool, egk-tool, eidenv,
64           gids-tool, iasecc-tool, netkey-tool, npa-tool, openpgp-tool,
65           opensc-asn1, opensc-explorer, opensc-notify, opensc-tool, piv-tool,
66           pkcs11-tool, pkcs15-crypt, pkcs15-init, pkcs15-tool, sc-hsm-tool,
67           westcos-tool: Configuration block for OpenSC tools
68
69

CONFIGURATION OPTIONS

71       debug = num;
72           Amount of debug info to print (Default: 0). A greater value means
73           more debug info.
74
75           The environment variable OPENSC_DEBUG overwrites this setting.
76
77       debug_file = filename;
78           The file to which debug output will be written (Default: stderr).
79           Special values stdout and stderr are recognized.
80
81       profile_dir = filename;
82           PKCS#15 initialization/personalization profiles directory for
83           pkcs15-init(1) (Default: /usr/share/opensc).
84
85           If this configuration value is not found on Windows, the registry
86           key Software\OpenSC Project\OpenSC\ProfileDir is checked.
87
88       disable_popups = bool;
89           Disable pop-ups of built-in GUI (Default: false).
90
91       enable_default_driver = bool;
92           Enable default card driver (Default: false). Default card driver is
93           explicitly enabled for opensc-explorer(1) and opensc-tool(1)
94
95       card_drivers = name...;
96           Whitelist of card drivers to load at start-up. The special value
97           internal (the default) will load all statically linked drivers.
98
99           If an unknown (i.e. not internal or old) driver is supplied, a
100           separate configuration configuration block has to be written for
101           the driver. A special value old will load all statically linked
102           drivers that may be removed in the future.
103
104           The list of supported card driver names can be retrieved from the
105           output of opensc-tool --list-drivers.
106
107           The environment variable OPENSC_DRIVER overwrites this setting.
108
109       ignored_readers = name...;
110           List of readers to ignore (Default: empty). If any of the comma
111           separated strings listed is matched in a reader name (case
112           sensitive, partial matching possible), the reader is ignored by
113           OpenSC. Use opensc-tool --list-readers to see all currently
114           connected readers.
115
116       reader_driver name { block_contents }
117           Configuration of the smart card reader driver where name is one of:
118
119           ·   ctapi: See the section called “Configuration of CT-API Readers”
120
121           ·   pcsc: See the section called “Configuration of PC/SC Readers”
122
123           ·   openct: See the section called “Configuration of OpenCT
124               Readers”
125
126           ·   cryptotokenkit: Configuration block for CryptoTokenKit readers
127
128           See the section called “Configuration of Smart Card Reader Driver”.
129
130       card_driver name { block_contents }
131           Configuration of the card driver where name is one of:
132
133           ·   npa: See the section called “Configuration Options for German
134               ID Card”
135
136           ·   dnie: See the section called “Configuration Options for DNIe”
137
138           ·   Any other value: Configuration block for an externally loaded
139               card driver
140
141
142       card_atr hexstring { block_contents }
143           In addition to the built-in list of known cards in the card driver,
144           you can configure a new card for the driver using the card_atr
145           block.
146
147           For details see the section called “Configuration based on ATR”.
148
149       secure_messaging name { block_contents }
150           Configuration options for the secure messaging profile name:
151
152           module_name = filename;
153               Name of external SM module (Default: libsmm-local.so).
154
155           module_path = filename;
156               Directory with external SM module (Default: /usr/lib64).
157
158               If this configuration value is not found on Windows, the
159               registry key Software\OpenSC Project\OpenSC\SmDir is checked.
160
161           module_data = value;
162               Specific data to tune the module initialization.
163
164           mode = value;
165               Secure messaging mode. Known parameters:
166
167               ·   transmit: In this mode the procedure to securize an APDU is
168                   called by the OpenSC general APDU transmit procedure. In
169                   this mode all APDUs, except the ones filtered by the card
170                   specific procedure, are securized.
171
172               ·   acl: In this mode APDU are securized only if needed by the
173                   ACLs of the command to be executed.
174
175
176           flags = value;
177               Secure messaging type specific flags.
178
179           kmc = hexstring;
180               Default KMC of the GP Card Manager for the Oberthur's Java
181               cards.
182
183           ifd_serial = hexstring;
184
185           keyset[_aid]_num_enc = value; keyset[_aid]_num_mac = value;
186               Keyset values from IAM profiles of the Gemalto IAS/ECC cards
187               with an optional application identifier
188
189       framework name { block_contents }
190           Internal configuration options where name is one of:
191
192           ·   pkcs15: See the section called “Configuration of PKCS#15
193               Framework”
194
195           ·   tokend: See the section called “Configuration of Tokend”
196
197
198       pkcs11 { block_contents }
199           Parameters for the OpenSC PKCS11 module.
200
201           For details see the section called “Configuration of PKCS#11”.
202
203   Configuration of Smart Card Reader Driver
204       Configuration Options for all Reader Drivers
205           max_send_size = num; max_recv_size = num;
206               Limit command and response sizes (Default: max_send_size = 255,
207               max_recv_size = 256) . Some Readers don't propagate their
208               transceive capabilities correctly. max_send_size and
209               max_recv_size allow setting the limits manually, for example to
210               enable extended length capabilities.
211
212           enable_escape bool;
213               Detect reader capabilities with escape commands (wrapped APDUs
214               with CLA=0xFF as defined by PC/SC pt. 3 and BSI TR-03119, e.g.
215               for getting the UID, escaped PIN commands and the reader's
216               firmware version, Default: false)
217
218       Configuration of CT-API Readers
219           module filename { ports = nums; }
220               Load the specified CT-API module with the specified number of
221               ports.
222
223       Configuration of PC/SC Readers
224           connect_exclusive = bool;
225               Connect to reader in exclusive mode (Default: false)? This
226               option has no effect in Windows' minidriver.
227
228           disconnect_action = action;
229               What to do when disconnecting from a card (SCardDisconnect).
230               Valid values are leave, reset, unpower (Default: leave). This
231               option has no effect in Windows' minidriver.
232
233           transaction_end_action = action;
234               What to do at the end of a transaction (SCardEndTransaction).
235               Valid values are leave, reset, unpower (Default: leave). This
236               option has no effect in Windows' minidriver.
237
238           reconnect_action = action;
239               What to do when reconnection to a card (SCardReconnect). Valid
240               values are leave, reset, unpower (Default: leave). This option
241               has no effect in Windows' minidriver.
242
243           enable_pinpad = bool;
244               Enable pinpad if detected (PC/SC v2.0.2 Part 10, Default: true)
245
246           fixed_pinlength = num;
247               Some pinpad readers can only handle one exact length of the
248               PIN.  fixed_pinlength sets this value so that OpenSC expands
249               the padding to this length (Default: 0, i.e. not fixed).
250
251           provider_library = filename;
252               Use specific PC/SC provider (Default: libpcsclite.so.1).
253
254       Configuration of OpenCT Readers
255           readers = num;
256               Virtual readers to allocate (Default: 2).
257
258   Configuration Options for German ID Card
259       can = value;
260           German ID card requires the CAN to be verified before QES PIN.
261           This, however, is not part of the PKCS#15 profile of the card. So
262           for verifying the QES PIN we actually need both. The CAN may be
263           given here. If the CAN is not given here, it will be prompted on
264           the command line or on the reader (depending on the reader's
265           capabilities).
266
267       st_dv_certificate = filename; st_certificate = filename; st_key =
268       filename;
269           QES is only possible with a Comfort Reader (CAT-K), which holds a
270           cryptographic key to authenticate itself as signature terminal
271           (ST). We usually will use the reader's capability to sign the data.
272           However, during developement you may specify soft certificates and
273           keys for a ST.
274
275           An example PKI can be found in the example data for the German ID
276           card emulator[1]
277
278   Configuration Options for DNIe
279       user_consent_enabled = bool;
280           Configure the warning message when performing a signature operation
281           with the DNIe. Only used if compiled with --enable-dnie-ui
282
283       user_consent_app = filename;
284           Specify the pinentry application to use if warning is configured to
285           be displayed using pinentry (Default: /usr/bin/pinentry). Only used
286           if compiled with --enable-dnie-ui
287
288   Configuration based on ATR
289       atrmask = hexstring;
290           The mask is logically AND'd with an card ATR prior to comparison
291           with the ATR reference value above. Using this mask allows
292           identifying and configuring multiple ATRs as the same card model.
293
294       driver = name;
295           When enabled, overrides all possible settings from the card drivers
296           built-in card configuration list.
297
298       name = name;
299           Set card name for card drivers that allows it.
300
301       type = num;
302           Allows setting the exact type of the card internally used by the
303           card driver. Allowed values can be found in the source code of
304           cards.h.
305
306       flags = value...;
307           Card flags as an hex value. Multiple values are OR'd together.
308           Depending on card driver, this allows fine-tuning the capabilities
309           in the card driver for your card.
310
311           Optionally, some known parameters can be specified as strings:
312
313           ·   rng: On-board random number source
314
315           ·   keep_alive: Request the card driver to send a "keep alive"
316               command before each transaction to make sure that the required
317               applet is still selected.
318
319
320       pkcs15emu = name;
321           When using PKCS#15 emulation, force the emulation driver for
322           specific cards. Required for external drivers, but can be used with
323           built-in drivers, too.
324
325       force_protocol = value;
326           Force protocol selection for specific cards. Known parameters:
327
328           ·   t0
329
330           ·   t1
331
332           ·   raw
333
334
335       md_read_only = bool;
336           Mark card as read/only card in Minidriver/BaseCSP interface
337           (Default: false).
338
339       md_supports_X509_enrollment = bool;
340           Indicate X509 enrollment support at Minidriver/BaseCSP interface
341           (Default: false).
342
343       md_guid_as_id = bool;
344           Use the GUID generated for the key as id in the PKCS#15 structure
345           (Default: false, i.e. auto generated)
346
347       md_guid_as_label = bool;
348           Use the GUID generated for the key as label in the PKCS#15
349           structure (Default: false, i.e. no label set).
350
351       md_supports_container_key_gen = bool;
352           Card allows generating key pairs on the card (Default: false).
353
354       md_supports_container_key_import = bool;
355           Card allows importing private keys (Default: false).
356
357       md_pinpad_dlg_title = value;
358           Window title of the PIN pad dialog (Default: "Windows Security").
359
360       md_pinpad_dlg_icon = filename;
361           Filename of the icon for the PIN pad dialog; use "" for no icon
362           (Default: Built-in smart card icon).
363
364       md_pinpad_dlg_main = value;
365           Main instruction of the PIN pad dialog (Default: "OpenSC Smart Card
366           Provider").
367
368       md_pinpad_dlg_content_user = value;
369           Content of the PIN pad dialog for role "user" (Default: "Please
370           enter your PIN on the PIN pad.").
371
372       md_pinpad_dlg_content_user_sign = value;
373           Content of the PIN pad dialog for role "user+signature" (Default:
374           "Please enter your digital signature PIN on the PIN pad.").
375
376       md_pinpad_dlg_content_admin = value;
377           Content of the PIN pad dialog for role "admin" (Default: "Please
378           enter your PIN to unblock the user PIN on the PIN pad.")
379
380       md_pinpad_dlg_expanded = value;
381           Expanded information of the PIN pad dialog (Default: "This window
382           will be closed automatically after the PIN has been submitted on
383           the PIN pad (timeout typically after 30 seconds).")
384
385       md_pinpad_dlg_enable_cancel = bool;
386           Allow the user to cancel the PIN pad dialog (Default: false). If
387           this value is set to true, the user needs to click "OK" to start
388           the PIN verification on the PIN pad. The user can choose the
389           default behavior by enabling or disabling the checkbox of the
390           dialog. The setting is saved by the program's full path
391           (program_path) that uses OpenSC.
392
393           The registry key HKCU\Software\OpenSC
394           Project\OpenSC\md_pinpad_dlg_enable_cancel\program_path overwrites
395           this setting with a DWORD set to either 1 (enabled) or 0
396           (disabled).
397
398       md_pinpad_dlg_timeout = num;
399           Time in seconds for the progress bar of the PIN pad dialog to tick.
400           0 removes the progress bar (Default: 30).
401
402       notify_card_inserted = value; notify_card_inserted_text = value;
403           Notification title and text when card was inserted (Default: "Smart
404           card detected", ATR of the card).
405
406       notify_card_removed = value; notify_card_removed_text = value;
407           Notification title and text when card was removed (Default: "Smart
408           card removed", name of smart card reader).
409
410       notify_pin_good = value; notify_pin_good_text = value;
411           Notification title and text when PIN was verified (Default: "PIN
412           verified", "Smart card is unlocked").
413
414       notify_pin_bad = value; notify_pin_bad_text = value;
415           Notification title and text when PIN was wrong (Default: "PIN not
416           verified", "Smart card is locked").
417
418   Configuration of PKCS#15 Framework
419       use_file_caching = bool;
420           Whether to cache the card's files (e.g. certificates) on disk in
421           file_cache_dir (Default: false).
422
423           If caching is done by a system process, the cached files may be
424           placed inaccessible from the user account. Use a globally readable
425           and writable location if you wish to share the cached information.
426           Note that the cached files may contain personal data such as name
427           and mail address.
428
429       file_cache_dir = filename;
430           Where to cache the card's files. The default values are:
431
432           ·   HOME/.eid/cache/ (Unix)
433
434           ·   USERPROFILE\.eid-cache\ (Windows)
435
436           If caching is done by a system process, the cached files may be
437           placed inaccessible from a user account. Use a globally readable
438           and writable location if you wish to share the cached information.
439           Note that the cached files may contain personal data such as name
440           and mail address.
441
442       use_pin_caching = bool;
443           Use PIN caching (Default: true)?
444
445       pin_cache_counter = num;
446           How many times to use a PIN from cache before re-authenticating it
447           (Default: 10)?
448
449       pin_cache_ignore_user_consent = bool;
450           Older PKCS#11 applications not supporting CKA_ALWAYS_AUTHENTICATE
451           may need to set this to get signatures to work with some cards
452           (Default: false).
453
454       enable_pkcs15_emulation = bool;
455           Enable pkcs15 emulation (Default: true).
456
457       try_emulation_first = bool;
458           Prefer pkcs15 emulation code before the normal pkcs15 processing
459           (Default: no). Some cards work in emu-only mode, and do not depend
460           on this option.
461
462       enable_builtin_emulation = bool;
463           Enable builtin emulators (Default: true).
464
465       builtin_emulators = emulators;
466           List of the builtin pkcs15 emulators to test (Default: westcos,
467           openpgp, infocamere, starcert, tcos, esteid, itacns, postecert,
468           PIV-II, cac, gemsafeGPK, gemsafeV1, actalis, atrust-acos, tccardos,
469           entersafe, pteid, oberthur, sc-hsm, dnie, gids, iasecc, jpki,
470           coolkey, din66291)
471
472       pkcs11_enable_InitToken = bool;
473           Enable initialization and card recognition (Default: false).
474
475       emulate name { block_contents }
476           Configuration options for a PKCS#15 emulator where name is a short
477           name for an external card driver.
478
479           module = filename;
480               For pkcs15 emulators loaded from an external shared
481               library/DLL, you need to specify the path name of the module
482               and customize the card_atr example above correctly.
483
484           function = name;
485               Get the init function name of the emulator (Default:
486               sc_pkcs15_init_func_ex)
487
488       application hexstring { block_contents }
489           Configuration of the on-card-application where hexstring is the
490           application identifier (AID).
491
492           type = name;
493               Type of application where name is one of:
494
495               ·   generic
496
497               ·   protected
498
499               Used to distinguish the common access application and
500               application for which authentication to perform some operation
501               cannot be obtained with the common procedures (ex. object
502               creation protected by secure messaging). Used by PKCS#11 module
503               configured to expose restricted number of slots. (for ex.
504               configured to expose only User PIN slot, User and Sign PINs
505               slots, ...)
506
507           model = name;
508
509           disable = bool;
510               Do not expose application in PKCS#15 framework (Default: false)
511
512   Configuration of Tokend
513       score = num;
514           Score for OpenSC.tokend (Default: 300). The tokend with the highest
515           score shall be used.
516
517       ignore_private_certificate = bool;
518           Tokend ignore to read PIN protected certificate that is set
519           SC_PKCS15_CO_FLAG_PRIVATE flag (Default: true).
520
521   Configuration of PKCS#11
522       max_virtual_slots = num;
523           Maximum Number of virtual slots (Default: 16). If there are more
524           slots than defined here, the remaining slots will be hidden from
525           PKCS#11.
526
527       slots_per_card = num;
528           Maximum number of slots per smart card (Default: 4). If the card
529           has fewer keys than defined here, the remaining number of slots
530           will be empty.
531
532       lock_login = bool;
533           By default, the OpenSC PKCS#11 module will not lock your card once
534           you authenticate to the card via C_Login (Default: false). Thus the
535           other users or other applications is not prevented from connecting
536           to the card and perform crypto operations (which may be possible
537           because you have already authenticated with the card). This setting
538           is not very secure.
539
540           Also, if your card is not locked, you can enconter problems due to
541           limitation of the OpenSC framework, that still is not thoroughly
542           tested in the multi threads environment.
543
544           Your settings will be more secure if you choose to lock your card.
545           Nevertheless this behavior is a known violation of PKCS#11
546           specification. Now once one application has started using your card
547           with C_Login, no other application can use it, until the first is
548           done and calls C_Logout or C_Finalize. In the case of many PKCS#11
549           application this does not happen until you exit the application.
550
551           Thus it is impossible to use several smart card aware applications
552           at the same time, e.g. you cannot run both Firefox and Thunderbird
553           at the same time, if both are configured to use your smart card.
554
555       atomic = bool;
556           By default, interacting with the OpenSC PKCS#11 module may change
557           the state of the token, e.g. whether a user is logged in or not
558           (Default: false).
559
560           Thus other users or other applications may change or use the state
561           of the token unknowingly. Other applications may create signatures
562           abusing an existing login or they may logout unnoticed.
563
564           With this setting enabled the login state of the token is tracked
565           and cached (including the PIN). Every transaction is preceded by
566           restoring the login state. After every transaction a logout is
567           performed. This setting by default also enables lock_login to
568           disable access for other applications during the atomic
569           transactions.
570
571           Please note that any PIN-pad should be disabled (see
572           enable_pinpad), because the user would have to input his PIN for
573           every transaction.
574
575       init_sloppy = bool;
576           With this setting disabled, the OpenSC PKCS#11 module will
577           initialize the slots available when the application calls
578           C_GetSlotList. With this setting enabled, the slots will also get
579           initialized when C_GetSlotInfo is called (Default: true).
580
581           This setting is a workaround for Java which does not call
582           C_GetSlotList when configured with a static slot instead of
583           slotListIndex.
584
585       user_pin_unblock_style = mode;
586           User PIN unblock style mode is one of:
587
588           ·   none (Default): PIN unblock is not possible with PKCS#11 API
589
590           ·   set_pin_in_unlogged_session: C_SetPIN in unlogged session: PUK
591               is passed as the OldPin argument of the C_SetPIN call.
592
593           ·   set_pin_in_specific_context: C_SetPIN in the
594               CKU_SPECIFIC_CONTEXT logged session: PUK is passed as the
595               OldPin argument of the C_SetPIN call.
596
597           ·   init_pin_in_so_session: C_InitPIN in CKU_SO logged session:
598               User PIN 'UNBLOCK' is protected by SOPIN. (PUK == SOPIN).
599
600
601       create_puk_slot = bool;
602           Create slot for unblocking PIN with PUK (Default: false). This way
603           PKCS#11 API can be used to login with PUK and change a PIN. May
604           cause problems with some applications like Firefox and Thunderbird.
605
606       create_slots_for_pins = mode...;
607           Symbolic names of PINs for which slots are created where mode is a
608           list of:
609
610           ·   all (Default): All non-SO-PIN, non-unblocking PINs
611
612           ·   user: The first global or first local PIN
613
614           ·   sign: The second PIN (first local, second global or second
615               local)
616
617           Card can contain more then one PINs or more then one on-card
618           application with its own PINs. Normally, to access all of them with
619           the PKCS#11 API a slot has to be created for all of them. Many
620           slots could be annoying for some of widely used application, like
621           FireFox. This configuration parameter allows to select the PIN(s)
622           for which PKCS#11 slot will be created.
623
624           Only PINs initialised, non-SO-PIN, non-unblocking are associated
625           with symbolic name.
626
627           For the module to simulate the opensc-onepin module behavior the
628           following option create_slots_for_pins = "user";
629

ENVIRONMENT

631       OPENSC_CONF
632           Filename for a user defined configuration file
633
634           If this environment variable is not found on Windows, the registry
635           key Software\OpenSC Project\OpenSC\ConfigFile is checked.
636
637       OPENSC_DEBUG
638           See debug = num;
639
640       OPENSC_DRIVER
641           See card_drivers = name...;
642
643       CARDMOD_LOW_LEVEL_DEBUG
644           Write minidriver debug information to C:\tmp\md.log, if set to 1.
645
646           If this environment variable is not found on Windows, the registry
647           key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.
648
649       PIV_EXT_AUTH_KEY, PIV_9A_KEY, PIV_9C_KEY, PIV_9D_KEY, PIV_9E_KEY
650           PIV configuration during initialization with piv-tool.
651

FILES

653       /etc/opensc.conf
654           System-wide configuration file
655
656       /usr/share/doc/opensc/opensc.conf
657           Extended example configuration file
658

NOTES

660        1. German ID card emulator
661           https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data
662
663
664
665opensc                            09/30/2019                    OPENSC.CONF(5)
Impressum