resolvconf.conf

package: openresolv

title: resolvconf.conf(5)

summary: resolvconf configuration file

text:
# resolvconf.conf(5)

## NAME
resolvconf.conf — resolvconf configuration file

## DESCRIPTION
resolvconf.conf is the configuration file for resolvconf(8). The resolvconf.conf file is a shell script that is sourced by resolvconf(8), meaning that resolvconf.conf must contain valid shell commands. Listed below are the standard resolvconf.conf variables that may be set. If the values contain whitespace, wildcards or other special shell characters, ensure they are quoted and escaped correctly. See the replace variable for an example on quoting.

After updating this file, you may wish to run resolvconf -u to apply the new configuration.

When a dynamically generated list is appended or prepended to, the whole is made unique where left-most wins.

## RESOLVCONF OPTIONS
resolvconf

Set to NO to disable resolvconf from running any subscribers. Defaults to YES.

allow_interfaces

If set, only these interfaces will be processed.

deny_interfaces

If set, these interfaces will not be processed.

exclude

Is a space separated list of key/value pairs to match. If all key/value pairs in one element can be found in the file, then the whole file will be excluded from processing. The syntax is this: $keyword/$match[/$keyword/$match] For example given this configuration:

```
exclude="search/foo*/nameserver/1.2.3.4 search/bar.org"
```

Then any resolv.conf with both a search option starting with foo with a nameserver of 1.2.3.4 OR a search option of bar.org would be excluded.

interface_order

These interfaces will always be processed first. If unset, defaults to the following:-

```
lo lo[0-9]* lo.*
```

dynamic_order

These interfaces will be processed next, unless they have a metric. If unset, defaults to the following:-

```
tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]*
```

inclusive_interfaces

Ignore any exclusive marking for these interfaces. This is handy when 3rd party integrations force the resolvconf -x option and you want to disable it easily.

local_nameservers

If unset, defaults to the following:-

```
127.* 0.0.0.0 255.255.255.255 ::1
```

search_domains

Prepend search domains to the dynamically generated list.

search_domains_append

Append search domains to the dynamically generated list.

domain_blacklist

A list of domains to be removed from consideration. To remove a domain, you can use foo.* To remove a sub domain, you can use *.bar

name_servers

Prepend name servers to the dynamically generated list. You should set this to 127.0.0.1 if you use a local name server other than libc.

name_servers_append

Append name servers to the dynamically generated list.

name_server_blacklist

A list of name servers to be removed from consideration. The default is 0.0.0.0 as some faulty routers send it via DHCP. To remove a block, you can use 192.168.*

private_interfaces

These interfaces name servers will only be queried for the domains listed in their resolv.conf. Useful for VPN domains. Setting private_interfaces="*" will stop the forwarding of the root zone and allows the local resolver to recursively query the root servers directly. Requires a local nameserver other than libc. This is equivalent to the resolvconf -p option.

public_interfaces

Force these interface to be public, overriding the private marking. This is handy when 3rd party integrations force the resolvconf -p option and you want to disable it easily.

replace

Is a space separated list of replacement keywords. The syntax is this: $keyword/$match/$replacement Example, given this resolv.conf:

```
domain foo.org
search foo.org dead.beef
nameserver 1.2.3.4
nameserver 2.3.4.5
```

and this configuration:

```
replace="search/foo*/bar.com"
replace="$replace nameserver/1.2.3.4/5.6.7.8"
replace="$replace nameserver/2.3.4.5/"
```

you would get this resolv.conf instead:

```
domain foo.org
search bar.com
nameserver 5.6.7.8
```

replace_sub

Works the same way as replace except it works on each space separated value rather than the whole line, so it's useful for the replacing a single domain within the search directive. Using the same example resolv.conf and changing replace to replace_sub, you would get this resolv.conf instead:

```
domain foo.org
search bar.com dead.beef
nameserver 5.6.7.8
```

state_dir

Override the default state directory of /run/resolvconf. This should not be changed once resolvconf is in use unless the old directory is copied to the new one.

## LIBC OPTIONS
The following variables affect resolv.conf(5) directly:-

resolv_conf

Defaults to /etc/resolv.conf if not set.

resolv_conf_options

A list of libc resolver options, as specified in resolv.conf(5).

resolv_conf_passthrough

When set to YES the latest resolv.conf is written to resolv_conf without any alteration. When set to /dev/null or NULL, resolv_conf_local_only is defaulted to NO, local_nameservers is unset unless overridden and only the information set in resolvconf.conf is written to resolv_conf.

resolv_conf_sortlist

A libc resolver sortlist, as specified in resolv.conf(5).

resolv_conf_local_only

If a local name server is configured then the default is just to specify that and ignore all other entries as they will be configured for the local name server. Set this to NO to also list non-local nameservers. This will give you working DNS even if the local nameserver stops functioning at the expense of duplicated server queries.

append_nameservers

Append name servers to the dynamically generated list.

prepend_nameservers

Prepend name servers to the dynamically generated list.

append_search

Append search domains to the dynamically generated list.

prepend_search

Prepend search domains to the dynamically generated list.

resolv_conf_mv

