SE RT Services Utilities library

| SE RT Services Utilities library

Macros | Typedefs | Functions
Key lifetimes
IFX SE PSA crypto API » Key attributes operations

## General Description

Key lifetimes operations definitions.

## Macros
#define | IFX_SE_KEY_LIFETIME_VOLATILE ((ifx_se_key_lifetime_t)0x00000000)
| The default lifetime for volatile keys. More...
#define | IFX_SE_KEY_LIFETIME_PERSISTENT ((ifx_se_key_lifetime_t)0x00000001)
| The default lifetime for persistent keys. More...
#define | IFX_SE_KEY_PERSISTENCE_VOLATILE ((ifx_se_key_persistence_t)0x00)
| The persistence level of volatile keys. More...
#define | IFX_SE_KEY_PERSISTENCE_DEFAULT ((ifx_se_key_persistence_t)0x01)
| The default persistence level for persistent keys. More...
#define | IFX_SE_KEY_PERSISTENCE_READ_ONLY ((ifx_se_key_persistence_t)0xff)
| A persistence level indicating that a key is never destroyed. More...
#define | IFX_SE_KEY_LIFETIME_GET_PERSISTENCE(lifetime) ((ifx_se_key_persistence_t)((lifetime) & 0x000000ffuL))
| See ifx_se_key_persistence_t for more information.
#define | IFX_SE_KEY_LIFETIME_GET_LOCATION(lifetime) ((ifx_se_key_location_t)((lifetime) >> 8))
| See ifx_se_key_persistence_t for more information.
#define | IFX_SE_KEY_LIFETIME_IS_VOLATILE(lifetime)
| Whether a key lifetime indicates that the key is volatile. More...
#define | IFX_SE_KEY_LIFETIME_IS_READ_ONLY(lifetime)
| Whether a key lifetime indicates that the key is read-only. More...
#define | IFX_SE_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) (((location) << 8) | (persistence))
| Construct a lifetime from a persistence level and a location. More...
#define | IFX_SE_KEY_LOCATION_LOCAL_STORAGE ((ifx_se_key_location_t)0x000000)
| The local storage area for persistent keys. More...
#define | IFX_SE_KEY_LOCATION_SE ((ifx_se_key_location_t)0x800001)
| The SE RT Services storage area. More...

## Typedefs
typedef uint32_t | ifx_se_key_lifetime_t
| Encoding of key lifetimes. More...
typedef uint8_t | ifx_se_key_persistence_t
| Encoding of key persistence levels. More...
typedef uint32_t | ifx_se_key_location_t
| Encoding of key location indicators. More...

## Functions
static void | ifx_se_set_key_lifetime (ifx_se_key_attributes_t *attributes, ifx_se_key_lifetime_t lifetime)
| Sets key lifetime in key attributes structure. More...
static ifx_se_key_lifetime_t | ifx_se_get_key_lifetime (const ifx_se_key_attributes_t *attributes)
| Gets key lifetime from key attributes structure. More...

## Macro Definition Documentation

## ◆ IFX_SE_KEY_LIFETIME_VOLATILE

#define IFX_SE_KEY_LIFETIME_VOLATILE ((ifx_se_key_lifetime_t)0x00000000)

The default lifetime for volatile keys.

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.

A key with this lifetime is typically stored in the RAM area of the PSA Crypto subsystem. 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.

## ◆ IFX_SE_KEY_LIFETIME_PERSISTENT

#define IFX_SE_KEY_LIFETIME_PERSISTENT ((ifx_se_key_lifetime_t)0x00000001)

The default lifetime for persistent keys.

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, but integrations may 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. Integrations of Mbed TLS may support other persistent lifetimes. See ifx_se_key_lifetime_t for more information.

## ◆ IFX_SE_KEY_PERSISTENCE_VOLATILE

#define IFX_SE_KEY_PERSISTENCE_VOLATILE ((ifx_se_key_persistence_t)0x00)

The persistence level of volatile keys.

See ifx_se_key_persistence_t for more information.

## ◆ IFX_SE_KEY_PERSISTENCE_DEFAULT

#define IFX_SE_KEY_PERSISTENCE_DEFAULT ((ifx_se_key_persistence_t)0x01)

The default persistence level for persistent keys.

See ifx_se_key_persistence_t for more information.

## ◆ IFX_SE_KEY_PERSISTENCE_READ_ONLY

#define IFX_SE_KEY_PERSISTENCE_READ_ONLY ((ifx_se_key_persistence_t)0xff)

A persistence level indicating that a key is never destroyed.

See ifx_se_key_persistence_t for more information.

## ◆ IFX_SE_KEY_LIFETIME_IS_VOLATILE

#define IFX_SE_KEY_LIFETIME_IS_VOLATILE | ( |  | lifetime | ) |

Value:
(IFX_SE_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
IFX_SE_KEY_PERSISTENCE_VOLATILE)
IFX_SE_KEY_LIFETIME_GET_PERSISTENCE
#define IFX_SE_KEY_LIFETIME_GET_PERSISTENCE(lifetime)
See ifx_se_key_persistence_t for more information.
Definition: ifx_se_psacrypto_values.h:2354

Whether a key lifetime indicates that the key is volatile.

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).

Parameters

  lifetime | The lifetime value to query (value of type ifx_se_key_lifetime_t).

Returns
  `1` if the key is volatile, otherwise `0`.

## ◆ IFX_SE_KEY_LIFETIME_IS_READ_ONLY

