SE RT Services Utilities library

| SE RT Services Utilities library

API Reference | Data Structures | Macros | Typedefs | Functions
Key attributes operations
IFX SE PSA crypto API

## General Description

Key attributes operations definitions.

## API Reference
| Key types
| Key types operations definitions.
| Key algorithms
| Key algorithms operations definitions.
| Key policies
| Key policies operations definitions.
| Key lifetimes
| Key lifetimes operations definitions.
| Built-In keys
| Built-In keys definitions.

## Data Structures
struct | ifx_se_svc_key_id_t
| Encoding of key identifiers as seen inside the PSA Crypto implementation. More...

## Macros
#define | IFX_SE_KEY_ATTRIBUTES_INIT
| The initial value of the key attributes. More...
#define | IFX_SE_KEY_ID_NULL ((ifx_se_key_id_t)0)
| The null key identifier.
#define | IFX_SE_KEY_ID_USER_MIN ((ifx_se_key_id_t)0x00000001)
| The minimum value for a key identifier chosen by the application.
#define | IFX_SE_KEY_ID_USER_MAX ((ifx_se_key_id_t)0x3fffffff)
| The maximum value for a key identifier chosen by the application.
#define | IFX_SE_KEY_ID_VENDOR_MIN ((ifx_se_key_id_t)0x40000000)
| The minimum value for a key identifier chosen by the implementation.
#define | IFX_SE_KEY_ID_VENDOR_MAX ((ifx_se_key_id_t)0x7fffffff)
| The maximum value for a key identifier chosen by the implementation.
#define | IFX_SE_KEY_ID_BUILTIN_MIN ((ifx_se_key_id_t)0x7fff0000)
| The minimum value for a key identifier that is built into the implementation. More...
#define | IFX_SE_KEY_ID_BUILTIN_MAX ((ifx_se_key_id_t)0x7fffefff)
| The maximum value for a key identifier that is built into the implementation. More...

## Typedefs
typedef uint32_t | ifx_se_key_id_t
| Encoding of identifiers of persistent keys. More...
typedef int32_t | ifx_se_key_owner_id_t
| Building for the PSA Crypto service on a PSA platform, a key owner is a PSA partition identifier.
typedef struct ifx_se_key_id_fih_s | ifx_se_key_id_fih_t
| The type of the of keys identifier transfer data. More...
typedef struct ifx_se_key_attributes_s | ifx_se_key_attributes_t
| The type of a structure containing key attributes. More...

## Functions
void | ifx_se_reset_key_attributes (ifx_se_key_attributes_t *attributes)
| Reset a key attribute structure to a freshly initialized state. More...
ifx_se_status_t | ifx_se_get_key_attributes (ifx_se_key_id_fih_t key, ifx_se_key_attributes_t *attributes, void *ctx)
| Retrieve the attributes of a key. More...
static struct ifx_se_key_attributes_s | ifx_se_key_attributes_init (void)
| Sets key attributes structure with initial value. More...
static void | ifx_se_set_key_id (ifx_se_key_attributes_t *attributes, ifx_se_svc_key_id_t key)
| Sets key ID in key attributes structure. More...
static ifx_se_svc_key_id_t | ifx_se_get_key_id (const ifx_se_key_attributes_t *attributes)
| Gets key ID from key attributes structure. More...
static ifx_se_svc_key_id_t | ifx_se_svc_key_id_make (ifx_se_key_owner_id_t owner_id, ifx_se_key_id_t key_id)
| Utility to initialize a key identifier at runtime. More...

## Data Structure Documentation

## ◆ ifx_se_svc_key_id_t

struct ifx_se_svc_key_id_t

Data Fields
ifx_se_key_id_t | key_id | Key ID in persistent key storage
ifx_se_key_owner_id_t | owner | Encoded owner of a key with this ID

## Macro Definition Documentation

## ◆ IFX_SE_KEY_ATTRIBUTES_INIT

#define IFX_SE_KEY_ATTRIBUTES_INIT

Value:
{ IFX_SE_KEY_TYPE_NONE, 0, \
IFX_SE_KEY_LIFETIME_VOLATILE, \
IFX_SE_KEY_POLICY_INIT, \
IFX_SE_SVC_KEY_ID_INIT }
IFX_SE_KEY_TYPE_NONE
#define IFX_SE_KEY_TYPE_NONE
An invalid key type value.
Definition: ifx_se_psacrypto_values.h:337

The initial value of the key attributes.

## ◆ IFX_SE_KEY_ID_BUILTIN_MIN

#define IFX_SE_KEY_ID_BUILTIN_MIN ((ifx_se_key_id_t)0x7fff0000)