Defaults to NO. Defines if /etc/resolv.conf is updated by writing to a temporary file and then moving it vs writing directly to it.

## SUBSCRIBER OPTIONS
openresolv ships with subscribers for the name servers dnsmasq(8), named(8), pdnsd(8), pdns_recursor(1), and unbound(8). Each subscriber can create configuration files which should be included in the subscribers main configuration file.

To disable a subscriber, simply set its name to NO. For example, to disable the libc subscriber you would set:

```
libc=NO
```

dnsmasq_conf

This file tells dnsmasq which name servers to use for specific domains.

dnsmasq_resolv

This file tells dnsmasq which name servers to use for global lookups. Example resolvconf.conf for dnsmasq:

```
name_servers=127.0.0.1
dnsmasq_conf=/etc/dnsmasq-conf.conf
dnsmasq_resolv=/etc/dnsmasq-resolv.conf
```

Example dnsmasq.conf:

```
listen-address=127.0.0.1
# If dnsmasq is compiled for DBus then we can take
# advantage of not having to restart dnsmasq.
enable-dbus
conf-file=/etc/dnsmasq-conf.conf
resolv-file=/etc/dnsmasq-resolv.conf
```

named_options

Include this file in the named options block. This file tells named which name servers to use for global lookups.

named_zones

Include this file in the named global scope, after the options block. This file tells named which name servers to use for specific domains. Example resolvconf.conf for named:

```
name_servers=127.0.0.1
named_options=/etc/named-options.conf
named_zones=/etc/named-zones.conf
```

Example named.conf:

```
options {
	listen-on { 127.0.0.1; };
	include "/etc/named-options.conf";
};

include "/etc/named-zones.conf";
```

pdnsd_conf

This is the main pdnsd configuration file which we modify to add our forward domains to. If this variable is not set then we rely on the pdnsd configuration file setup to read pdnsd_resolv as documented below.

pdnsd_resolv

This file tells pdnsd about global name servers. If this variable is not set then it's written to pdnsd_conf. Example resolvconf.conf for pdnsd:

```
name_servers=127.0.0.1
pdnsd_conf=/etc/pdnsd.conf
# pdnsd_resolv=/etc/pdnsd-resolv.conf
```

Example pdnsd.conf:

```
global {
	server_ip = 127.0.0.1;
	status_ctl = on;
}
server {
	# A server definition is required, even if empty.
	label="empty";
	proxy_only=on;
	# file="/etc/pdnsd-resolv.conf";
}
```

pdns_zones

This file tells pdns_recursor about specific and global name servers. Example resolvconf.conf for pdns_recursor:

```
name_servers=127.0.0.1
pdns_zones=/etc/pdns/recursor-zones.conf
```

Example recursor.conf:

```
allow-from=127.0.0.0/8, ::1/128
forward-zones-file=/etc/pdns/recursor-zones.conf
```

unbound_conf

This file tells unbound about specific and global name servers.

unbound_insecure

When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC.

unbound_private

When set to YES, unbound marks the domains as private, allowing it and its subdomains to contain private addresses.

unbound_forward_zone_options

Options appended to each forward zone. Each option should be separated by an embedded new line. Example resolvconf.conf for unbound:

```
name_servers=127.0.0.1
unbound_conf=/etc/unbound-resolvconf.conf
```

Example unbound.conf:

```
include: /etc/unbound-resolvconf.conf
```

## SUBSCRIBER INTEGRATION
Not all distributions store the files the subscribers need in the same locations. For example, named service scripts have been called named, bind and rc.bind and they could be located in a directory called /etc/rc.d, /etc/init.d or similar. Each subscriber attempts to automatically configure itself, but not every distribution has been catered for. Also, users could equally want to use a different version from the one installed by default, such as bind8 and bind9. To accommodate this, the subscribers have these files in configurable variables, documented below.

dnsmasq_service

Name of the dnsmasq service.

dnsmasq_restart

Command to restart the dnsmasq service.

dnsmasq_pid

Location of the dnsmasq pidfile.

libc_service

Name of the libc service.

libc_restart

Command to restart the libc service.

named_service

Name of the named service.

named_restart

Command to restart the named service.

pdnsd_restart

Command to restart the pdnsd service.

pdns_service

Command to restart the pdns_recursor service.

pdns_restart

Command to restart the pdns_recursor service.

unbound_service

Name of the unbound service.

unbound_restart

Command to restart the unbound service.

unbound_pid

Location of the unbound pidfile.

## SEE ALSO
sh(1), resolv.conf(5), resolvconf(8)

## AUTHORS
Roy Marples <roy@marples.name>

## BUGS
Each distribution is a special snowflake and likes to name the same thing differently, namely the named service script.

Please report them to https://roy.marples.name/projects/openresolv


opensc.conf

package: opensc

title: opensc.conf(5)

summary: configuration file for OpenSC

text:
# opensc.conf(5)

## NAME
opensc.conf - configuration file for OpenSC

## DESCRIPTION
OpenSC obtains configuration data from the following sources in the following order

1.command-line options

2.environment variables

3.Windows registry key in HKEY_CURRENT_USER (if available)

