9.3. Key lifetimes

The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.

Lifetime values are composed from:

• A persistence level, which indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or persistent. See psa_key_persistence_t for more information.

• A location indicator, which indicates where the key is stored and where operations on the key are performed. See psa_key_location_t for more information.

There are two main types of lifetime, indicated by the persistence level: volatile and persistent.

9.3.1. Volatile keys

Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Volatile keys can be explicitly destroyed by the application.

Conceptually, a volatile key is stored in RAM. Volatile keys have the lifetime PSA_KEY_LIFETIME_VOLATILE.

To create a volatile key:

1. Populate a psa_key_attributes_t object with the required type, size, policy and other key attributes.

2. Create the key with one of the key creation functions. If successful, these functions output a transient key identifier.

To destroy a volatile key: call psa_destroy_key() with the key identifier. There must be a matching call to psa_destroy_key() for each successful call to a create a volatile key.

9.3.2. Persistent keys

Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.

Each persistent key has a permanent key identifier, which acts as a name for the key. Within an application, the key identifier corresponds to a single key. The application specifies the key identifier when the key is created and when using the key.

The lifetime attribute of a persistent key indicates how and where it is stored. The default lifetime value for a persistent key is PSA_KEY_LIFETIME_PERSISTENT, which corresponds to a default storage area. This specification defines how implementations can provide other lifetime values corresponding to different storage areas with different retention policies, or to secure elements with different security characteristics.

To create a persistent key:

1. Populate a psa_key_attributes_t object with the key’s type, size, policy and other attributes.

2. In the attributes object, set the desired lifetime and persistent identifier for the key.

3. Create the key with one of the key creation functions. If successful, these functions output the key identifier that was specified by the application in step 2.

To access an existing persistent key: use the key identifier in any API that requires a key.

To destroy a persistent key: call psa_destroy_key() with the key identifier. Destroying a persistent key permanently removes it from memory and storage.

By default, persistent key material is removed from volatile memory when not in use. Frequently used persistent keys can benefit from caching, depending on the implementation and the application. Caching can be enabled by creating the key with the PSA_KEY_USAGE_CACHE policy. Cached keys can be removed from volatile memory by calling psa_purge_key(). See also Memory cleanup and Managing key material.

9.3.3. Lifetime encodings

psa_key_lifetime_t (typedef)

Encoding of key lifetimes.

typedef uint32_t psa_key_lifetime_t;

The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.

Lifetime values have the following structure:

Bits[7:0]: Persistence level

This value indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or persistent. See psa_key_persistence_t for more information.

PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) returns the persistence level for a key lifetime value.

Bits[31:8]: Location indicator

This value indicates where the key material is stored (or at least where it is accessible in cleartext) and where operations on the key are performed. See psa_key_location_t for more information.

PSA_KEY_LIFETIME_GET_LOCATION(lifetime) returns the location indicator for a key lifetime value.

Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.

Persistent keys have a key identifier of type psa_key_id_t. This identifier remains valid throughout the lifetime of the key, even if the application instance that created the key terminates.

This specification defines two basic lifetime values:

• Keys with the lifetime PSA_KEY_LIFETIME_VOLATILE are volatile. All implementations should support this lifetime.

• Keys with the lifetime PSA_KEY_LIFETIME_PERSISTENT are persistent. All implementations that have access to persistent storage with appropriate security guarantees should support this lifetime.

psa_key_persistence_t (typedef)

Encoding of key persistence levels.

typedef uint8_t psa_key_persistence_t;

What distinguishes different persistence levels is which device management events can cause keys to be destroyed. For example, power reset, transfer of device ownership, or a factory reset are device management events that can affect keys at different persistence levels. The specific management events which affect persistent keys at different levels is outside the scope of the Crypto API.

Values for persistence levels defined by Crypto API are shown in Table 5.

Table 5 Key persistence level values

Persistence level	Definition
0 = PSA_KEY_PERSISTENCE_VOLATILE	Volatile key. A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device.
1 = PSA_KEY_PERSISTENCE_DEFAULT	Persistent key with a default lifetime. Implementations should support this value if they support persistent keys at all. Applications should use this value if they have no specific needs that are only met by implementation-specific features.
2 – 127	Persistent key with a PSA Certified API-specified lifetime. The Crypto API does not define the meaning of these values, but another PSA Certified API may do so.
128 – 254	Persistent key with a vendor-specified lifetime. No PSA Certified API will define the meaning of these values, so implementations may choose the meaning freely. As a guideline, higher persistence levels should cause a key to survive more management events than lower levels.
255 = PSA_KEY_PERSISTENCE_READ_ONLY	Read-only or write-once key. A key with this persistence level cannot be destroyed. Implementations that support such keys may either allow their creation through the Crypto API, preferably only to applications with the appropriate privilege, or only expose keys created through implementation-specific means such as a factory ROM engraving process. Note that keys that are read-only due to policy restrictions rather than due to physical limitations should not have this persistence level.

