1717 lines
54 KiB
XML
1717 lines
54 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<refentry id="opensc.conf">
|
||
<refmeta>
|
||
<refentrytitle>opensc.conf</refentrytitle>
|
||
<manvolnum>5</manvolnum>
|
||
<refmiscinfo class="productname">OpenSC</refmiscinfo>
|
||
<refmiscinfo class="manual">OpenSC File Formats</refmiscinfo>
|
||
<refmiscinfo class="source">opensc</refmiscinfo>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>opensc.conf</refname>
|
||
<refpurpose>configuration file for OpenSC</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
<para>
|
||
OpenSC obtains configuration data from the following sources in the following order
|
||
<orderedlist>
|
||
<listitem><para>
|
||
command-line options
|
||
</para></listitem>
|
||
<listitem><para>
|
||
environment variables
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Windows registry key in
|
||
<literal>HKEY_CURRENT_USER</literal> (if available)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Windows registry key in
|
||
<literal>HKEY_LOCAL_MACHINE</literal> (if available)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
system-wide configuration file
|
||
(<literal>@sysconfdir@/opensc.conf</literal>)
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
<para>
|
||
The configuration file, <literal>opensc.conf</literal>, is composed
|
||
of <replaceable>block</replaceable>s, which, in general, have the
|
||
following format:
|
||
<programlisting>
|
||
<replaceable>key</replaceable><arg choice="opt" rep="repeat">, <replaceable>name</replaceable></arg> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</programlisting>
|
||
<replaceable>block_contents</replaceable> is one or more
|
||
<replaceable>block_item</replaceable>s where a
|
||
<replaceable>block_item</replaceable> is one of
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
# <replaceable>comment string</replaceable>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<replaceable>key</replaceable><arg choice="opt" rep="repeat">, <replaceable>name</replaceable></arg> = <replaceable>value</replaceable>;
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<replaceable>block</replaceable>
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
At the root level, <literal>opensc.conf</literal> should contain
|
||
one or more application specific configuration blocks:
|
||
<programlisting>
|
||
app <replaceable>application</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</programlisting>
|
||
<replaceable>application</replaceable>
|
||
specifies one of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>default</literal>: The fall-back configuration block for all applications
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>opensc-pkcs11</literal>: Configuration block for the PKCS#11 module (<filename>opensc-pkcs11@DYN_LIB_EXT@</filename>)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>onepin-opensc-pkcs11</literal>: Configuration block for the PKCS#11 one-PIN-module (<filename>onepin-opensc-pkcs11@DYN_LIB_EXT@</filename>)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>cardmod</literal>: Configuration block for Windows' minidriver (<filename>opensc-minidriver.dll</filename>)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>tokend</literal>: Configuration block for macOS' tokend (<application>OpenSC.tokend</application>)
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>cardos-tool</literal>,
|
||
<literal>cryptoflex-tool</literal>,
|
||
<literal>dnie-tool</literal>,
|
||
<literal>egk-tool</literal>,
|
||
<literal>eidenv</literal>,
|
||
<literal>gids-tool</literal>,
|
||
<literal>iasecc-tool</literal>,
|
||
<literal>netkey-tool</literal>,
|
||
<literal>npa-tool</literal>,
|
||
<literal>openpgp-tool</literal>,
|
||
<literal>opensc-asn1</literal>,
|
||
<literal>opensc-explorer</literal>,
|
||
<literal>opensc-notify</literal>,
|
||
<literal>opensc-tool</literal>,
|
||
<literal>piv-tool</literal>,
|
||
<literal>pkcs11-tool</literal>,
|
||
<literal>pkcs15-crypt</literal>,
|
||
<literal>pkcs15-init</literal>,
|
||
<literal>pkcs15-tool</literal>,
|
||
<literal>sc-hsm-tool</literal>,
|
||
<literal>westcos-tool</literal>:
|
||
Configuration block for OpenSC tools
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Configuration Options</title>
|
||
<variablelist>
|
||
<varlistentry id="debug">
|
||
<term>
|
||
<option>debug = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Amount of debug info to print (Default:
|
||
<literal>0</literal>). A greater value means more
|
||
debug info.
|
||
</para>
|
||
<para>
|
||
The environment variable
|
||
<envar>OPENSC_DEBUG</envar> overwrites this
|
||
setting.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>debug_file = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
The file to which debug output will be written
|
||
(Default: <literal>stderr</literal>). Special
|
||
values <literal>stdout</literal> and
|
||
<literal>stderr</literal> are recognized.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>profile_dir = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
PKCS#15 initialization/personalization profiles
|
||
directory for
|
||
<citerefentry>
|
||
<refentrytitle>pkcs15-init</refentrytitle>
|
||
<manvolnum>1</manvolnum>.
|
||
</citerefentry>
|
||
(Default: <literal>@PROFILE_DIR_DEFAULT@</literal>).
|
||
</para>
|
||
<para>
|
||
If this configuration value is not found on
|
||
Windows, the registry key
|
||
<filename>Software\OpenSC
|
||
Project\OpenSC\ProfileDir</filename> is
|
||
checked.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>disable_colors = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Disable colors of log messages (Default:
|
||
<literal>false</literal> if attached to a console,
|
||
<literal>true</literal> otherwise).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>disable_popups = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Disable pop-ups of built-in GUI (Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>enable_default_driver = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Enable default card driver (Default:
|
||
<literal>false</literal>). Default card driver is
|
||
explicitly enabled for
|
||
<citerefentry>
|
||
<refentrytitle>opensc-explorer</refentrytitle>
|
||
<manvolnum>1</manvolnum>.
|
||
</citerefentry>
|
||
and
|
||
<citerefentry>
|
||
<refentrytitle>opensc-tool</refentrytitle>
|
||
<manvolnum>1</manvolnum>.
|
||
</citerefentry>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry id="card_drivers">
|
||
<term>
|
||
<option>card_drivers = <arg choice="plain"
|
||
rep="repeat"><replaceable>name</replaceable></arg>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Whitelist of card drivers to load at start-up.
|
||
The special value <literal>internal</literal> (the
|
||
default) will load all statically linked drivers.
|
||
</para>
|
||
<para>
|
||
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 <literal>old</literal> will load all
|
||
statically linked drivers that may be removed in
|
||
the future.
|
||
</para>
|
||
<para>
|
||
The list of supported card driver names can be
|
||
retrieved from the output of <command>opensc-tool
|
||
--list-drivers</command>.
|
||
</para>
|
||
<para>
|
||
The environment variable
|
||
<envar>OPENSC_DRIVER</envar> overwrites this
|
||
setting.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>ignored_readers = <arg choice="plain"
|
||
rep="repeat"><replaceable>name</replaceable></arg>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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
|
||
<command>opensc-tool --list-readers</command> to
|
||
see all currently connected readers.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>reader_driver <replaceable>name</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Configuration of the smart card reader driver where <replaceable>name</replaceable> is one of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>ctapi</literal>: See <xref linkend="ctapi"/>
|
||
</para>
|
||
</listitem>
|
||
<listitem><para>
|
||
<literal>pcsc</literal>: See <xref linkend="pcsc"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>openct</literal>: See <xref linkend="openct"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>cryptotokenkit</literal>: Configuration block for CryptoTokenKit readers
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
See <xref linkend="reader_driver"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>card_driver <replaceable>name</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Configuration of the card driver where <replaceable>name</replaceable> is one of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>npa</literal>: See <xref linkend="npa"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>dnie</literal>: See <xref linkend="dnie"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>edo</literal>: See <xref linkend="edo"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>myeid</literal>: See <xref linkend="myeid"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Any other value: Configuration block for an externally loaded card driver
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>card_atr <replaceable>hexstring</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
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 <option>card_atr</option>
|
||
block.
|
||
</para>
|
||
<para>
|
||
For details see <xref linkend="card_atr"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>secure_messaging <replaceable>name</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Configuration options for the secure messaging profile <replaceable>name</replaceable>:
|
||
</para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>module_name = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Name of external SM module (Default: @DEFAULT_SM_MODULE@).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>module_path = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Directory with external SM module
|
||
(Default: @libdir@).
|
||
</para>
|
||
<para>
|
||
If this configuration value is not
|
||
found on Windows, the registry key
|
||
<filename>Software\OpenSC
|
||
Project\OpenSC\SmDir</filename> is
|
||
checked.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>module_data = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Specific data to tune the module initialization.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>mode = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Secure messaging mode. Known parameters:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>transmit</literal>:
|
||
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.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>acl</literal>:
|
||
In this mode APDU are
|
||
securized only if
|
||
needed by the ACLs of
|
||
the command to be
|
||
executed.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>flags = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Secure messaging type specific flags.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>kmc = <replaceable>hexstring</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Default KMC of the GP Card Manager for the Oberthur's Java cards.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>ifd_serial = <replaceable>hexstring</replaceable>;</option>
|
||
</term>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>keyset[_<replaceable>aid</replaceable>]_<replaceable>num</replaceable>_enc =
|
||
<replaceable>value</replaceable>;</option>
|
||
<option>keyset[_<replaceable>aid</replaceable>]_<replaceable>num</replaceable>_mac =
|
||
<replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Keyset values from IAM profiles of
|
||
the Gemalto IAS/ECC cards with an
|
||
optional application identifier
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>framework <replaceable>name</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Internal configuration options where <replaceable>name</replaceable> is one of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>pkcs15</literal>: See <xref linkend="framework pkcs15"/>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>tokend</literal>: See <xref linkend="framework tokend"/>
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>pkcs11 {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Parameters for the OpenSC PKCS11 module.
|
||
</para>
|
||
<para>
|
||
For details see <xref linkend="pkcs11"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<refsect2 id="reader_driver">
|
||
<title>Configuration of Smart Card Reader Driver</title>
|
||
|
||
<refsect3>
|
||
<title>Configuration Options for all Reader Drivers</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>max_send_size = <replaceable>num</replaceable>;</option>
|
||
<option>max_recv_size = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Limit command and response sizes
|
||
(Default:
|
||
<option>max_send_size</option>
|
||
= <literal>255</literal>,
|
||
<option>max_recv_size</option>
|
||
= <literal>256</literal>) . 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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>enable_escape <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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: <literal>false</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect3>
|
||
|
||
<refsect3 id="ctapi">
|
||
<title>Configuration of CT-API Readers</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>module <replaceable>filename</replaceable> {
|
||
ports = <replaceable>nums</replaceable>;
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Load the specified CT-API module with the specified number of ports.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect3>
|
||
|
||
<refsect3 id="pcsc">
|
||
<title>Configuration of PC/SC Readers</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>connect_exclusive = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Connect to reader in exclusive mode
|
||
(Default: <literal>false</literal>)?
|
||
This option has no effect in Windows' minidriver.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>disconnect_action = <replaceable>action</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
What to do when disconnecting from
|
||
a card (SCardDisconnect). Valid
|
||
values are
|
||
<literal>leave</literal>,
|
||
<literal>reset</literal>,
|
||
<literal>unpower</literal> (Default:
|
||
<literal>leave</literal>).
|
||
This option has no effect in Windows' minidriver.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>transaction_end_action = <replaceable>action</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
What to do at the end of a
|
||
transaction (SCardEndTransaction).
|
||
Valid values
|
||
are <literal>leave</literal>,
|
||
<literal>reset</literal>,
|
||
<literal>unpower</literal> (Default:
|
||
<literal>leave</literal>).
|
||
This option has no effect in Windows' minidriver.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>reconnect_action = <replaceable>action</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
What to do when reconnection to a
|
||
card (SCardReconnect). Valid values
|
||
are <literal>leave</literal>,
|
||
<literal>reset</literal>,
|
||
<literal>unpower</literal> (Default:
|
||
<literal>leave</literal>).
|
||
This option has no effect in Windows' minidriver.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>enable_pinpad = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Enable pinpad if detected (PC/SC
|
||
v2.0.2 Part 10, Default:
|
||
<literal>true</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>fixed_pinlength = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Some pinpad readers can only handle
|
||
one exact length of the PIN.
|
||
<option>fixed_pinlength</option>
|
||
sets this value so that OpenSC
|
||
expands the padding to this length
|
||
(Default: <literal>0</literal>,
|
||
i.e. not fixed).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>provider_library = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Use specific PC/SC provider
|
||
(Default:
|
||
<literal>@DEFAULT_PCSC_PROVIDER@</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect3>
|
||
|
||
<refsect3 id="openct">
|
||
<title>Configuration of OpenCT Readers</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>readers = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Virtual readers to allocate (Default: <literal>2</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect3>
|
||
|
||
</refsect2>
|
||
|
||
<refsect2 id="myeid">
|
||
<title>Configuration Options for MyEID Card</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>disable_hw_pkcs1_padding = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
The MyEID card can internally
|
||
encapsulate the data (hash code)
|
||
into a DigestInfo ASN.1 structure
|
||
according to the selected hash
|
||
algorithm (currently only for SHA1).
|
||
DigestInfo is padded to RSA key
|
||
modulus length according to PKCS#1
|
||
v1.5, block type 01h. Size of the
|
||
DigestInfo must not exceed 40%
|
||
of the RSA key modulus length. If
|
||
this limit is unsatisfactory (for
|
||
example someone needs RSA 1024
|
||
with SHA512), the user can disable
|
||
this feature. In this case, the
|
||
card driver will do everything
|
||
necessary before sending the data
|
||
(hash code) to the card.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="npa">
|
||
<title>Configuration Options for German ID Card</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>can = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>st_dv_certificate = <replaceable>filename</replaceable>;</option>
|
||
<option>st_certificate = <replaceable>filename</replaceable>;</option>
|
||
<option>st_key = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
An example PKI can be found in the
|
||
example data for the
|
||
<ulink
|
||
url="https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data">German
|
||
ID card emulator</ulink>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="dnie">
|
||
<title>Configuration Options for DNIe</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>user_consent_enabled = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Configure the warning message when
|
||
performing a signature operation
|
||
with the DNIe. Only used if
|
||
compiled with
|
||
<option>--enable-dnie-ui</option>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>user_consent_app = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Specify the pinentry application to
|
||
use if warning is configured to be
|
||
displayed using pinentry (Default:
|
||
<literal>/usr/bin/pinentry</literal>).
|
||
Only used if compiled with
|
||
<option>--enable-dnie-ui</option>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="edo">
|
||
<title>Configuration Options for Polish eID Card</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>can = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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 <literal>EDO_CAN</literal>
|
||
environment variable. Currently, it is not
|
||
possible to set it in any other way.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="card_atr">
|
||
<title>Configuration based on ATR</title>
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>atrmask = <replaceable>hexstring</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>driver = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
When enabled, overrides all
|
||
possible settings from the card
|
||
drivers built-in card configuration
|
||
list.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>name = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Set card name for card drivers that
|
||
allows it.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>type = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Allows setting the exact type of
|
||
the card internally used by the
|
||
card driver. Allowed values can be
|
||
found in the source code of
|
||
<filename>cards.h</filename>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>flags = <arg choice="plain"
|
||
rep="repeat"><replaceable>value</replaceable></arg>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
Optionally, some known parameters
|
||
can be specified as strings:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>rng</literal>:
|
||
On-board random number
|
||
source
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>keep_alive</literal>:
|
||
Request the card driver
|
||
to send a "keep alive"
|
||
command before each
|
||
transaction to make
|
||
sure that the required
|
||
applet is still
|
||
selected.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>pkcs15emu = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>force_protocol = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Force protocol selection for
|
||
specific cards. Known parameters:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>t0</literal>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>t1</literal>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>raw</literal>
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>read_only = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Mark card as read/only card in
|
||
PKCS#11/Minidriver/BaseCSP interface
|
||
(Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_supports_X509_enrollment = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Indicate X509 enrollment support at
|
||
Minidriver/BaseCSP interface
|
||
(Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_guid_as_id = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Use the GUID generated for the key
|
||
as id in the PKCS#15 structure
|
||
(Default: <literal>false</literal>, i.e. auto generated)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_guid_as_label = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Use the GUID generated for the key
|
||
as label in the PKCS#15 structure
|
||
(Default: <literal>false</literal>,
|
||
i.e. no label set).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_supports_container_key_gen = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Card allows generating key pairs on the card (Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_supports_container_key_import = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Card allows importing private keys
|
||
(Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_title = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Window title of the PIN pad dialog
|
||
(Default: <literal>"Windows
|
||
Security"</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_icon = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Filename of the icon for the PIN
|
||
pad dialog; use
|
||
<literal>""</literal> for no icon
|
||
(Default: Built-in smart card icon).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_main = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Main instruction of the PIN pad
|
||
dialog (Default: <literal>"OpenSC
|
||
Smart Card Provider"</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_content_user = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Content of the PIN pad dialog for
|
||
role "user" (Default:
|
||
<literal>"Please enter your PIN on the PIN
|
||
pad."</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_content_user_sign = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Content of the PIN pad dialog for
|
||
role "user+signature" (Default:
|
||
<literal>"Please enter your digital signature
|
||
PIN on the PIN pad."</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_content_admin = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Content of the PIN pad dialog for
|
||
role "admin" (Default:
|
||
<literal>"Please enter your PIN to unblock the
|
||
user PIN on the PIN pad."</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_expanded = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Expanded information of the PIN pad
|
||
dialog (Default: <literal>"This window will be
|
||
closed automatically after the PIN has been
|
||
submitted on the PIN pad (timeout typically
|
||
after 30 seconds)."</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_enable_cancel = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Allow the user to cancel the PIN
|
||
pad dialog (Default:
|
||
<literal>false</literal>).
|
||
|
||
If this value is set to
|
||
<literal>true</literal>, 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
|
||
(<replaceable>program_path</replaceable>) that
|
||
uses OpenSC.
|
||
</para>
|
||
<para>
|
||
The registry key <filename>HKCU\Software\OpenSC
|
||
Project\OpenSC\md_pinpad_dlg_enable_cancel\<replaceable>program_path</replaceable></filename>
|
||
overwrites this setting with a
|
||
<literal>DWORD</literal> set to either
|
||
<literal>1</literal> (enabled) or
|
||
<literal>0</literal> (disabled).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>md_pinpad_dlg_timeout = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Time in seconds for the progress
|
||
bar of the PIN pad dialog to tick.
|
||
<literal>0</literal> removes the
|
||
progress bar (Default:
|
||
<literal>30</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>notify_card_inserted = <replaceable>value</replaceable>;</option>
|
||
<option>notify_card_inserted_text = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Notification title and text when
|
||
card was inserted (Default:
|
||
<literal>"Smart card
|
||
detected"</literal>, ATR of
|
||
the card).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>notify_card_removed = <replaceable>value</replaceable>;</option>
|
||
<option>notify_card_removed_text = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Notification title and text when
|
||
card was removed (Default:
|
||
<literal>"Smart card
|
||
removed"</literal>, name of
|
||
smart card reader).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>notify_pin_good = <replaceable>value</replaceable>;</option>
|
||
<option>notify_pin_good_text = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Notification title and text when
|
||
PIN was verified (Default:
|
||
<literal>"PIN verified"</literal>,
|
||
<literal>"Smart card is
|
||
unlocked"</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>notify_pin_bad = <replaceable>value</replaceable>;</option>
|
||
<option>notify_pin_bad_text = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Notification title and text when
|
||
PIN was wrong (Default:
|
||
<literal>"PIN not
|
||
verified"</literal>,
|
||
<literal>"Smart card is
|
||
locked"</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</refsect2>
|
||
|
||
<refsect2 id="framework pkcs15">
|
||
<title>Configuration of PKCS#15 Framework</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>use_file_caching = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Whether to cache the card's files (e.g.
|
||
certificates) on disk in
|
||
<option>file_cache_dir</option> (Default:
|
||
<literal>false</literal>).
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>file_cache_dir = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Where to cache the card's files. The default values are:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<filename><envar>$XDG_CACHE_HOME</envar>/opensc/</filename> (If <envar>$XDG_CACHE_HOME</envar> is defined)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<filename><envar>$HOME</envar>/.cache/opensc/</filename> (Unix)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<filename><envar>$USERPROFILE</envar>\.eid-cache\</filename> (Windows)
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>use_pin_caching = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Use PIN caching (Default: <literal>true</literal>)?
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>pin_cache_counter = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
How many times to use a PIN from cache before
|
||
re-authenticating it (Default:
|
||
<literal>10</literal>)?
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>pin_cache_ignore_user_consent = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Older PKCS#11 applications not supporting
|
||
<literal>CKA_ALWAYS_AUTHENTICATE</literal> may
|
||
need to set this to get signatures to work with
|
||
some cards (Default: <literal>false</literal>).
|
||
</para>
|
||
<para>
|
||
It is recommended to enable also PIN caching using
|
||
<literal>use_pin_caching</literal> option for OpenSC
|
||
to be able to provide PIN for the card when needed.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>private_certificate = <replaceable>value</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
How to handle a PIN-protected certificate. Known
|
||
parameters:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>protect</literal>: The certificate stays PIN-protected.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>declassify</literal>: Allow
|
||
reading the certificate without
|
||
enforcing verification of the PIN.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>ignore</literal>: Ignore PIN-protected certificates.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
(Default: <literal>ignore</literal> in Tokend,
|
||
<literal>protect</literal> otherwise).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>enable_pkcs15_emulation = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Enable pkcs15 emulation (Default:
|
||
<literal>true</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>try_emulation_first = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Prefer pkcs15 emulation code before the normal
|
||
pkcs15 processing (Default:
|
||
<literal>no</literal>). Some cards work in
|
||
emu-only mode, and do not depend on this
|
||
option.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>enable_builtin_emulation = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Enable builtin emulators (Default:
|
||
<literal>true</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>builtin_emulators = <replaceable>emulators</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
List of the builtin pkcs15 emulators to test
|
||
(Default: <literal>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</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>pkcs11_enable_InitToken = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Enable initialization and card recognition
|
||
(Default: <literal>false</literal>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>emulate <replaceable>name</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem><para>
|
||
Configuration options for a PKCS#15 emulator
|
||
where <replaceable>name</replaceable> is a
|
||
short name for an external card driver.
|
||
</para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>module = <replaceable>filename</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>function = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Get the init function name of the
|
||
emulator (Default:
|
||
<literal>sc_pkcs15_init_func_ex</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>application <replaceable>hexstring</replaceable> {
|
||
<replaceable>block_contents</replaceable>
|
||
}
|
||
</option>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Configuration of the on-card-application where
|
||
<replaceable>hexstring</replaceable> is the
|
||
application identifier (AID).
|
||
</para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>type = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Type of application where
|
||
<replaceable>name</replaceable> is one
|
||
of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>generic</literal>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>protected</literal>
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
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, ...)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>model = <replaceable>name</replaceable>;</option>
|
||
</term>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>disable = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Do not expose application in PKCS#15
|
||
framework (Default:
|
||
<literal>false</literal>)
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="framework tokend">
|
||
<title>Configuration of Tokend</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>score = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Score for <application>OpenSC.tokend</application>
|
||
(Default: <literal>300</literal>). The tokend with
|
||
the highest score shall be used.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2 id="pkcs11">
|
||
<title>Configuration of PKCS#11</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>max_virtual_slots = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Maximum Number of virtual slots (Default:
|
||
<literal>16</literal>). If there are more slots
|
||
than defined here, the remaining slots will be
|
||
hidden from PKCS#11.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>slots_per_card = <replaceable>num</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Maximum number of slots per smart card (Default:
|
||
<literal>4</literal>). If the card has fewer keys
|
||
than defined here, the remaining number of slots
|
||
will be empty.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>lock_login = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
By default, the OpenSC PKCS#11 module will not lock
|
||
your card once you authenticate to the card via
|
||
<literal>C_Login</literal> (Default:
|
||
<literal>false</literal>).
|
||
|
||
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.
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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
|
||
<literal>C_Login</literal>, no other application
|
||
can use it, until the first is done and calls
|
||
<literal>C_Logout</literal> or
|
||
<literal>C_Finalize</literal>. In the case of many
|
||
PKCS#11 application this does not happen until you
|
||
exit the application.
|
||
</para>
|
||
<para>
|
||
Thus it is impossible to use several smart card
|
||
aware applications at the same time, e.g. you
|
||
cannot run both <application>Firefox</application>
|
||
and <application>Thunderbird</application> at the
|
||
same time, if both are configured to use your smart
|
||
card.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>atomic = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
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:
|
||
<literal>false</literal>).
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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
|
||
<option>lock_login</option> to disable access for
|
||
other applications during the atomic transactions.
|
||
</para>
|
||
<para>
|
||
Please note that any PIN-pad should be disabled
|
||
(see <option>enable_pinpad</option>), because the
|
||
user would have to input his PIN for every
|
||
transaction.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>init_sloppy = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
With this setting disabled, the OpenSC PKCS#11
|
||
module will initialize the slots available when the
|
||
application calls <literal>C_GetSlotList</literal>.
|
||
With this setting enabled, the slots will also get
|
||
initialized when <literal>C_GetSlotInfo</literal>
|
||
is called (Default: <literal>true</literal>).
|
||
</para>
|
||
<para>
|
||
This setting is a workaround for
|
||
<application>Java</application> which does not call
|
||
<literal>C_GetSlotList</literal> when configured
|
||
with a static <literal>slot</literal> instead of
|
||
<literal>slotListIndex</literal>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>user_pin_unblock_style = <replaceable>mode</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
User PIN unblock style <replaceable>mode</replaceable>
|
||
is one of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>none</literal> (Default): PIN
|
||
unblock is not possible with PKCS#11 API
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>set_pin_in_unlogged_session</literal>:
|
||
<literal>C_SetPIN</literal> in unlogged
|
||
session: PUK is passed as the
|
||
<literal>OldPin</literal> argument of the
|
||
<literal>C_SetPIN</literal> call.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>set_pin_in_specific_context</literal>:
|
||
<literal>C_SetPIN</literal> in the
|
||
<literal>CKU_SPECIFIC_CONTEXT</literal>
|
||
logged session: PUK is passed as the
|
||
<literal>OldPin</literal> argument of the
|
||
<literal>C_SetPIN</literal> call.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>init_pin_in_so_session</literal>:
|
||
<literal>C_InitPIN</literal> in
|
||
<literal>CKU_SO</literal> logged session:
|
||
User PIN 'UNBLOCK' is protected by SOPIN.
|
||
(PUK == SOPIN).
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>create_puk_slot = <replaceable>bool</replaceable>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Create slot for unblocking PIN with PUK (Default:
|
||
<literal>false</literal>). This way PKCS#11 API can
|
||
be used to login with PUK and change a PIN. May
|
||
cause problems with some applications like
|
||
<application>Firefox</application> and
|
||
<application>Thunderbird</application>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>create_slots_for_pins = <arg choice="plain"
|
||
rep="repeat"><replaceable>mode</replaceable></arg>;</option>
|
||
</term>
|
||
<listitem><para>
|
||
Symbolic names of PINs for which slots are created
|
||
where <replaceable>mode</replaceable> is a list of:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<literal>all</literal> (Default): All
|
||
non-SO-PIN, non-unblocking PINs
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>user</literal>: The first
|
||
global or first local PIN
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<literal>sign</literal>: The second PIN
|
||
(first local, second global or second
|
||
local)
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
Only PINs initialised, non-SO-PIN, non-unblocking
|
||
are associated with symbolic name.
|
||
</para>
|
||
<para>
|
||
For the module to simulate the opensc-onepin module
|
||
behavior the following option
|
||
<option>create_slots_for_pins = "user";</option>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Environment</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<envar>OPENSC_CONF</envar>
|
||
</term>
|
||
<listitem><para>
|
||
Filename for a user defined configuration file
|
||
</para>
|
||
<para>
|
||
If this environment variable is not found on
|
||
Windows, the registry key
|
||
<filename>Software\OpenSC
|
||
Project\OpenSC\ConfigFile</filename> is
|
||
checked.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<envar>OPENSC_DEBUG</envar>
|
||
</term>
|
||
<listitem><para>
|
||
See <xref linkend="debug"/>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<envar>OPENSC_DRIVER</envar>
|
||
</term>
|
||
<listitem><para>
|
||
See <xref linkend="card_drivers"/>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<envar>CARDMOD_LOW_LEVEL_DEBUG</envar>
|
||
</term>
|
||
<listitem><para>
|
||
Write minidriver debug information to
|
||
<filename>C:\tmp\md.log</filename>, if set to
|
||
<literal>1</literal>.
|
||
</para>
|
||
<para>
|
||
If this environment variable is not found on
|
||
Windows, the registry key
|
||
<filename>Software\OpenSC
|
||
Project\OpenSC\MiniDriverDebug</filename> is
|
||
checked.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<envar>PIV_EXT_AUTH_KEY</envar>,
|
||
<envar>PIV_9A_KEY</envar>,
|
||
<envar>PIV_9C_KEY</envar>,
|
||
<envar>PIV_9D_KEY</envar>,
|
||
<envar>PIV_9E_KEY</envar>
|
||
</term>
|
||
<listitem><para>
|
||
PIV configuration during initialization with
|
||
<application>piv-tool</application>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Files</title>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<filename>@sysconfdir@/opensc.conf</filename>
|
||
</term>
|
||
<listitem><para>
|
||
System-wide configuration file
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<filename>@docdir@/opensc.conf</filename>
|
||
</term>
|
||
<listitem><para>
|
||
Extended example configuration file
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
</refentry>
|