4.Windows registry key in HKEY_LOCAL_MACHINE (if available)

5.system-wide configuration file (/etc/opensc.conf)

The configuration file, opensc.conf, is composed of blocks, which, in general, have the following format:

```
key [, name...] {
	block_contents
}

```

block_contents is one or more block_items where a block_item is one of

•# comment string

•key[, name...] = value;

•block

At the root level, opensc.conf should contain one or more application specific configuration blocks:

```
app application {
	block_contents
}

```

application specifies one of:

•filename: Configuration block for the application with specified file path.

•default: The fall-back configuration block for all applications

•opensc-pkcs11: Configuration block for the PKCS#11 module (opensc-pkcs11.so)

•onepin-opensc-pkcs11: Configuration block for the PKCS#11 one-PIN-module (onepin-opensc-pkcs11.so)

•cardmod: Configuration block for Windows' minidriver (opensc-minidriver.dll)

•cardos-tool, cryptoflex-tool, dnie-tool, egk-tool, eidenv, gids-tool, iasecc-tool, netkey-tool, npa-tool, openpgp-tool, opensc-asn1, opensc-explorer, opensc-notify, opensc-tool, piv-tool, pkcs11-tool, pkcs15-crypt, pkcs15-init, pkcs15-tool, sc-hsm-tool, westcos-tool: Configuration block for OpenSC tools

## CONFIGURATION OPTIONS
debug = num;

Amount of debug info to print (Default: 0). A greater value means more debug info. The environment variable OPENSC_DEBUG overwrites this setting.

debug_file = filename;

The file to which debug output will be written (Default: stderr). Special values stdout and stderr are recognized.

profile_dir = filename;

PKCS#15 initialization/personalization profiles directory for pkcs15-init(1) (Default: /usr/share/opensc). If this configuration value is not found on Windows, the registry key Software\OpenSC Project\OpenSC\ProfileDir is checked.

disable_colors = bool;

Disable colors of log messages (Default: false if attached to a console, true otherwise).

disable_popups = bool;

Disable pop-ups of built-in GUI (Default: false).

enable_default_driver = bool;

Enable default card driver (Default: false). Default card driver is explicitly enabled for opensc-explorer(1) and opensc-tool(1)

card_drivers = name...;

Allowlist of card drivers to load at start-up. The special value internal (the default) will load all statically linked drivers. If an unknown (i.e. not internal or old) driver is supplied, a separate configuration block has to be written for the driver. A special value old will load all statically linked drivers that may be removed in the future.

The list of supported card driver names can be retrieved from the output of opensc-tool --list-drivers.

The environment variable OPENSC_DRIVER overwrites this setting.

ignored_readers = name...;

List of readers to ignore (Default: empty). If any of the comma separated strings listed is matched in a reader name (case sensitive, partial matching possible), the reader is ignored by OpenSC. Use opensc-tool --list-readers to see all currently connected readers.

reader_driver name { block_contents }

Configuration of the smart card reader driver where name is one of:

•ctapi: See the section called “Configuration of CT-API Readers”

•pcsc: See the section called “Configuration of PC/SC Readers”

•openct: See the section called “Configuration of OpenCT Readers”

•cryptotokenkit: Configuration block for CryptoTokenKit readers

See the section called “Configuration of Smart Card Reader Driver”.

card_driver name { block_contents }

Configuration of the card driver where name is one of:

•npa: See the section called “Configuration Options for German ID Card”

•dnie: See the section called “Configuration Options for DNIe”

•edo: See the section called “Configuration Options for Polish eID Card”

•eoi: See the section called “Configuration Options for Slovenian eID Card”

•myeid: See the section called “Configuration Options for MyEID Card”

•dtrust: See the section called “Configuration Options for D-Trust Signature Cards”

•Any other value: Configuration block for an externally loaded card driver

card_atr hexstring { block_contents }

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 card_atr block. For details see the section called “Configuration based on ATR”.

disable_hw_pkcs1_padding = value;

Disabling PKCS#1 v1.5 padding in HW when card supports doing raw RSA operations. Known parameters:

•no: PKCS#1 v1.5 padding is enabled in HW when card supports it.

•sign: PKCS#1 v1.5 padding is disabled only for signatures (PKCS#1 v1.5 type 1).

•decipher: PKCS#1 v1.5 padding is disabled only for decryption (PKCS#1 v1.5 type 2).

•both: PKCS#1 v1.5 padding is disabled both for signatures and decryption (PKCS#1 v1.5 type 1 and 2).

(Default: decipher).

openssl_config = path;

Specify a OpenSSL configuration file to be loaded into the OpenSC's library context. This should not be needed for general operation, but is needed if you need to configure some specifics of OpenSSL, without the need to rebuild OpenSC (for example configure and load a FIPS provider). For more information about configuring OpenSSL, see config(5) and fips_config(5). (Default: empty).

secure_messaging name { block_contents }

Configuration options for the secure messaging profile name: module_name = filename;

Name of external SM module (Default: libsmm-local.so).

module_path = filename;

Directory with external SM module (Default: /usr/lib64). If this configuration value is not found on Windows, the registry key Software\OpenSC Project\OpenSC\SmDir is checked.

