Back to top

TIMA CCM Keystore support for PKCS

This feature was deprecated in API level 33 with Knox SDK v3.7. For more information, see Deprecation of TIMA/CCM Keystore support.

This section provides an overview of the TIMA CCM keystore support for the PKCS #11 API.

About support for PKCS 11 APIs

This topic describes how the TIMA CCM Keystore works with the Public Key Cryptography Standard (PKCS) 11 APIs.

The TIMA CCM Keystore supports proprietary interfaces to perform the following:

  • Install encrypted PKCS 8 private key/certificate files
  • Request for TrustZone key pair generation followed by certificate signing request issuance
  • Access default, pre-installed, client certificates which are signed by the device root key

Once the Keystore creates the keys, the keys are never seen in the normal world. One can only exercise these keys using the standard PKCS 11 cryptographic token standard, which mandates password-based logins for sensitive cryptographic operations.

About PKCS 11 API standard

There are many portable devices out there like Smartcards, CAC cards, PCMCIA cards and so on. which have the ability to store keys securely, under the control of a single user. With such devices, sensitive private keys never leave the device and cryptographic operations are performed on the card itself. PKCS 11 standard is a standard programming interface to talk to such cards.

At the native layer, the PKCS 11 interfaces are exposed and implemented by the shared library libtlc_tz_ccm.so. Any PKCS 11 crypto-key library has a static CK_FUNCTION_LIST structure and a pointer to it can be obtained by the C_GetFunctionList function. This function is in the TZ CCM PKCS 11 library is named TZ_CCM_C_GetFunctionList.

The table below summarizes the list of supported PKCS 11 interfaces. The return values and API behaviors are compliant with the PKCS 11 standard and the library expects the caller to use them in a standard way.

PKCS #11 API Synopsis
C_Initialize Initializes the TZ CCM TrustZone application if the Trusted Boot measurements match Samsung authorized values
C_Finalize Closes the TZ CCM application. Unloads the TZ Application if there are not outstanding clients being serviced

C_OpenSession,

C_CloseSession

Opens a session with CCM

Closes a session with CCM

C_Login,

C_Logout

Login to a slot with a previously registered password (through the installation APIs)

Logout of the slot

C_GetSlotList Obtain the list of slots

C_FindObjectsInit,

C_FindObjects,

C_FindObjectsFinal

Initialize, continue, and finish an object search operation

C_SignInit,

C_Sign

Initialize and perform signing operation

C_DecryptInit,

C_Decrypt

Initialize and perform a decryption operation

C_EncryptInit,

C_Encrypt

Initialize and perform an encryption operation
C_Digest Perform a digest operation

C_VerifyInit,

C_Verify

Initialize and perform signature verification operation
C_GetInfo General TZ CCM information
C_GetSessionInfo PKCS #11 session information
C_GetSlotInfo PKCS #11 slot information
C_GetTokenInfo PKCS #11 token information

The following PKCS 11 interfaces are not supported:

  • C_InitToken
  • C_InitPIN, C_SetPIN
  • C_UnwrapKey, C_WrapKey
  • C_SeedRandom, C_GenerateRandom
  • C_DeriveKey, C_GenerateKey, C_GenerateKeyPair
  • C_SetAttributeValue, C_SetOperationState
  • C_WaitForSlotEvent
  • C_CancelFunction
  • C_CloseAllSessions
  • C_GetMechanismList, C_GetMechanismInfo
  • C_GetOperationState
  • C_GetInfo, C_GetSessionInfo, C_GetSlotInfo, C_GetTokenInfo
  • C_CreateObject, C_CopyObject, C_DestroyObject, C_GetObjectSize

Also, none of the crypto UPDATE/FINAL operations, such as C_DigestUpdate or C_DigestFinal, are supported.

Supported cryptographic formats in the TIMA Keystores

The following encryption formats are supported by the TIMA Keystore.

Android Class Algorithm Supported API Level Notes
Cipher

AES/CBC/PKS7Padding

AES/GDM/NoPadding

RSA/ECB/NoPadding

RSA/ECB/PKCS1Padding

23+
23+

18+
18+

256

Support for 12-byte initialization vectors only

KeyGenerator AES 23+ Supported sizes: 128, 192, 256
KeyPairGenerator RSA 18+

TIMA API: TZ_gen_keypair

Supported sizes: 1024, 2048,

Supported public exponents: 3, 65537

Default public exponent: 65537

Signature

NONEwithRSA

SHA1withRSA

SHA256withRSA

18+

18+

18+

TIMA API: TZ_sign_CKM_SHA1_RSA_PKCS 2048 bit

TIMA API: TZ_sign_CKM_SHA256_RSA_PKCs

2048 bit

Keystore Same algorithms as the KeyGenerator and KeyPairGenerator classes

Is this page helpful?