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