module_data = value;

Specific data to tune the module initialization.

mode = value;

Secure messaging mode. Known parameters:

•transmit: In this mode the procedure to securize an APDU is called by the OpenSC general APDU transmit procedure. In this mode all APDUs, except the ones filtered by the card specific procedure, are securized.

•acl: In this mode APDU are securized only if needed by the ACLs of the command to be executed.

flags = value;

Secure messaging type specific flags.

kmc = hexstring;

Default KMC of the GP Card Manager for the Oberthur's Java cards.

ifd_serial = hexstring;

keyset[_aid]_num_enc = value; keyset[_aid]_num_mac = value;

Keyset values from IAM profiles of the Gemalto IAS/ECC cards with an optional application identifier

framework name { block_contents }

Internal configuration options where name is one of:

•pkcs15: See the section called “Configuration of PKCS#15 Framework”

pkcs11 { block_contents }

Parameters for the OpenSC PKCS11 module. For details see the section called “Configuration of PKCS#11”.

### Configuration of Smart Card Reader Driver
Configuration Options for all Reader Drivers

max_send_size = num; max_recv_size = num;

Limit command and response sizes (Default: max_send_size = 255, max_recv_size = 256) . Some Readers don't propagate their transceive capabilities correctly. max_send_size and max_recv_size allow setting the limits manually, for example to enable extended length capabilities.

enable_escape bool;

Detect reader capabilities with escape commands (wrapped APDUs with CLA=0xFF as defined by PC/SC pt. 3 and BSI TR-03119, e.g. for getting the UID, escaped PIN commands and the reader's firmware version, Default: false)

Configuration of CT-API Readers

module filename { ports = nums; }

Load the specified CT-API module with the specified number of ports.

Configuration of PC/SC Readers

connect_exclusive = bool;

Connect to reader in exclusive mode (Default: false)? This option has no effect in Windows' minidriver.

disconnect_action = action;

What to do when disconnecting from a card (SCardDisconnect). Valid values are leave, reset, unpower (Default: leave). This option has no effect in Windows' minidriver.

transaction_end_action = action;

What to do at the end of a transaction (SCardEndTransaction). Valid values are leave, reset, unpower (Default: leave). This option has no effect in Windows' minidriver.

reconnect_action = action;

What to do when reconnection to a card (SCardReconnect). Valid values are leave, reset, unpower (Default: leave). This option has no effect in Windows' minidriver.

enable_pinpad = bool;

Enable pinpad if detected (PC/SC v2.0.2 Part 10, Default: true)

fixed_pinlength = num;

Some pinpad readers can only handle one exact length of the PIN. fixed_pinlength sets this value so that OpenSC expands the padding to this length (Default: 0, i.e. not fixed).

provider_library = filename;

Use specific PC/SC provider (Default: /usr/lib64/libpcsclite.so.1).

Configuration of OpenCT Readers

readers = num;

Virtual readers to allocate (Default: 2).

### Configuration Options for MyEID Card
disable_hw_pkcs1_padding = bool;

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. PKCS#1 v1.5 padding in HW can be globally disabled by option disable_hw_pkcs1_padding. 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.

### Configuration Options for German ID Card
can = value;

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).

st_dv_certificate = filename; st_certificate = filename; st_key = filename;

QES is only possible with a Comfort Reader (CAT-K), which holds a cryptographic key to authenticate itself as signature terminal (ST). We usually will use the reader's capability to sign the data. However, during development you may specify soft certificates and keys for a ST. An example PKI can be found in the example data for the German ID card emulator[1]

### Configuration Options for DNIe
user_consent_enabled = bool;

Configure the warning message when performing a signature operation with the DNIe. Only used if compiled with --enable-dnie-ui

user_consent_app = filename;

Specify the pinentry application to use if warning is configured to be displayed using pinentry (Default: /usr/bin/pinentry). Only used if compiled with --enable-dnie-ui

### Configuration Options for Polish eID Card
can = value;

CAN (Card Access Number – 6 digit number printed on the right bottom corner of the front side of the document) is required to establish connection with the card. It might be overwritten by EDO_CAN environment variable. Currently, it is not possible to set it in any other way.

### Configuration Options for Slovenian eID Card
can = value;

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 EOI_CAN 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.

### Configuration Options for D-Trust Signature Cards
can = value;

CAN (Card Access Number – 6 digit number printed on the front side of the card) is required to establish connection with the card. It might be overwritten by DTRUST_CAN environment variable. If not specified here, the CAN will be read from a card specific cache, prompted on the card readers PIN pad or prompted interactively in the following order.

1.Environment variable DTRUST_CAN

2.This configuration file option

3.PKCS#15 card-specific cache

4.Pin pad of a PACE-capable card reader

can_use_cache = bool;

Cache the CAN number of a card once it was provided by the user in the directory file_cache_dir. The cached CAN is used later to avoid interactively prompting for the CAN. This feature is enabled by default.

### Configuration based on ATR
atrmask = hexstring;

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.

driver = name;

When enabled, overrides all possible settings from the card drivers built-in card configuration list.

name = name;