The minimum value for a key identifier that is built into the implementation.

This value is part of the library's ABI since changing it would invalidate the values of built-in key identifiers in applications.

## ◆ IFX_SE_KEY_ID_BUILTIN_MAX

#define IFX_SE_KEY_ID_BUILTIN_MAX ((ifx_se_key_id_t)0x7fffefff)

The maximum value for a key identifier that is built into the implementation.

See IFX_SE_KEY_ID_BUILTIN_MIN for more information.

## Typedef Documentation

## ◆ ifx_se_key_id_t

typedef uint32_t ifx_se_key_id_t

Encoding of identifiers of persistent keys.

- Applications may freely choose key identifiers in the range IFX_SE_KEY_ID_USER_MIN to IFX_SE_KEY_ID_USER_MAX.
- The implementation may define additional key identifiers in the range IFX_SE_KEY_ID_VENDOR_MIN to IFX_SE_KEY_ID_VENDOR_MAX.
- 0 is reserved as an invalid key identifier.
- Key identifiers outside these ranges are reserved for future use.

## ◆ ifx_se_key_id_fih_t

typedef struct ifx_se_key_id_fih_s ifx_se_key_id_fih_t

The type of the of keys identifier transfer data.

This is an implementation-defined `struct`. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Members:

- ifx_se_fih_uint key_id - ID of a key
- ifx_se_fih_uint owner - Key owner

## ◆ ifx_se_key_attributes_t

typedef struct ifx_se_key_attributes_s ifx_se_key_attributes_t

The type of a structure containing key attributes.

Members:

- ifx_se_key_type_t type - Defines key type
- ifx_se_key_bits_t bits - Defines size of a key in bits
- ifx_se_key_lifetime_t lifetime - Defines type of storage (persistent or volatile storage)
- ifx_se_key_policy_t policy - Defines usage policy (algorithms, etc)
- ifx_se_svc_key_id_t id - Defined ID for persistent keys

This is an opaque structure that can represent the metadata of a key object. Metadata that can be stored in attributes includes:

- The location of the key in storage, indicated by its key identifier and its lifetime.
- The key's policy, comprising usage flags and a specification of the permitted algorithm(s).
- Information about the key itself: the key type and its size.
- Additional implementation-defined attributes.

The actual key material is not considered an attribute of a key. Key attributes do not contain information that is generally considered highly confidential.

An attribute structure works like a simple data structure where each function `ifx_se_set_key_xxx` sets a field and the corresponding function `ifx_se_get_key_xxx` retrieves the value of the corresponding field. However, a future version of the library may report values that are equivalent to the original one, but have a different encoding. Invalid values may be mapped to different, also invalid values.

An attribute structure may contain references to auxiliary resources, for example pointers to allocated memory or indirect references to pre-calculated values. In order to free such resources, the application must call ifx_se_reset_key_attributes(). As an exception, calling ifx_se_reset_key_attributes() on an attribute structure is optional if the structure has only been modified by the following functions since it was initialized or last reset with ifx_se_reset_key_attributes():

- ifx_se_set_key_id()
- ifx_se_set_key_lifetime()
- ifx_se_set_key_type()
- ifx_se_set_key_bits()
- ifx_se_set_key_usage_flags()
- ifx_se_set_key_algorithm()

Before calling any function on a key attribute structure, the application must initialize it by any of the following means:

- Set the structure to all-bits-zero, for example:
  ifx_se_key_attributes_t attributes;
  memset(&attributes, 0, sizeof(attributes));
  ifx_se_key_attributes_t
  struct ifx_se_key_attributes_s ifx_se_key_attributes_t
  The type of a structure containing key attributes.
  Definition: ifx_se_psacrypto_types.h:465
- Initialize the structure to logical zero values, for example:
  ifx_se_key_attributes_t attributes = {0};
- Initialize the structure to the initializer IFX_SE_KEY_ATTRIBUTES_INIT, for example:
  ifx_se_key_attributes_t attributes = IFX_SE_KEY_ATTRIBUTES_INIT;
  IFX_SE_KEY_ATTRIBUTES_INIT
  #define IFX_SE_KEY_ATTRIBUTES_INIT
  The initial value of the key attributes.
  Definition: ifx_se_psacrypto_struct.h:239
- Assign the result of the function ifx_se_key_attributes_init() to the structure, for example:
  ifx_se_key_attributes_t attributes;
  attributes = ifx_se_key_attributes_init();
  ifx_se_key_attributes_init
  static struct ifx_se_key_attributes_s ifx_se_key_attributes_init(void)
  Sets key attributes structure with initial value.
  Definition: ifx_se_psacrypto_struct.h:248

