3.3.3. Key Store

KeyStore is a container for all secure keys and objects inside a secure storage.

../../_images/key_store.png

3.3.3.1. APIs

group sss_key_store

Secure storage for keys and certificates.

Enums

enum sss_key_store_prop_au8_t

properties of a Key Store that return array

Values:

kSSS_KeyStoreProp_au8_Optional_Start = 0x00FFFFFFu

Optional Properties Start

enum sss_tunnel_dest_t

Entity on the other side of the tunnel

Values:

kSSS_TunnelDest_None = 0

Default value

kSSS_TunnelType_Se05x_Iot_applet

SE05X IoT Applet

Functions

sss_status_t sss_key_store_allocate(sss_key_store_t *keyStore, uint32_t keyStoreId)

Get handle to key store. If the key store already exists, nothing is allocated. If the key store does not exists, new empty key store is created and initialized. Key store context structure is updated with actual information.

Parameters
  • [out] keyStore: Pointer to key store context. Key store context is updated on function return.

  • keyStoreId: Implementation specific ID, can be used in case security subsystem manages multiple different key stores.

void sss_key_store_context_free(sss_key_store_t *keyStore)

Destructor for the key store context.

sss_status_t sss_key_store_context_init(sss_key_store_t *keyStore, sss_session_t *session)

Constructor for the key store context data structure.

Parameters
  • [out] keyStore: Pointer to key store context. Key store context is updated on function return.

  • session: Session context.

sss_status_t sss_key_store_erase_key(sss_key_store_t *keyStore, sss_object_t *keyObject)

Delete / destroy allocated keyObect .

Return

The sss status.

Parameters
  • keyStore: The key store

  • keyObject: The key object to be deleted

sss_status_t sss_key_store_freeze_key(sss_key_store_t *keyStore, sss_object_t *keyObject)

The referenced key cannot be updated any more.

Return

The sss status.

Parameters
  • keyStore: The key store

  • keyObject: The key object to be locked / frozen.

sss_status_t sss_key_store_generate_key(sss_key_store_t *keyStore, sss_object_t *keyObject, size_t keyBitLen, void *options)

This function generates key[] in the destination key store.

sss_status_t sss_key_store_get_key(sss_key_store_t *keyStore, sss_object_t *keyObject, uint8_t *data, size_t *dataLen, size_t *pKeyBitLen)

This function exports plain key[] from key store (if constraints and user id allows reading)

sss_status_t sss_key_store_load(sss_key_store_t *keyStore)

Load from persistent memory to cached objects.

sss_status_t sss_key_store_open_key(sss_key_store_t *keyStore, sss_object_t *keyObject)

Access key store using one more level of encryption.

e.g. Access keys / encryption key during storage

Return

The sss status.

Parameters
  • keyStore: The key store

  • keyObject: The key object that is to be used as a KEK (Key Encryption Key)

sss_status_t sss_key_store_save(sss_key_store_t *keyStore)

Save all cached persistent objects to persistent memory.

sss_status_t sss_key_store_set_key(sss_key_store_t *keyStore, sss_object_t *keyObject, const uint8_t *data, size_t dataLen, size_t keyBitLen, void *options, size_t optionsLen)

This function moves data[] from memory to the destination key store.

Return

Parameters
  • keyStore: Key store context

  • keyObject: Reference to a key and it’s properties

  • data: Data to be stored in Key. When setting ecc private key only, do not include key header.

  • dataLen: Length of the data

  • keyBitLen: Crypto algorithm key bit length

  • options: Pointer to implementation specific options

  • optionsLen: Length of the options in bytes

struct sss_key_store_t
#include <fsl_sss_api.h>

Store for secure and non secure key objects within a cryptographic system.

  • A cryptographic system may have more than partitions to store such keys.

Public Members

uint8_t data[(0 + (1 * sizeof(void *)) + (4 * sizeof(void *)) + 32)]
struct sss_key_store_t::[anonymous] extension

Reserved memory for implementation specific extension

sss_session_t *session

Virtual connection between application (user context) and specific security subsystem and function thereof.

3.3.3.2. Key Format

The sss_key_store_set_key and sss_key_store_get_key API’s do not impose a specific format on the data parameter. Different implementations of the SSS API can have different capabilities in dealing with an input format (relevant for sss_key_store_set_key) and will use a specific output format (relevant for sss_key_store_get_key). The following section illustrates this by taking the example of the SE050 implementation in the context of EC Key pairs.

3.3.3.2.1. EC Key pair

When passing an EC key pair as data argument to the sss_key_store_set_key API, the key pair data must be DER encoded using either the pkcs#8 format or classic OpenSSL format.

When retrieving an EC key pair as data argument from the sss_key_store_get API, the full key pair cannot be retrieved. Instead the public key value is returned. The public key is retrieved in ANSI X9.62 uncompressed format.