Set card name for card drivers that allows it.

type = num;

Allows setting the exact type of the card internally used by the card driver. Allowed values can be found in the source code of cards.h.

flags = value...;

Card flags as an hex value. Multiple values are OR'd together. Depending on card driver, this allows fine-tuning the capabilities in the card driver for your card. Optionally, some known parameters can be specified as strings:

•rng: On-board random number source

•keep_alive: Request the card driver to send a "keep alive" command before each transaction to make sure that the required applet is still selected.

pkcs15emu = name;

When using PKCS#15 emulation, force the emulation driver for specific cards. Required for external drivers, but can be used with built-in drivers, too.

force_protocol = value;

Force protocol selection for specific cards. Known parameters:

•t0

•t1

•raw

read_only = bool;

Mark card as read/only card in PKCS#11/Minidriver/BaseCSP interface (Default: false).

md_supports_X509_enrollment = bool;

Indicate X509 enrollment support at Minidriver/BaseCSP interface (Default: false).

md_guid_as_id = bool;

Use the GUID generated for the key as id in the PKCS#15 structure (Default: false, i.e. auto generated)

md_guid_as_label = bool;

Use the GUID generated for the key as label in the PKCS#15 structure (Default: false, i.e. no label set).

md_supports_container_key_gen = bool;

Card allows generating key pairs on the card (Default: false).

md_supports_container_key_import = bool;

Card allows importing private keys (Default: false).

md_pinpad_dlg_title = value;

Window title of the PIN pad dialog (Default: "Windows Security").

md_pinpad_dlg_icon = filename;

Filename of the icon for the PIN pad dialog; use "" for no icon (Default: Built-in smart card icon).

md_pinpad_dlg_main = value;

Main instruction of the PIN pad dialog (Default: "OpenSC Smart Card Provider").

md_pinpad_dlg_content_user = value;

Content of the PIN pad dialog for role "user" (Default: "Please enter your PIN on the PIN pad.").

md_pinpad_dlg_content_user_sign = value;

Content of the PIN pad dialog for role "user+signature" (Default: "Please enter your digital signature PIN on the PIN pad.").

md_pinpad_dlg_content_admin = value;

Content of the PIN pad dialog for role "admin" (Default: "Please enter your PIN to unblock the user PIN on the PIN pad.")

md_pinpad_dlg_expanded = value;

Expanded information of the PIN pad dialog (Default: "This window will be closed automatically after the PIN has been submitted on the PIN pad (timeout typically after 30 seconds).")

md_pinpad_dlg_enable_cancel = bool;

Allow the user to cancel the PIN pad dialog (Default: false). If this value is set to true, the user needs to click "OK" to start the PIN verification on the PIN pad. The user can choose the default behavior by enabling or disabling the checkbox of the dialog. The setting is saved by the program's full path (program_path) that uses OpenSC. The registry key HKCU\Software\OpenSC Project\OpenSC\md_pinpad_dlg_enable_cancel\program_path overwrites this setting with a DWORD set to either 1 (enabled) or 0 (disabled).

md_pinpad_dlg_timeout = num;

Time in seconds for the progress bar of the PIN pad dialog to tick. 0 removes the progress bar (Default: 30).

notify_card_inserted = value; notify_card_inserted_text = value;

Notification title and text when card was inserted (Default: "Smart card detected", ATR of the card).

notify_card_removed = value; notify_card_removed_text = value;

Notification title and text when card was removed (Default: "Smart card removed", name of smart card reader).

notify_pin_good = value; notify_pin_good_text = value;

Notification title and text when PIN was verified (Default: "PIN verified", "Smart card is unlocked").

notify_pin_bad = value; notify_pin_bad_text = value;

Notification title and text when PIN was wrong (Default: "PIN not verified", "Smart card is locked").

### Configuration of PKCS#15 Framework
use_file_caching = value;

Whether to cache the card's files (e.g. certificates) on disk in file_cache_dir. Possible parameters:

•yes: Cache all files (public and private).

•public: Cache only public files.

•no: File caching disabled.

(Default: public for the following card drivers atrust-acos (deactivated driver), belpic, cac1, cac, coolkey, dnie, edo, esteid2018, esteid2025, flex (deactivated driver), cyberflex (deactivated driver), gemsafeV1, idprime, itacns, jpki, MaskTech, mcrd (deactivated driver), npa, nqapplet, tcos, dtrust and otherwise no).

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.

file_cache_dir = filename;

Where to cache the card's files. The default values are:

•$XDG_CACHE_HOME/opensc/ (If $XDG_CACHE_HOME is defined)

•$HOME/.cache/opensc/ (Unix)

•$USERPROFILE\.eid-cache\ (Windows)

If caching is done by a system process, the cached files may be placed inaccessible from a user account. Use a globally readable and writable location if you wish to share the cached information. Note that the cached files may contain personal data such as name and mail address.

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 "http://"DNS name"/"ASCII-HEX OffCardKeyHistoryFile, then the searches for the file name OffCardKeyHistoryFile in the cache directory.

use_pin_caching = bool;

Use PIN caching (Default: true)?

pin_cache_counter = num;