A freshly initialized attribute structure contains the following values:

- lifetime: IFX_SE_KEY_LIFETIME_VOLATILE.
- key identifier: 0 (which is not a valid key identifier).
- type: `0` (meaning that the type is unspecified).
- key size: `0` (meaning that the size is unspecified).
- usage flags: `0` (which allows no usage except exporting a public key).
- algorithm: `0` (which allows no cryptographic usage, but allows exporting).

A typical sequence to create a key is as follows:

1. Create and initialize an attribute structure.
2. If the key is persistent, call ifx_se_set_key_id(). Also call ifx_se_set_key_lifetime() to place the key in a non-default location.
3. Set the key policy with ifx_se_set_key_usage_flags() and ifx_se_set_key_algorithm().
4. Set the key type with ifx_se_set_key_type(). Skip this step if copying an existing key with ifx_se_copy_key().
5. When generating a random key with ifx_se_generate_key() or deriving a key with ifx_se_key_derivation_output_key(), set the desired key size with ifx_se_set_key_bits().
6. Call a key creation function: ifx_se_import_key(), ifx_se_generate_key(), ifx_se_key_derivation_output_key() or ifx_se_copy_key(). This function reads the attribute structure, creates a key with these attributes, and outputs a key identifier to the newly created key.
7. The attribute structure is now no longer necessary. You may call ifx_se_reset_key_attributes(), although this is optional with the workflow presented here because the attributes currently defined in this specification do not require any additional resources beyond the structure itself.

A typical sequence to query a key's attributes is as follows:

1. Call ifx_se_get_key_attributes().
2. Call `ifx_se_get_key_xxx` functions to retrieve the attribute(s) that you are interested in.
3. Call ifx_se_reset_key_attributes() to free any resources that may be used by the attribute structure.

Once a key has been created, it is impossible to change its attributes.

## Function Documentation

## ◆ ifx_se_reset_key_attributes()

void ifx_se_reset_key_attributes | ( | ifx_se_key_attributes_t * | attributes | ) |

Reset a key attribute structure to a freshly initialized state.

You must initialize the attribute structure as described in the documentation of the type ifx_se_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time.

This function frees any auxiliary resources that the structure may contain.

Parameters

  [in,out] | attributes | The attribute structure to reset.

## ◆ ifx_se_get_key_attributes()

ifx_se_status_t ifx_se_get_key_attributes | ( | ifx_se_key_id_fih_t | key,
|  | ifx_se_key_attributes_t * | attributes,
|  | void * | ctx
| ) |  |

Retrieve the attributes of a key.

This function first resets the attribute structure as with ifx_se_reset_key_attributes(). It then copies the attributes of the given key into the given attribute structure.

Note
  This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call ifx_se_reset_key_attributes() to free these resources.

Parameters

  [in] | key | Identifier of the key to query.
  [in,out] | attributes | On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS |
  IFX_SE_ERROR_INVALID_HANDLE |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_STORAGE_FAILURE |
  IFX_SE_ERROR_DATA_CORRUPT |
  IFX_SE_ERROR_DATA_INVALID |
  IFX_SE_ERROR_BAD_STATE | The library has not been previously initialized by ifx_se_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## ◆ ifx_se_key_attributes_init()

static struct ifx_se_key_attributes_s ifx_se_key_attributes_init | ( | void |  | ) |
| inlinestatic

Sets key attributes structure with initial value.

Returns
  ifx_se_key_attributes_s structure

## ◆ ifx_se_set_key_id()

static void ifx_se_set_key_id | ( | ifx_se_key_attributes_t * | attributes,
|  | ifx_se_svc_key_id_t | key
| ) |  |
| inlinestatic

Sets key ID in key attributes structure.

Parameters

  [in] | attributes | Key attributes structure
  [in] | key | Key ID

## ◆ ifx_se_get_key_id()

static ifx_se_svc_key_id_t ifx_se_get_key_id | ( | const ifx_se_key_attributes_t * | attributes | ) |
| inlinestatic

Gets key ID from key attributes structure.

Parameters

  [in] | attributes | Key attributes structure

Returns
  Key ID

## ◆ ifx_se_svc_key_id_make()

static ifx_se_svc_key_id_t ifx_se_svc_key_id_make | ( | ifx_se_key_owner_id_t | owner_id,
|  | ifx_se_key_id_t | key_id
| ) |  |
| inlinestatic

Utility to initialize a key identifier at runtime.

Parameters

  owner_id | Identifier of the key owner.
  key_id | Identifier of the key.

Returns
  Key identifier value