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 Whitelist 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 (Default: false).
452 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 file_cache_dir = filename;
460 Where to cache the card's files. The default values are:
461 • $XDG_CACHE_HOME/opensc/ (If $XDG_CACHE_HOME is defined)
463 • $HOME/.cache/opensc/ (Unix)
465 • $USERPROFILE\.eid-cache\ (Windows)
467 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 use_pin_caching = bool;
475 Use PIN caching (Default: true)?
476 pin_cache_counter = num;
478 How many times to use a PIN from cache before re-authenticating it
479 (Default: 10)?
480 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 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 private_certificate = value;
491 How to handle a PIN-protected certificate. Known parameters:
492 • protect: The certificate stays PIN-protected.
494 • declassify: Allow reading the certificate without enforcing
496 verification of the PIN.
497 • ignore: Ignore PIN-protected certificates.
499 (Default: ignore in Tokend, protect otherwise).
501 enable_pkcs15_emulation = bool;
503 Enable pkcs15 emulation (Default: true).
504 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 enable_builtin_emulation = bool;
511 Enable builtin emulators (Default: true).
512 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 pkcs11_enable_InitToken = bool;
520 Enable initialization and card recognition (Default: false).
521 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 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 function = name;
532 Get the init function name of the emulator (Default:
533 sc_pkcs15_init_func_ex)
534 application hexstring { block_contents }
536 Configuration of the on-card-application where hexstring is the
537 application identifier (AID).
538 type = name;
540 Type of application where name is one of:
541 • generic
543 • protected
545 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 model = name;
555 disable = bool;
557 Do not expose application in PKCS#15 framework (Default: false)
558 Configuration of Tokend
560 score = num;
561 Score for OpenSC.tokend (Default: 300). The tokend with the highest
562 score shall be used.
563 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 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 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 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 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 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 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 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 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 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 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 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 user_pin_unblock_style = mode;
629 User PIN unblock style mode is one of:
630 • none (Default): PIN unblock is not possible with PKCS#11 API
632 • set_pin_in_unlogged_session: C_SetPIN in unlogged session: PUK
634 is passed as the OldPin argument of the C_SetPIN call.
635 • 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 • init_pin_in_so_session: C_InitPIN in CKU_SO logged session:
641 User PIN 'UNBLOCK' is protected by SOPIN. (PUK == SOPIN).
642 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 create_slots_for_pins = mode...;
650 Symbolic names of PINs for which slots are created where mode is a
651 list of:
652 • all (Default): All non-SO-PIN, non-unblocking PINs
654 • user: The first global or first local PIN
656 • sign: The second PIN (first local, second global or second
658 local)
659 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 Only PINs initialised, non-SO-PIN, non-unblocking are associated
668 with symbolic name.
669 For the module to simulate the opensc-onepin module behavior the
671 following option create_slots_for_pins = "user";
672
674 OPENSC_CONF
675 Filename for a user defined configuration file
676 If this environment variable is not found on Windows, the registry
678 key Software\OpenSC Project\OpenSC\ConfigFile is checked.
679 OPENSC_DEBUG
681 See debug = num;
682 OPENSC_DRIVER
684 See card_drivers = name...;
685 CARDMOD_LOW_LEVEL_DEBUG
687 Write minidriver debug information to C:\tmp\md.log, if set to 1.
688 If this environment variable is not found on Windows, the registry
690 key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.
691 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
696 /etc/opensc.conf
697 System-wide configuration file
698 /usr/share/doc/opensc/opensc.conf
700 Extended example configuration file
701
703 1. German ID card emulator
704 https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data
705opensc 08/10/2021 OPENSC.CONF(5)