A newer version of this documentation is available.

PKCS11

This section controls the behavior of the PKCS#11 library.

AlwaysLoginForSSL

This entry is used to always require login for SSL/TLS. When enabled, an automatic logout will be done each time an SSL/TLS connection is established.

0: No automatic logout
1: Automatic logout

Default value is 0; no automatic logout when SSL/TLS connection is established.

See Pkcs11>LoginTimeout for another way to handle automatic logout.

This feature is normally used in combination with soft tokens to require password/PIN dialog even when renegotiating SSL/TLS connections.

DetectNewSlots

This entry specifies whether new slots should be detected each time the application asks for the current slot list. A slot is either a smart card reader or a soft token, so this parameter may be used to detect arrival of new smart card readers.

0: Will not detect new slots
1: Will detect new slots

Default value is 0; no detect of new slots.

See SmartCardReader>Detect for another way to detect arrival of smart card readers.

Recommended value for Detect is 1, when used in combination with this parameter.

DisableDuplicate

This entry specifies a list of applications, separated with ;, which will not be able to use duplicate certificates. Duplicates are certificates with identical issuer and subject field and same public key. Only the newest certificate will be available for the application.

DisableDuplicate=Firefox;Mozilla

Default value is none; all applications will see duplicate certificates.

DisableNonRep

This entry specifies a list of applications, separated with ;, which will not be able to use certificates with non-repudiation key usage.

DisableNonRep=Firefox;Mozilla

Default value is none; all applications will be able to use non-repudiation certificates.

EnableExternalMutex

This entry enables/disables the use of external mutex to protect multi-threaded sessions.

0: Internal mutex used
1: External mutex used (if available)

Default value is 0; always use internal mutex.

Multi-thread support is vital and to allow this protection to be handled externally may cause unknown results.

FriendlyName

This entry enables generation of a certificate label according to a specific format instead of using the default label from the token. The following wild cards may be used:

%label%
%issuer.<object identifier>%
%subject.<object identifier>%

Label is the certificate label stored with a certificate object, issuer and subject is any of the object identifiers available in the subject or issuer fields from the certificate. Any combination of static texts and wild cards above may be used.

Default value is none; the stored certificate label is used.

LoginTimeout

This entry is used to set a timeout for the login. When enabled an automatic logout will happen after the number of specified seconds.

0: No automatic logout
X: Automatic logout after X seconds

Default value is 0; no automatic logout.

See AlwaysLoginForSSL above for another way to handle automatic logout.

LogonApplication

This entry specifies a list of applications that should be considered as logon applications. This means that PIN cache always is ignored and that PIN always is verified even when being the same value as in PIN cache.

LogonApplication=lsass.exe;winlogon.exe

Default value is lsass.exe;winlogon.exe.

LogoutAtLastSession

This entry is used to control the behavior when the last session towards a token is closed. Specifies a list of applications that will generate a logout, separated with ;.

LogoutAtLastSession=svchost;winlogon

Default value is empty; no application will generate an automatic logout.

The reason for not logging out is to avoid unnecessary password/PIN dialogs. Usually PKCS#11 applications will open a session, login if needed, do something and thereafter close the session again. Setting no logout will keep the password/PIN status when the application opens the session again.

InsertEmptySlots

This entry is used to always create a number of empty slots which always will be available even when no smart card readers and/or soft tokens are present.

0: No extra empty slots
X: Add X extra slots

Default value is 0; no extra slots.

This parameter is only used for Firefox and installation of the PKCS#11 component. During installation the Firefox flag public readable certificates must be set, to avoid password/PIN dialosg when Firefox is searching for certificates. This flag will be set for the slots available at installation. Using this parameter will prepare a number of slots to have this flag set, so slots may be added after the installation and still get the public readable flag.

MechanismAllow

The MechanismAllow parameter tells which mechanisms that are permitted for the PKCS#11 library.

A mechanism in PKCS#11 is an algorithm that specifies how a certain cryptographic process is performed.

[PKCS11]
MechanismAllow=<wild-card-list>

Values

wild-card-list: Use mechanism name according to PKCS#11. Separate names with a semicolon. Use * for wildcards.

Examples

Example 1. Allow and deny algorithms using specified patterns.

Patterns are given for MechanismAllow and MechanismDeny to set which algorithms that are permitted.

[PKCS11]
MechanismAllow=*RSA*
MechanismDeny=CKM_SHA1;*_PSS;

Trace output

[00008044:00011868] 13.02.34.814 CryptoKi - Mechanism BLOCKED by policy: CKM_RSA_PKCS_PSS
[00008044:00011868] 13.02.34.815 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA_1
[00008044:00011868] 13.02.34.815 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA_1_HMAC
[00008044:00011868] 13.02.34.815 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA224
[00008044:00011868] 13.02.34.815 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA224_HMAC
[00008044:00011868] 13.02.34.815 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA256
[00008044:00011868] 13.02.34.816 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA256_HMAC
[00008044:00011868] 13.02.34.816 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA384
[00008044:00011868] 13.02.34.816 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA384_HMAC
[00008044:00011868] 13.02.34.816 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA512
[00008044:00011868] 13.02.34.816 CryptoKi - Mechanism BLOCKED by policy: CKM_SHA512_HMAC
[00008044:00011868] 13.02.34.817 CryptoKi - Mechanism BLOCKED by policy: CKM_PKCS5_PBKD2
[00008044:00011868] 13.02.34.817 CryptoKi - Mechanism BLOCKED by policy: CKM_AES_CMAC

