Key Storage Overview¶

The following sections provide a high level overview of the Key Storage functionality available in the CC13x4 and CC26x4 family of devices.

Key Storage is the storage mechanism by which the Key Store driver will retrieve/store keys used for cryptographic operations. This functionality is used by the application to import, export, generate and/or destroy plain text keys & certificates with an associated key identifier. Key Storage keys are stored in a secured partition in TF-M enabled projects.

We will discuss how Key Storage works as well as how to add Key Storage to an existing project. Platform Security Architecture Internal Trusted Storage (ITS) service handles the storage and retrieval of the data in flash and calls TI’s CMSIS driver to perform any required write, read, or erase operations on internal flash.

Key Storage Implementation¶

Note

The Key Storage module is only available in TF-M Enabled projects.

This implementation requires the KeyStore API to enable its core functionality. The KeyStore API is used interface with the keys stored in the secured/non-secure partition.

The KeyStore API allows application code to store cryptographic keys and use them indirectly via a key identifier. The KeyStore API supports the storage of keys generated using the following algorithms:

AES (128, 192, 256-bit keys)

HMAC (up to 1024-bit keys)

Elliptic Curve (key pairs with size up to SECP512 curve)

The KeyStore API provides the following functionality:

Import of keys along with their attributes

Enforcement of policies relating to key usage

Retrieval of key attributes

Generation of random keys

Retrieval of key pre-provisioned keys

Purging of keys cached in RAM.

Export of public keys and any keys designated as exportable when originally created.

Destruction of persistent and volatile keys & certificates.

Types of keys supported by KeyStore:

Volatile keys

Persistent keys

Persistent certificates

TF-M Enabled Key Storage Implementation¶

In the TF-M enabled configuration the keys are stored in the secure partition’s secure memory which cannot be access by the application code.

For additional details on the TF-M enabled configuration, please reference Trusted Firmware-M (TF-M). section of the User’s Guide.

In TF-M enabled projects, the KeyStore API is used to communicate between the non-secure and secure partitions to store and retrieve cryptographic keys. Since memory is not shared between the secure and non-secure partitions, the KeyStore keys cannot be accessed by the non-secure application. Both persistent and volatile keys are owned by the partition which called the key import API and pre-provisioned keys have predefined owners.

Adding Key Storage to Custom Project¶

A few relevant APIs are listed in the following table for future reference:

Table 28. Relevant KeyStore APIs¶
KeyStore API	Description
`KeyStore_PSA_init()`	Initializes the KeyStore driver
`KeyStore_PSA_setKeyId()`	Sets the key ID attribute
`KeyStore_PSA_setKeyLifetime()`	Sets the key Lifetime attribute
`KeyStore_PSA_setKeyType()`	Sets the key type attribute
`KeyStore_PSA_setKeyUsageFlags()`	Sets the key usage flags attribute
`KeyStore_PSA_setKeyAlgorithm()`	Sets the key algorithm attribute
`KeyStore_PSA_importKey()`	Stores a plaintext key in KeyStore
`KeyStore_PSA_initKey()`	Initializes a `CryptoKey` type
`KeyStore_PSA_initBlankKey()`	Initializes a blank `CryptoKey` type
`KeyStore_PSA_exportKey()`	Export a key in binary format, if allowed by key properties
`KeyStore_PSA_exportPublicKey()`	Export a public key or the public part of a key pair in binary format
`KeyStore_PSA_purgeKey()`	Remove non-essential copies of key material from memory
`KeyStore_PSA_destroyKey()`	Destroy a key

The following code example showcases how to create a KeyStore key and how to import the key after creation.

KeyStore_PSA_key_file_id_t keyID;
int_fast16_t status;
KeyStore_PSA_key_attributes_t attributes = KEYSTORE_PSA_KEY_ATTRIBUTES_INIT;

KeyStore_PSA_setKeyUsageFlags(&attributes, (KEYSTORE_PSA_KEY_USAGE_DECRYPT | KEYSTORE_PSA_KEY_USAGE_ENCRYPT));
KeyStore_PSA_setKeyAlgorithm(&attributes, KEYSTORE_PSA_ALG_CCM);
KeyStore_PSA_setKeyType(&attributes, KEYSTORE_PSA_KEY_TYPE_AES);
KeyStore_PSA_setKeyLifetime(&attributes, KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT);
keyID.key_id = KEYSTORE_PSA_KEY_ID_PERSISTENT_USER_MIN;
GET_KEY_ID(keyID, KEYSTORE_PSA_KEY_ID_PERSISTENT_USER_MIN);

status = KeyStore_PSA_importKey(&attributes,symmetricKeyMaterial, AES_KEY_LENGTH, &keyID);

The code example shown above may be used as a reference for adding Key Storage to a project that does not currently have Key Storage capabilities.

As a reference point, the code example showed below shows how to use AESCCM encryption with a key identifier from Key Storage.

AESCCM_Handle handle;
AESCCM_Operation operation;
CryptoKey symmetricKey;

//...

CryptoKeyPlaintext_initKey&symmetricKey, symmetricKeyMaterial, AES_KEY_LENGTH);

//...

operation.key = symmetricKey;

//...

encryptionResult = AESCCM_oneStepEncrypt(handle, &operation);

The code example shown above may be modified to use Key Storage as shown below:

AESCCM_Handle handle;
AESCCM_Operation operation;
KeyStore_PSA_key_file_id_t keyID;
int_fast16_t status;
KeyStore_PSA_key_attributes_t attributes = KEYSTORE_PSA_KEY_ATTRIBUTES_INIT;

KeyStore_PSA_setKeyUsageFlags(&attributes, (KEYSTORE_PSA_KEY_USAGE_DECRYPT | KEYSTORE_PSA_KEY_USAGE_ENCRYPT));
KeyStore_PSA_setKeyAlgorithm(&attributes, KEYSTORE_PSA_ALG_CCM);
KeyStore_PSA_setKeyType(&attributes, KEYSTORE_PSA_KEY_TYPE_AES);
KeyStore_PSA_setKeyLifetime(&attributes, KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT);
keyID.key_id = KEYSTORE_PSA_KEY_ID_PERSISTENT_USER_MIN;
GET_KEY_ID(keyID, KEYSTORE_PSA_KEY_ID_PERSISTENT_USER_MIN);

status = KeyStore_PSA_importKey(&attributes,symmetricKeyMaterial, AES_KEY_LENGTH, &keyID);
KeyStore_PSA_initKey(&symmetricKey, keyID, AES_KEY_LENGTH);

//...

operation.key = symmetricKey;

//...

encryptionResult = AESCCM_oneStepEncrypt(handle, &operation);

For more information about the the KeyStore API please reference the following API references:

cryptoutils/cryptokey/CryptoKeyKeyStore_PSA.h
cryptoutils/cryptokey/CryptoKeyKeyStore_PSA_init.h