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 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](https://developer.arm.com/documentation/ihi0086/latest/).

PSA Key Lifetimes¶

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

Key Location¶

The location defines whether or not the HSM will be involved in storing the key material. The HSM will be involved in using the key material regardless if the CryptoKey encoding is CryptoKey_HSM. 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_ASSSET_STORE	The key material is stored in plaintext inside the HSM. It can only be used as an ‘asset’ in a crypto operation.

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](https://developer.arm.com/documentation/ihi0086/latest/).

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
    )
);