1OPENSC.CONF(5) OpenSC File Formats OPENSC.CONF(5)
2
6 opensc.conf - configuration file for OpenSC
7
9 OpenSC obtains configuration data from the following sources in the
10 following order
11 1. command-line options
13 2. environment variables
15 3. Windows registry key in HKEY_CURRENT_USER (if available)
17 4. Windows registry key in HKEY_LOCAL_MACHINE (if available)
19 5. system-wide configuration file (/etc/opensc.conf)
21 The configuration file, opensc.conf, is composed of blocks, which, in
23 general, have the following format:
24 key [, name...] {
26 block_contents
27 }
28 block_contents is one or more block_items where a block_item is one of
32 • # comment string
34 • key[, name...] = value;
36 • block
38 At the root level, opensc.conf should contain one or more application
40 specific configuration blocks:
41 app application {
43 block_contents
44 }
45 application specifies one of:
49 • default: The fall-back configuration block for all applications
51 • opensc-pkcs11: Configuration block for the PKCS#11 module
53 (opensc-pkcs11.so)
54 • onepin-opensc-pkcs11: Configuration block for the PKCS#11
56 one-PIN-module (onepin-opensc-pkcs11.so)
57 • cardmod: Configuration block for Windows' minidriver
59 (opensc-minidriver.dll)
60 • tokend: Configuration block for macOS' tokend (OpenSC.tokend)
62 • 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
71 debug = num;
72 Amount of debug info to print (Default: 0). A greater value means
73 more debug info.
74 The environment variable OPENSC_DEBUG overwrites this setting.
76 debug_file = filename;
78 The file to which debug output will be written (Default: stderr).
79 Special values stdout and stderr are recognized.
80 profile_dir = filename;
82 PKCS#15 initialization/personalization profiles directory for
83 pkcs15-init(1) (Default: /usr/share/opensc).
84 If this configuration value is not found on Windows, the registry
86 key Software\OpenSC Project\OpenSC\ProfileDir is checked.
87 disable_colors = bool;
89 Disable colors of log messages (Default: false if attached to a
90 console, true otherwise).
91 disable_popups = bool;
93 Disable pop-ups of built-in GUI (Default: false).
94 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 card_drivers = name...;
100 Allowlist of card drivers to load at start-up. The special value
101 internal (the default) will load all statically linked drivers.
102 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 The list of supported card driver names can be retrieved from the
109 output of opensc-tool --list-drivers.
110 The environment variable OPENSC_DRIVER overwrites this setting.
112 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 reader_driver name { block_contents }
121 Configuration of the smart card reader driver where name is one of:
122 • ctapi: See the section called “Configuration of CT-API Readers”
124 • pcsc: See the section called “Configuration of PC/SC Readers”
126 • openct: See the section called “Configuration of OpenCT
128 Readers”
129 • cryptotokenkit: Configuration block for CryptoTokenKit readers
131 See the section called “Configuration of Smart Card Reader Driver”.
133 card_driver name { block_contents }
135 Configuration of the card driver where name is one of:
136 • npa: See the section called “Configuration Options for German
138 ID Card”
139 • dnie: See the section called “Configuration Options for DNIe”
141 • edo: See the section called “Configuration Options for Polish
143 eID Card”
144 • myeid: See the section called “Configuration Options for MyEID
146 Card”
147 • Any other value: Configuration block for an externally loaded
149 card driver
150 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 For details see the section called “Configuration based on ATR”.
158 secure_messaging name { block_contents }
160 Configuration options for the secure messaging profile name:
161 module_name = filename;
163 Name of external SM module (Default: libsmm-local.so).
164 module_path = filename;
166 Directory with external SM module (Default: /usr/lib64).
167 If this configuration value is not found on Windows, the
169 registry key Software\OpenSC Project\OpenSC\SmDir is checked.
170 module_data = value;
172 Specific data to tune the module initialization.
173 mode = value;
175 Secure messaging mode. Known parameters:
176 • 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 • acl: In this mode APDU are securized only if needed by the
183 ACLs of the command to be executed.
184 flags = value;
187 Secure messaging type specific flags.
188 kmc = hexstring;
190 Default KMC of the GP Card Manager for the Oberthur's Java
191 cards.
192 ifd_serial = hexstring;
194 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 framework name { block_contents }
200 Internal configuration options where name is one of:
201 • pkcs15: See the section called “Configuration of PKCS#15
203 Framework”
204 • tokend: See the section called “Configuration of Tokend”
206 pkcs11 { block_contents }
209 Parameters for the OpenSC PKCS11 module.
210 For details see the section called “Configuration of PKCS#11”.
212 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 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 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 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 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 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 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 enable_pinpad = bool;
254 Enable pinpad if detected (PC/SC v2.0.2 Part 10, Default: true)
255 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 provider_library = filename;
262 Use specific PC/SC provider (Default: libpcsclite.so.1).
263 Configuration of OpenCT Readers
265 readers = num;
266 Virtual readers to allocate (Default: 2).
267 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 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 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 An example PKI can be found in the example data for the German ID
298 card emulator[1]
299 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 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 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 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 driver = name;
325 When enabled, overrides all possible settings from the card drivers
326 built-in card configuration list.
327 name = name;
329 Set card name for card drivers that allows it.
330 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 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 Optionally, some known parameters can be specified as strings:
342 • rng: On-board random number source
344 • 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 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 force_protocol = value;
356 Force protocol selection for specific cards. Known parameters:
357 • t0
359 • t1
361 • raw
363 read_only = bool;
366 Mark card as read/only card in PKCS#11/Minidriver/BaseCSP interface
367 (Default: false).
368 md_supports_X509_enrollment = bool;
370 Indicate X509 enrollment support at Minidriver/BaseCSP interface
371 (Default: false).
372 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 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 md_supports_container_key_gen = bool;
382 Card allows generating key pairs on the card (Default: false).
383 md_supports_container_key_import = bool;
385 Card allows importing private keys (Default: false).
386 md_pinpad_dlg_title = value;
388 Window title of the PIN pad dialog (Default: "Windows Security").
389 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 md_pinpad_dlg_main = value;
395 Main instruction of the PIN pad dialog (Default: "OpenSC Smart Card
396 Provider").
397 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 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 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 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 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 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 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 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 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 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 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 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. Possible parameters:
452 • yes: Cache all files (public and private).
454 public: Cache only public files.
455 •
458 no: File caching disabled.
459 •
462 (Default: no).
464 If caching is done by a system process, the cached files may be
466 placed inaccessible from the user account. Use a globally readable
467 and writable location if you wish to share the cached information.
468 Note that the cached files may contain personal data such as name
469 and mail address.
470 file_cache_dir = filename;
472 Where to cache the card's files. The default values are:
473 • $XDG_CACHE_HOME/opensc/ (If $XDG_CACHE_HOME is defined)
475 • $HOME/.cache/opensc/ (Unix)
477 • $USERPROFILE\.eid-cache\ (Windows)
479 If caching is done by a system process, the cached files may be
481 placed inaccessible from a user account. Use a globally readable
482 and writable location if you wish to share the cached information.
483 Note that the cached files may contain personal data such as name
484 and mail address.
485 use_pin_caching = bool;
487 Use PIN caching (Default: true)?
488 pin_cache_counter = num;
490 How many times to use a PIN from cache before re-authenticating it
491 (Default: 10)?
492 pin_cache_ignore_user_consent = bool;
494 Older PKCS#11 applications not supporting CKA_ALWAYS_AUTHENTICATE
495 may need to set this to get signatures to work with some cards
496 (Default: false).
497 It is recommended to enable also PIN caching using use_pin_caching
499 option for OpenSC to be able to provide PIN for the card when
500 needed.
501 private_certificate = value;
503 How to handle a PIN-protected certificate. Known parameters:
504 • protect: The certificate stays PIN-protected.
506 • declassify: Allow reading the certificate without enforcing
508 verification of the PIN.
509 • ignore: Ignore PIN-protected certificates.
511 (Default: ignore in Tokend, protect otherwise).
513 enable_pkcs15_emulation = bool;
515 Enable pkcs15 emulation (Default: true).
516 try_emulation_first = bool;
518 Prefer pkcs15 emulation code before the normal pkcs15 processing
519 (Default: no). Some cards work in emu-only mode, and do not depend
520 on this option.
521 enable_builtin_emulation = bool;
523 Enable builtin emulators (Default: true).
524 builtin_emulators = emulators;
526 List of the builtin pkcs15 emulators to test (Default: internal)
527 Special value of internal will try all not disabled builtin pkcs15
529 emulators.
530 Special value of old will try all disabled pkcs15 emulators.
532 pkcs11_enable_InitToken = bool;
534 Enable initialization and card recognition (Default: false).
535 emulate name { block_contents }
537 Configuration options for a PKCS#15 emulator where name is a short
538 name for an external card driver.
539 module = filename;
541 For pkcs15 emulators loaded from an external shared
542 library/DLL, you need to specify the path name of the module
543 and customize the card_atr example above correctly.
544 function = name;
546 Get the init function name of the emulator (Default:
547 sc_pkcs15_init_func_ex)
548 application hexstring { block_contents }
550 Configuration of the on-card-application where hexstring is the
551 application identifier (AID).
552 type = name;
554 Type of application where name is one of:
555 • generic
557 • protected
559 Used to distinguish the common access application and
561 application for which authentication to perform some operation
562 cannot be obtained with the common procedures (ex. object
563 creation protected by secure messaging). Used by PKCS#11 module
564 configured to expose restricted number of slots. (for ex.
565 configured to expose only User PIN slot, User and Sign PINs
566 slots, ...)
567 model = name;
569 disable = bool;
571 Do not expose application in PKCS#15 framework (Default: false)
572 Configuration of Tokend
574 score = num;
575 Score for OpenSC.tokend (Default: 300). The tokend with the highest
576 score shall be used.
577 Configuration of PKCS#11
579 max_virtual_slots = num;
580 Maximum Number of virtual slots (Default: 16). If there are more
581 slots than defined here, the remaining slots will be hidden from
582 PKCS#11.
583 slots_per_card = num;
585 Maximum number of slots per smart card (Default: 4). If the card
586 has fewer keys than defined here, the remaining number of slots
587 will be empty.
588 lock_login = bool;
590 By default, the OpenSC PKCS#11 module will not lock your card once
591 you authenticate to the card via C_Login (Default: false). Thus the
592 other users or other applications is not prevented from connecting
593 to the card and perform crypto operations (which may be possible
594 because you have already authenticated with the card). This setting
595 is not very secure.
596 Also, if your card is not locked, you can enconter problems due to
598 limitation of the OpenSC framework, that still is not thoroughly
599 tested in the multi threads environment.
600 Your settings will be more secure if you choose to lock your card.
602 Nevertheless this behavior is a known violation of PKCS#11
603 specification. Now once one application has started using your card
604 with C_Login, no other application can use it, until the first is
605 done and calls C_Logout or C_Finalize. In the case of many PKCS#11
606 application this does not happen until you exit the application.
607 Thus it is impossible to use several smart card aware applications
609 at the same time, e.g. you cannot run both Firefox and Thunderbird
610 at the same time, if both are configured to use your smart card.
611 atomic = bool;
613 By default, interacting with the OpenSC PKCS#11 module may change
614 the state of the token, e.g. whether a user is logged in or not
615 (Default: false).
616 Thus other users or other applications may change or use the state
618 of the token unknowingly. Other applications may create signatures
619 abusing an existing login or they may logout unnoticed.
620 With this setting enabled the login state of the token is tracked
622 and cached (including the PIN). Every transaction is preceded by
623 restoring the login state. After every transaction a logout is
624 performed. This setting by default also enables lock_login to
625 disable access for other applications during the atomic
626 transactions.
627 Please note that any PIN-pad should be disabled (see
629 enable_pinpad), because the user would have to input his PIN for
630 every transaction.
631 init_sloppy = bool;
633 With this setting disabled, the OpenSC PKCS#11 module will
634 initialize the slots available when the application calls
635 C_GetSlotList. With this setting enabled, the slots will also get
636 initialized when C_GetSlotInfo is called (Default: true).
637 This setting is a workaround for Java which does not call
639 C_GetSlotList when configured with a static slot instead of
640 slotListIndex.
641 user_pin_unblock_style = mode;
643 User PIN unblock style mode is one of:
644 • none (Default): PIN unblock is not possible with PKCS#11 API
646 • set_pin_in_unlogged_session: C_SetPIN in unlogged session: PUK
648 is passed as the OldPin argument of the C_SetPIN call.
649 • set_pin_in_specific_context: C_SetPIN in the
651 CKU_SPECIFIC_CONTEXT logged session: PUK is passed as the
652 OldPin argument of the C_SetPIN call.
653 • init_pin_in_so_session: C_InitPIN in CKU_SO logged session:
655 User PIN 'UNBLOCK' is protected by SOPIN. (PUK == SOPIN).
656 create_puk_slot = bool;
659 Create slot for unblocking PIN with PUK (Default: false). This way
660 PKCS#11 API can be used to login with PUK and change a PIN. May
661 cause problems with some applications like Firefox and Thunderbird.
662 create_slots_for_pins = mode...;
664 Symbolic names of PINs for which slots are created where mode is a
665 list of:
666 • all (Default): All non-SO-PIN, non-unblocking PINs
668 • user: The first global or first local PIN
670 • sign: The second PIN (first local, second global or second
672 local)
673 Card can contain more then one PINs or more then one on-card
675 application with its own PINs. Normally, to access all of them with
676 the PKCS#11 API a slot has to be created for all of them. Many
677 slots could be annoying for some of widely used application, like
678 FireFox. This configuration parameter allows to select the PIN(s)
679 for which PKCS#11 slot will be created.
680 Only PINs initialised, non-SO-PIN, non-unblocking are associated
682 with symbolic name.
683 For the module to simulate the opensc-onepin module behavior the
685 following option create_slots_for_pins = "user";
686
688 OPENSC_CONF
689 Filename for a user defined configuration file
690 If this environment variable is not found on Windows, the registry
692 key Software\OpenSC Project\OpenSC\ConfigFile is checked.
693 OPENSC_DEBUG
695 See debug = num;
696 OPENSC_DRIVER
698 See card_drivers = name...;
699 CARDMOD_LOW_LEVEL_DEBUG
701 Write minidriver debug information to C:\tmp\md.log, if set to 1.
702 If this environment variable is not found on Windows, the registry
704 key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.
705 PIV_EXT_AUTH_KEY, PIV_9A_KEY, PIV_9C_KEY, PIV_9D_KEY, PIV_9E_KEY
707 PIV configuration during initialization with piv-tool.
708
710 /etc/opensc.conf
711 System-wide configuration file
712 /usr/share/doc/opensc/opensc.conf
714 Extended example configuration file
715
717 1. German ID card emulator
718 https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data
719opensc 12/02/2022 OPENSC.CONF(5)