KeyStore¶

KeyStore is a security design that allows applications to use keys without direct access to the key material. Applications will import keys to a secure storage area, and they will receive a key identifier to reference the key in future operations. Therefore, the key material does not have to be exposed in the application space. Further, the implementation of KeyStore is required to use the Platform Security Architecture (PSA) API, which take key identifiers as input instead of plaintext.

For more information regarding the PSA API please refer to the PSA Certified Crypto API.

Adding KeyStore Support to your Project¶

In the SysConfig for your project, scroll to the ‘Crypto Drivers’ section. Find ‘PSA Crypto + KeyStore’ and add it to your project.

Figure 75. KeyStore + PSA Sysconfig.¶

Note that it will automatically add the modules it depends on. Read below for details on the potential configuration options. By default, there is no space for volatile keys in KeyStore. These must be selected via the SysConfig tool.

KeyStore Volatile & Non-Volatile Memory Space¶

KeyStore RAM occupies, by default, 1018 bytes of memory. This consists of the metadata of 3 HSM Asset Store keys (configuratble via Sysconfig), metadata of 3 persistent keys (non-configurable), and the key material of 3 cahced persistent keys.

KeyStore Flash occupies, by default 8 kB of flash. However, this may be adjusted via the Sysconfig module by selecting which key types/sizes will be used by the application. There are 3 available options:

4 kB (10 persistent keys of any type)
8 kB (23 persistent keys of any type)
16 kB (35 persistent keys of any type)

Figure 76. KeyStore + PSA Sysconfig.¶

Warning

Regardless of the linker command file layout, the region of flash allocated for Non-Volatile KeyStore may be reserved for the last 2-5 pages before the HSM firmware region.

Key Lifetimes¶

Key Lifetime is the combination of key location and key persistence in PSA Key Attributes.

Key Location¶

The key location defines whether or not the HSM will be involved in storing the key material. If the CryptoKey encoding is CryptoKey_HSM, the HSM will be used to perform the cryptographic operation regardless of the key location. The location specifies where/how the material is stored before being provided to the HSM for the crypto operation.

Location

Meaning

PSA KeyStore

The plaintext key material will be stored in KeyStore RAM or KeyStore NVM (TF-M Internal Trusted Storage).

HSM Asset Store

The plaintext key material will only be accessible inside the HSM when the crypto operation is being executed. Depending on the key persistence, the key material will either be only in the HSM (unwrapped, i.e unecrypted) or in KeyStore RAM/NVM (wrapped, i.e encrypted).

Note: Plaintext key material cannot be exported from the HSM Asset Store - this location should not be used if that is the goal.

Key Persistence¶

The persistence defines the actual memory destination–that is, the location where either a plaintext or wrapped key will exist when it is imported.

Note

References to “key material” in the table below could mean plaintext or wrapped key material. This depends on the combination of location + persistence.

Persistence	Meaning
PSA_KEY_PERSISTENCE_VOLATILE	The key material is stored in KeyStore RAM.
PSA_KEY_PERSISTENCE_DEFAULT	The key material is stored in KeyStore NVM, using psa_its_<> APIs. It is also cached inside KeyStore RAM. Persistent keys in the cache may be replaced if space is limited. Persistent keys with usage PSA_KEY_USAGE_CACHE have preference to avoid replacement in the cache.
PSA_KEY_PERSISTENCE_HSM_ASSET_STORE	The key material is stored in plaintext inside the HSM. It can only be used as an ‘asset’ in a crypto operation. Keys with this persistence are lost when the device loses power.

Key Lifetime Combinations¶

Below are the different available Key Lifetime combinations supported by the PSA wrapper. For more information regarding the specification please refer to PSA Certified Crypto API

Note

Key Lifetime should be set using the PSA Crypto API:

psa_set_key_lifetime(
        &attributes,
        PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(...)
    );

PSA_KEY_LOCATION_LOCAL_STORAGE + PSA_KEY_PERSISTENCE_VOLATILE¶

Purpose/Usage:

A volatile key ID is OUTPUT when a key with this lifetime is created.
The attributes struct should not provide a key ID as input.
For temporary keys that require default KeyStore security.

psa_set_key_lifetime(
    &attributes,
    PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
        PSA_KEY_PERSISTENCE_VOLATILE,
        PSA_KEY_LOCATION_LOCAL_STORAGE
    )
);

PSA_KEY_LOCATION_LOCAL_STORAGE + PSA_KEY_PERSISTENCE_DEFAULT¶

Purpose/Usage:

The attribute struct should provide a key ID via the psa_set_key_id API before creating a key with this lifetime.
For persistent keys that will be used for an extended period and require default KeyStore security.

psa_set_key_lifetime(
    &attributes,
    PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
        PSA_KEY_PERSISTENCE_DEFAULT,
        PSA_KEY_LOCATION_LOCAL_STORAGE
    )
);

PSA_KEY_LOCATION_LOCAL_STORAGE + PSA_KEY_PERSISTENCE_HSM_ASSET_STORE¶

Not Supported.

PSA_KEY_LOCATION_HSM_ASSET_STORE + PSA_KEY_PERSISTENCE_VOLATILE¶

Purpose/Usage:

A volatile key ID is OUTPUT when a key with this lifetime is created. The attributes struct should not provide a key ID as input.
For temporary keys that will be used for an extended period and also require maximum possible security of existing only (in plaintext) in the secure element.
This combination has more overhead than the PERSISTENCE_HSM_ASSET_STORE.

psa_set_key_lifetime(
    &attributes,
    PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
        PSA_KEY_PERSISTENCE_VOLATILE,
        PSA_KEY_LOCATION_HSM_ASSET_STORE
    )
);

PSA_KEY_LOCATION_HSM_ASSET_STORE + PSA_KEY_PERSISTENCE_DEFAULT¶

Purpose/Usage:

The attributes struct should provide a key ID via the psa_set_key_id API before creating a key with this lifetime.
For persistent keys that will be used for an extended period and also require the maximum possible security of existing only (in plaintext) in the secure element.

psa_set_key_lifetime(
    &attributes,
    PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
        PSA_KEY_PERSISTENCE_DEFAULT,
        PSA_KEY_LOCATION_HSM_ASSET_STORE
    )
)

PSA_KEY_LOCATION_HSM_ASSET_STORE + PSA_KEY_PERSISTENCE_HSM_ASSET_STORE¶

Purpose/Usage:

The attributes struct should provide a key ID via the psa_set_key_id API before creating a key with this lifetime.
For keys that require the maximum possible security of existing only in the secure element and that require low overhead for usage.
The HSM Asset Store has limited space, so keys that are retained within it (this key lifetime only) should be the highest priority/most frequently used keys.
This lifetime offers the lowest overhead of the HSM Asset Store Location combinations, since there are no keyblobs involved.

psa_set_key_lifetime(
    &attributes,
    PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
        PSA_KEY_PERSISTENCE_HSM_ASSET_STORE,
        PSA_KEY_LOCATION_HSM_ASSET_STORE
    )
);