Key Attributes API#

The following table lists the PSA Crypto API for the key attributes.

API	Description
`psa_key_attributes_init(…)`	Initialize the key attributes (`psa_key_attributes_t`) before calling any function.
`psa_get_key_attributes(…)`	Retrieve the key attributes (`psa_key_attributes_t`) of a key if successful.
`psa_reset_key_attributes(…)`	Reset the key attributes (`psa_key_attributes_t`) to an initialized state.
`psa_set_key_type(…)`	Declare the key type (`psa_key_type_t`) of a key.
`psa_get_key_type(…)`	Retrieve the key type (`psa_key_type_t`) from key attributes.
`psa_set_key_bits(…)`	Declare the key size (`psa_key_bits_t`) of a key.
`psa_get_key_bits(…)`	Retrieve the key size (`size_t`) from key attributes.
`psa_set_key_usage_flags(…)`	Declare the usage flags (`psa_key_usage_t`) for a key.
`psa_get_key_usage_flags(…)`	Retrieve the usage flags (`psa_key_usage_t`) from key attributes.
`psa_set_key_algorithm(…)`	Declare the permitted algorithm policy (`psa_algorithm_t`) for a key.
`psa_get_key_algorithm(…)`	Retrieve the algorithm policy (`psa_algorithm_t`) from key attributes.
`psa_set_key_id(…)`	Declare a key as persistent and set its key identifier (`psa_key_id_t`).
`psa_get_key_id(…)`	Retrieve the key identifier (`psa_key_id_t`) from key attributes.
`psa_set_key_lifetime(…)`	Set the location (`psa_key_lifetime_t`) of a persistent key.
`psa_get_key_lifetime(…)`	Retrieve the lifetime (`psa_key_lifetime_t`) from key attributes.

The following sections describe how to use the key attributes API to set up the storage for a key. Refer to the quick reference examples in Symmetric Key and Asymmetric Key for more details.

Volatile Plain Key

Key ID	Persistence Level	Location Indicator	API Flow
= 0	`PSA_KEY_PERSISTENCE_VOLATILE`	Local (0x0)	It is the default setting after calling `psa_key_attributes_init()`. No need to call `psa_set_key_id()` and `psa_set_key_lifetime()`.

Example:

psa_key_attributes_t key_attr;
key_attr = psa_key_attributes_init();
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&key_attr, 256);
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH);
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA_ANY);

Persistent Plain Key

Key ID	Persistence Level	Location Indicator	API Flow
> 0	`PSA_KEY_PERSISTENCE_DEFAULT`	Local (0x0)	A non-zero key ID in `psa_set_key_id()` will change the persistence level from `PSA_KEY_PERSISTENCE_VOLATILE` to `PSA_KEY_PERSISTENCE_DEFAULT`.

Example:

psa_key_attributes_t key_attr;
key_attr = psa_key_attributes_init();
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&key_attr, 256);
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH);
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA_ANY);
psa_set_key_id(&key_attr, 0x02);

Volatile Wrapped Key

Key ID	Persistence Level	Location Indicator	API Flow
= 0	`PSA_KEY_PERSISTENCE_VOLATILE`	Secure (0x1)	Use the `psa_set_key_lifetime()` to change the location indicator from Local to Secure (0x01).

Example:

psa_key_attributes_t key_attr;
key_attr = psa_key_attributes_init();
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&key_attr, 256);
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH);
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA_ANY);
psa_set_key_lifetime(&key_attr, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(PSA_KEY_PERSISTENCE_VOLATILE, 0x01));

Persistent Wrapped Key

Key ID	Persistence Level	Location Indicator	API Flow
> 0	`PSA_KEY_PERSISTENCE_DEFAULT`	Local (0x0)	A non-zero key ID in `psa_set_key_id()` will change the persistence level from `PSA_KEY_PERSISTENCE_VOLATILE` to `PSA_KEY_PERSISTENCE_DEFAULT`.
> 0	`PSA_KEY_PERSISTENCE_DEFAULT`	Secure (0x1)	Use the `psa_set_key_lifetime()` to change the location indicator from Local to Secure (0x01).

Example:

psa_key_attributes_t key_attr;
key_attr = psa_key_attributes_init();
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&key_attr, 256);
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH);
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA_ANY);
psa_set_key_id(&key_attr, 0x02);
psa_set_key_lifetime(&key_attr, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(PSA_KEY_PERSISTENCE_DEFAULT, 0x01));

Note:
The PSA_KEY_PERSISTENCE_DEFAULT is equal to PSA_KEY_LIFETIME_PERSISTENT.
Refer to Key Identifiers for details about the Key ID.