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

ENVIRONMENT

657       OPENSC_CONF
658           Filename for a user defined configuration file
659
660           If this environment variable is not found on Windows, the registry
661           key Software\OpenSC Project\OpenSC\ConfigFile is checked.
662
663       OPENSC_DEBUG
664           See debug = num;
665
666       OPENSC_DRIVER
667           See card_drivers = name...;
668
669       CARDMOD_LOW_LEVEL_DEBUG
670           Write minidriver debug information to C:\tmp\md.log, if set to 1.
671
672           If this environment variable is not found on Windows, the registry
673           key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.
674
675       PIV_EXT_AUTH_KEY, PIV_9A_KEY, PIV_9C_KEY, PIV_9D_KEY, PIV_9E_KEY
676           PIV configuration during initialization with piv-tool.
677

FILES

679       /etc/opensc.conf
680           System-wide configuration file
681
682       /usr/share/doc/opensc/opensc.conf
683           Extended example configuration file
684

NOTES

686        1. German ID card emulator
687           https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data
688
689
690
691opensc                            02/25/2021                    OPENSC.CONF(5)
Impressum