#define IFX_SE_KEY_LIFETIME_IS_READ_ONLY | ( |  | lifetime | ) |

Value:
(IFX_SE_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
IFX_SE_KEY_PERSISTENCE_READ_ONLY)

Whether a key lifetime indicates that the key is read-only.

Read-only keys cannot be created or destroyed through the PSA Crypto API. They must be created through platform-specific means that bypass the API.

Some platforms may offer ways to destroy read-only keys. For example, consider a platform with multiple levels of privilege, where a low-privilege application can use a key but is not allowed to destroy it, and the platform exposes the key to the application with a read-only lifetime. High-privilege code can destroy the key even though the application sees the key as read-only.

Parameters

  lifetime | The lifetime value to query (value of type ifx_se_key_lifetime_t).

Returns
  `1` if the key is read-only, otherwise `0`.

## ◆ IFX_SE_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION

#define IFX_SE_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION | ( |  | persistence,
|  |  | location
| ) |  | (((location) << 8) | (persistence))

Construct a lifetime from a persistence level and a location.

Parameters

  persistence | The persistence level (value of type ifx_se_key_persistence_t).
  location | The location indicator (value of type ifx_se_key_location_t).

Returns
  The constructed lifetime value.

## ◆ IFX_SE_KEY_LOCATION_LOCAL_STORAGE

#define IFX_SE_KEY_LOCATION_LOCAL_STORAGE ((ifx_se_key_location_t)0x000000)

The local storage area for persistent keys.

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

See ifx_se_key_location_t for more information.

## ◆ IFX_SE_KEY_LOCATION_SE

#define IFX_SE_KEY_LOCATION_SE ((ifx_se_key_location_t)0x800001)

The SE RT Services storage area.

See ifx_se_key_location_t for more information.

## Typedef Documentation

## ◆ ifx_se_key_lifetime_t

typedef uint32_t ifx_se_key_lifetime_t

Encoding of key lifetimes.

The lifetime of a key indicates where it is stored and what system actions may create and destroy it.

Lifetime values have the following structure:

- Bits 0-7 (IFX_SE_KEY_LIFETIME_GET_PERSISTENCE(`lifetime`)): 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 ifx_se_key_persistence_t for more information.
- Bits 8-31 (IFX_SE_KEY_LIFETIME_GET_LOCATION(`lifetime`)): location indicator. This value indicates which part of the system has access to the key material and can perform operations using the key. See ifx_se_key_location_t for more information.

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 integration-specific device management event occurs (for example, a factory reset).

Persistent keys have a key identifier of type ifx_se_svc_key_id_t. This identifier remains valid throughout the lifetime of the key, even if the application instance that created the key terminates. The application can call ifx_se_open_key() to open a persistent key that it created previously.

The default lifetime of a key is IFX_SE_KEY_LIFETIME_VOLATILE. The lifetime IFX_SE_KEY_LIFETIME_PERSISTENT is supported if persistent storage is available. Other lifetime values may be supported depending on the library configuration.

## ◆ ifx_se_key_persistence_t

typedef uint8_t ifx_se_key_persistence_t

Encoding of key persistence levels.

What distinguishes different persistence levels is what device management events may cause keys to be destroyed. Volatile keys are destroyed by a power reset. Persistent keys may be destroyed by events such as a transfer of ownership or a factory reset. What management events actually affect persistent keys at different levels is outside the scope of the PSA Cryptography specification.

The PSA Cryptography specification defines the following values of persistence levels:

- `0` = IFX_SE_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` = IFX_SE_KEY_PERSISTENCE_DEFAULT: persistent key with a default lifetime.
- `2-254`: currently not supported by Mbed TLS.
- `255` = IFX_SE_KEY_PERSISTENCE_READ_ONLY: read-only or write-once key. A key with this persistence level cannot be destroyed. Mbed TLS does not currently offer a way to create such keys, but integrations of Mbed TLS can use it for built-in keys that the application cannot modify (for example, a hardware unique key (HUK)).

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

## ◆ ifx_se_key_location_t

typedef uint32_t ifx_se_key_location_t

Encoding of key location indicators.

If an integration of Mbed TLS 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. Depending on the design of the secure element, the key material may be stored either in the secure element, or in wrapped (encrypted) form alongside the key metadata in the primary local storage.

The PSA Cryptography API specification defines the following values of location indicators:

- `0`: primary local storage. This location is always available. The primary local storage is typically the same storage area that contains the key metadata.
- `1`: primary secure element. Integrations of Mbed TLS 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 PSA Cryptography API does not currently assign any meaning to these locations, but future versions of that specification or other PSA specifications may do so.
- `0x800000-0xffffff`: vendor-defined locations. No PSA specification will assign a meaning to locations in this range.

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

## Function Documentation

## ◆ ifx_se_set_key_lifetime()

static void ifx_se_set_key_lifetime | ( | ifx_se_key_attributes_t * | attributes,
|  | ifx_se_key_lifetime_t | lifetime
| ) |  |
| inlinestatic

Sets key lifetime in key attributes structure.

Parameters

  [in] | attributes | Key attributes structure
  [in] | lifetime | Key lifetime

## ◆ ifx_se_get_key_lifetime()

static ifx_se_key_lifetime_t ifx_se_get_key_lifetime | ( | const ifx_se_key_attributes_t * | attributes | ) |
| inlinestatic

Gets key lifetime from key attributes structure.

Parameters

  [in] | attributes | Key attributes structure

Returns
  Key lifetime