How many times to use a PIN from cache before re-authenticating it (Default: 10)?

pin_cache_ignore_user_consent = bool;

Older PKCS#11 applications not supporting CKA_ALWAYS_AUTHENTICATE may need to set this to get signatures to work with some cards (Default: false). It is recommended to enable also PIN caching using use_pin_caching option for OpenSC to be able to provide PIN for the card when needed.

pin_protected_certificate = value;

How to handle a PIN-protected certificate. Known parameters:

•protect: The certificate stays PIN-protected.

•declassify: Allow reading the certificate without enforcing verification of the PIN.

•ignore: Ignore PIN-protected certificates.

(Default: protect.

enable_pkcs15_emulation = bool;

Enable pkcs15 emulation (Default: true).

try_emulation_first = bool;

Prefer pkcs15 emulation code before the normal pkcs15 processing (Default: no). Some cards work in emu-only mode, and do not depend on this option.

enable_builtin_emulation = bool;

Enable builtin emulators (Default: true).

builtin_emulators = emulators;

List of the builtin pkcs15 emulators to test (Default: internal) Special value of internal will try all not disabled builtin pkcs15 emulators.

Special value of old will try all disabled pkcs15 emulators.

pkcs11_enable_InitToken = bool;

Enable initialization and card recognition (Default: false).

emulate name { block_contents }

Configuration options for a PKCS#15 emulator where name is a short name for an external card driver. module = filename;

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.

function = name;

Get the init function name of the emulator (Default: sc_pkcs15_init_func_ex)

application hexstring { block_contents }

Configuration of the on-card-application where hexstring is the application identifier (AID). type = name;

Type of application where name is one of:

•generic

•protected

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, ...)

model = name;

disable = bool;

Do not expose application in PKCS#15 framework (Default: false)

user_pin = name;

Name of the User PIN object that will be used as the main PIN.

sign_pin = name;

Name of the PIN object that will be used for signing.

### Configuration of PKCS#11
max_virtual_slots = num;

Maximum Number of virtual slots (Default: 16). If there are more slots than defined here, the remaining slots will be hidden from PKCS#11.

slots_per_card = num;

Maximum number of PIN slots per smart card (Default: 4). If the card has fewer PINs than defined here, the remaining number of slots will be empty. For Firefox, Chrome and Chromium, the slots_per_card is set to 1, to avoid prompting for unrelated PINs. Typically, this effectively disables signature PINs and keys.

lock_login = bool;

By default, the OpenSC PKCS#11 module will not lock your card once you authenticate to the card via C_Login (Default: false). Thus the other users or other applications is not prevented from connecting to the card and perform crypto operations (which may be possible because you have already authenticated with the card). This setting is not very secure. Also, if your card is not locked, you can enconter problems due to limitation of the OpenSC framework, that still is not thoroughly tested in the multi threads environment.

Your settings will be more secure if you choose to lock your card. Nevertheless this behavior is a known violation of PKCS#11 specification. Now once one application has started using your card with C_Login, no other application can use it, until the first is done and calls C_Logout or C_Finalize. In the case of many PKCS#11 application this does not happen until you exit the application.

Thus it is impossible to use several smart card aware applications at the same time, e.g. you cannot run both Firefox and Thunderbird at the same time, if both are configured to use your smart card.

atomic = bool;

By default, interacting with the OpenSC PKCS#11 module may change the state of the token, e.g. whether a user is logged in or not (Default: false). Thus other users or other applications may change or use the state of the token unknowingly. Other applications may create signatures abusing an existing login or they may logout unnoticed.

With this setting enabled the login state of the token is tracked and cached (including the PIN). Every transaction is preceded by restoring the login state. After every transaction a logout is performed. This setting by default also enables lock_login to disable access for other applications during the atomic transactions.

Please note that any PIN-pad should be disabled (see enable_pinpad), because the user would have to input his PIN for every transaction.

init_sloppy = bool;

With this setting disabled, the OpenSC PKCS#11 module will initialize the slots available when the application calls C_GetSlotList. With this setting enabled, the slots will also get initialized when C_GetSlotInfo is called (Default: true). This setting is a workaround for Java which does not call C_GetSlotList when configured with a static slot instead of slotListIndex.

user_pin_unblock_style = mode;

User PIN unblock style mode is one of:

•none (Default): PIN unblock is not possible with PKCS#11 API

•set_pin_in_unlogged_session: C_SetPIN in unlogged session: PUK is passed as the OldPin argument of the C_SetPIN call.

•set_pin_in_specific_context: C_SetPIN in the CKU_SPECIFIC_CONTEXT logged session: PUK is passed as the OldPin argument of the C_SetPIN call.

•init_pin_in_so_session: C_InitPIN in CKU_SO logged session: User PIN 'UNBLOCK' is protected by SOPIN. (PUK == SOPIN).

create_puk_slot = bool;

Create slot for unblocking PIN with PUK (Default: false). This way PKCS#11 API can be used to login with PUK and change a PIN. May cause problems with some applications like Firefox and Thunderbird.

create_slots_for_pins = mode...;

Symbolic names of PINs for which slots are created where mode is a list of:

•all (Default): All non-SO-PIN, non-unblocking PINs

•user: The first global or first local PIN

•sign: The second PIN (first local, second global or second local)

Card can contain more then one PINs or more then one on-card application with its own PINs. Normally, to access all of them with the PKCS#11 API a slot has to be created for all of them. Many slots could be annoying for some of widely used application, like FireFox. This configuration parameter allows to select the PIN(s) for which PKCS#11 slot will be created.

Only PINs initialised, non-SO-PIN, non-unblocking are associated with symbolic name.

For the module to simulate the opensc-onepin module behavior the following option create_slots_for_pins = "user";

## ENVIRONMENT
OPENSC_CONF

Filename for a user defined configuration file If this environment variable is not found on Windows, the registry key Software\OpenSC Project\OpenSC\ConfigFile is checked.

OPENSC_DEBUG

See debug = num;

OPENSC_DRIVER

See card_drivers = name...;

CARDMOD_LOW_LEVEL_DEBUG

Write minidriver debug information to C:\tmp\md.log, if set to 1. If this environment variable is not found on Windows, the registry key Software\OpenSC Project\OpenSC\MiniDriverDebug is checked.

PIV_EXT_AUTH_KEY, PIV_9A_KEY, PIV_9C_KEY, PIV_9D_KEY, PIV_9E_KEY

PIV configuration during initialization with piv-tool.

PIV_USE_SM, PIV_PAIRING_CODE

PIV configuration during initialization See Configuration Options for PIV Card.

## FILES
/etc/opensc.conf

System-wide configuration file

/usr/share/doc/opensc/opensc.conf

Extended example configuration file

## NOTES
1.

German ID card emulator

https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data

branch: sisyphus


title: pkcs15-profile(5)

summary: format of profile for pkcs15\-init

text:
# pkcs15-profile(5)

## NAME
pkcs15-profile - format of profile for pkcs15-init

## DESCRIPTION
The pkcs15-init utility for PKCS #15 smart card personalization is controlled via profiles. When starting, it will read two such profiles at the moment, a generic application profile, and a card specific profile. The generic profile must be specified on the command line, while the card-specific file is selected based on the type of card detected.

The generic application profile defines general information about the card layout, such as the path of the application DF, various PKCS #15 files within that directory, and the access conditions on these files. It also defines general information about PIN, key and certificate objects. Currently, there is only one such generic profile, pkcs15.profile.

The card specific profile contains additional information required during card initialization, such as location of PIN files, key references etc. Profiles currently reside in /usr/share/opensc

Basic PKCS#15 terminology:

1.MF (Master File) is root of the filesystem hierarchy

