-
Notifications
You must be signed in to change notification settings - Fork 32
PKCS11
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.
The PKCS#11 module can be configured using environment variables:
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.
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.
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
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.
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.
Initialize PKCS#11 module
Terminate module and free allocated resources
Obtain information about the module
Get list of exported module functions
Return the current list of slots, which may grow when new token or readers are attached to the system.
Return information about a slot identified by it's slot id.
Return information about a token inserted into a slot.
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.
Return information about a specific mechanism
Implemented, but does not provide any functionality
Reset retry counter and set PIN in SO session.
Change User PIN or SO PIN
Supports all types of sessions, but does not support session notifications with arguments pApplication and Notify.
Close a single session.
Close all sessions.
Get information about a specific session.
Not supported
Not supported
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.
Logout user or security officer
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.
Not supported
Supports deleting keys and certificates on a SmartCard-HSM. No supported on STARCOS cards.
Returns the total amount of memory required by encoding all object attributes
Return one or more object attributes
Allows changing the CKA_ID and CKA_LABEL attribute of keys and certificates.
Initialize an object search
Return all or a part of the search result
Complete a search operation freeing all allocated resources
Initialize encrypt operation using a RSA public key or AES key
Encrypt a plain test using RSA public key or AES key
Partial message, collected internally to a full message presented to C_Encrypt.
Partial message, collected internally to a full message presented to C_Encrypt.
Initialize decrypt operation with SmartCard-HSM and RSA or AES key
Decrypt RSA block and check padding or decrypt using AES
Partial message, collected internally to a full message presented to C_Encrypt.
Partial message, collected internally to a full message presented to C_Encrypt.
Supported for CKA_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384 and CKM_SHA512
Supported
Supported
Not supported
Supported
Initialize signing operation with SmartCard-HSM
Sign a single data block
Update internal buffer storing signature input
Create signature from data collected with C_SignUpdate
Not supported
Not supported
Initialize verification of RSA or ECDSA signature
Verify RSA or ECDSA signature with public key on device
Partial message, collected internally to a full message presented to C_Verify.
Partial message, collected internally to a full message presented to C_Verify.
Not supported
Not supported
Not supported
Not supported
Not supported
Not supported
Supported for AES keys on a SmartCard-HSM
Supported for RSA and ECC keys on a SmartCard-HSM.
Not supported
Not supported
Not supported
Not supported
Supported to obtain randomness from the smart card.
Not supported
Supported to wait for changing slots, i.e. added slots, inserted or removed cards.
Supported to cancel a pending C_WaitForSlotEvent.