Key locations
Key lifetimes
PSA_KEY_LIFETIME_VOLATILE (macro)
A lifetime value that indicates a volatile key.
#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000)
A volatile key only exists as long as the identifier to it is not destroyed.
The key material is guaranteed to be erased on a power reset.
PSA_KEY_LIFETIME_PERSISTENT (macro)
The default storage area for persistent keys.
#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001)
A persistent key remains in storage until it is explicitly destroyed or until the corresponding storage area is wiped. This specification does not define any mechanism to wipe a storage area. Implementations are permitted to provide their own mechanism, for example, to perform a factory reset, to prepare for device refurbishment, or to uninstall an application.
This lifetime value is the default storage area for the calling application. Implementations can offer other storage areas designated by other lifetime values as implementation-specific extensions.
Key identifiers
PSA_KEY_ID_NULL (macro)
The null key identifier.
#define PSA_KEY_ID_NULL ((psa_key_id_t)0)
The null key identifier is always invalid, except when used without in a call to psa_destroy_key() which will return PSA_SUCCESS.
PSA_KEY_ID_USER_MIN (macro)
The minimum value for a key identifier chosen by the application.
#define PSA_KEY_ID_USER_MIN ((psa_key_id_t)0x00000001)
PSA_KEY_ID_USER_MAX (macro)
The maximum value for a key identifier chosen by the application.
#define PSA_KEY_ID_USER_MAX ((psa_key_id_t)0x3fffffff)
PSA_KEY_ID_VENDOR_MIN (macro)
The minimum value for a key identifier chosen by the implementation.
#define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t)0x40000000)
PSA_KEY_ID_VENDOR_MAX (macro)
The maximum value for a key identifier chosen by the implementation.
#define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t)0x7fffffff)
Attribute accessors
psa_set_key_lifetime (function)
Set the location of a persistent key.
void psa_set_key_lifetime(psa_key_attributes_t * attributes, psa_key_lifetime_t lifetime);
Parameters
-
attributes - The attribute object to write to.
-
lifetime - The lifetime for the key. If this is
PSA_KEY_LIFETIME_VOLATILE, the key will be volatile, and the key identifier attribute is reset toPSA_KEY_ID_NULL.
Returns: void
Description
To make a key persistent, give it a persistent key identifier by using psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile.
This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().
Implementation note
This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:
- This function can be declared as
staticorinline, instead of using the default external linkage. - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.
psa_get_key_lifetime (function)
Retrieve the lifetime from key attributes.
psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t * attributes);
Parameters
-
attributes - The key attribute object to query.
Returns: psa_key_lifetime_t
The lifetime value stored in the attribute object.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:
- This function can be declared as
staticorinline, instead of using the default external linkage. - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.
psa_set_key_id (function)
Declare a key as persistent and set its key identifier.
void psa_set_key_id(psa_key_attributes_t * attributes, psa_key_id_t id);
Parameters
-
attributes - The attribute object to write to.
-
id - The persistent identifier for the key.
Returns: void
Description
If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to PSA_KEY_LIFETIME_PERSISTENT.
This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().
Implementation note
This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:
- This function can be declared as
staticorinline, instead of using the default external linkage. - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.
psa_get_key_id (function)
Retrieve the key identifier from key attributes.
psa_key_id_t psa_get_key_id(const psa_key_attributes_t * attributes);
Parameters
-
attributes - The key attribute object to query.
Returns: psa_key_id_t
The persistent identifier stored in the attribute object. This value is unspecified if the attribute object declares the key as volatile.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:
- This function can be declared as
staticorinline, instead of using the default external linkage. - This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.