2.DF(PKCS#15) is directory containing the PKCS#15 files and directories

3.EF(ODF) (Object Directory File) is elementary file containing pointers to other elementary files (PrKDFs, PuKDFs, SKDFs, CDFs, DODFs, AODFs)

4.PrKDF (Private Key Directory File) is elementary file containing pointers to the private keys and additional information about the private keys

5.PubKDF (Public Key Directory File) is elementary file containing pointers to the public keys and additional information about the public keys

6.CDF (Certificate Directory File) is elementary file containing pointers to the certificates and additional information about the certificates

7.EF(TokenInfo) is elementary file with generic information about the card

## SYNTAX AND SEMANTICS
The block syntax of profile files is in general similar to the configuration file. The profile file, is composed of blocks, which, in general, have the following format:

```
key [, name...] {
	block_contents
}

```

block_contents is one or more block_items where a block_item is one of

•# comment string

•key[, name...] = value;

•block

At the root level, the profile contains several configuration blocks. The block keys are as follows:

•cardinfo: Configuration for general information about card.

•pkcs15: Control for some of the general aspects of the PKCS#15 put onto the card.

•option: Profile options to modify the behavior of profile.

•PIN: Configuration and limits for particular PIN type.

•filesystem: Specification for filesystem that is to be created on the card.

•macros

### Profile file configuration
Configuration of Card Information

cardinfo { block_contents }

Configuration for general information about card: label = name;

Card label (Default: OpenSC Card).

manufacturer = name;

Card manufacturer (Default: OpenSC Project).

min-pin-length = int;

Minimal length of PIN (Default: 4).

max-pin-length = int;

Maximal length of PIN, should be overridden in the per-card profile (Default: 8).

pin-encoding = value;

Encoding type of PIN. Known parameters:

•BCD: binary-coded decimal

•ascii-numeric: ASCII numerical values

•utf8

•half-nibble-bcd

•iso9564-1

(Default: ascii-numeric).

pin-pad-char = value;

Character used for padding the PIN when needed (Default: 0x00).

pin-domains = bool;

Some cards need to keep all their PINs in separate directories. The particular keys in that domain will be put below the DF of the specified PIN. (Default: no)

Configuration of PKCS#15

pkcs15 { block_contents }

Control for some of the general aspects of the PKCS#15 put onto the card. Parameters in this block are: direct-certificates = bool;

The PKCS#15 system must contain at least one CDF, it contains the certificates directly or references to certificates. This options defines whether the certificates should be put directly in the CDF itself or not (Default: no).

encode-df-length = bool;

Save length of DF into ODF file. Useful if we store certificates directly in the CDF for better better performance and robustness (Default: no).

do-last-update = value;

Store information about last update in the EF(TokenInfo) (Default: yes).

pkcs15-id-style = value;

Method to calculate ID of the crypto objects. Known parameters:

•native: 'E' + number_of_present_objects_of_the_same_type

•mozilla: SHA1(modulus) for RSA

•rfc2459 SHA1(SequenceASN1 of public key components as ASN1 integers)

(Default: native) .sp

minidriver-support-style = value;

Style of pkcs15-init support of minidriver. Known parameters:

•none

•gemalto

(Default: none)

Configuration of Profile Option

option name { block_contents } .PP The name specifies profile options to modify the behavior of profile, it can be .PP .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . default: option specifies default settings and this block with option is always processed, .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . onepin: option for using 1 user PIN, creation/deletion/generation is controlled by the user PIN and thus by the user (as a result, only 1 user PIN is possible), .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . small option suitable for cards with small memory. .RE .sp .PP The options are used by pkcs15-init tool by --profile name, -p name: .PP .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . pkcs15+default: the default (not needed to specify it) .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . pkcs15+onepin: for the onepin profile option .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . pkcs15+small for the small profile option .RE .sp .PP The option block can contain following sub-blocks:

macros { block_contents }

Macros are specified in form of name = value; pairs.

pkcs15 { block_contents }

Inner block for configuration of PKCS#15 structure.

Configuration of PINs

PIN name { block_contents } .PP The name specifies PIN type, it can be .PP .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . pin or user-pin (no need to set file path or reference as it is done dynamically) .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . puk or user-puk .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . sopin or so-pin .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . sopuk or so-puk .RE .sp

Known parameters are: attempts = int;

Defines number of attempts for the given PIN (Default: 3).

flags = value...;

Flags define properties of the PIN. Possible flags:

•case-sensitive

•local

•change-disabled

•unblock-disabled

•initialized

•needs-padding

•unblockingPin

•soPin

•disable-allowed

•integrity-protected

•confidentiality-protected

•exchangeRefData

(Default: local,initialized,needs-padding).

auth-id = value;

Value used for auth ID (Default: 0).

min-length = int;

Minimal length of PIN (Default: value min-pin-length set in cardinfo block).

max-length = int;

Maximal length of PIN (Default: value max-pin-length set in cardinfo block).

reference = int;

Value of reference of the PIN (Default: set in particular card driver).

file = name;

File with PIN, obsolete option (Default: None).

offset = int;

Offset of PIN in PIN file, obsolete option (Default: 0).

encoding = value;

Encoding type of PIN. Possible values:

•BCD

•ascii-numeric

•utf8

•half-nibble-bcd

•iso9564-1

(Default: value pin-encoding set in cardinfo block).

stored-length = int;

(Default: value max-pin-length set in cardinfo block).

max-unlocks = int;

(Default: 0).

Values in this block can be set by macros. That allows to specify the particular values with the usage of option.

Configuration of Filesystem

filesystem { block_contents } .PP This block contains the specification for filesystem that is to be created on the card. The filesystem consists of several nested blocks representing DF and EF files. When the DFs or EFs are specified in card specific profile, this is added to the file system info specified in the main profile. EF name { block_contents } .PP This block defines elementary file in PKCS#15 file hierarchy. The name can be one of: .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-TokenInfo .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-ODF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-UnusedSpace .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-PRKDF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-PUKDF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-PUKDF-TRUSTED .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-SKDF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-CDF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-CDF-TRUSTED .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-CDF-USEFUL .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-DODF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-AODF .RE .sp .PP The EF block can contain:

type = EF;

Type must match type of file.

acl = value;

Value of ACL (Access Control List) (Default: NONE)

file-id = EF;

File ID, relative path.

structure = value;

File structure is one of:

•TRANSPARENT

•LINEAR-FIXED

•LINEAR-FIXED-TLV

•LINEAR-VARIABLE

•LINEAR-VARIABLE-TLV

•CYCLIC

•CYCLIC-TLV

DF name { block_contents } .PP This block defines directory file in PKCS#15 file hierarchy. The name can be one of: .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . MF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . PKCS15-AppDF .RE .sp .RS 4 .ie n • . .el .sp -1 .IP • 2.3 . Special cases for those DFs handled separately by the PKCS15 logic .RE .sp .PP The DF block can contain:

type = DF;

Type must match type of file.

path = value;

Specification of path of the directory file.

file-id = value;

File ID, relative path.

aid = value;

Value of AID, in XX:XX:XX:...:XX:XX:XX notation.

acl = value;

Type must match type of file.

size = int;

Size of the file in bytes.

EF name { block_contents }

Block specifying nested elementary file.

Typically, the root DF is MF.

It is mandatory that profile file contains DF entry for MF (Master File). Otherwise the profile file is incomplete and cannot be used.

The DF can contain other DF or MF blocks. For examples how the filesystem structure may look like, please refer to pkcs15.profile or any other present profile file.

## SEE ALSO
pkcs15-init(1), pkcs15-crypt(1)