opensc.conf5OpenSCOpenSC File Formatsopenscopensc.confconfiguration file for OpenSCDescription
OpenSC obtains configuration data from the following sources in the following order
command-line options
environment variables
Windows registry key in
HKEY_CURRENT_USER (if available)
Windows registry key in
HKEY_LOCAL_MACHINE (if available)
system-wide configuration file
(@sysconfdir@/opensc.conf)
The configuration file, opensc.conf, is composed
of blocks, which, in general, have the
following format:
key, name {
block_contents
}
block_contents is one or more
block_items where a
block_item is one of
# comment stringkey, name = value;
block
At the root level, opensc.conf should contain
one or more application specific configuration blocks:
app application {
block_contents
}
application
specifies one of:
default: The fall-back configuration block for all applications
opensc-pkcs11: Configuration block for the PKCS#11 module (opensc-pkcs11@DYN_LIB_EXT@)
onepin-opensc-pkcs11: Configuration block for the PKCS#11 one-PIN-module (onepin-opensc-pkcs11@DYN_LIB_EXT@)
cardmod: Configuration block for Windows' minidriver (opensc-minidriver.dll)
tokend: Configuration block for macOS' tokend (OpenSC.tokend)
cardos-tool,
cryptoflex-tool,
dnie-tool,
egk-tool,
eidenv,
gids-tool,
iasecc-tool,
netkey-tool,
npa-tool,
openpgp-tool,
opensc-asn1,
opensc-explorer,
opensc-notify,
opensc-tool,
piv-tool,
pkcs11-tool,
pkcs15-crypt,
pkcs15-init,
pkcs15-tool,
sc-hsm-tool,
westcos-tool:
Configuration block for OpenSC tools
Configuration Options
Amount of debug info to print (Default:
0). A greater value means more
debug info.
The environment variable
OPENSC_DEBUG overwrites this
setting.
The file to which debug output will be written
(Default: stderr). Special
values stdout and
stderr are recognized.
PKCS#15 initialization/personalization profiles
directory for
pkcs15-init1.
(Default: @PROFILE_DIR_DEFAULT@).
If this configuration value is not found on
Windows, the registry key
Software\OpenSC
Project\OpenSC\ProfileDir is
checked.
Disable colors of log messages (Default:
false if attached to a console,
true otherwise).
Disable pop-ups of built-in GUI (Default: false).
Enable default card driver (Default:
false). Default card driver is
explicitly enabled for
opensc-explorer1.
and
opensc-tool1.
Whitelist of card drivers to load at start-up.
The special value internal (the
default) will load all statically linked drivers.
If an unknown (i.e. not internal or old) driver is
supplied, a separate configuration
block has to be written for the driver. A special
value old will load all
statically linked drivers that may be removed in
the future.
The list of supported card driver names can be
retrieved from the output of opensc-tool
--list-drivers.
The environment variable
OPENSC_DRIVER overwrites this
setting.
List of readers to ignore (Default: empty). If any
of the comma separated strings listed is matched in
a reader name (case sensitive, partial matching
possible), the reader is ignored by OpenSC. Use
opensc-tool --list-readers to
see all currently connected readers.
Configuration of the smart card reader driver where name is one of:
ctapi: See pcsc: See openct: See cryptotokenkit: Configuration block for CryptoTokenKit readers
See .
Configuration of the card driver where name is one of:
npa: See dnie: See edo: See
Any other value: Configuration block for an externally loaded card driver
In addition to the built-in list of known cards in
the card driver, you can configure a new card for
the driver using the
block.
For details see .
Configuration options for the secure messaging profile name:
Name of external SM module (Default: @DEFAULT_SM_MODULE@).
Directory with external SM module
(Default: @libdir@).
If this configuration value is not
found on Windows, the registry key
Software\OpenSC
Project\OpenSC\SmDir is
checked.
Specific data to tune the module initialization.
Secure messaging mode. Known parameters:
transmit:
In this mode the
procedure to securize
an APDU is called by
the OpenSC general APDU
transmit procedure. In
this mode all APDUs,
except the ones
filtered by the card
specific procedure, are
securized.
acl:
In this mode APDU are
securized only if
needed by the ACLs of
the command to be
executed.
Secure messaging type specific flags.
Default KMC of the GP Card Manager for the Oberthur's Java cards.
Keyset values from IAM profiles of
the Gemalto IAS/ECC cards with an
optional application identifier
Internal configuration options where name is one of:
pkcs15: See tokend: See
Parameters for the OpenSC PKCS11 module.
For details see .
Configuration of Smart Card Reader DriverConfiguration Options for all Reader Drivers
Limit command and response sizes
(Default:
= 255,
= 256) . Some
Readers don't propagate their
transceive capabilities correctly.
max_send_size and max_recv_size
allow setting the limits manually,
for example to enable extended
length capabilities.
Detect reader capabilities with
escape commands (wrapped APDUs with
CLA=0xFF as defined by PC/SC pt. 3
and BSI TR-03119, e.g. for getting
the UID, escaped PIN commands and
the reader's firmware version,
Default: false)
Configuration of CT-API Readers
Load the specified CT-API module with the specified number of ports.
Configuration of PC/SC Readers
Connect to reader in exclusive mode
(Default: false)?
This option has no effect in Windows' minidriver.
What to do when disconnecting from
a card (SCardDisconnect). Valid
values are
leave,
reset,
unpower (Default:
leave).
This option has no effect in Windows' minidriver.
What to do at the end of a
transaction (SCardEndTransaction).
Valid values
are leave,
reset,
unpower (Default:
leave).
This option has no effect in Windows' minidriver.
What to do when reconnection to a
card (SCardReconnect). Valid values
are leave,
reset,
unpower (Default:
leave).
This option has no effect in Windows' minidriver.
Enable pinpad if detected (PC/SC
v2.0.2 Part 10, Default:
true)
Some pinpad readers can only handle
one exact length of the PIN.
sets this value so that OpenSC
expands the padding to this length
(Default: 0,
i.e. not fixed).
Use specific PC/SC provider
(Default:
@DEFAULT_PCSC_PROVIDER@).
Configuration of OpenCT Readers
Virtual readers to allocate (Default: 2).
Configuration Options for German ID Card
German ID card requires the CAN to
be verified before QES PIN. This,
however, is not part of the PKCS#15
profile of the card. So for
verifying the QES PIN we actually
need both. The CAN may be given
here. If the CAN is not given here,
it will be prompted on the command
line or on the reader (depending on
the reader's capabilities).
QES is only possible with a Comfort
Reader (CAT-K), which holds a
cryptographic key to authenticate
itself as signature terminal (ST).
We usually will use the reader's
capability to sign the data.
However, during development you
may specify soft certificates and
keys for a ST.
An example PKI can be found in the
example data for the
German
ID card emulatorConfiguration Options for DNIe
Configure the warning message when
performing a signature operation
with the DNIe. Only used if
compiled with
Specify the pinentry application to
use if warning is configured to be
displayed using pinentry (Default:
/usr/bin/pinentry).
Only used if compiled with
Configuration Options for Polish eID Card
CAN (Card Access Number – 6 digit number
printed on the right bottom corner of the
front side of the document) is required
to establish connection with the card.
It might be overwritten by EDO_CAN
environment variable. Currently, it is not
possible to set it in any other way.
Configuration based on ATR
The mask is logically AND'd with an
card ATR prior to comparison with
the ATR reference value above.
Using this mask allows identifying
and configuring multiple ATRs as
the same card model.
When enabled, overrides all
possible settings from the card
drivers built-in card configuration
list.
Set card name for card drivers that
allows it.
Allows setting the exact type of
the card internally used by the
card driver. Allowed values can be
found in the source code of
cards.h.
Card flags as an hex value.
Multiple values are OR'd together.
Depending on card driver, this
allows fine-tuning the capabilities
in the card driver for your card.
Optionally, some known parameters
can be specified as strings:
rng:
On-board random number
source
keep_alive:
Request the card driver
to send a "keep alive"
command before each
transaction to make
sure that the required
applet is still
selected.
When using PKCS#15 emulation, force
the emulation driver for specific
cards. Required for external
drivers, but can be used with
built-in drivers, too.
Force protocol selection for
specific cards. Known parameters:
t0t1raw
Mark card as read/only card in
PKCS#11/Minidriver/BaseCSP interface
(Default: false).
Indicate X509 enrollment support at
Minidriver/BaseCSP interface
(Default: false).
Use the GUID generated for the key
as id in the PKCS#15 structure
(Default: false, i.e. auto generated)
Use the GUID generated for the key
as label in the PKCS#15 structure
(Default: false,
i.e. no label set).
Card allows generating key pairs on the card (Default: false).
Card allows importing private keys
(Default: false).
Window title of the PIN pad dialog
(Default: "Windows
Security").
Filename of the icon for the PIN
pad dialog; use
"" for no icon
(Default: Built-in smart card icon).
Main instruction of the PIN pad
dialog (Default: "OpenSC
Smart Card Provider").
Content of the PIN pad dialog for
role "user" (Default:
"Please enter your PIN on the PIN
pad.").
Content of the PIN pad dialog for
role "user+signature" (Default:
"Please enter your digital signature
PIN on the PIN pad.").
Content of the PIN pad dialog for
role "admin" (Default:
"Please enter your PIN to unblock the
user PIN on the PIN pad.")
Expanded information of the PIN pad
dialog (Default: "This window will be
closed automatically after the PIN has been
submitted on the PIN pad (timeout typically
after 30 seconds).")
Allow the user to cancel the PIN
pad dialog (Default:
false).
If this value is set to
true, the user needs to
click "OK" to start the PIN verification on the
PIN pad. The user can choose the default
behavior by enabling or disabling the checkbox
of the dialog. The setting is saved by the
program's full path
(program_path) that
uses OpenSC.
The registry key HKCU\Software\OpenSC
Project\OpenSC\md_pinpad_dlg_enable_cancel\program_path
overwrites this setting with a
DWORD set to either
1 (enabled) or
0 (disabled).
Time in seconds for the progress
bar of the PIN pad dialog to tick.
0 removes the
progress bar (Default:
30).
Notification title and text when
card was inserted (Default:
"Smart card
detected", ATR of
the card).
Notification title and text when
card was removed (Default:
"Smart card
removed", name of
smart card reader).
Notification title and text when
PIN was verified (Default:
"PIN verified",
"Smart card is
unlocked").
Notification title and text when
PIN was wrong (Default:
"PIN not
verified",
"Smart card is
locked").
Configuration of PKCS#15 Framework
Whether to cache the card's files (e.g.
certificates) on disk in
(Default:
false).
If caching is done by a system process, the
cached files may be placed inaccessible from
the user account. Use a globally readable and
writable location if you wish to share the
cached information. Note that the cached files
may contain personal data such as name and mail
address.
Where to cache the card's files. The default values are:
HOME/.eid/cache/ (Unix)
USERPROFILE\.eid-cache\ (Windows)
If caching is done by a system process, the
cached files may be placed inaccessible from
a user account. Use a globally readable and
writable location if you wish to share the
cached information. Note that the cached files
may contain personal data such as name and mail
address.
Use PIN caching (Default: true)?
How many times to use a PIN from cache before
re-authenticating it (Default:
10)?
Older PKCS#11 applications not supporting
CKA_ALWAYS_AUTHENTICATE may
need to set this to get signatures to work with
some cards (Default: false).
It is recommended to enable also PIN caching using
use_pin_caching option for OpenSC
to be able to provide PIN for the card when needed.
How to handle a PIN-protected certificate. Known
parameters:
protect: The certificate stays PIN-protected.
declassify: Allow
reading the certificate without
enforcing verification of the PIN.
ignore: Ignore PIN-protected certificates.
(Default: ignore in Tokend,
protect otherwise).
Enable pkcs15 emulation (Default:
true).
Prefer pkcs15 emulation code before the normal
pkcs15 processing (Default:
no). Some cards work in
emu-only mode, and do not depend on this
option.
Enable builtin emulators (Default:
true).
List of the builtin pkcs15 emulators to test
(Default: westcos, openpgp,
starcert, tcos, esteid, itacns,
PIV-II, cac, gemsafeGPK, gemsafeV1, actalis,
atrust-acos, tccardos, entersafe, pteid,
oberthur, sc-hsm, dnie, gids, iasecc, jpki,
coolkey, din66291)
Enable initialization and card recognition
(Default: false).
Configuration options for a PKCS#15 emulator
where name is a
short name for an external card driver.
For pkcs15 emulators loaded from an
external shared library/DLL, you need to
specify the path name of the module and
customize the card_atr example above
correctly.
Get the init function name of the
emulator (Default:
sc_pkcs15_init_func_ex)
Configuration of the on-card-application where
hexstring is the
application identifier (AID).
Type of application where
name is one
of:
genericprotected
Used to distinguish the common access
application and application for which
authentication to perform some
operation cannot be obtained with the
common procedures (ex. object creation
protected by secure messaging). Used
by PKCS#11 module configured to expose
restricted number of slots. (for ex.
configured to expose only User PIN
slot, User and Sign PINs slots, ...)
Do not expose application in PKCS#15
framework (Default:
false)
Configuration of Tokend
Score for OpenSC.tokend
(Default: 300). The tokend with
the highest score shall be used.
Configuration of PKCS#11
Maximum Number of virtual slots (Default:
16). If there are more slots
than defined here, the remaining slots will be
hidden from PKCS#11.
Maximum number of slots per smart card (Default:
4). If the card has fewer keys
than defined here, the remaining number of slots
will be empty.
By default, the OpenSC PKCS#11 module will not lock
your card once you authenticate to the card via
C_Login (Default:
false).
Thus the other users or other applications is not
prevented from connecting to the card and perform
crypto operations (which may be possible because
you have already authenticated with the card). This
setting is not very secure.
Also, if your card is not locked, you can enconter
problems due to limitation of the OpenSC framework,
that still is not thoroughly tested in the multi
threads environment.
Your settings will be more secure if you choose to
lock your card. Nevertheless this behavior is a
known violation of PKCS#11 specification. Now once
one application has started using your card with
C_Login, no other application
can use it, until the first is done and calls
C_Logout or
C_Finalize. In the case of many
PKCS#11 application this does not happen until you
exit the application.
Thus it is impossible to use several smart card
aware applications at the same time, e.g. you
cannot run both Firefox
and Thunderbird at the
same time, if both are configured to use your smart
card.
By default, interacting with the OpenSC PKCS#11
module may change the state of the token, e.g.
whether a user is logged in or not (Default:
false).
Thus other users or other applications may change
or use the state of the token unknowingly. Other
applications may create signatures abusing an
existing login or they may logout unnoticed.
With this setting enabled the login state of the
token is tracked and cached (including the PIN).
Every transaction is preceded by restoring the
login state. After every transaction a logout is
performed. This setting by default also enables
to disable access for
other applications during the atomic transactions.
Please note that any PIN-pad should be disabled
(see ), because the
user would have to input his PIN for every
transaction.
With this setting disabled, the OpenSC PKCS#11
module will initialize the slots available when the
application calls C_GetSlotList.
With this setting enabled, the slots will also get
initialized when C_GetSlotInfo
is called (Default: true).
This setting is a workaround for
Java which does not call
C_GetSlotList when configured
with a static slot instead of
slotListIndex.
User PIN unblock style mode
is one of:
none (Default): PIN
unblock is not possible with PKCS#11 API
set_pin_in_unlogged_session:
C_SetPIN in unlogged
session: PUK is passed as the
OldPin argument of the
C_SetPIN call.
set_pin_in_specific_context:
C_SetPIN in the
CKU_SPECIFIC_CONTEXT
logged session: PUK is passed as the
OldPin argument of the
C_SetPIN call.
init_pin_in_so_session:
C_InitPIN in
CKU_SO logged session:
User PIN 'UNBLOCK' is protected by SOPIN.
(PUK == SOPIN).
Create slot for unblocking PIN with PUK (Default:
false). This way PKCS#11 API can
be used to login with PUK and change a PIN. May
cause problems with some applications like
Firefox and
Thunderbird.
Symbolic names of PINs for which slots are created
where mode is a list of:
all (Default): All
non-SO-PIN, non-unblocking PINs
user: The first
global or first local PIN
sign: The second PIN
(first local, second global or second
local)
Card can contain more then one PINs or more then
one on-card application with its own PINs.
Normally, to access all of them with the PKCS#11
API a slot has to be created for all of them. Many
slots could be annoying for some of widely used
application, like FireFox. This configuration
parameter allows to select the PIN(s) for which
PKCS#11 slot will be created.
Only PINs initialised, non-SO-PIN, non-unblocking
are associated with symbolic name.
For the module to simulate the opensc-onepin module
behavior the following option
EnvironmentOPENSC_CONF
Filename for a user defined configuration file
If this environment variable is not found on
Windows, the registry key
Software\OpenSC
Project\OpenSC\ConfigFile is
checked.
OPENSC_DEBUG
See OPENSC_DRIVER
See CARDMOD_LOW_LEVEL_DEBUG
Write minidriver debug information to
C:\tmp\md.log, if set to
1.
If this environment variable is not found on
Windows, the registry key
Software\OpenSC
Project\OpenSC\MiniDriverDebug is
checked.
PIV_EXT_AUTH_KEY,
PIV_9A_KEY,
PIV_9C_KEY,
PIV_9D_KEY,
PIV_9E_KEY
PIV configuration during initialization with
piv-tool.
Files@sysconfdir@/opensc.conf
System-wide configuration file
@docdir@/opensc.conf
Extended example configuration file