MechanismDeny

The MechanismDeny parameter tells which mechanisms that are not permitted for the PKCS#11 library.

A mechanism in PKCS#11 is an algorithm that specifies how a certain cryptographic process is performed.

[PKCS11]
MechanismDeny=<wild-card-list>

Values

wild-card-list: Use mechanism name according to PKCS#11. Separate names with a semicolon. Use * for wildcards.

Examples

For example, see MechanismAllow examples.

OpenSSL

This entry is used to specify an OpenSSL library that should be loaded to generate random and/or key pairs. Typical names for different platforms:

libeay32.dll – Windows
libcrypto.so – Linux
libcrypto.dylib – macOS

Default value is none; internal algorithms will be used for generating random and/or key pairs.

For Windows platform Microsoft CryptoAPI will be used for key pair generation, since their implementation is much faster than internal algorithm.

PinMaxDigits

This entry sets the global maximum number of digits policy. Specify the maximum number of required digits.

0: No maximum number of digits
X: X number of digits required

Default value is 0; no minimum number of digits required.

This parameter should not be used, use PIN policy flags in [SmartCard] or [SoftToken] instead.

PinMinDigits

This entry set the global minimum number of digits policy. Specify the minimum number of required digits.

0: No minimum number of digits
X: X number of digits required

Default value is 0; no minimum number of digits required.

This parameter should not be used, use PIN policy flags in [SmartCard] or [SoftToken] instead.

PinReportError

This entry is used to specify a location to report failed logon attempts on Windows platform. May be configured to report to either Windows EventViewer or to an ODBC source. Reporting to an ODBC source will require the table to be correctly formatted, more information is available from your support contact.

PinReportError=-eventlog
PinReportError=-database -connection <ODBC> -table <TABLE> -username <USER> -password <PWD>

Default value is none; no error reporting.

RandomDisabled

This entry is used to enable/disable the support of random generation.

0: Random generation support enabled
1: Random generation support disabled

Default value is 0; random generation available.

This only affects external applications; they will not be able to use the library to generate random bytes. Internally random generation will still be available.

ResetTempFiles

This entry is used to enable/disable reset of internal temporary files at initialize.

0: Reset at initialize disabled
1: Reset at initialize enabled

Default value is 0; reset at initialize disabled.

Will delete eventual smart card cache files, which may impact performance.

SeparateThreadSearch

This entry is used to enable/disable concurrent searches in different threads using the same session.

0: Don’t allow concurrent searches in different threads using same session
1: Allow concurrent searches in different threads using same session

Default value is 0; concurrent searches are not allowed in different threads using the same session.

DO NOT EDIT. This behavior is against standards and should never be used. Different threads may use the same session context, but the expected behavior should be to follow the PKCS#11 standard. Enabling of this behavior is against the PKCS#11 standard, but was added to show a proof-of-concept with an application unaware of their own multi-threading implementation.

SessionToken

This entry specifies a list of applications, separated with ;, which will set a write protected soft token.

SinglePin

This entry is used to enable/disable the use of a single password/PIN for smart cards. The parameter has no affect for soft tokens, since they always have a single password/PIN.

0: All available passwords/PINs usable
1: Only first password/PIN usable

Default value is 0; all available PINs are usable.

Will remove possible secondary PIN for the calling applications. This is usable for situations where your application has bad support for multiple PINs, or when only the first PIN objects should be used (everything connected with secondary PINs will be hidden).

TraceExecuteTime

This entry is used to enable/disable calculation of execute time. The time is the number of milliseconds spent within the pkcs#11 library. This will generate an extra trace entry with the number of milliseconds within library and also the number of milliseconds spent on card during this time. Used to measure the performance.

0: Execute time not written to trace
1: Execute time written to trace

Default value is 0; execute time not written.

This time may be misleading when measuring small time differences, since most of the time may be spent writing to trace.

UpdateSlotsForEvent

This entry is used to enable/disable update of slot list when library is called for active event list (C_WaitForSlotEvent). Default behavior will use [SmartCardReader[>Poll parameter to detect smart card insert/remove and [SmartCardReader]>Detect parameter to detect smart card reader insert/remove.

0: No update slot list when checking for event list
1: Update slot list when checking for event list

Default value is 0.

VerifyAlgorithms

This entry is used to enable/disable verification of cryptographic algorithms during initialize.

0: Algorithms not verified
1: Algorithms verified

Default value is 0; algorithms not verified.

WaitForSmartCardService

This entry is used to enable/disable wait for Windows smart cards service to start before initialize continues.

0: No wait
X: Wait X number of seconds

Default value is 0; no wait for smart card service.

This parameter was required for earlier versions of Windows, but is not needed any longer.