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

ENVIRONMENT

674       OPENSC_CONF
675           Filename for a user defined configuration file
676
677           If this environment variable is not found on Windows, the registry
678           key Software\OpenSC Project\OpenSC\ConfigFile is checked.
679
680       OPENSC_DEBUG
681           See debug = num;
682
683       OPENSC_DRIVER
684           See card_drivers = name...;
685
686       CARDMOD_LOW_LEVEL_DEBUG
687           Write minidriver debug information to C:\tmp\md.log, if set to 1.
688
689           If this environment variable is not found on Windows, the registry
690           key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.
691
692       PIV_EXT_AUTH_KEY, PIV_9A_KEY, PIV_9C_KEY, PIV_9D_KEY, PIV_9E_KEY
693           PIV configuration during initialization with piv-tool.
694

FILES

696       /etc/opensc.conf
697           System-wide configuration file
698
699       /usr/share/doc/opensc/opensc.conf
700           Extended example configuration file
701

NOTES

703        1. German ID card emulator
704           https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data
705
706
707
708opensc                            05/02/2022                    OPENSC.CONF(5)
Impressum