PKCS#11 Module Specification

The PKCS#11 module implements access to keys and certificates stored on a SmartCard-HSM or on STARCOS based electronic signature cards, in particular

• the new signature card from the Bundesnotarkammer (2014, Starcos 3.5),
• the D-TRUST card 3.0 (2011, Starcos 3.4),
• the current Signtrust/Bundesnotarkammer card (2009, Starcos 3.2) and
• the new DGN HBA (2014, Starcos 3.5).

The PKCS#11 module supports qualified electronic signatures, advanced electronic signatures and decryption operations with STARCOS cards in single PIN, double PIN, single-sign and multi-sign configurations. QES keys are made available with the CKA_ALWAYS_AUTHENTICATE attribute in the single-sign configuration.

In combination with the SmartCard-HSM, then module support key generation and writing certificates. The module supports X.509 and Card Verifiable Certificates (CVC) as defined in TR-03110.

For a SmartCard-HSM this module is somewhat smaller than the PKCS#11 implementation in OpenSC. Both use the same data structure on the SmartCard-HSM, so you can use a device with both variants.

Configuration

The PKCS#11 module can be configured using environment variables:

PKCS11_IGNORE_PINPAD

If this environment variable is set to any value, then a class 3 PIN pad is ignored and CKF_PROTECTED_AUTHENTICATION_PATH is not indicated to the client.

PKCS11_PREALLOCATE_VIRTUAL_SLOTS

The PKCS#11 module allocates a slot for each PIN on the card. For a signature card with user PIN and two QES PINs, three slots are allocated.

Slots are dynamically allocated when a card supporting multiple PINs is inserted. On Firefox this may cause problems as the FRIENDLY flag that prevent unnecessary PIN requests is not honoured for dynamically created slots.

The PKCS11_PREALLOCATE_VIRTUAL_SLOTS environment variable can be set to either 1 or 2 defining the number of additional virtual slots created for each card reader in the system.

PKCS11_READER_FILTER

This environment variable allows to define a filter, effectively selecting only a subset of the card readers installed in the system.

The filter may contain '?' (match a single character) and '*' (non-greedy match any character) wildcards.

Examples

• "ACME Card *" - match all card reader starting with "ACME Card "
• "*Card*" - match all card reader that have a "Card" in their name

Troubleshooting

The PKCS#11 module is available as a release and debug version. The debug version can write a detailed log about it's internal control flow and states. The log is written to /var/tmp/sc-hsm-embedded, if that directory exists.

Starting with version 2.10, the log is written to a user directory ($HOME/tmp/sc-hsm-embedded), if the application is started by a user. System processes still use /var/tmp/sc-hsm-embedded.

On Windows the log file is written to %HOMEDIR%/appdata/LocalLow/sc-hsm-embedded if this directory exists. On Linux the log file is written to %HOME%/tmp/sc-hsm-embedded. appdata is a hidden directory on Windows and only visible if hidden directories are enabled in Windows Explorer.

The log file contains the id of the process that attached the DLL/shared object. Each log line contains the thread id acting at the interface.

PKCS#11 Interface

The following functions are implemented at the PKCS#11 interface according to version 2.20 of the PKCS#11 specifications. The interface is compatible with popular PKCS#11 aware applications like Firefox, Thunderbird, Acrobat Reader, OpenOffice/LibreOffice, OpenVPN and Truecrypt.

C_Initialize

Initialize PKCS#11 module

C_Finalize

Terminate module and free allocated resources

C_GetInfo

Obtain information about the module

C_GetFunctionList

Get list of exported module functions

C_GetSlotList

Return the current list of slots, which may grow when new token or readers are attached to the system.

C_GetSlotInfo

Return information about a slot identified by it's slot id.

C_GetTokenInfo

Return information about a token inserted into a slot.

C_GetMechanismList

Return list of mechanisms supported by token. The module in combination with the SmartCard-HSM supports

• CKM_RSA_X_509 (Sign,Verify,Encrypt,Decrypt)
• CKM_RSA_PKCS (Sign,Verify,Encrypt,Decrypt)
• CKM_RSA_PKCS_PSS (Sign,Verify)
• CKM_RSA_PKCS_OAEP (Encrypt,Decrypt)
• CKM_SHA1_RSA_PKCS (Sign,Verify)
• CKM_SHA256_RSA_PKCS (Sign,Verify)
• CKM_SHA1_RSA_PKCS_PSS (Sign,Verify)
• CKM_SHA256_RSA_PKCS_PSS (Sign,Verify)
• CKM_ECDSA (Sign,Verify)
• CKM_ECDSA_SHA1 (Sign,Verify)
• CKM_RSA_PKCS_KEY_PAIR_GEN (Keygen)
• CKM_EC_KEY_PAIR_GEN (Keygen)
• CKM_AES_KEY_GEN (Keygen)
• CKM_SHA_1
• CKM_SHA224
• CKM_SHA256
• CKM_SHA384
• CKM_SHA512

