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 to PSA_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 static or inline, 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 static or inline, 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 static or inline, 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 static or inline, 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.