8.7. PKCS#11 Standalone Library¶
PKCS#11(v2.40) is a Public-Key Cryptography Standard for cryptographic data manipulation. It is mainly used with Hardware Security Modules and smart cards.
PKCS#11 standalone library is supported with SE05x for Linux based platforms.
8.7.1. PKCS#11 Label Handling¶
PKCS#11 library has three ways to calculate keyId through LabelToKeyId()
:
If
labelSize == 0
- keyId is generated through a random generator.If label starts with
sss:
- keyId is generated by interpreting following string as hex value of the keyID.Note
keyID is interpreted as little endian uint32_t value when reading label or attribute CKA_ID
Example - If label is
sss:20181001
, keyID is 0x01101820Any other label - KeyId is generated as the last 4 bytes of SHA512 digest of label.
8.7.2. PKCS#11 Object cacheing¶
PKCS#11 library supports cacheing objects during C_FindObjects()
operation
which can improve execution time of subsequent functions. The objects are cached during
C_FindObjects()
operation and are valid until C_FindObjectsFinal()
is called.
On calling C_FindObjectsFinal()
, the cached objects are invalidated.
Maximum objects that can be cached is 200. By default only 1 object is cached to save memory.
However, this can be increased in sss_pkcs11_pal.h
for platforms which do not have a memory constraint:
8.7.3. PKCS#11 specifications¶
- Token Label
SSS_PKCS11
- Pin
Not required
- Supported Mechanisms
- RSA Mechanisms
CKM_RSA_PKCS
CKM_SHA1_RSA_PKCS
CKM_SHA224_RSA_PKCS
CKM_SHA256_RSA_PKCS
CKM_SHA384_RSA_PKCS
CKM_SHA512_RSA_PKCS
CKM_RSA_PKCS_PSS
CKM_SHA1_RSA_PKCS_PSS
CKM_SHA224_RSA_PKCS_PSS
CKM_SHA256_RSA_PKCS_PSS
CKM_SHA384_RSA_PKCS_PSS
CKM_SHA512_RSA_PKCS_PSS
CKM_RSA_PKCS_OAEP
- AES Mechanisms
CKM_AES_ECB
CKM_AES_CBC
CKM_AES_CTR
- Digest Mechanisms
CKM_SHA_1
CKM_SHA224
CKM_SHA256
CKM_SHA384
CKM_SHA512
- ECDSA Mechanisms
CKM_ECDSA
CKM_ECDSA_SHA1
- Key Generation Mechanisms
CKM_EC_KEY_PAIR_GEN
CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_AES_KEY_GEN
CKM_DES2_KEY_GEN
CKM_DES3_KEY_GEN
- Key Derivation Mechanisms
CKM_ECDH1_DERIVE
- Supported API
- General-purpose functions
C_Initialize
C_Finalize
C_GetInfo
C_GetFunctionList
- Slot and token management functions
C_GetSlotList
C_GetSlotInfo
C_GetTokenInfo
C_GetMechanismList
C_GetMechanismInfo
- Session management functions
C_OpenSession
C_CloseSession
C_GetSessionInfo
C_Login
C_Logout
- Object management functions
C_CreateObject
C_DestroyObject
C_GetAttributeValue
C_FindObjectsInit
C_FindObjects
C_FindObjectsFinal
- Encryption functions
C_EncryptInit
C_Encrypt
- Decryption functions
C_DecryptInit
C_Decrypt
- Message digesting functions
C_DigestInit
C_Digest
C_DigestUpdate
C_DigestFinal
- Signing and MACing functions
C_SignInit
C_Sign
C_VerifyInit
C_Verify
- Key management functions
C_GenerateKey
C_GenerateKeyPair
C_DeriveKey
- Random number generation functions
C_SeedRandom
C_GenerateRandom
8.7.4. Building on Linux/Raspberry Pi3¶
PKCS#11 standalone shared library can be built on Linux platforms and Raspberry Pi3.
Build PKCS#11 library for Raspberry pi 3 with the following CMake configurations:
RTOS_Default
: ONSSS_HAVE_HOSTCRYPTO_MBEDTLS
: ONSSS_HAVE_MBEDTLS_ALT_SSS
: ONWithSharedLIB
: OFFProject:
sss_pkcs11
Note
The PKCS#11 library is not completely standalone as mbedTLS library is also used for parsing data.
Note
While using PKCS#11 as a library on multithreaded systems, the application must ensure proper locking is used. Calling multiple APIs from the library from different threads without proper locks can lead to unexpected behaviour.
8.7.5. Using with pkcs11-tool¶
Install pkcs11-tool
by running:
sudo apt-get install opensc-pkcs11
Set environment variable to the installed PKCS#11 shared library:
export PKCS11_MODULE=/usr/local/lib/libsss_pkcs11.so
The .so file is available in binaries/pkcs11
directory.
Generating new keypair:
pkcs11-tool --module $PKCS11_MODULE --keypairgen --key-type rsa:1024 --label "sss:20202020"
Signing:
pkcs11-tool --module $PKCS11_MODULE --sign --label sss:20181001 -m SHA256-RSA-PKCS --slot 1 -i in.der -o signature.der
Decryption:
pkcs11-tool --module $PKCS11_MODULE --decrypt --label sss:20202020 -m SHA256-RSA-PKCS --slot 1 -i in.der -o decrypt.der
Hashing:
pkcs11-tool --module $PKCS11_MODULE --hash -m SHA256 -i in.der -o hash.der
8.7.6. Notes¶
The monotonic counter will increase by one each time its value is read as specificed in “PKCS #11 Cryptographic Token Interface Base Specification Version 2.40”. This will cause NVM write accesses.