9.4. Key identifiers

Key identifiers are integral values that act as permanent names for persistent keys, or as transient references to volatile keys. Key identifiers use the psa_key_id_t type, and the range of identifier values is divided as follows:

PSA_KEY_ID_NULL = 0

Reserved as an invalid key identifier.

PSA_KEY_ID_USER_MIN – PSA_KEY_ID_USER_MAX

Applications can freely choose persistent key identifiers in this range.

PSA_KEY_ID_VENDOR_MIN – PSA_KEY_ID_VENDOR_MAX

Implementations can define additional persistent key identifiers in this range, and must allocate any volatile key identifiers from this range.

Key identifiers outside these ranges are reserved for future use.

Key identifiers are output from a successful call to one of the key creation functions. For persistent keys, this is the same identifier as the one specified in the key attributes used to create the key. The key identifier remains valid until it is invalidated by passing it to psa_destroy_key(). A volatile key identifier must not be used after it has been invalidated.

If an invalid key identifier is provided as a parameter in any function, the function will return PSA_ERROR_INVALID_HANDLE; except for the special case of calling psa_destroy_key(PSA_KEY_ID_NULL), which has no effect and always returns PSA_SUCCESS.

Valid key identifiers must have distinct values within the same application. If the implementation provides caller isolation, then key identifiers are local to each application. That is, the same key identifier in two applications corresponds to two different keys.

9.4.1. Key identifier type

psa_key_id_t (typedef)

Key identifier.

typedef uint32_t psa_key_id_t;

A key identifier can be a permanent name for a persistent key, or a transient reference to volatile key. See 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)

9.4.2. Attribute accessors

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

The application must choose a value for id between PSA_KEY_ID_USER_MIN and PSA_KEY_ID_USER_MAX.

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. It can be efficiently implemented as a static inline function or a function-like-macro.

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. It can be efficiently implemented as a static inline function or a function-like-macro.