with RSA key sizes 1024,1536,2048,3072 and 4096 as well as ECDSA key sizes 196,224,256,320,384,512 and 521 bits. AES keys with 128,192 and 256 are supported.

Four vendor mechanisms are defined

• CKM_SC_HSM_PSS_SHA1 - Hash provided by application, PSS padding with MGF1 and SHA-1 by the device
• CKM_SC_HSM_PSS_SHA256 - Hash provided by application, PSS padding with MGF1 and SHA-256 by the device
• CKM_SC_HSM_ECDSA_SHA224 - Hash with SHA-224 and ECDSA in the device
• CKM_SC_HSM_ECDSA_SHA256 - Hash with SHA-256 and ECDSA in the device

Vendor defined mechanisms are declared in sc-hsm/sc-hsm-pkcs11.h.

STARCOS cards implemented different mechanisms based on the card profile. See the relevant source module for details.

C_GetMechanismInfo

Return information about a specific mechanism

C_InitToken

Implemented, but does not provide any functionality

C_InitPIN

Reset retry counter and set PIN in SO session.

C_SetPIN

Change User PIN or SO PIN

C_OpenSession

Supports all types of sessions, but does not support session notifications with arguments pApplication and Notify.

C_CloseSession

Close a single session.

C_CloseAllSessions

Close all sessions.

C_GetSessionInfo

Get information about a specific session.

C_GetOperationState

Not supported

C_SetOperationState

Not supported

C_Login

Login as user (CKU_USER) or security officer (CKU_SO). Login with CKU_SO is supported but does not verify the provided code against the initialization code of the SmartCard-HSM.

C_Logout

Logout user or security officer

C_CreateObject

Supports creating EE and CA certificate objects on the token and on a per-session basis. The per-session creation of certificates can be used to decode CVC certificates without implementing a separate parser in the application.

C_CopyObject

Not supported

C_DestroyObject

Supports deleting keys and certificates on a SmartCard-HSM. No supported on STARCOS cards.

C_GetObjectSize

Returns the total amount of memory required by encoding all object attributes

C_GetAttributeValue

Return one or more object attributes

C_SetAttributeValue

Allows changing the CKA_ID and CKA_LABEL attribute of keys and certificates.

C_FindObjectsInit

Initialize an object search

C_FindObjects

Return all or a part of the search result

C_FindObjects

Complete a search operation freeing all allocated resources

C_EncryptInit

Initialize encrypt operation using a RSA public key or AES key

C_Encrypt

Encrypt a plain test using RSA public key or AES key

C_EncryptUpdate

Partial message, collected internally to a full message presented to C_Encrypt.

C_EncryptFinal

Partial message, collected internally to a full message presented to C_Encrypt.

C_DecryptInit

Initialize decrypt operation with SmartCard-HSM and RSA or AES key

C_Decrypt

Decrypt RSA block and check padding or decrypt using AES

C_DecryptUpdate

Partial message, collected internally to a full message presented to C_Encrypt.

C_DecryptFinal

Partial message, collected internally to a full message presented to C_Encrypt.

C_DigestInit

Supported for CKA_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384 and CKM_SHA512

C_Digest

Supported

C_DigestUpdate

Supported

C_DigestKey

Not supported

C_DigestFinal

Supported

C_SignInit

Initialize signing operation with SmartCard-HSM

C_Sign

Sign a single data block

C_SignUpdate

Update internal buffer storing signature input

C_SignFinal

Create signature from data collected with C_SignUpdate

C_SignRecoverInit

Not supported

C_SignRecover

Not supported

C_VerifyInit

Initialize verification of RSA or ECDSA signature

C_Verify

Verify RSA or ECDSA signature with public key on device

C_VerifyUpdate

Partial message, collected internally to a full message presented to C_Verify.

C_VerifyFinal

Partial message, collected internally to a full message presented to C_Verify.

C_VerifyRecoverInit

Not supported

C_VerifyRecover

Not supported

C_DigestEncryptUpdate

Not supported

C_DecryptDigestUpdate

Not supported

C_SignEncryptUpdate

Not supported

C_DecryptVerifyUpdate

Not supported

C_GenerateKey

Supported for AES keys on a SmartCard-HSM

C_GenerateKeyPair

Supported for RSA and ECC keys on a SmartCard-HSM.

C_WrapKey

Not supported

C_UnwrapKey

Not supported

C_DeriveKey

Not supported

C_SeedRandom

Not supported

C_GenerateRandom

Supported to obtain randomness from the smart card.

C_GetFunctionStatus

Not supported

C_WaitForSlotEvent

Supported to wait for changing slots, i.e. added slots, inserted or removed cards.

C_CancelFunction

Supported to cancel a pending C_WaitForSlotEvent.