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