.. _keylifetimes_cc23xx:

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 <https://developer.arm.com/documentation/ihi0086/latest/>`_.

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. 

.. _fig-keystore_sysconfig:
.. figure:: resources/keystore_sysconfig.png
    :align: center

    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)

.. _fig-keystore_psa:
.. figure:: resources/keystore_psa.png
    :align: center

    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 <https://developer.arm.com/documentation/ihi0086/latest/>`_

.. note::
    Key Lifetime should be set using the PSA Crypto API:

    .. code:: C

        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.

.. code:: C

    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.

.. code:: C

    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. 

.. code:: C

    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.

.. code:: C

    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.

.. code:: C

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