Key Store is an access control-based service with access to trusted hardware bound cryptography. It ensures that all cryptographic keys generated are bound to the device cryptographically and all cryptographic operations run in a trusted execution environment.

Key Store service provides APIs to applications for key management, key access control, and cryptographic operations. It has a built-in reliable and secure backend storage to save cryptographic keys created by client applications. It also supports client authentication which means only the key owner has the permission to access or use the key for certain purposes.

IPC interfaces binding

The functions of this API are provided by the tafKeyStoreSvc application service.

The following example illustrates how to bind to the Key Store service.

bindings:
{
    clientExe.clientComponent.taf_ks -> tafKeyStoreSvc.taf_ks
}

Key management

A new key can be created using taf_ks_CreateKey() with the desired key name and key usage passed as input parameters. A key reference output parameter is returned to the client for subsequent operations.

New keys initially have no value and cannot be used for any cryptographic operations. Applications shall call taf_ks_ProvisionXXX() API to provision or import the key value and save the key into backend storage. The following key provision/import APIs are supported.

taf_ks_ProvisionRsaEncKeyValue() – Provisions or imports a RSA encryption key value.
taf_ks_ProvisionRsaSigKeyValue() – Provisions or imports a RSA signing key value.
taf_ks_ProvisionAesKeyValue() – Provisions or imports an AES key value.
taf_ks_ProvisionEcdsaKeyValue() – Provisions or imports an ECDSA key value.
taf_ks_ProvisionHmacKeyValue() – Provisions or imports a HMAC key value.

The following example illustrates how to create and provision an AES GCM key.

const char keyId[] = "MyAesGcmKey";
taf_ks_KeyRef_t keyRef;
if (LE_NOT_FOUND == taf_ks_GetKey(keyId, &keyRef))
{
    LE_ASSERT(LE_OK == taf_ks_CreateKey(keyId,TAF_KS_AES_ENCRYPT_DECRYPT, &keyRef));
    LE_ASSERT(LE_OK == taf_ks_ProvisionAesKeyValue(keyRef,
                                                   TAF_KS_AES_SIZE_256,
                                                   TAF_KS_AES_MODE_GCM,
                                                   NULL, 0));
}

Note: A key only allows one-shot provisioning after creation.

Optionally, application can call taf_ks_SetKeyXXX() to set the attribute of key access control before key provisioning. The following key access control APIs are supported.

taf_ks_SetKeyMaxUsesPerBoot() – Sets the maximum number of times that a key can be used per system boot.
taf_ks_SetKeyMinSecondsBetweenOps() – Sets the minimum amount of time that elapses between allowed cryptographic operations using a key.
taf_ks_SetKeyActiveDateTime() – Sets the date and time at which the key becomes active. Prior to this time any attempt to use the key will fail.
taf_ks_SetKeyOriginationExpireDateTime() – Sets the date and time at which the key expires for signing and encryption. After this time any attempt to use a key for signing or encryption will fail.
taf_ks_SetKeyUsageExpireDateTime() – Sets the date and time at which the key expires for verification and decryption. After this time any attempt to use a key for verification and decryption will fail.

Note: The key access control APIs are not currently implemented.

Call taf_ks_GetKey() to get a key reference by the key name and call taf_ks_GetKeyUsage() to get the key usage by the key reference.

Note: taf_ks_GetKey() returns LE_NOT_FOUND if the key is created but not provisioned.

Call taf_ks_ExportKey() to export the x.509 DER format public key.

Call taf_ks_DeleteKey() to delete a key from the backend storage.

Cryptographic operation

The typical use cases are data encryption/decryption and message signing/verification. Each cryptographic operation must be processed within a context. A cryptographic session bound to the context must be created to use a key for certain cryptographic operations.

Create and start context session

Call taf_ks_CryptoSessionCreate() to create a session and get the session reference for subsequent operations.

Call taf_ks_CryptoSessionSetAesNonce() to set the NONCE specifically for the AES CBC/CTR/GCM key.

Call taf_ks_CryptoSessionStart() to start the session.

The following example illustrates how to create a cryptographic session and start the session for data encryption.

taf_ks_CryptoSessionRef_t sessionRef;
const uint8_t nonce[12] = {"abcdefghijk"}; // Shall be customized and filled by application.
LE_ASSERT(LE_OK == taf_ks_CryptoSessionCreate(keyRef, &sessionRef));
LE_ASSERT(LE_OK == taf_ks_CryptoSessionSetAesNonce(sessionRef, nonce, sizeof(nonce)));
LE_ASSERT(LE_OK == taf_ks_CryptoSessionStart(sessionRef, TAF_KS_CRYPTO_ENCRYPT));

Process data within the session

Call taf_ks_CryptoSessionProcess() to process the input data and get the output data in a running crypto session started with taf_ks_CryptoSessionStart(). It shall be called for multiple times if the input data size is greater than TAF_KS_MAX_PACKET_SIZE, which means the input data shall be split into small pieces with the size of each piece less than TAF_KS_MAX_PACKET_SIZE.

Note: For AES GCM keys, taf_ks_CryptoSessionProcessAead() must be called one or multiple times to pass the AEAD before calling taf_ks_CryptoSessionProcess(). taf_ks_CryptoSessionAbort() is used to abort a running session, if needed.

Call taf_ks_CryptoSessionEnd() to normally finish the cryptographic operation in the running session after all input data is processed by taf_ks_CryptoSessionProcess().

The following example illustrates how to process the input plain text and get the encrypted data, the encrypted data will be saved in the byte array of encryptedData with size of totalEncSize.

const uint8_t plainText[] = "Keystore service for AES GCM test messages.";
uint8_t encryptedData[TAF_KS_MAX_PACKET_SIZE] = {0};
size_t encryptedDataSize = sizeof(encryptedData);
const uint8_t aead[] = {"123456789"}; // Shall be customized and filled by application.
LE_ASSERT(LE_OK == taf_ks_CryptoSessionProcessAead(sessionRef, aead, sizeof(aead)));
LE_ASSERT(LE_OK == taf_ks_CryptoSessionProcess(sessionRef,
                                               plainText,
                                               sizeof(plainText),
                                               encryptedData,
                                               &encryptedDataSize));
size_t totalEncSize = encryptedDataSize;
encryptedDataSize = sizeof(encryptedData) - totalEncSize;
LE_ASSERT(LE_OK == taf_ks_CryptoSessionEnd(sessionRef,
                                           NULL, 0,
                                           encryptedData + totalEncSize,
                                           &encryptedDataSize));
totalEncSize = totalEncSize + encryptedDataSize;

Note: The crypto session is automatically deleted after taf_ks_CryptoSessionAbort() or taf_ks_CryptoSessionEnd() is called, or when any error occurs in taf_ks_CryptoSessionStart() and taf_ks_CryptoSessionProcess().