<?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><replaceable>filename</replaceable></literal>: Configuration block for the application with specified file path.
				</para></listitem>
				<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>
						Allowlist 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>eoi</literal>: See <xref linkend="eoi"/>
							</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>disable_hw_pkcs1_padding = <replaceable>value</replaceable>;</option>
				</term>
				<listitem><para>
						Disabling PKCS#1 v1.5 padding in HW when card supports doing raw RSA operations.
						Known parameters:
						<itemizedlist>
							<listitem><para>
									<literal>no</literal>: PKCS#1 v1.5 padding is enabled in HW when card supports it.
							</para></listitem>
							<listitem><para>
									<literal>sign</literal>: PKCS#1 v1.5 padding
								is disabled only for signatures (PKCS#1 v1.5 type 1).
							</para></listitem>
							<listitem><para>
									<literal>decipher</literal>: PKCS#1 v1.5 padding
								is disabled only for decryption (PKCS#1 v1.5 type 2).
							</para></listitem>
							<listitem><para>
									<literal>both</literal>: PKCS#1 v1.5 padding
								is disabled both for signatures and decryption (PKCS#1 v1.5 type 1 and 2).
							</para></listitem>
						</itemizedlist>
						(Default: <literal>decipher</literal>).
				</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><para>
							PKCS#1 v1.5 padding in HW can be globally disabled by option <literal>disable_hw_pkcs1_padding</literal>.
							When the global option is used to disable padding, the padding will be disabled even though the MyEID-specific option does not turn it off.
					</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="eoi">
			<title>Configuration Options for Slovenian 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>EOI_CAN</literal>
							environment variable. As CAN is also stored on the card
							(in encrypted form) it can be used to automatically establish
							secure connection, but only if the card is accessed over the
							contact interface.
					</para></listitem>
				</varlistentry>
			</variablelist>
		</refsect2>

		<refsect2 id="piv">
			<title>Configuration Options for PIV Card</title>
			<variablelist>
				<!-- Commented out until PIV SM is built be default
				<varlistentry>
					<term><option>piv_use_sm = <replaceable>name</replaceable>;</option>
					</term>
					<listitem><para>
						Use optional secure messaging as define by NIST SP 800-73-4
					<replaceable>name</replaceable> is one of:
					<itemizedlist>
						<listitem><para><literal>always</literal>
							- Use secure messaging for commands.
						</para></listitem>
						<listitem><para><literal>never</literal>
							- Used for debugging.  Card may still require use of secure messaging.
						</para></listitem>
					</itemizedlist>
						Ignored if card does not support secure messaging.
						Default is use secure messaging as required by card issuer
						policies which are different for contact and contactless.
						It might be overwritten by <literal>PIV_USE_SM</literal>
						environment variable.
					</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>piv_pairing_code = <replaceable>num</replaceable>;</option>
					</term>
					<listitem><para>
						Ignored if card does not support piv_pairing_code.
						Card issuer may require a pairing code be used especially over contactless
						reader. Not normally used in conf file because pairing code is card specific.
						Use <literal>PIV_PAIRING_CODE</literal> environment variable.
					</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>value</replaceable>;</option>
					</term>
					<listitem><para>
							Whether to cache the card's files (e.g.
							certificates) on disk in
							<option>file_cache_dir</option>.
							Possible parameters:
							<itemizedlist>
								<listitem><para>
									<literal>yes</literal>: Cache all files (public and private).
								</para></listitem>
								<listitem><para>
									<literal>public</literal>: Cache only public files.
								</para></listitem>
								<listitem><para>
									<literal>no</literal>: File caching disabled.
								</para></listitem>
							</itemizedlist>
							(Default: <literal>public</literal>
							for the following card drivers
							<literal>atrust-acos</literal> (deactivated driver),
							<literal>belpic</literal>,
							<literal>cac1</literal>,
							<literal>cac</literal>,
							<literal>coolkey</literal>,
							<literal>dnie</literal>,
							<literal>edo</literal>,
							<literal>esteid2018</literal>,
							<literal>flex</literal> (deactivated driver),
							<literal>cyberflex</literal> (deactivated driver),
							<literal>gemsafeV1</literal>,
							<literal>idprime</literal>,
							<literal>itacns</literal>,
							<literal>jpki</literal>,
							<literal>MaskTech</literal>,
							<literal>mcrd</literal> (deactivated driver),
							<literal>npa</literal>,
							<literal>nqapplet</literal>,
							<literal>tcos</literal> and otherwise <literal>no</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>
						<para>
                            The PIV-II card driver supports the history object's
                            list of retired keys and certificates if they are
							readable in the file cache directory.
							If the specified object's URL is
							<literal>"http://"</literal><replaceable>DNS name</replaceable><literal>"/"</literal><replaceable>ASCII-HEX OffCardKeyHistoryFile</replaceable>,
							then the searches for the file name
							<replaceable>OffCardKeyHistoryFile</replaceable>
							in the cache directory.
					</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>pin_protected_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>internal</literal>)
						</para>
						<para>
							Special value of <literal>internal</literal> will try all not disabled builtin pkcs15 emulators.
						</para>
						<para>
							Special value of <literal>old</literal> will try all disabled pkcs15 emulators.
					</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>
							<varlistentry>
								<term>
									<option>user_pin = <replaceable>name</replaceable>;</option>
								</term>
								<listitem><para>
									Name of the User PIN object that will be used as the main PIN.
								</para></listitem>
							</varlistentry>
							<varlistentry>
								<term>
									<option>sign_pin = <replaceable>name</replaceable>;</option>
								</term>
								<listitem><para>
									Name of the PIN object that will be used for signing.
								</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 PIN slots per smart card (Default:
							<literal>4</literal>).  If the card has fewer PINs
							than defined here, the remaining number of slots
                            will be empty. For Firefox, Chrome and Chromium, the
							<option>slots_per_card</option> is set to <literal>1</literal>,
							to avoid prompting for unrelated PINs.  Typically, this
							effectively disables signature PINs and keys.
					</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>
			<varlistentry>
				<term>
					<envar>PIV_USE_SM</envar>,
					<envar>PIV_PAIRING_CODE</envar>
				</term>
				<listitem><para>
						PIV configuration during initialization
						See Configuration Options for PIV Card.
				</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>