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():

  1. If labelSize == 0
    • keyId is generated through a random generator.

  2. If CKA_LABEL starts with sss:
    • keyID is generated by interpreting following string as hex value of the keyID. Example - If CKA_LABEL is sss:20181001, keyID is 0x01101820

      Note

      keyID is interpreted as little endian uint32_t value when reading attribute CKA_LABEL or attribute CKA_ID. Also, keyID is the value used to reference objects inside SE05x and is handled internally. This value should not be confused with CKA_ID or CKA_LABEL.

  3. Any other CKA_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:

/* Define max objects to read during C_FindObjects
 * Should not be more than MAX_ID_LIST_SIZE
 */
#define USER_MAX_ID_LIST_SIZE 1

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: ON

  • SSS_HAVE_HOSTCRYPTO_MBEDTLS: ON

  • Project: 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.