Note

Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes (type psa_key_lifetime_t), and encode the persistence value as the lower 8 bits of a 32-bit value.

psa_key_location_t (typedef)

Encoding of key location indicators.

typedef uint32_t psa_key_location_t;

If an implementation of the Crypto API can make calls to external cryptoprocessors such as secure elements, the location of a key indicates which secure element performs the operations on the key. If the key material is not stored persistently inside the secure element, it must be stored in a wrapped form such that only the secure element can access the key material in cleartext.

Values for location indicators defined by this specification are shown in Table 6.

Table 6 Key location indicator values

Location indicator	Definition
0	Primary local storage. All implementations should support this value. The primary local storage is typically the same storage area that contains the key metadata.
1	Primary secure element. Implementations should support this value if there is a secure element attached to the operating environment. As a guideline, secure elements may provide higher resistance against side channel and physical attacks than the primary local storage, but may have restrictions on supported key types, sizes, policies and operations and may have different performance characteristics.
2 – 0x7fffff	Other locations defined by a PSA specification. The Crypto API does not currently assign any meaning to these locations, but future versions of this specification or other PSA Certified APIs may do so.
0x800000 – 0xffffff	Vendor-defined locations. No PSA Certified API will assign a meaning to locations in this range.

Note

Key location indicators are 24-bit values. Key management interfaces operate on lifetimes (type psa_key_lifetime_t), and encode the location as the upper 24 bits of a 32-bit value.

9.3.4. Lifetime values

PSA_KEY_LIFETIME_VOLATILE (macro)

The default lifetime for volatile keys.

#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t) 0x00000000)

A volatile key only exists as long as its identifier is not destroyed. The key material is guaranteed to be erased on a power reset.

A key with this lifetime is typically stored in the RAM area of the Crypto API implementation. However this is an implementation choice. If an implementation stores data about the key in a non-volatile memory, it must release all the resources associated with the key and erase the key material if the calling application terminates.

PSA_KEY_LIFETIME_PERSISTENT (macro)

The default lifetime 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.

PSA_KEY_PERSISTENCE_VOLATILE (macro)

The persistence level of volatile keys.

#define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t) 0x00)

See psa_key_persistence_t for more information.

PSA_KEY_PERSISTENCE_DEFAULT (macro)

The default persistence level for persistent keys.

#define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t) 0x01)

See psa_key_persistence_t for more information.

PSA_KEY_PERSISTENCE_READ_ONLY (macro)

A persistence level indicating that a key is never destroyed.

#define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t) 0xff)

See psa_key_persistence_t for more information.

PSA_KEY_LOCATION_LOCAL_STORAGE (macro)

The local storage area for persistent keys.

#define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t) 0x000000)

This storage area is available on all systems that can store persistent keys without delegating the storage to a third-party cryptoprocessor.

See psa_key_location_t for more information.

PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT (macro)

The default secure element storage area for persistent keys.

#define PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT ((psa_key_location_t) 0x000001)

This storage location is available on systems that have one or more secure elements that are able to store keys.

Vendor-defined locations must be provided by the system for storing keys in additional secure elements.

See psa_key_location_t for more information.

9.3.5. 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(), psa_key_agreement(), 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_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. It can be efficiently implemented as a static inline function or a function-like-macro.

9.3.6. Support macros

PSA_KEY_LIFETIME_GET_PERSISTENCE (macro)

Extract the persistence level from a key lifetime.

#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \
    ((psa_key_persistence_t) ((lifetime) & 0x000000ff))

Parameters

lifetime

The lifetime value to query: a value of type psa_key_lifetime_t.

PSA_KEY_LIFETIME_GET_LOCATION (macro)

Extract the location indicator from a key lifetime.

#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \
    ((psa_key_location_t) ((lifetime) >> 8))

Parameters

lifetime

The lifetime value to query: a value of type psa_key_lifetime_t.

PSA_KEY_LIFETIME_IS_VOLATILE (macro)

Whether a key lifetime indicates that the key is volatile.

#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \
    (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == PSA_KEY_PERSISTENCE_VOLATILE)

Parameters

lifetime

The lifetime value to query: a value of type psa_key_lifetime_t.

Returns

1 if the key is volatile, otherwise 0.

Description

A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device.

A key that is not volatile is persistent. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.

PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION (macro)

Construct a lifetime from a persistence level and a location.

#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \
    ((location) << 8 | (persistence))

Parameters

persistence

The persistence level: a value of type psa_key_persistence_t.

location

The location indicator: a value of type psa_key_location_t.

Returns

The constructed lifetime value.