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