i.MX 8ULP EdgeLock Enclave Hardware Security Module

Semiconductors
RM00284
EdgeLock Enclave Hardware Security Module API
Rev. 1.0 — 15 December 2023
Reference manual

Document information

Module, API
Abstract| This document is a software reference description of the API provided by the i.MX 8ULP and i.MX 93 Hardware Security Module (HSM) solutions for the EdgeLock Enclave (ELE) Platform.

Overview

This document is a software reference description of the API provided by the i.MX 8ULP and i.MX 93 Hardware Security Module (HSM) solutions for the EdgeLock Enclave (ELE) Platform.
Note: A reference implementation of this API is available at https://github.com/nxp-imx/imx-secure-enclave. All code examples in this document use this implementation.

General Concepts Related to the API

2.1 Session
The API must be initialized by a potential requestor by opening a session.
The session establishes a route (MU, DomainID…) between the requester and the HSM. When a session is opened, the HSM returns a handle identifying the session to the requester.
2.2 Service flow
For a given category of services that require service handle, the requestor is expected to open a service flow by invoking the appropriate HSM API.
The session handle, as well as the control data needed for the service flow, are provided as parameters of the call.
Upon reception of the open request, the HSM allocates a context in which the session handle, as well as the provided control parameters are stored and return a handle identifying the service flow.
The context is preserved until the service flow, or the session, are closed by the user and it is used by the HSM to proceed with the sub-sequent operations requested by the user on the service flow.

2.3 Example

/ Open a session: create a route between the user and the HSM /
hsm_open_session(&open_session_args, &session_hdl):
/ Open a key store user is authenticated /
hsm_open_key_store_service(session_hdl, open_svc_key_store args,
&key_store_hdl);
/ Open cipher service it grants access to ciphering operations /
hsm_open_cipher_service(key_store_hdl, &open_svc_cipher_args, &cipher_hdl):
/ Perform ECB, CCB … /
hsm_cipher_one_go (cipher_hdl, &op_cipher_one_go_args);
/ Perform authenticate and encryption algos: e.g GCM /
hsm_auth_enc (cipher_hdl, &op_auth_enc_args);
/ Perform hashing operations: e.g SHA /
hsm_hash_one_go (hash_hdl, &op_hash_one_go args);
/ Close the session and all the related services /
hsm_close_session (session_hdl);

2.4 Key store
A key store can be created by specifying the CREATE flag in the hsm_open_key_store_service API.
The created key store is not stored in the NVM until a key is generated or imported specifying the “STRICT OPERATION” flag.
Only symmetric and private keys are stored into the key store. Public keys can be exported during the key pair generation operation or recalculated through the hsm_pub_key_recovery API.
Secret keys cannot be exported under any circumstances, while they can be imported in encrypted form.

2.4.1 Key management
Keys are divided in groups. Keys belonging to the same group are written/read from the NVM as a monolithic block.
Up to 2 key groups can be handled in the HSM local memory (those immediately available to perform crypto operations), while up to 100 key groups can be handled in the external NVM and imported in the local memory as needed.
If the local memory is full (2 key groups already reside in the HSM local memory) and a new key group is needed by an incoming user request, the HSM swaps one of the local key group with the one needed by the user request.
The user can control which key group to be kept in the local memory (cached) through the manage_key_group API lock/unlock mechanism.
As general concept, frequently used keys should be kept, when possible, in the same key group and locked in the local memory for performance optimization.

2.4.2 NVM writing
All the APIs creating a key store (open key store API) or modifying its content (key generation, key management, key derivation functions) provide a “STRICT OPERATION” flag. If the flag is set, the HSM exports the relevant key store blocks into the external NVM. In case of key generation/derivation/update, the “STRICT OPERATION” has effect only on the target key group.
Any update to the key store must be considered as effective only after an operation specifying flag “STRICT OPERATION” is acknowledged by the HSM. All the operations not specifying the “STRICT OPERATION” flags impact the HSM local memory only and will be lost in case of system reset.
Due to the limited monotonic counter size, the user should, when possible, perform multiple update before setting the “STRICT OPERATION” flag (for example, keys to be updated should be kept in the same key group).
When the monotonic counter is completely blown, a warning is returned on each key store export to the NVM to inform the user that the new updates are not roll-back protected.

2.5 Implementation specificities
HSM API with common features are supported on i.MX 8ULP and i.MX 93. The details of the supported features per chip are listed in the platform specificities.

Module Documentation

3.1 Session
The API must be initialized by a potential requestor by opening a session.
Once a session is closed, all the associated service flows are closed by the HSM.

Data structures

• struct hsm_session_hdl_s
• struct hsm_service_hdl_s
• struct open_session_args_t

Macros

• define HSM_MAX_SESSIONS (8u)

  Maximum sessions supported.

• define HSM_MAX_SERVICES (32u)

  Maximum services supported.

• define HSM_OPEN_SESSION_PRIORITY_LOW (0x00U)

  Low priority. Default settings on platforms that do not support sessions priorities.

• define HSM_OPEN_SESSION_PRIORITY_HIGH (0x01U)

  High Priority session.

• define HSM_OPEN_SESSION_FIPS_MODE_MASK (1u << 0)

  Only FIPS certified operations authorized in this session.

• define HSM_OPEN_SESSION_EXCLUSIVE_MASK (1u << 1)

  No other HSM sessions are authorized on the same security enclave.

• define HSM_OPEN_SESSION_LOW_LATENCY_MASK (1u << 3)

  Use a low latency HSM implementation.

• define HSM_OPEN_SESSION_NO_KEY_STORE_MASK (1u << 4)

  No key store is attached to this session. May provide better performances on some operations depending on the implementation. Usage of the session is restricted to the operations that do not involve secret keys (e.g., hash, signature verification, and random generation).

• define HSM_OPEN_SESSION_RESERVED_MASK ((1u << 2) | (1u << 5) | (1u << 6) | (1u << 7))

  Bits reserved for future use. Should be set to 0.

Typedefs

• typedef uint32_t hsm_hdl_t

Functions

• hsm_err_thsm_open_session (open_session_args_t args, hsm_hdl_t session_hdl)
• hsm_err_thsm_close_session (hsm_hdl_t session_hdl)
• struct hsm_session_hdl_s * session_hdl_to_ptr (uint32_t hdl)
• struct hsm_service_hdl_s * service_hdl_to_ptr (uint32_t hdl)
• void delete_session (struct hsm_session_hdl_s *s_ptr)
• void delete_service (struct hsm_service_hdl_s *s_ptr)
• struct hsm_session_hdl_s * add_session (void)
• struct hsm_service_hdl_s add_service (struct hsm_session_hdl_s session)

3.1.1 Detailed description
The API must be initialized by a potential requestor by opening a session.
When a session is closed, all the associated service flows are closed by the HSM.

3.1.2 Data structure documentation
3.1.2.1 struct hsm_session_hdl_s
Structure describing the session handle members.

Data Fields

3.1.2.2 struct hsm_service_hdl_s
Structure describing the service handle members.
Data Fields

3.1.2.3 struct open_session_args_t
Structure detailing the open session operation member arguments.

Data Fields

session.
uint8_t| operating_mode| Options for the session to be opened (bitfield).
uint8_t| interrupt_idx| Interrupt number of the MU used to indicate data availability.

3.1.3 Typedef documentation
3.1.3.1 hsm_hdl_t

typedef uint32_t hsm_hdl_t
Define the HSM handle type.

3.1.4 Function documentation
3.1.4.1 hsm_open_session()

hsm_err_t hsm_open_session (
open_session_args_t args,
hsm_hdl_t session_hdl)

Parameters

Returns
Error code.

3.1.4.2 hsm_close_session()

hsm_err_t hsm_close_session (hsm_hdl_t session_hdl)
Terminate a previously opened session. All the services opened under this session are closed as well.

Parameters

Returns
Error code.

3.1.4.3 session_hdl_to_ptr()

struct hsm_session_hdl_s* session_hdl_to_ptr (uint32_t hdl)
Returns pointer to the session handle.
Parameters

Returns
Pointer to the session handle.

3.1.4.4 service_hdl_to_ptr()
struct hsm_service_hdl_s* service_hdl_to_ptr (uint32_t hdl)
Returns pointer to the service handle.
Parameters

Returns
Pointer to the service handle.
3.1.4.5 delete_session()

void delete_session (struct hsm_session_hdl_s * s_ptr)
Delete the session.
Parameters

3.1.4.6 delete_service()
void delete_service (struct hsm_service_hdl_s * s_ptr)
Delete the service.
Parameters

3.1.4.7 add_session()
struct hsm_session_hdl_s* add_session (void )
Add the session.
Returns
Pointer to the session.
3.1.4.8 add_service()

struct hsm_service_hdl_s add_service (
struct hsm_session_hdl_s session)
Add the service.
Returns
Pointer to the service.

3.2 Key management
Data Structures

• struct op_delete_key_args_t
• struct op_get_key_attr_args_t
• struct op_import_key_args_t
• struct kek_enc_key_hdr_t
• struct op_generate_key_args_t
• struct open_svc_key_management_args_t
• struct op_manage_key_group_args_t

Macros

• define HSM_OP_DEL_KEY_FLAGS_STRICT_OPERATION ((hsm_op_delete_key_flags_t)(1u << 7))

• define HSM_OP_IMPORT_KEY_INPUT_E2GO_TLV ((hsm_op_import_key_flags_t)(1u << 0))

  Bit 0: set 1 means input is E2GO_TLV.

• define HSM_OP_IMPORT_KEY_INPUT_SIGNED_MSG ((hsm_op_import_key_flags_t)(0u << 0))

  Bit 0: set 0 means input is signed message.

• define HSM_OP_IMPORT_KEY_FLAGS_STRICT_OPERATION ((hsm_op_import_key_flags_t) (1u << 7))

  Bit 7: Strict: Request completed – New key written to NVM with updated MC.

• define HSM_KEY_USAGE_ENCRYPT ((hsm_key_usage_t) (1u << 8))

• define HSM_KEY_USAGE_DECRYPT ((hsm_key_usage_t) (1u << 9))

• define HSM_KEY_USAGE_SIGN_MSG ((hsm_key_usage_t) (1u << 10))

• define HSM_KEY_USAGE_VERIFY_MSG ((hsm_key_usage_t) (1u << 11))

• define HSM_KEY_USAGE_SIGN_HASH ((hsm_key_usage_t) (1u << 12))

• define HSM_KEY_USAGE_VERIFY_HASH ((hsm_key_usage_t) (1u << 13))

• define HSM_KEY_USAGE_DERIVE ((hsm_key_usage_t) (1u << 14))

• define HSM_KEY_INFO_PERSISTENT ((hsm_key_info_t)(0u << 1))

• define HSM_KEY_INFO_PERMANENT ((hsm_key_info_t)(1u << 0))

• define HSM_KEY_INFO_TRANSIENT ((hsm_key_info_t)(1u << 1))

• define HSM_OP_KEY_GENERATION_FLAGS_STRICT_OPERATION ((hsm_op_key_gen_flags_t)(1u << 7))

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_CACHE_LOCKDOWN ((hsm_op_manage_key_group_flags_t) (1u << 0))

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_CACHE_UNLOCK ((hsm_op_manage_key_group_flags_t) (1u << 1)) Import the key group.

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_IMPORT ((hsm_op_manage_key_group_flags_t) (1u << 2))

  Export the key group.

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_EXPORT ((hsm_op_manage_key_group_flags_t) (1u << 3))

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_MONOTONIC

• ((hsm_op_manage_key_group_flags_t) (1u << 5))

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_SYNC_KEYSTORE ((hsm_op_manage_key_group_flags_t) (1u << 6))

• define HSM_OP_MANAGE_KEY_GROUP_FLAGS_STRICT_OPERATION ((hsm_op_manage_key_group_flags_t) (1u << 7))

Typedefs

• typedef uint8_t hsm_op_delete_key_flags_t

• typedef uint8_t hsm_op_import_key_flags_t

• typedef uint32_t hsm_key_usage_t

• typedef uint16_t hsm_key_group_t

• typedef uint16_t hsm_key_info_t

• typedef uint8_t hsm_op_key_gen_flags_t
  Reserverd Bits 0 – 6.

• typedef uint8_t hsm_svc_key_management_flags_t

• typedef uint8_t hsm_op_manage_key_group_flags_t

Enumerations

• enum hsm_storage_loc_t {
  HSM_SE_KEY_STORAGE = 0x00000000 }

• enum hsm_storage_persist_lvl_t {
  HSM_VOLATILE_STORAGE = 0x0,
  HSM_PERSISTENT_STORAGE = 0x1,
  HSM_PERMANENT_STORAGE = 0xFF }

• enum hsm_key_lifetime_t {
  HSM_SE_KEY_STORAGE_VOLATILE = HSM_SE_KEY_STORAGE | HSM_VOLATILE_STORAGE,
  HSM_SE_KEY_STORAGE_PERSISTENT = HSM_SE_KEY_STORAGE | HSM_PERSISTENT_STORAGE,
  HSM_SE_KEY_STORAGE_PERS_PERM = HSM_SE_KEY_STORAGE | HSM_PERMANENT_STORAGE }

• enum hsm_pubkey_type_t {
  HSM_PUBKEY_TYPE_RSA = 0x4001,
  HSM_PUBKEY_TYPE_ECC_BP_R1 = 0x4130,
  HSM_PUBKEY_TYPE_ECC_NIST = 0x4112,
  HSM_PUBKEY_TYPE_ECC_BP_T1 = 0xC180 }

• enum hsm_key_type_t {
  HSM_KEY_TYPE_HMAC = 0x1100,
  HSM_KEY_TYPE_AES = 0x2400,
  HSM_KEY_TYPE_SM4 = 0x2405,
  HSM_KEY_TYPE_RSA = 0x7001,
  HSM_KEY_TYPE_ECC_BP_R1 = 0x7130,
  HSM_KEY_TYPE_ECC_NIST = 0x7112 }

• enum hsm_bit_key_sz_t {
  HSM_KEY_SIZE_HMAC_224 = 224,
  HSM_KEY_SIZE_HMAC_256 = 256,
  HSM_KEY_SIZE_HMAC_384 = 384,
  HSM_KEY_SIZE_HMAC_512 = 512,
  HSM_KEY_SIZE_AES_128 = 128,
  HSM_KEY_SIZE_AES_192 = 192,
  HSM_KEY_SIZE_AES_256 = 256,
  HSM_KEY_SIZE_SM4_128 = 128,
  HSM_KEY_SIZE_RSA_2048 = 2048,
  HSM_KEY_SIZE_RSA_3072 = 3072,
  HSM_KEY_SIZE_RSA_4096 = 4096,
  HSM_KEY_SIZE_ECC_BP_R1_224 = 224,
  HSM_KEY_SIZE_ECC_BP_R1_256 = 256,
  HSM_KEY_SIZE_ECC_BP_R1_320 = 320,
  HSM_KEY_SIZE_ECC_BP_R1_384 = 384,
  HSM_KEY_SIZE_ECC_BP_R1_512 = 512,
  HSM_KEY_SIZE_ECC_NIST_224 = 224,
  HSM_KEY_SIZE_ECC_NIST_256 = 256,
  HSM_KEY_SIZE_ECC_NIST_384 = 384,
  HSM_KEY_SIZE_ECC_NIST_521 = 521,
  HSM_KEY_SIZE_ECC_BP_T1_224 = 224,
  HSM_KEY_SIZE_ECC_BP_T1_256 = 256,
  HSM_KEY_SIZE_ECC_BP_T1_320 = 320,
  HSM_KEY_SIZE_ECC_BP_T1_384 = 384 }

• enum hsm_permitted_algo_t {
  PERMITTED_ALGO_SHA224 = ALGO_HASH_SHA224,
  PERMITTED_ALGO_SHA256 = ALGO_HASH_SHA256,
  PERMITTED_ALGO_SHA384 = ALGO_HASH_SHA384,
  PERMITTED_ALGO_SHA512 = ALGO_HASH_SHA512,
  PERMITTED_ALGO_SM3 = ALGO_HASH_SM3,
  PERMITTED_ALGO_HMAC_SHA256 = ALGO_HMAC_SHA256,
  PERMITTED_ALGO_HMAC_SHA384 = ALGO_HMAC_SHA384,
  PERMITTED_ALGO_CMAC = ALGO_CMAC,
  PERMITTED_ALGO_CTR = ALGO_CIPHER_CTR,
  PERMITTED_ALGO_CFB = ALGO_CIPHER_CFB,
  PERMITTED_ALGO_OFB = ALGO_CIPHER_OFB,
  PERMITTED_ALGO_ECB_NO_PADDING = ALGO_CIPHER_ECB_NO_PAD,
  PERMITTED_ALGO_CBC_NO_PADDING = ALGO_CIPHER_CBC_NO_PAD,
  PERMITTED_ALGO_CCM = ALGO_CCM,
  PERMITTED_ALGO_GCM = ALGO_GCM,
  PERMITTED_ALGO_RSA_PKCS1_V15_SHA224 = ALGO_RSA_PKCS1_V15_SHA224,
  PERMITTED_ALGO_RSA_PKCS1_V15_SHA256 = ALGO_RSA_PKCS1_V15_SHA256,
  PERMITTED_ALGO_RSA_PKCS1_V15_SHA384 = ALGO_RSA_PKCS1_V15_SHA384,
  PERMITTED_ALGO_RSA_PKCS1_V15_SHA512 = ALGO_RSA_PKCS1_V15_SHA512,
  PERMITTED_ALGO_RSA_PKCS1_PSS_MGF1_SHA224 = ALGO_RSA_PKCS1_PSS_MGF1_SHA224,
  PERMITTED_ALGO_RSA_PKCS1_PSS_MGF1_SHA256 = ALGO_RSA_PKCS1_PSS_MGF1_SHA256,
  PERMITTED_ALGO_RSA_PKCS1_PSS_MGF1_SHA384 = ALGO_RSA_PKCS1_PSS_MGF1_SHA384,
  PERMITTED_ALGO_RSA_PKCS1_PSS_MGF1_SHA512 = ALGO_RSA_PKCS1_PSS_MGF1_SHA512,
  PERMITTED_ALGO_ECDSA_SHA224 = ALGO_ECDSA_SHA224,
  PERMITTED_ALGO_ECDSA_SHA256 = ALGO_ECDSA_SHA256,
  PERMITTED_ALGO_ECDSA_SHA384 = ALGO_ECDSA_SHA384,
  PERMITTED_ALGO_ECDSA_SHA512 = ALGO_ECDSA_SHA512,
  PERMITTED_ALGO_HMAC_KDF_SHA256 = ALGO_HMAC_KDF_SHA256,
  PERMITTED_ALGO_ALL_CIPHER = ALGO_CIPHER_ALL,
  PERMITTED_ALGO_ALL_AEAD = ALGO_ALL_AEAD,
  PERMITTED_ALGO_OTH_KEK_CBC = ALGO_CIPHER_KEK_CBC }

• enum hsm_key_lifecycle_t {
  HSM_KEY_LIFECYCLE_OPEN = 0x1,
  HSM_KEY_LIFECYCLE_CLOSED = 0x2,
  HSM_KEY_LIFECYCLE_CLOSED_LOCKED = 0x4 }

Functions

• hsm_err_thsm_delete_key (hsm_hdl_t key_management_hdl, op_delete_key_args_t *args)
• hsm_err_thsm_get_key_attr (hsm_hdl_t key_management_hdl, op_get_key_attr_args_t *args)
• hsm_err_thsm_import_key (hsm_hdl_t key_management_hdl, op_import_key_args_t *args)
• hsm_err_thsm_generate_key (hsm_hdl_t key_management_hdl, op_generate_key_args_t *args)
• hsm_err_thsm_open_key_management_service (hsm_hdl_t key_store_hdl, open_svc_key_management_args_t args, hsm_hdl_t key_management_hdl)
• hsm_err_thsm_close_key_management_service (hsm_hdl_t key_management_hdl)
• hsm_err_t hsm_manage_key_group (hsm_hdl_t key_management_hdl, op_manage_key_group_args_t *args)

The entire key group is cached in the HSM local memory.

3.2.1 Detailed description
3.2.2 Data structure documentation
3.2.2.1 struct op_delete_key_args_t

Structure detailing the delete key operation member arguments.
Data Fields

3.2.2.2 struct op_get_key_attr_args_t
Structure describing the get key attribute operation arguments.
Data Fields

key persistence level and location where the key is stored.
hsm_key_usage_t| key_usage| Indicates the cryptographic operations that key can execute.
hsm_permitted_algo_t| permitted_algo| Indicates the key permitted algorithm.
hsm_key_lifecycle_t| lifecycle| Indicates the device lifecycle in which key is usable.

3.2.2.3 struct op_import_key_args_t
Structure detailing the import key operation member arguments.
Data Fields

uint32_t| key_identifier| Identifier of the KEK used to encrypt the key to be imported (Ignored if KEK is not used as set as part of the “flags” field).
---|---|---
uint8_t *| input_lsb_addr| Address in the requester space where:
• EdgeLock 2GO TLV can be found.
• Ignore this field if not E2GO_TLV.
uint32_t| input_size| Size in bytes of:
• EdgeLock 2GO TLV can be found.
• Ignore this field if not E2GO_TLV.
hsm_op_import_key_flags_t| flags| Bitmap specifying the operation properties.

3.2.2.4 struct kek_enc_key_hdr_t
Structure describing the encryption key header.

Data Fields

3.2.2.5 struct op_generate_key_args_t
Structure describing the generate key operation member arguments.
Data Fields

uint32_t | key_identifier| Pointer to the identifier of the key to be used for the operation. In case of create operation, the new key identifier is stored in this location.
---|---|---
uint16_t| out_size| Length in bytes of the generated key. It must be 0 in case of symmetric keys.
hsm_op_key_gen_flags_t| flags| Bitmap specifying the operation properties.
hsm_key_type_t| key_type| Indicates which type of key must be generated.
hsm_key_group_t| key_group| Key group of the generated key. It must be a value in the range of 0-99. Keys belonging to the same group can be cached in the HSM local memory through the hsm_manage_key_group API.
uint8_t | out_key| Pointer to the output area where the generated public key must be written.
uint16_t| exp_out_size| Expected output key buffer size, valid in case of HSM_OUTTOO SMALL (0x1D) error code.
hsm_bit_key_sz_t| bit_key_sz| Indicates key security size in bits.
hsm_key_lifecycle_t| key_lifecycle| Defines the key lifecycle in which the key is usable. If it is set to 0 , the current key lifecycle is used.
hsm_key_lifetime_t| key_lifetime| This attribute comprises of two indicaters- key persistence level and location where the key is stored.
hsm_key_usage_t| key_usage| Indicates the cryptographic operations that the key can execute.
hsm_permitted_algo_t| permitted_algo| Indicates the key permitted algorithm.

3.2.2.6 struct open_svc_key_management_args_t
Structure detailing the key management open service member arguments.
Data Fields

hsm_hdl_t| keymanagement hdl| Handle identifying the key management service flow.
---|---|---
hsm_svc_key_management_flags_t| flags| Bitmap specifying the services properties.

3.2.2.7 struct op_manage_key_group_args_t
Data Fields

hsm_key_group_t| key_group| It must be a value in the range of 0-99. Keys belonging to the same group can be cached in the HSM local memory through the hsm_manage_key_group API.
---|---|---
hsm_op_manage_key_group_flags_t| flags| Bitmap specifying the operation properties.
uint8_t| reserved| –

3.2.3 Macro definition documentation
3.2.3.1 HSM_OP_DEL_KEY_FLAGS_STRICT_OPERATION

define HSM_OP_DEL_KEY_FLAGS_STRICT_OPERATION ((hsm_op_delete_key_flags_t)(1u

<<7))
Bitmap detailing the delete key operation properties.

• Bits 0-4: Reserved.
• Bit 5: Monotonic counter increment.
• Bit 6: Reserved.
• Bit 7: Strict: Request completed – New key written to NVM with updated MC.

3.2.3.2 HSM_KEY_USAGE_ENCRYPT

define HSM_KEY_USAGE_ENCRYPT ((hsm_key_usage_t) (1u << 8))

Bit indicating the permission to encrypt a message with the key.
3.2.3.3 HSM_KEY_USAGE_DECRYPT

define HSM_KEY_USAGE_DECRYPT ((hsm_key_usage_t) (1u << 9))

Bit indicating the permission to decrypt a message with the key.
3.2.3.4 HSM_KEY_USAGE_SIGN_MSG

define HSM_KEY_USAGE_SIGN_MSG ((hsm_key_usage_t) (1u << 10))

Bit indicating the permission to sign a message with the key.
3.2.3.5 HSM_KEY_USAGE_VERIFY_MSG

define HSM_KEY_USAGE_VERIFY_MSG ((hsm_key_usage_t) (1u << 11))

Bit indicating the permission to verify a message signature with the key.
3.2.3.6 HSM_KEY_USAGE_SIGN_HASH

define HSM_KEY_USAGE_SIGN_HASH ((hsm_key_usage_t) (1u << 12))

Bit indicating the permission to sign a hashed message with the key.
3.2.3.7 HSM_KEY_USAGE_VERIFY_HASH

define HSM_KEY_USAGE_VERIFY_HASH ((hsm_key_usage_t) (1u << 13))

Bit indicating the permission to verify a hashed message signature with the key.
3.2.3.8 HSM_KEY_USAGE_DERIVE

define HSM_KEY_USAGE_DERIVE ((hsm_key_usage_t) (1u << 14))

Bit indicating the permission to derive other keys from this key.
3.2.3.9 HSM_KEY_INFO_PERSISTENT

define HSM_KEY_INFO_PERSISTENT ((hsm_key_info_t) (0u << 1))

Bit indicating persistent keys, which are stored in the external NVM. The entire key group is written in the NVM at the next STRICT operation.
3.2.3.10 HSM_KEY_INFO_PERMANENT

define HSM_KEY_INFO_PERMANENT ((hsm_key_info_t) (1u << 0))

Bit indicating the key is permanent. When set, the key is permanent (write locked). Once created, it is not possible to update or delete the key anymore. Transient keys are deleted after a PoR or when the corresponding key store service flow is closed. This bit can never be reset.
3.2.3.11 HSM_KEY_INFO_TRANSIENT

define HSM_KEY_INFO_TRANSIENT ((hsm_key_info_t) (1u << 1))

Bit indicating the key is transient. Transient keys are deleted when the corresponding key store service flow is closed or after a PoR. Transient keys cannot be in the same key group as persistent keys.
3.2.3.12 HSM_OP_KEY_GENERATION_FLAGS_STRICT_OPERATION

define HSM_OP_KEY_GENERATION_FLAGS_STRICT_OPERATION ((hsm_op_key_gen_flags_t)

(1u << 7))
The request is completed only when the new key is written in the NVM. This is applicable for the persistent and permanent keys.
3.2.3.13 HSM_OP_MANAGE_KEY_GROUP_FLAGS_CACHE_LOCKDOWN #define
HSM_OP_MANAGE_KEY_GROUP_FLAGS_CACHE_LOCKDOWN ((hsm_op_manage_key_group_flags_t) (1u << 0))
The entire key group is cached in the HSM local memory.

3.2.3.14 HSM_OP_MANAGE_KEY_GROUP_FLAGS_EXPORT

define HSM_OP_MANAGE_KEY_GROUP_FLAGS_EXPORT

((hsm_op_manage_key_group_flags_t)
(1u << 3))
Export the key group.
3.2.3.15 HSM_OP_MANAGE_KEY_GROUP_FLAGS_MONOTONIC

define

HSM_OP_MANAGE_KEY_GROUP_FLAGS_MONOTONIC ((hsm_op_manage_key_group_flags_t) (1u << 5))
When used in conjunction with the SYNC key group or SYNC key store and storage only, the request is completed only when the monotonic counter is updated.
3.2.3.16 HSM_OP_MANAGE_KEY_GROUP_FLAGS_SYNC_KEYSTORE

define

HSM_OP_MANAGE_KEY_GROUP_FLAGS_SYNC_KEYSTORE ((hsm_op_manage_key_group_flags_t) (1u << 6))

The request is completed only when the update is written in the NVM. Not applicable for cache lockdown/ unlock.
3.2.4 Typedef documentation
3.2.4.1 hsm_op_delete_key_flags_t

typedef uint8_t hsm_op_delete_key_flags_t
Bitmap describing the delete key operation properties.

3.2.4.2 hsm_op_import_key_flags_t
typedef uint8_t hsm_op_import_key_flags_t
Bitmap specifying the import key operation supported properties.

• Bit 0: Defines input configuration.
• Bits 1-4: Reserved.
• Bit 5: Monotonic counter increment.
• Bit 6: Reserved.
• Bit 7: Strict.

3.2.4.3 hsm_key_usage_t
typedef uint32_t hsm_key_usage_t
Bitmap indicating the cryptographic operations that the key can execute.

3.2.4.4 hsm_key_group_t
typedef uint16_t hsm_key_group_t
Bit field indicating the key group.
3.2.4.5 hsm_key_info_t
typedef uint16_t hsm_key_info_t
Bit field indicating the key information.
3.2.4.6 hsm_op_key_gen_flags_t
typedef uint8_t hsm_op_key_gen_flags_t
Reserved Bits 0 – 6.
Bitmap specifying the key generate operation supported properties.
3.2.4.7 hsm_svc_key_management_flags_t
typedef uint8_t hsm_svc_key_management_flags_t
Bitmap specifying the key management service supported properties.
3.2.5 Enumeration type documentation
3.2.5.1 hsm_storage_loc_t
enum hsm_storage_loc_t
Enum indicating the key location indicator.
3.2.5.2 hsm_storage_persist_lvl_t
enum hsm_storage_persist_lvl_t
Enum indicating the key persistent level indicator.
3.2.5.3 hsm_key_lifetime_t
enum hsm_key_lifetime_t
Enum indicating the key lifetime.
3.2.5.4 hsm_pubkey_type_t
enum hsm_pubkey_type_t
Enum indicating the public key type.
3.2.5.5 hsm_key_type_t
enum hsm_key_type_t
Enum indicating the key type.
3.2.5.6 hsm_bit_key_sz_t
enum hsm_bit_key_sz_t
Enum indicating the key security size in bits.
3.2.5.7 hsm_permitted_algo_t
enum hsm_permitted_algo_t
Enum describing the permitted algorithm.
Permitted algorithm attribute.

• MAC default algorithms supported
• HMAC truncated permitted algorithm encoding, CMAC truncated permitted algorithm encoding, and Cipher algorithms supported
• AEAD algorithms supported
• Signature algorithms supported

Note: Only one of the previous algorithms could be set.
3.2.5.8 hsm_key_lifecycle_t
enum hsm_key_lifecycle_t
Enum detailing the permitted key lifecycle.
3.2.6 Function documentation
3.2.6.1 hsm_delete_key()
hsm_err_t hsm_delete_key (hsm_hdl_t key_management_hdl, op_delete_key_args_t * args)
This command is designed to perform the following operation:

• Delete an existing key.

Parameters

Returns
Error code
3.2.6.2 hsm_get_key_attr()

hsm_err_t hsm_get_key_attr(
hsm_hdl_t key_management_hdl,
op_get_key_attr_args_t * args)
This command is designed to perform the following operation:

• Get attributes of an existing key.

Parameters

Returns
Error code

3.2.6.3 hsm_import_key()
hsm_err_t hsm_import_key (
hsm_hdl_t key_management_hdl,
op_import_key_args_t * args)

This API is used to import the key.
Parameters

Returns
Error code

3.2.6.4 hsm_generate_key()
hsm_err_t hsm_generate_key (
hsm_hdl_t key_management_hdl,
op_generate_key_args_t * args)
Generate a key or a key pair. Only the confidential keys (symmetric and private keys) are stored in the internal key store, while the non-confidential keys (public key) are exported.
The generated key can be stored using a new or existing key identifier with the restriction that an existing key can be replaced only by a key of the same type.

Parameters

Returns
Error code

3.2.6.5 hsm_open_key_management_service()

hsm_err_t hsm_open_key_management_service (
hsm_hdl_t key_store_hdl,
open_svc_key_management_args_t args,
hsm_hdl_t key_management_hdl )
Open a key management service flow.
Users must open this service flow to perform operation on the key store keys (generate, update, delete).
Parameters

must be written.

Returns
Error code.

3.2.6.6 hsm_close_key_management_service()
hsm_err_t hsm_close_key_management_service (hsm_hdl_t key_management_hdl)
Terminate a previously opened key management service flow.
Parameters

Returns
Error code
3.2.6.7 hsm_manage_key_group()

hsm_err_t hsm_manage_key_group (
hsm_hdl_t key_management_hdl,
op_manage_key_group_args_t * args)
The entire key group is cached in the HSM local memory.
This command is designed to perform the following operations:

• Lock/Unlock down a key group in the HSM local memory so that the keys are available to the HSM without additional latency.
• Un-lock a key group. HSM may export the key group into the external NVM to free up the local memory as needed.
• Delete an existing key group.

Users can call this function only after having opened a key management service flow.

Parameters

Returns
Error code

3.3 Ciphering
Modules

• i.MX 8ULP

Data Structures

• struct op_auth_enc_args_t
• struct open_svc_cipher_args_t
• struct op_cipher_one_go_args_t

Macros

• define HSM_AUTH_ENC_FLAGS_DECRYPT ((hsm_op_auth_enc_flags_t)(0u << 0))

• define HSM_AUTH_ENC_FLAGS_ENCRYPT ((hsm_op_auth_enc_flags_t)(1u << 0))

• define HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV ((hsm_op_auth_enc_flags_t)(1u << 1))

• define HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV ((hsm_op_auth_enc_flags_t)(1u << 2))

• define HSM_CIPHER_ONE_GO_FLAGS_DECRYPT ((hsm_op_cipher_one_go_flags_t)(0u << 0))

• define HSM_CIPHER_ONE_GO_FLAGS_ENCRYPT ((hsm_op_cipher_one_go_flags_t)(1u << 0))

Typedefs

• typedef uint8_t hsm_op_auth_enc_flags_t
• typedef uint8_t hsm_svc_cipher_flags_t
• typedef uint8_t hsm_op_cipher_one_go_flags_t

Enumerations

• enum hsm_op_auth_enc_algo_t {
  HSM_AEAD_ALGO_CCM = ALGO_CCM,
  HSM_AEAD_ALGO_GCM = ALGO_GCM,
  HSM_AEAD_ALGO_ALL_AEAD = ALGO_ALL_AEAD }

• enum hsm_op_cipher_one_go_algo_t {
  HSM_CIPHER_ONE_GO_ALGO_CTR = ALGO_CIPHER_CTR,
  HSM_CIPHER_ONE_GO_ALGO_CFB = ALGO_CIPHER_CFB,
  HSM_CIPHER_ONE_GO_ALGO_OFB = ALGO_CIPHER_OFB,
  HSM_CIPHER_ONE_GO_ALGO_ECB = ALGO_CIPHER_ECB_NO_PAD,
  HSM_CIPHER_ONE_GO_ALGO_CBC = ALGO_CIPHER_CBC_NO_PAD }

Functions

• hsm_err_thsm_do_cipher (hsm_hdl_t cipher_hdl, op_cipher_one_go_args_t *cipher_one_go)
• hsm_err_thsm_auth_enc (hsm_hdl_t cipher_hdl, op_auth_enc_args_t *args)
• hsm_err_thsm_open_cipher_service (hsm_hdl_t key_store_hdl, open_svc_cipher_args_t args, hsm_hdl_t cipher_hdl)
• hsm_err_thsm_cipher_one_go (hsm_hdl_t cipher_hdl, op_cipher_one_go_args_t *args)
• hsm_err_thsm_close_cipher_service (hsm_hdl_t cipher_hdl)

3.3.1 Detailed description
3.3.2 Data structure documentation
3.3.2.1 struct op_auth_enc_args_t
Structure describing the authenticated encryption operation arguments.

Data Fields

nonce, when applicable, otherwise 0.
uint16_t| iv_size| Size of the fixed part of the initialization vector. For GCM algorithm, it can be:
• 0 when the full IV is internally generated (RBG-based construction, Bit 1 of “Flags” field).
• 4 when the counter IV generation option is used (deterministic construction, Bit 2 of “Flags” field).
• 12 when the IV is entirely generated by the user (Bit 1 and Bit 2 of “Flags” field must be set to 0).
For CCM algorithm IV size, it must be 12 bytes.
uint8_t | aad| Pointer to the additional authentication data.
uint16_t| aad_size| Length in bytes of the additional authentication data.
hsm_op_auth_enc_algo_t| ae_algo| Algorithm to be used for the operation.
hsm_op_auth_enc_flags_t| flags| Bitmap specifying the operation attributes.
uint8_t | input| Pointer to the input area.
• Plaintext for encryption
• Ciphertext + Tag (16 bytes) for decryption
uint8_t *| output| Pointer to the output area. Ciphertext + Tag (16 bytes)
• IV for encryption
• Plaintext for decryption if the Tag is verified
uint32_t| input_size| Length in bytes of the input.
uint32_t| output_size| Length in bytes of the output.
uint32_t| exp_output_size| Expected output buffer size in bytes, valid in case of HSMOUT TOO_SMALL (0x1D) error code.

3.3.2.2 struct open_svc_cipher_args_t
Structure describing the open cipher service members.

Data Fields

3.3.2.3 struct op_cipher_one_go_args_t
Structure describing the cipher one go operation arguments.
Data Fields

0 for algorithms not using the initialization vector.
uint8_t| svc_flags| Bitmap specifying the services properties.
uint8_t| flags| Bitmap specifying the operation attributes.
uint32_t| cipher_algo| Algorithm to be used for the operation.
uint8_t | input| Pointer to the input area:
• Plaintext for encryption
• Ciphertext for decryption
uint8_t | output| Pointer to the output area:
• Ciphertext for encryption
• Plaintext for decryption
uint32_t| input_size| Length in bytes of the input.
• In case of CBC and ECB, the input size should be multiple of a block cipher size (16 bytes).
uint32_t| output_size| Length in bytes of the output.
uint32_t| exp_output_size| Expected output buffer size in bytes, valid in case of (0x1D) error code.

3.3.3 Macro definition documentation
3.3.3.1 HSM_AUTH_ENC_FLAGS_DECRYPT

define HSM_AUTH_ENC_FLAGS_DECRYPT ((hsm_op_auth_enc_flags_t)(0u << 0))

Bit indicating the decryption operation.
3.3.3.2 HSM_AUTH_ENC_FLAGS_ENCRYPT

define HSM_AUTH_ENC_FLAGS_ENCRYPT ((hsm_op_auth_enc_flags_t)(1u << 0))

Bit indicating the encryption operation.
3.3.3.3 HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV

define HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV ((hsm_op_auth_enc_flags_t) (1u

<<1))
Bit indicating the Full IV is internally generated (only relevant for encryption).
3.3.3.4 HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV

define HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV ((hsm_op_auth_enc_flags_t)(1u

<<2))
Bit indicating 4 bytes supplied other bytes internally generated (only relevant for encryption).
3.3.3.5 HSM_CIPHER_ONE_GO_FLAGS_DECRYPT

define HSM_CIPHER_ONE_GO_FLAGS_DECRYPT ((hsm_op_cipher_one_go_flags_t) (0u

<<0))
Bit indicating the decrypt operation.
3.3.3.6 HSM_CIPHER_ONE_GO_FLAGS_ENCRYPT

define HSM_CIPHER_ONE_GO_FLAGS_ENCRYPT ((hsm_op_cipher_one_go_flags_t) (1u

<<0))
Bit indicating the encrypt operation.
3.3.4 Typedef documentation
3.3.4.1 hsm_op_auth_enc_flags_t
typedef uint8_t hsm_op_auth_enc_flags_t
Bit field indicating the authenticated encryption operations.
3.3.4.2 hsm_svc_cipher_flags_t
typedef uint8_t hsm_svc_cipher_flags_t
Bit field describing the open cipher service requested operation.
3.3.4.3 hsm_op_cipher_one_go_flags_t
typedef uint8_t hsm_op_cipher_one_go_flags_t
Bit field indicating the requested operations.
3.3.5 Enumeration type documentation
3.3.5.1 hsm_op_auth_enc_algo_t
enum hsm_op_auth_enc_algo_t
Bit field indicating the supported algorithm.

Enumerator

3.3.5.2 hsm_op_cipher_one_go_algo_t
enum hsm_op_cipher_one_go_algo_t
Enum describing the cipher one go operation algorithm.
Enumerator

3.3.6 Function documentation
3.3.6.1 hsm_do_cipher()
hsm_err_t hsm_do_cipher (
hsm_hdl_t cipher_hdl,
op_cipher_one_go_args_t * cipher_one_go)
Secondary API to perform ciphering operation.
This API does the following operations:

• Opens an Cipher service flow.
• Performs the Ciphering operation.
• Terminates a previously opened Cipher service flow.

Users can call this function only after having opened a cipher service flow.

Parameters

Returns
Error code
3.3.6.2 hsm_auth_enc()

hsm_err_t hsm_auth_enc (
hsm_hdl_t cipher_hdl,
op_auth_enc_args_t * args)
Perform authenticated encryption operation.

Users can call this function only after having opened a Cipher service flow.
For decryption operations, the full IV is supplied by the caller through the iv and iv_size parameters.
HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV and HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV flags are ignored.

For encryption operations, either HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV or HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV must be set when calling this function:

• When HSM_AUTH_ENC_FLAGS_GENERATE_FULL_IV is set, the full IV is internally generated, iv and iv_size must be set to 0.
• When HSM_AUTH_ENC_FLAGS_GENERATE_COUNTER_IV is set, the user supplies a 4 byte fixed part of the IV. The other IV bytes are internally generated.

Parameters

Returns
Error code
3.3.6.3 hsm_open_cipher_service()

hsm_err_t hsm_open_cipher_service (hsm_hdl_t key_store_hdl, open_svc_cipher_args_t args, hsm_hdl_t cipher_hdl)

• Open a Cipher service flow.
• Users can call this function only after having opened a key-store service flow.
• Users must open this service to perform Ciphering operation.

Parameters

written.

Returns
Error code
3.3.6.4 hsm_cipher_one_go()

hsm_err_t hsm_cipher_one_go (
hsm_hdl_t cipher_hdl,
op_cipher_one_go_args_t * args)
Perform Ciphering operation.
Users can call this function only after having opened a cipher service flow.

Parameters

Returns
Error code

3.3.6.5 hsm_close_cipher_service()

hsm_err_t hsm_close_cipher_service (hsm_hdl_t cipher_hdl)
Terminate a previously opened Cipher service flow.

Parameters

cipher_hdl| Pointer to handle identifying the Cipher service flow to be closed.
---|---

Returns
Error code

3.4 Signature generation
Data Structures

• struct open_svc_sign_gen_args_t
• struct op_generate_sign_args_t
• struct op_prepare_sign_args_t

Macros

• define HSM_OP_GENERATE_SIGN_FLAGS_INPUT_DIGEST ((hsm_op_generate_sign_flags_t) (0u << 0))

• define HSM_OP_GENERATE_SIGN_FLAGS_INPUT_MESSAGE ((hsm_op_generate_sign_flags_t)(1u <<0))

• define HSM_OP_PREPARE_SIGN_INPUT_DIGEST ((hsm_op_prepare_signature_flags_t)(0u << 0)) Bit indicating input digest.

• define HSM_OP_PREPARE_SIGN_INPUT_MESSAGE ((hsm_op_prepare_signature_flags_t) (1u << 0)) Bit indicating input message.

• define HSM_OP_PREPARE_SIGN_COMPRESSED_POINT ((hsm_op_prepare_signature_flags_t) (1u << 1))

  Bit indicating compressed point.

Typedefs

• typedef uint8_t hsm_op_generate_sign_flags_t
• typedef uint8_t hsm_op_prepare_signature_flags_t

Enumerations

• enum hsm_signature_scheme_id_t { HSM_SIGNATURE_SCHEME_RSA_PKCS1_V15_SHA224 = 0x06000208,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_V15_SHA256 = 0x06000209,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_V15_SHA384 = 0x0600020A,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_V15_SHA512 = 0x0600020B,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_V15_ANY_HASH = 0x060002FF,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_PSS_MGF1_SHA224 = 0x06000308,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_PSS_MGF1_SHA256 = 0x06000309,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_PSS_MGF1_SHA384 = 0x0600030A,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_PSS_MGF1_SHA512 = 0x0600030B,
  HSM_SIGNATURE_SCHEME_RSA_PKCS1_PSS_MGF1_ANY_HASH = 0x060003FF,
  HSM_SIGNATURE_SCHEME_ECDSA_ANY = 0x06000600,
  HSM_SIGNATURE_SCHEME_ECDSA_SHA224 = 0x06000608,
  HSM_SIGNATURE_SCHEME_ECDSA_SHA256 = 0x06000609,
  HSM_SIGNATURE_SCHEME_ECDSA_SHA384 = 0x0600060A,
  HSM_SIGNATURE_SCHEME_ECDSA_SHA512 = 0x0600060B }

Functions

• hsm_err_thsm_do_sign (hsm_hdl_t key_store_hdl, op_generate_sign_args_t *args)
• hsm_err_thsm_open_signature_generation_service (hsm_hdl_t key_store_hdl, open_svc_sign_gen_args_t
  args, hsm_hdl_t signature_gen_hdl)
• hsm_err_thsm_close_signature_generation_service (hsm_hdl_t signature_gen_hdl)
• hsm_err_thsm_generate_signature (hsm_hdl_t signature_gen_hdl, op_generate_sign_args_t *args)
• hsm_err_thsm_prepare_signature (hsm_hdl_t signature_gen_hdl, op_prepare_sign_args_t *args)

3.4.1 Detailed description
3.4.2 Data structure documentation
3.4.2.1 struct open_svc_sign_gen_args_t

Structure to represent the generate sign open service arguments.

Data Fields

3.4.2.2 struct op_generate_sign_args_t
Structure to represent the generate sign operation arguments.
Data Fields

signed.
uint8_t *| signature| Pointer to the output area where the signature must be stored. The signature S=(r,s) is stored in the format r||s||Ry where:
• Ry is an additional byte containing the lsb of y. Ry is considered valid only if the HSM_OP_GENERATE_SIGNFLAGS COMPRESSED_POINT is set.
uint16_t| signature_size| Length in bytes of the output. After the signature generation operation, this field contains the expected signature buffer size, if the operation fails due to the provided output buffer size being too short.
uint32_t| message_size| Length in bytes of the input.
hsm_signature_scheme_id_t| scheme_id| Identifier of the digital signature scheme to be used for the operation.
uint16_t| salt_len| Salt length in bytes.
uint16_t| exp_signature_size| Expected signature buffer size for output, returned by FW in case the input signature size provided is less than the required size.
hsm_op_generate_sign_flags_t| flags| Bitmap specifying the operation attributes.
---|---|---

3.4.2.3 struct op_prepare_sign_args_t
Structure detailing the prepare signature operation member arguments.
Data Fields

hsm_signature_scheme_id_t| scheme_id| Identifier of the digital signature scheme to be used for the operation.
---|---|---
hsm_op_preparesignature flags_t| flags| Bitmap specifying the operation attributes.

3.4.3 Macro definition documentation
3.4.3.1 HSM_OP_GENERATE_SIGN_FLAGS_INPUT_DIGEST

define HSM_OP_GENERATE_SIGN_FLAGS_INPUT_DIGEST

((hsm_op_generate_sign_flags_t) (0u << 0))
Bit field indicating the input is the message digest.

3.4.3.2 HSM_OP_GENERATE_SIGN_FLAGS_INPUT_MESSAGE

define HSM_OP_GENERATE_SIGN_FLAGS_INPUT_MESSAGE

((hsm_op_generate_sign_flags_t)
(1u << 0))
Bit field indicating the input is the actual message.
3.4.4 Typedef documentation
3.4.4.1 hsm_op_generate_sign_flags_t
typedef uint8_t hsm_op_generate_sign_flags_t
Bit field indicating the requested operation.
3.4.4.2 hsm_op_prepare_signature_flags_t
typedef uint8_t hsm_op_prepare_signature_flags_t
Bitmap specifying the prepare signature operation supported attributes.
3.4.5 Enumeration type documentation
3.4.5.1 hsm_signature_scheme_id_t
enum hsm_signature_scheme_id_t
Bit field indicating the PSA compliant requested operations:
Bits 2-7: Reserved.

3.4.6 Function documentation
3.4.6.1 hsm_do_sign()

hsm_err_t hsm_do_sign (
hsm_hdl_t key_store_hdl,
op_generate_sign_args_t * args)
Secondary API to generate the signature on the given message.
This API does the following:

• Open a service flow for signature generation.
• Based on the flag to identify the type of message: Digest or actual message, generate the signature using the key corresponding to the key ID.
• Post performing the operation, terminate the previously opened signature-generation service flow.

Users can call this function only after having opened a key-store.
Parameters

Returns
Error code

3.4.6.2 hsm_open_signature_generation_service()
hsm_err_t hsm_open_signature_generation_service (
hsm_hdl_t key_store_hdl,
open_svc_sign_gen_args_t args,
hsm_hdl_t signature_gen_hdl)

• Open a signature generation service flow.
• Users can call this function only after having opened a key store service flow.
• Users must open this service to perform signature generation operations.

Parameters

handle must be written.

Returns
Error code
3.4.6.3 hsm_close_signature_generation_service()

hsm_err_t hsm_close_signature_generation_service (hsm_hdl_t signature_gen_hdl)

Terminate a previously opened signature generation service flow.
Parameters

signature_gen_hdl| Handle identifying the signature generation service flow to be closed.
---|---

Returns
Error code

3.4.6.4 hsm_generate_signature()

hsm_err_t hsm_generate_signature (
hsm_hdl_t signature_gen_hdl,
op_generate_sign_args_t * args)
Generate a digital signature according to the signature scheme.
Users can call this function only after having opened a signature generation service flow.
The signature S=(r,s) is stored in the format r||s||Ry where:

• Ry is an additional byte containing the lsb of y. Ry has to be considered valid only if the HSM_OP_GENERATE_SIGN_FLAGS_COMPRESSED_POINT is set.

Parameters

Returns
Error code

3.4.6.5 hsm_prepare_signature()
hsm_err_t hsm_prepare_signature (
hsm_hdl_t signature_gen_hdl,
op_prepare_sign_args_t * args)

Prepare the creation of a signature by pre-calculating the operations having no dependencies on the input message.
The pre-calculated value is stored internally and used once hsm_generate_signature is called. Up to 20
pre-calculated values can be stored, and additional preparation operations have no effects.
Users can call this function only after having opened a signature generation service flow.
The signature S=(r,s) is stored in the format r||s||Ry where:

• Ry is an additional byte containing the lsb of y. Ry has to be considered valid only if the HSM_OPPREPARE SIGN_COMPRESSED_POINT is set.

Parameters

Returns

3.5 Signature verification
Data Structures

• struct open_svc_sign_ver_args_t
• struct op_verify_sign_args_t

Macros

• define HSM_OP_VERIFY_SIGN_FLAGS_INPUT_DIGEST ((hsm_op_verify_sign_flags_t)(0u << 0))

• define HSM_OP_VERIFY_SIGN_FLAGS_INPUT_MESSAGE ((hsm_op_verify_sign_flags_t) (1u << 0))

• define HSM_OP_VERIFY_SIGN_FLAGS_COMPRESSED_POINT ((hsm_op_verify_sign_flags_t) (1u << 1))

• define HSM_OP_VERIFY_SIGN_FLAGS_KEY_INTERNAL ((hsm_op_verify_sign_flags_t) (1u << 2))

• define HSM_VERIFICATION_STATUS_SUCCESS ((hsm_verification_status_t) (0x5A3CC3A5u))

• define HSM_VERIFICATION_STATUS_FAILURE ((hsm_verification_status_t) (0x2B4DD4B2u))

Typedefs

• typedef uint32_t hsm_verification_status_t
• typedef uint8_t hsm_op_verify_sign_flags_t

Functions

• hsm_err_thsm_verify_sign (hsm_hdl_t session_hdl, op_verify_sign_args_t args, hsm_verification_status_t verification_status)
• hsm_err_thsm_open_signature_verification_service (hsm_hdl_t session_hdl, open_svc_sign_ver_args_t args, hsm_hdl_t signature_ver_hdl)
• hsm_err_thsm_close_signature_verification_service (hsm_hdl_t signature_ver_hdl)
• hsm_err_thsm_verify_signature (hsm_hdl_t signature_ver_hdl, op_verify_sign_args_t args, hsm_verification_status_t status)

3.5.1 Detailed description
3.5.2 Data structure documentation
3.5.2.1 struct open_svc_sign_ver_args_t

Structure to represent verify sign open service arguments.

Data Fields

3.5.2.2 struct op_verify_sign_args_t
Structure to represent verify signature operation arguments.
Data Fields

uint8_t | key| Pointer to the public key to be used for the verification. If the HSM_OP_VERIFY_SIGN_FLAGS_KEY_INTERNAL is set, it must point to the key reference returned by the hsm_import_public_key API.
---|---|---
uint8_t | message| Pointer to the input (message or message digest).
uint8_t *| signature| Pointer to the input signature. The signature S=(r,s) is expected to be in the format r||s||Ry, where Ry is an additional byte containing the lsb of y. Ry is considered as valid only if the HSM_OP_VERIFY_SIGN_FLAGS_COMPRESSED_POINT is set.
uint16_t| key_size| Length in bytes of the input key.
uint16_t| signature_size| Length in bytes of the output. It must contain one additional byte where to store the Ry.
uint32_t| message_size| Length in bytes of the input message.
hsm_verification_status_t| verification_status| Verification status.
hsm_signature_scheme_id_t| scheme_id| Identifier of the digital signature scheme to be used for the operation.
uint16_t| salt_len| Salt length in bytes.
hsm_bit_key_sz_t| key_sz| Indicates key security size in bits.
hsm_pubkey_type_t| pkey_type| Indicates the public key type.
hsm_op_verify_sign_flags_t| flags| Bitmap specifying the operation attributes.

3.5.3 Macro Definition Documentation
3.5.3.1 HSM_OP_VERIFY_SIGN_FLAGS_INPUT_DIGEST

define HSM_OP_VERIFY_SIGN_FLAGS_INPUT_DIGEST ((hsm_op_verify_sign_flags_t)

(0u<< 0))
Verify signature bit indicating input is message digest.
3.5.3.2 HSM_OP_VERIFY_SIGN_FLAGS_INPUT_MESSAGE

define HSM_OP_VERIFY_SIGN_FLAGS_INPUT_MESSAGE ((hsm_op_verify_sign_flags_t)

(1u<< 0))
Verify signature bit indicating input is actual message.
3.5.3.3 HSM_OP_VERIFY_SIGN_FLAGS_COMPRESSED_POINT

define HSM_OP_VERIFY_SIGN_FLAGS_COMPRESSED_POINT

((hsm_op_verify_sign_flags_t) (1u << 1))
Verify signature bit indicating input based on signature format.
3.5.3.4 HSM_OP_VERIFY_SIGN_FLAGS_KEY_INTERNAL

define HSM_OP_VERIFY_SIGN_FLAGS_KEY_INTERNAL ((hsm_op_verify_sign_flags_t)

(1u<< 2))
Verify signature bit indicating input is key argument.

3.5.3.5 HSM_VERIFICATION_STATUS_SUCCESS

define HSM_VERIFICATION_STATUS_SUCCESS ((hsm_verification_status_t)

(0x5A3CC3A5u))
Verify signature response success status.
3.5.3.6 HSM_VERIFICATION_STATUS_FAILURE

define HSM_VERIFICATION_STATUS_FAILURE ((hsm_verification_status_t)

(0x2B4DD4B2u))
Verify signature response failure status.
3.5.4 Typedef documentation
3.5.4.1 hsm_verification_status_t
typedef uint32_t hsm_verification_status_t
Bit indicating the response verification status.
3.5.4.2 hsm_op_verify_sign_flags_t
typedef uint8_t hsm_op_verify_sign_flags_t
Bit indicating the requested operations.
3.5.5 Function documentation
3.5.5.1 hsm_verify_sign()
hsm_err_t hsm_verify_sign (
hsm_hdl_t session_hdl,
op_verify_sign_args_t args,
hsm_verification_status_t verification_status)
Secondary API to verify a message signature.
This API does the following:

• Open a flow for verification of the signature.
• Based on the flag to identify the type of message: Digest or actual message, verification of the signature is done using the public key.
• Post performing the operation, terminate the previously opened signature-verification service flow.

Users can call this function only after having opened a session.
Parameters

Returns
Error code
3.5.5.2 hsm_open_signature_verification_service()

hsm_err_t hsm_open_signature_verification_service(
hsm_hdl_t session_hdl,
open_svc_sign_ver_args_t args,
hsm_hdl_t signature_ver_hdl)

Users must open this service to perform signature verification operations. Users can call this function only after opening a session.

Parameters

handle must be written.

Returns
Error code
3.5.5.3 hsm_close_signature_verification_service()

hsm_err_t hsm_close_signature_verification_service (hsm_hdl_t signature_ver_hdl)
Terminate a previously opened signature verification service flow.
Parameters

signature_ver_hdl| Handle identifying the signature verification service flow to be closed.
---|---

Returns
Error code
3.5.5.4 hsm_verify_signature()

hsm_err_t hsm_verify_signature (
hsm_hdl_t signature_ver_hdl,
op_verify_sign_args_t args,
hsm_verification_status_t status)
Verify a digital signature according to the signature scheme. Users can call this function only after opening a signature verification service flow.
The signature S=(r,s) is expected to be in format r||s||Ry, where:

• Ry is an additional byte containing the lsb of y. Ry is considered as valid only if the HSM_OP_VERIFY_SIGN_FLAGS_COMPRESSED_POINT is set.

Only not-compressed keys (x,y) can be used by this command. Compressed keys can be decompressed by using the dedicated API.

Parameters

verification succeed, the value
HSM_VERIFICATION_STATUS_SUCCESS is returned.

Returns
Error code

3.6 Random number generation
Data Structures

• struct op_get_random_args_t

Functions

• hsm_err_thsm_do_rng (hsm_hdl_t session_hdl, op_get_random_args_t *args)
• hsm_err_thsm_get_random (hsm_hdl_t rng_hdl, op_get_random_args_t *args)

3.6.1 Detailed description
3.6.2 Data structure documentation
3.6.2.1 struct op_get_random_args_t

Structure detailing the get random number operation member arguments.

Data Fields

uint8_t *| output| Pointer to the output area where the random number must be written.
---|---|---
uint32_t| random_size| Length in bytes of the random number to be provided.

3.6.3 Function documentation
3.6.3.1 hsm_do_rng()
hsm_err_t hsm_do_rng (
hsm_hdl_t session_hdl,
op_get_random_args_t * args)
Secondary API to fetch the Random Number.
This API does the following:
Get a freshly generated random number.

Parameters

Returns
Error code

3.6.3.2 hsm_get_random()
hsm_err_t hsm_get_random (
hsm_hdl_t rng_hdl,
op_get_random_args_t * args)
Get a freshly generated random number.
Users can call this function only after opening an RNG service flow.

Parameters

Returns
Error code

3.7 Hashing
Data Structures

• struct op_hash_one_go_args_t

Macros

• define HSM_HASH_FLAG_ALLOWED

Enumerations

• enum hsm_hash_algo_t {
  HSM_HASH_ALGO_SHA_224 = 0x02000008,
  HSM_HASH_ALGO_SHA_256 = 0x02000009,
  HSM_HASH_ALGO_SHA_384 = 0x0200000A,
  HSM_HASH_ALGO_SHA_512 = 0x0200000B }

• enum hsm_hash_svc_flags_t {
  HSM_HASH_FLAG_ONE_SHOT = 0x1,
  HSM_HASH_FLAG_INIT = 0x2,
  HSM_HASH_FLAG_UPDATE = 0x4,
  HSM_HASH_FLAG_FINAL = 0x8,
  HSM_HASH_FLAG_GET_CONTEXT = 0x80 }

Functions

• hsm_err_thsm_do_hash (hsm_hdl_t session_hdl, op_hash_one_go_args_t *args)
• hsm_err_thsm_hash_one_go (hsm_hdl_t hash_hdl, op_hash_one_go_args_t *args)

3.7.1 Detailed description
3.7.2 Data structure documentation
3.7.2.1 struct op_hash_one_go_args_t

Structure describing the hash one go operation arguments.
Data Fields

uint8_t | msb| Pointer to the MSB of address in the requester space where buffers can be found, must be 0 until supported.
---|---|---
uint8_t | ctx| Pointer to the context.
uint8_t | input| Pointer to the input data to be hashed.
uint8_t | output| Pointer to the output area where the resulting digest must be written.
uint32_t| input_size| Length in bytes of the input.
uint32_t| output_size| Length in bytes of the output.
hsm_hash_algo_t| algo| Hash algorithm to be used for the operation.
hsm_hash_svc_flags_t| svc_flags| Flags identifying the operation init() update(), final(), or one shot operation.
uint16_t| ctx_size| Size of context buffer in bytes, ignored in case of one shot operation.
uint32_t| exp_output_size| Expected output digest buffer size, returned by FW in case the provided output size is incorrect.
uint16_t| context_size| Expected context size to allocate in bytes, if flag Get context size is set or provided context size is incorrect.

3.7.3 Macro definition documentation
3.7.3.1 HSM_HASH_FLAG_ALLOWED

define HSM_HASH_FLAG_ALLOWED

Value: (HSM_HASH_FLAG_ONE_SHOT | HSM_HASH_FLAG_INIT \
| HSM_HASH_FLAG_UPDATE | HSM_HASH_FLAG_FINAL \
| HSM_HASH_FLAG_GET_CONTEXT)

Bitmap indicating the allowed hash service operations.
3.7.4 Enumeration type documentation
3.7.4.1 hsm_hash_algo_t

enum hsm_hash_algo_t
Bitmap indicating the supported hash algorithm.

3.7.4.2 hsm_hash_svc_flags_t
enum hsm_hash_svc_flags_t
Bit field indicating the hash service operations.

3.7.5 Function documentation
3.7.5.1 hsm_do_hash()

hsm_err_t hsm_do_hash (
hsm_hdl_t session_hdl,
op_hash_one_go_args_t * args)
Secondary API to digest a message.
This API performs hash.

Parameters

Returns
Error code
3.7.5.2 hsm_hash_one_go()
hsm_err_t hsm_hash_one_go (
hsm_hdl_t hash_hdl,
op_hash_one_go_args_t * args)
Perform the hash operation on a given input.
Users can call this function only after opening a hash service flow.

Parameters

Returns
Error code

3.8 Data storage
Data Structures

• struct open_svc_data_storage_args_t
• struct op_data_storage_args_t
• struct op_enc_data_storage_args_t

Macros

• define HSM_OP_DATA_STORAGE_FLAGS_EL2GO ((hsm_op_data_storage_flags_t) (1u << 0))

• define HSM_OP_DATA_STORAGE_FLAGS_DEFAULT ((hsm_op_data_storage_flags_t) (0u << 0)) Store data.

• define HSM_OP_DATA_STORAGE_FLAGS_STORE ((hsm_op_data_storage_flags_t) (1u << 1)) Retrieve data.

• define HSM_OP_DATA_STORAGE_FLAGS_RETRIEVE ((hsm_op_data_storage_flags_t) (0u << 1))

• define ENC_DATA_TLV_DEV_UUID_TAG 0x41u

• define ENC_DATA_TLV_IV_TAG 0x45u

• define ENC_DATA_TLV_ENC_DATA_TAG 0x46u

• define ENC_DATA_TLV_SIGN_TAG 0x5Eu

• define ENC_DATA_TLV_DEV_UUID_TAG_LEN 0x01u

• define ENC_DATA_TLV_IV_TAG_LEN 0x01u

• define ENC_DATA_TLV_ENC_DATA_TAG_LEN 0x01u

• define ENC_DATA_TLV_SIGN_TAG_LEN 0x01u

• define HSM_OP_ENC_DATA_STORAGE_FLAGS_RANDOM_IV ((hsm_op_enc_data_storage_flags_t) (1u << 0))

  Internally generate random IV, if needed for operation.

• define HSM_OP_ENC_DATA_STORAGE_FLAGS_READ_ONCE ((hsm_op_enc_data_storage_flags_t) (1u << 1))

  Read once, and delete data from NVM after retrieve.

Typedefs

• typedef uint8_t hsm_svc_data_storage_flags_t
• typedef uint8_t hsm_op_data_storage_flags_t
• typedef uint16_t hsm_op_enc_data_storage_flags_t

Functions

• hsm_err_thsm_data_ops (hsm_hdl_t key_store_hdl, op_data_storage_args_t *args)
• hsm_err_thsm_enc_data_ops (hsm_hdl_t key_store_hdl, op_enc_data_storage_args_t *args)
• hsm_err_thsm_open_data_storage_service (hsm_hdl_t key_store_hdl, open_svc_data_storage_args_t args, hsm_hdl_t data_storage_hdl)
• hsm_err_thsm_data_storage (hsm_hdl_t data_storage_hdl, op_data_storage_args_t *args)
• hsm_err_thsm_enc_data_storage (hsm_hdl_t data_storage_hdl, op_enc_data_storage_args_t *args)
• uint8_t decode_enc_data_tlv (op_data_storage_args_t *args)
• hsm_err_thsm_close_data_storage_service (hsm_hdl_t data_storage_hdl)

3.8.1 Detailed description
3.8.2 Data structure documentation
3.8.2.1 struct open_svc_data_storage_args_t
Structure specifying the data storage open service member arguments.
Data Fields

properties.
uint8_t| reserved[3]| –

3.8.2.2 struct op_data_storage_args_t
Structure detailing the data storage operation member arguments.

Data Fields

uint8_t | data| Pointer to the data. In case of store request, it is the input data to store. In case of retrieve, it is the pointer where to load data.
---|---|---
uint32_t| data_size| Length in bytes of the data.
uint32_t| data_id| ID of the data.
hsm_op_data_storage_flags_t| flags| Flags bitmap specifying the operation attributes.
hsm_svc_data_storage_flags_t| svc_flags| Bitmap specifying the services properties.
uint16_t| uuid_len| Device UUID length in bytes. In case of retrieve, if the data retrieved is in the TLV format, which was stored by Encrypted Data Storage API, the TLV format data is decoded to fill the following fields. Memory for storing uuid/iv/ciphertext/payload/signature is allocated by the HSM library. Caller of the function decode_enc_data_tlv(), needs to ensure freeing up memory.
uint8_t | uuid| Device UUID.
uint16_t| iv_len| IV length in bytes if needed, otherwise 0.
uint8_t | iv| IV buffer, if needed.
uint32_t| ciphertext_len| Encrypted text length in bytes.
uint8_t | ciphertext| Encrypted text buffer.
uint32_t| payload_len| Payload length in bytes.
uint8_t | payload| Payload data buffer to verify signature.
uint16_t| signature_len| Signature length in bytes.
uint8_t | signature| Signature buffer.
uint32_t| exp_output_size| Expected output buffer size in bytes, valid in case of HSMOUT TOO_SMALL (0x1D) error code.

3.8.2.3 struct op_enc_data_storage_args_t
Data Fields

attributes.
hsm_svc_data_storage_flags_t| svc_flags| Bitmap specifying the service attributes.
uint16_t| lifecycle| Bitmask of device lifecycle, in which the data can be retrieved.
uint32_t| out_data_size| Size (bytes) of the signed TLV stored, received with API resp.

3.8.3 Macro definition documentation
3.8.3.1 ENC_DATA_TLV_DEV_UUID_TAG

define ENC_DATA_TLV_DEV_UUID_TAG 0x41u

Encrypted Data TLV Tags.
3.8.3.2 ENC_DATA_TLV_DEV_UUID_TAG_LEN

define ENC_DATA_TLV_DEV_UUID_TAG_LEN 0x01u

Encrypted Data TLV Tags lengths.
3.8.4 Typedef documentation
3.8.4.1 hsm_svc_data_storage_flags_t
typedef uint8_t hsm_svc_data_storage_flags_t
Bitmap specifying the data storage open service supported properties.
3.8.4.2 hsm_op_data_storage_flags_t
typedef uint8_t hsm_op_data_storage_flags_t
Bitmap specifying the data storage operation supported attributes.
3.8.4.3 hsm_op_enc_data_storage_flags_t
typedef uint16_t hsm_op_enc_data_storage_flags_t
Bitmap specifying the encrypted data storage operation supported attributes.
3.8.5 Function Documentation
3.8.5.1 hsm_data_ops()
hsm_err_t hsm_data_ops (
hsm_hdl_t key_store_hdl,
op_data_storage_args_t * args)

Secondary API to store and retrieve data from the Linux filesystem managed by EdgeLock Enclave Firmware.
This API does the following:

• Open a data storage service Flow.

• Based on the flag for operation attribute: Store or Retrieve
  – Store the data.
  – Retrieve the data, from the non-volatile storage.

• Post performing the operation, terminate the previously opened data-storage service flow.

Users can call this function only after opening a key-store.

Parameters

Returns
Error code
3.8.5.3 hsm_open_data_storage_service()
hsm_err_t hsm_open_data_storage_service(
hsm_hdl_t key_store_hdl,
open_svc_data_storage_args_t args,
hsm_hdl_t data_storage_hdl)
Open a data storage service flow.
Users must open this service flow to store/retrieve generic data in/from the HSM.

Parameters

must be written.

Returns
Error code.
3.8.5.4 hsm_data_storage()

hsm_err_t hsm_data_storage (
hsm_hdl_t data_storage_hdl,
op_data_storage_args_t * args)
Store or retrieve generic data identified by a data_id.
Parameters

Returns
Error code
3.8.5.5 hsm_enc_data_storage()
hsm_err_t hsm_enc_data_storage (
hsm_hdl_t data_storage_hdl,
op_enc_data_storage_args_t * args)
Store encrypted and signed data in the NVM.
Parameters

Returns
Error code
3.8.5.6 decode_enc_data_tlv()
uint8_t decode_enc_data_tlv (op_data_storage_args_t * args)
Decode and populate the data storage op args for Encrypted Data TLV fields.
Parameters

args| Pointer to the structure containing Retrieved Encrypted Data TLV buffer and to be populated with decoded data from TLV.
---|---

Returns
Error code 0 for success
3.8.5.7 hsm_close_data_storage_service()
hsm_err_t hsm_close_data_storage_service(
hsm_hdl_t data_storage_hdl)
Terminate a previously opened data storage service flow
Parameters

Returns
Error code

3.9 Authenticated encryption
Functions

• hsm_err_thsm_do_auth_enc (hsm_hdl_t key_store_hdl, op_auth_enc_args_t *auth_enc_args)

3.9.1 Detailed description
3.9.2 Function documentation
3.9.2.1 hsm_do_auth_enc()

hsm_err_t hsm_do_auth_enc (
hsm_hdl_t key_store_hdl,
op_auth_enc_args_t * auth_enc_args)
Secondary API to perform Authenticated Encryption.
This API does the following:

• Opens Cipher service flow.
• Perform authenticated encryption operation.
• Terminates the previously opened Cipher service flow.

Users can call this function only after opening a key store service flow.
Parameters

Returns
Error code
3.10 MAC
Data Structures

• struct open_svc_mac_args_t
• struct op_mac_one_go_args_t

Macros

• define HSM_OP_MAC_ONE_GO_FLAGS_MAC_VERIFICATION ((hsm_op_mac_one_go_flags_t) (0u <<0))

• define HSM_OP_MAC_ONE_GO_FLAGS_MAC_GENERATION ((hsm_op_mac_one_go_flags_t)(1u << 0))

• define HSM_MAC_VERIFICATION_STATUS_SUCCESS ((hsm_mac_verification_status_t) (0x6C1AA1C6u))

Typedefs

• typedef uint8_t hsm_op_mac_one_go_flags_t
• typedef uint32_t hsm_mac_verification_status_t
• typedef hsm_permitted_algo_thsm_op_mac_one_go_algo_t

Functions

• hsm_err_thsm_do_mac (hsm_hdl_t key_store_hdl, op_mac_one_go_args_t *mac_one_go)
• hsm_err_thsm_open_mac_service (hsm_hdl_t key_store_hdl, open_svc_mac_args_t args, hsm_hdl_tmac_hdl)
• hsm_err_thsm_mac_one_go (hsm_hdl_t mac_hdl, op_mac_one_go_args_t args, hsm_mac_verification_status_t status)
• hsm_err_thsm_close_mac_service (hsm_hdl_t mac_hdl)

3.10.1 Detailed description
3.10.2 Data structure documentation
3.10.2.1 struct open_svc_mac_args_t

Structure describing the MAC open service member arguments.

Data Fields

3.10.2.2 struct op_mac_one_go_args_t
Structure describing the MAC one go operation member arguments.
Data Fields

• Specified in bytes if HSM_OP_MAC_ONE_GO_FLAGS_MAC_LENGTH_IN_BITS is clear.
• Specified in bits when HSM_OP_MAC_ONE_GO_FLAGS_MAC_LENGTH_IN_BITS is set.
– When specified in bytes, the MAC size cannot be less than 4 bytes.
– When specified in bits, the MAC size cannot be less than:
– The key specific min_mac_len setting if specified for this key when generated/injected.
– The min_mac_length value if specified at the key store provisioning. (If a key specific setting is not specified at key generation/injection).
– The default value (32 bit) if a minimum value is not specified using one of the 2 methods above.
hsm_mac_verification_status_t| verification_status| MAC verification status.
uint16_t| exp_mac_size| Expected MAC size for output, returned by FW in case the MAC size provided is less than the expected MAC size calculated from MAC algorithm.

3.10.3 Macro definition documentation
3.10.3.1 HSM_OP_MAC_ONE_GO_FLAGS_MAC_VERIFICATION

define HSM_OP_MAC_ONE_GO_FLAGS_MAC_VERIFICATION ((hsm_op_mac_one_go_flags_t)

(0u << 0))
Bit indicating MAC one go verification operation.
3.10.3.2 HSM_OP_MAC_ONE_GO_FLAGS_MAC_GENERATION

define HSM_OP_MAC_ONE_GO_FLAGS_MAC_GENERATION ((hsm_op_mac_one_go_flags_t)(1u

<< 0))
Bit indicating MAC one go generate operation.
3.10.3.3 HSM_MAC_VERIFICATION_STATUS_SUCCESS

define HSM_MAC_VERIFICATION_STATUS_SUCCESS ((hsm_mac_verification_status_t)

(0x6C1AA1C6u))
Bit indicating MAC verification success status.
3.10.4 Typedef documentation
3.10.4.1 hsm_op_mac_one_go_flags_t
typedef uint8_t hsm_op_mac_one_go_flags_t
Bitmap describing the MAC one go operation.

3.10.4.2 hsm_mac_verification_status_t
typedef uint32_t hsm_mac_verification_status_t
Bitmap describing the MAC verification status.
3.10.4.3 hsm_op_mac_one_go_algo_t
typedef hsm_permitted_algo_t hsm_op_mac_one_go_algo_t
Bitmap describing the MAC one go operation permitted algorithm.
The following three permitted algos are allowed:

• PERMITTED_ALGO_HMAC_SHA256 = 0x03800009
• PERMITTED_ALGO_HMAC_SHA384 = 0x0380000A
• PERMITTED_ALGO_CMAC = 0x03C00200

3.10.5 Function documentation
3.10.5.1 hsm_do_mac()
hsm_err_t hsm_do_mac (
hsm_hdl_t key_store_hdl,
op_mac_one_go_args_t * mac_one_go)
Secondary API to perform MAC operation.
This API does the following:

• Open an MAC Service Flow.
• Perform MAC operation.
• Terminate a previously opened MAC service flow.

Users can call this function only after opening a key store service flow.

Parameters

Returns
Error code
3.10.5.2 hsm_open_mac_service()

hsm_err_t hsm_open_mac_service (
hsm_hdl_t key_store_hdl,
open_svc_mac_args_t args,
hsm_hdl_t mac_hdl)
Open a MAC service flow.
Users can call this function only after opening a key store service flow.
Users must open this service to perform MAC operation.

Parameters

Returns
Error code
3.10.5.3 hsm_mac_one_go()

hsm_err_t hsm_mac_one_go (
hsm_hdl_t mac_hdl,
op_mac_one_go_args_t args,
hsm_mac_verification_status_t status)
Perform MAC operation.
Users can call this function only after opening a MAC service flow.
For CMAC algorithm, a key of type HSM_KEY_TYPE_AES_XXX must be used.
For HMAC algorithm, a key of type HSM_KEY_TYPE_HMAC_XXX must be used.
For MAC verification operations, the verified MAC length can be specified in:

• Bits by setting the HSM_OP_MAC_ONE_GO_FLAGS_MAC_LENGTH_IN_BITS flag.
• If this flag is clear, the mac_length is specified in bytes.

For MAC generation operations:

• MAC length must be set in bytes.
• HSM_OP_MAC_ONE_GO_FLAGS_MAC_LENGTH_IN_BITS flag must be 0.

Parameters

Returns
Error code

3.10.5.4 hsm_close_mac_service()
hsm_err_t hsm_close_mac_service (hsm_hdl_t mac_hdl)
Terminate a previously opened MAC service flow.

Parameters

Returns
Error code

3.11 Dump firmware log
Data Structures

• struct op_debug_dump_args_t

Functions

• hsm_err_tdump_firmware_log (hsm_hdl_t session_hdl)

3.11.1 Detailed description
3.11.2 Data structure documentation
3.11.2.1 struct op_debug_dump_args_t

Structure detailing the debug dump operation member arguments.

Data Fields

3.11.3 Function documentation
3.11.3.1 dump_firmware_log()

hsm_err_t dump_firmware_log (hsm_hdl_t session_hdl)

This command is designed to dump the firmware logs.
Parameters

Returns
Error code

3.12 Dev attest
Data Structures

• struct op_dev_attest_args_t

Macros

• define DEV_ATTEST_NOUNCE_SIZE_V1 (4)

• define DEV_ATTEST_NOUNCE_SIZE_V2 (16)

Functions

• hsm_err_thsm_dev_attest (hsm_hdl_t sess_hdl, op_dev_attest_args_t *args)

3.12.1 Detailed description
3.12.2 Data structure documentation
3.12.2.1 struct op_dev_attest_args_t

Structure describing the device attestation operation member arguments. Memory for storing uid/sha_rom_patch/sha_fw/signature is allocated by the HSM library. Caller of the function hsm_dev_attest() needs to ensure freeing up memory.

Data Fields

patch fuses.
uint16_t| sha_fw_sz| Buffer size in bytes for the first 256 bits of installed FW SHA.
uint8_t | sha_rom_patch| Pointer to the buffer containing SHA256 of Sentinel ROM patch fuses.
uint8_t | sha_fw| Pointer to the buffer containing first 256 bits of installed FW SHA.
uint16_t| nounce_sz| Buffer size in bytes for request nounce value.
uint8_t | nounce| Pointer to the input/request nounce value buffer.
uint16_t| rsp_nounce_sz| Size in bytes for FW nounce buffer, returned with FW resp.
uint8_t | rsp_nounce| Pointer to the FW nounce buffer, returned with FW resp.
uint16_t| oem_srkh_sz| Buffer size in bytes for OEM SRKH (version 2).
uint8_t | oem_srkh| Pointer to the buffer of OEM SRKH (version 2).
uint8_t| imem_state| IMEM state (version 2).
uint8_t| csal_state| CSAL state (version 2).
uint8_t| trng_state| TRNG state (version 2).
uint16_t| info_buf_sz| Size in bytes for info buffer.
uint8_t | info_buf| Pointer to the info buffer, for verification of the signature.
uint8_t| attest_result| Attest Result. 0 means pass. 1 means fail.
uint16_t| sign_sz| Buffer size in bytes for signature.
uint8_t *| signature| Pointer to the signature buffer.

3.12.3 Macro definition documentation
3.12.3.1 DEV_ATTEST_NOUNCE_SIZE_V1

define DEV_ATTEST_NOUNCE_SIZE_V1 (4)

Device Attestation Nounce sizes.

3.12.4 Function documentation
3.12.4.1 hsm_dev_attest()

hsm_err_t hsm_dev_attest (
hsm_hdl_t sess_hdl,
op_dev_attest_args_t * args)

Perform device attestation operation.
Users can call this function only after opening the session.

Parameters

Returns
Error code

3.13 Dev Info
Data Structures

• struct op_dev_getinfo_args_t

Functions

• hsm_err_thsm_dev_getinfo (hsm_hdl_t sess_hdl, op_dev_getinfo_args_t *args)

3.13.1 Detailed description
3.13.2 Data structure documentation
3.13.2.1 struct op_dev_getinfo_args_t

Structure detailing the device getinfo operation member arguments. Memory for storing uid/sha_rom_patch/ sha_fw/signature is allocated by the HSM library. Caller of the function hsm_dev_getinfo() needs to ensure freeing up memory.

Data Fields

fuses.
uint16_t| sha_fw_sz| Indicates the size of first 256 bits of installed FW SHA.
uint8_t | sha_rom_patch| Pointer to the SHA256 of sentinel ROM patch fuses digest.
uint8_t | sha_fw| Pointer to the first 256 bits of installed FW SHA digest.
uint16_t| oem_srkh_sz| Indicates the size of FW OEM SRKH.
uint8_t *| oem_srkh| Pointer to the FW OEM SRKH.
uint8_t| imem_state| Indicates the IMEM state.
uint8_t| csal_state| Crypto Lib random context initialization state.
uint8_t| trng_state| Indicates TRNG state.

3.13.3 Function documentation
3.13.3.1 hsm_dev_getinfo()
hsm_err_t hsm_dev_getinfo (
hsm_hdl_t sess_hdl,
op_dev_getinfo_args_t * args)
Perform the device attestation operation.
Users can call this function only after opening the session.
Parameters

Returns
Error code

3.14 Generic Crypto: Asymmetric Crypto
Data Structures

• struct op_gc_acrypto_args_t

Macros

• define HSM_OP_GC_ACRYPTO_FLAGS_INPUT_MESSAGE ((hsm_op_gc_acrypto_flags_t) (1u << 0))

• define HSM_GC_ACRYPTO_VERIFICATION_SUCCESS ((hsm_gc_acrypto_verification_status_t) (0x5A3CC3A5u))

• define HSM_GC_ACRYPTO_VERIFICATION_FAILURE ((hsm_gc_acrypto_verification_status_t) (0x2B4DD4B2u))

Typedefs

• typedef uint8_t hsm_op_gc_acrypto_flags_t
• typedef uint32_t hsm_gc_acrypto_verification_status_t

Enumerations

• enum hsm_op_gc_acrypto_algo_t {
  HSM_GC_ACRYPTO_ALGO_ECDSA_SHA224 = ALGO_ECDSA_SHA224,
  HSM_GC_ACRYPTO_ALGO_ECDSA_SHA256 = ALGO_ECDSA_SHA256,
  HSM_GC_ACRYPTO_ALGO_ECDSA_SHA384 = ALGO_ECDSA_SHA384,
  HSM_GC_ACRYPTO_ALGO_ECDSA_SHA512 = ALGO_ECDSA_SHA512,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_V15_SHA224 = ALGO_RSA_PKCS1_V15_SHA224,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_V15_SHA256 = ALGO_RSA_PKCS1_V15_SHA256,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_V15_SHA384 = ALGO_RSA_PKCS1_V15_SHA384,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_V15_SHA512 = ALGO_RSA_PKCS1_V15_SHA512,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_PSS_MGF1_SHA224 =
  ALGO_RSA_PKCS1_PSS_MGF1_SHA224,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_PSS_MGF1_SHA256 =
  ALGO_RSA_PKCS1_PSS_MGF1_SHA256,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_PSS_MGF1_SHA384 =
  ALGO_RSA_PKCS1_PSS_MGF1_SHA384,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_PSS_MGF1_SHA512 =
  ALGO_RSA_PKCS1_PSS_MGF1_SHA512,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_V15_CRYPT = ALGO_RSA_PKCS1_V15_CRYPT,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_OAEP_SHA1 = ALGO_RSA_PKCS1_OAEP_SHA1,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_OAEP_SHA224 = ALGO_RSA_PKCS1_OAEP_SHA224,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_OAEP_SHA256 = ALGO_RSA_PKCS1_OAEP_SHA256,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_OAEP_SHA384 = ALGO_RSA_PKCS1_OAEP_SHA384,
  HSM_GC_ACRYPTO_ALGO_RSA_PKCS1_OAEP_SHA512 = ALGO_RSA_PKCS1_OAEP_SHA512 }

• enum hsm_gc_acrypto_op_mode_t {
  HSM_GC_ACRYPTO_OP_MODE_ENCRYPT = 0x01,
  HSM_GC_ACRYPTO_OP_MODE_DECRYPT = 0x02,
  HSM_GC_ACRYPTO_OP_MODE_SIGN_GEN = 0x03,
  HSM_GC_ACRYPTO_OP_MODE_SIGN_VER = 0x04 }

Functions

• hsm_err_thsm_gc_acrypto (hsm_hdl_t session_hdl, op_gc_acrypto_args_t *args)

3.14.1 Detailed description
3.14.2 Data structure documentation
3.14.2.1 struct op_gc_acrypto_args_t

Structure describing the generic asymmetric crypto member arguments.
Data Fields

• Plaintext in case of encryption/decryption operation.
• Digest or message in case of signature generation/ verification operation.
uint8_t | data_buff2| Pointer to the data buffer 2:
• Ciphertext in case of encryption/decryption operation.
• Signature in case of signature generation/verification operation.
uint32_t| data_buff1_size| Size in bytes of data buffer 1.
uint32_t| data_buff2_size| Size in bytes of data buffer 2.
uint8_t | key_buff1| Pointer to the key modulus buffer.
uint8_t | key_buff2| Pointer the key exponent, either private or public.
• Encryption mode, public exponent
• Decryption mode, private exponent
• Signature Generation mode, private exponent
• Signature Verification mode, public exponent
uint16_t| key_buff1_size| Size in bytes of the key buffer 1.
uint16_t| key_buff2_size| Size in bytes of the key buffer 2.
uint8_t | rsa_label| RSA label address. Only used for OAEP encryption/ decryption operation mode and optional.
uint16_t| rsa_label_size| RSA label size in bytes. Only used for OAEP encryption/decryption operation mode.
uint16_t| rsa_salt_len| RSA salt length in bytes. Only used for PSS signature algorithm scheme.
uint32_t| exp_plaintext_len| Expected plaintext length in bytes, returned by FW in case of DECRYPT operation mode.
hsm_gc_acrypto_verification_status_t| verification_status| Signature verification status.

3.14.3 Macro definition documentation
3.14.3.1 HSM_OP_GC_ACRYPTO_FLAGS_INPUT_MESSAGE

define HSM_OP_GC_ACRYPTO_FLAGS_INPUT_MESSAGE ((hsm_op_gc_acrypto_flags_t) (1u

<< 0))
Bit indicating the generic asymmetric crypto input message operation.
3.14.3.2 HSM_GC_ACRYPTO_VERIFICATION_SUCCESS

define HSM_GC_ACRYPTO_VERIFICATION_SUCCESS

((hsm_gc_acrypto_verification_status_t) (0x5A3CC3A5u))
Bit indicating the generic asymmetric crypto success verification status.
3.14.3.3 HSM_GC_ACRYPTO_VERIFICATION_FAILURE

define HSM_GC_ACRYPTO_VERIFICATION_FAILURE

((hsm_gc_acrypto_verification_status_t) (0x2B4DD4B2u))
Bit indicating the generic asymmetric crypto failure verification status.

3.14.4 Typedef documentation
3.14.4.1 hsm_op_gc_acrypto_flags_t
typedef uint8_t hsm_op_gc_acrypto_flags_t
Bitmap describing the generic asymmetric crypto supported operation.
3.14.4.2 hsm_gc_acrypto_verification_status_t
typedef uint32_t hsm_gc_acrypto_verification_status_t
Bitmap describing the generic asymmetric crypto verification status.
3.14.5 Enumeration type documentation
3.14.5.1 hsm_op_gc_acrypto_algo_t
enum hsm_op_gc_acrypto_algo_t
Enum detailing the generic asymmetric crypto supported algorithms.
3.14.5.2 hsm_gc_acrypto_op_mode_t
enum hsm_gc_acrypto_op_mode_t
Enum describing the generic asymmetric crypto supported operating modes.
3.14.6 Function documentation
3.14.6.1 hsm_gc_acrypto()
hsm_err_t hsm_gc_acrypto (
hsm_hdl_t session_hdl,
op_gc_acrypto_args_t * args)
This command is designed to perform the following operations:

• Asymmetric crypto
• Encryption/decryption
• Signature generation/verification

Parameters

3.15 Generic Crypto Asymmetric Key Generate
Data Structures

• struct op_gc_akey_gen_args_t

Functions

• hsm_err_thsm_gc_akey_gen (hsm_hdl_t session_hdl, op_gc_akey_gen_args_t *args)

3.15.1 Detailed description
3.15.2 Data structure documentation
3.15.2.1 struct op_gc_akey_gen_args_t
Structure detailing the generic crypto asymmetric key generate operation members.
Table 1. Data Fields

exponent.
uint16_t| modulus_size| Size in bytes of the modulus buffer.
uint16_t| priv_buff_size| Size in bytes of the private exponent buffer.
uint16_t| pub_buff_size| Size in bytes of the public exponent buffer.
hsm_key_type_t| key_type| Indicates which type of keypair must be generated.
hsm_bit_key_sz_t| bit_key_sz| Size in bits of the keypair to be generated.

3.15.3 Function documentation
3.15.3.1 hsm_gc_akey_gen()

hsm_err_t hsm_gc_akey_gen (
hsm_hdl_t session_hdl,
op_gc_akey_gen_args_t * args)
This command is designed to perform the following operation:
Generate asymmetric keys, without using FW keystore.

Parameters

Returns
Error code
3.16 Get Info
Data Structures

• struct op_get_info_args_t

Functions

• hsm_err_thsm_get_info (hsm_hdl_t sess_hdl, op_get_info_args_t *args)

3.16.1 Detailed description
3.16.2 Data structure documentation
3.16.2.1 struct op_get_info_args_t

Structure describing the get info operation member arguments.
Data Fields

bits).
uint16_t| chip_life_cycle| Stores the chip current life cycle bitfield (16 bits).
uint32_t| version| Stores the module version (32 bits).
uint32_t| version_ext| Stores the module extended version (32 bits).
uint8_t| fips_mode| Stores the FIPS mode bitfield (8 bits). Bitmask definition:
bit0: FIPS mode of operation:
• Value 0: part is running in FIPS non-approved mode.
• Value 1: part is running in FIPS approved mode.
• Bit 1: FIPS certified part:
• Value 0: part is not FIPS certified.
• Value 1: part is FIPS certified.
• Bit 2-7: reserved
• Value 0.

3.16.3 Function documentation
3.16.3.1 hsm_get_info()
hsm_err_t hsm_get_info (
hsm_hdl_t sess_hdl,
op_get_info_args_t * args)
Perform device attestation operation.
Users can call this function only after opening the session.
Parameters

Returns
Error code

3.17 Public key recovery
Public Key Recovery is also known as Public Key Exportation, in PSA compliant APIs. The naming here has been kept unchanged, for backward compatibility and Non-PSA compliant APIs.

Data Structures

• struct op_pub_key_recovery_args_t

Functions

• hsm_err_thsm_pub_key_recovery (hsm_hdl_t key_store_hdl, op_pub_key_recovery_args_t *args)

3.17.1 Detailed description
Public Key Recovery is now known as Public Key Exportation, in PSA compliant APIs. The naming here has been kept unchanged, for backward compatibility and Non-PSA compliant APIs.

3.17.2 Data structure documentation
3.17.2.1 struct op_pub_key_recovery_args_t
Structure detailing the public key recovery opeation member arguments.

Data Fields

uint32_t| key_identifier| Pointer to the identifier of the key to be used for the operation.
---|---|---
uint8_t *| out_key| Pointer to the output area where the generated public key must be written.
uint16_t| out_key_size| Length in bytes of the output key.
uint16_t| exp_out_key_size| Expected output key buffer size, valid in case of HSM_OUT_TOO_SMALL (0x1D) resp code.

3.17.3 Function documentation
3.17.3.1 hsm_pub_key_recovery()
hsm_err_t hsm_pub_key_recovery (
hsm_hdl_t key_store_hdl,
op_pub_key_recovery_args_t * args)
Recover Public key from private key present in key store.
Users can call this function only after opening a key store.
Parameters

Returns
Error code

3.18 Key store
User must open a key store service flow to perform the following operations.

Data Structures

• struct open_svc_key_store_args_t

Macros

• define HSM_SVC_KEY_STORE_FLAGS_LOAD ((hsm_svc_key_store_flags_t)(0u << 0))

  It must be specified to load a previously created key store.

• define HSM_SVC_KEY_STORE_FLAGS_CREATE ((hsm_svc_key_store_flags_t)(1u << 0))

• define HSM_SVC_KEY_STORE_FLAGS_SET_MAC_LEN ((hsm_svc_key_store_flags_t)(1u << 3))

• define HSM_SVC_KEY_STORE_FLAGS_STRICT_OPERATION ((hsm_svc_key_store_flags_t)(1u << 7))

Typedefs

• typedef uint8_t hsm_svc_key_store_flags_t

Functions

• hsm_err_thsm_open_key_store_service (hsm_hdl_t session_hdl, open_svc_key_store_args_t args, hsm_hdl_t key_store_hdl)
• hsm_err_thsm_close_key_store_service (hsm_hdl_t key_store_hdl)

3.18.1 Detailed description
UserS must open a key store service flow to perform the following operations:

• Create a new key store.
• Perform operations involving keys stored in the key store (ciphering, signature generation…)
• Perform a key store reprovisioning using a signed message. A key store re-provisioning results in erasing all the key stores handled by the HSM.

Grant access to the key store. The caller is authenticated against the domain ID (DID) and Messaging Unit used at the keystore creation. In addition, an authentication nonce can be provided.

3.18.2 Data structure documentation
3.18.2.1 struct open_svc_key_store_args_t

Structure specifying the open key store service member arguments.

Data Fields

Only one key store service can be opened on a given key_store_identifier.
uint32_t| authentication_nonce| User defined nonce used as authentication proof for accessing the key store.
uint8_t| flags| Bitmap specifying the services properties.
uint8_t *| signed_message| Pointer to signed_message to be sent only in case of key store re- provisioning.
uint16_t| signed_msg_size| Size of the signed_message to be sent only in case of key store re- provisioning.
---|---|---

3.18.3 Macro definition documentation
3.18.3.1 HSM_SVC_KEY_STORE_FLAGS_CREATE

define HSM_SVC_KEY_STORE_FLAGS_CREATE ((hsm_svc_key_store_flags_t)(1u << 0))

It must be specified to create a new key store. The key store is stored in the NVM only if the STRICT
OPERATION flag is set.
3.18.3.2 HSM_SVC_KEY_STORE_FLAGS_SET_MAC_LEN

define HSM_SVC_KEY_STORE_FLAGS_SET_MAC_LEN ((hsm_svc_key_store_flags_t) (1u

<<3))
If set, the minimum MAC length specified in the min_mac_length field is stored in the key store when creating the key store. It must only be set at key store creation.
3.18.3.3 HSM_SVC_KEY_STORE_FLAGS_STRICT_OPERATION

define HSM_SVC_KEY_STORE_FLAGS_STRICT_OPERATION ((hsm_svc_key_store_flags_t)

(1u << 7))
The request is completed only when the new key store is written in the NVM. This is applicable for CREATE operations only.
3.18.4 Typedef documentation
3.18.4.1 hsm_svc_key_store_flags_t
typedef uint8_t hsm_svc_key_store_flags_t
Bitmap specifying the open key store service supported attributes.
3.18.5 Function documentation
3.18.5.1 hsm_open_key_store_service()
hsm_err_t hsm_open_key_store_service (
hsm_hdl_t session_hdl,
open_svc_key_store_args_t args,
hsm_hdl_t key_store_hdl)
Open a service flow on the specified key store. Only one key store service can be opened on a given key store.
Parameters

written.

Returns
Error code.
3.18.5.2 hsm_close_key_store_service()

hsm_err_t hsm_close_key_store_service (hsm_hdl_t key_store_hdl)
Close a previously opened key store service flow. The key store is deleted from the HSM local memory. Any update not written in the NVM is lost.

Parameters

Returns
Error code.
3.19 Life cycle update
Data Structures

• struct op_lc_update_msg_args_t

Enumerations

• enum hsm_lc_new_state_t {
  HSM_NXP_PROVISIONED_STATE = (1u << 0),
  HSM_OEM_OPEN_STATE = (1u << 1),
  HSM_OEM_CLOSE_STATE = (1u << 3),
  HSM_OEM_FIELD_RET_STATE = (1u << 4),
  HSM_NXP_FIELD_RET_STATE = (1u << 5),
  HSM_OEM_LOCKED_STATE = (1u << 7) }

Functions

• hsm_err_thsm_lc_update (hsm_hdl_t session_hdl, op_lc_update_msg_args_t *args)

3.19.1 Detailed description
3.19.2 Data structure documentation
3.19.2.1 struct op_lc_update_msg_args_t
Structure specifying the life cycle update message arguments.
Data Fields

3.19.3 Enumeration type documentation
3.19.3.1 hsm_lc_new_state_t

enum hsm_lc_new_state_t
Enum specifying the Life Cycle state.

3.19.4 Function documentation
3.19.4.1 hsm_lc_update()
hsm_err_t hsm_lc_update (
hsm_hdl_t session_hdl,
op_lc_update_msg_args_t * args)

This API performs the Life Cycle update.
Parameters

Returns
Error code

3.20 Global information
Data Structures

• struct global_info_s

Functions

• void populate_global_info (hsm_hdl_t hsm_session_hdl)
• void show_global_info (void)
• uint8_t hsm_get_dev_attest_api_ver (void)
• const char * get_soc_id_str (uint16_t soc_id)
• const char * get_soc_rev_str (uint16_t soc_rev)
• const char * get_soc_lf_str (uint16_t lifecycle)

Variables

• struct global_info_sglobal_info

3.20.1 Detailed description
3.20.2 Data structure documentation
3.20.2.1 struct global_info_s

Global Information structure contains the information about SoC and the Library. It is used globally to take platform specific decisions.

Data Fields

3.20.3 Function documentation
3.20.3.1 populate_global_info()

void populate_global_info (hsm_hdl_t hsm_session_hdl)
This function is called to populate the Global Information structure.

Parameters

3.20.3.2 show_global_info()
void show_global_info (void )
This function prints the Global Information of the library.
3.20.3.3 hsm_get_dev_attest_api_ver()
uint8_t hsm_get_dev_attest_api_ver (void )
This function returns the version supported for Device Attestation.
3.20.3.4 get_soc_id_str()
const char* get_soc_id_str (uint16_t soc_id)
This function returns a string representating SoC ID.
Parameters

Returns
String represention of the SoC ID.
3.20.3.5 get_soc_rev_str()

const char* get_soc_rev_str (uint16_t soc_rev)
This function returns a string representating SoC Revision.
Table 2. Parameters

Returns
String represention of the SoC revision.

3.20.3.6 get_soc_lf_str()
const char* get_soc_lf_str (uint16_t lifecycle)
This function returns a string representating Lifecycle.

Table 3. Parameters

Returns
A string represention of Lifecycle
3.20.4 Variable documentation
3.20.4.1 global_info

struct global_info_s global_info
Global Information structure instance, which is populated and then is used for getting the required platform or library details.

3.21 Error codes
Enumerations

• enum hsm_err_t {
  HSM_NO_ERROR = 0x0,
  HSM_INVALID_MESSAGE = 0x1,
  HSM_INVALID_ADDRESS = 0x2,
  HSM_UNKNOWN_ID = 0x3,
  HSM_INVALID_PARAM = 0x4,
  HSM_NVM_ERROR = 0x5,
  HSM_OUT_OF_MEMORY = 0x6,
  HSM_UNKNOWN_HANDLE = 0x7,
  HSM_UNKNOWN_KEY_STORE = 0x8,
  HSM_KEY_STORE_AUTH = 0x9,
  HSM_KEY_STORE_ERROR = 0xA,
  HSM_ID_CONFLICT = 0xB,
  HSM_RNG_NOT_STARTED = 0xC,
  HSM_CMD_NOT_SUPPORTED = 0xD,
  HSM_INVALID_LIFECYCLE = 0xE,
  HSM_KEY_STORE_CONFLICT = 0xF,
  HSM_KEY_STORE_COUNTER = 0x10,
  HSM_FEATURE_NOT_SUPPORTED = 0x11,
  HSM_SELF_TEST_FAILURE = 0x12,
  HSM_NOT_READY_RATING = 0x13,
  HSM_FEATURE_DISABLED = 0x14,
  HSM_KEY_GROUP_FULL = 0x19,
  HSM_CANNOT_RETRIEVE_KEY_GROUP = 0x1A,
  HSM_KEY_NOT_SUPPORTED = 0x1B,
  HSM_CANNOT_DELETE_PERMANENT_KEY = 0x1C,
  HSM_OUT_TOO_SMALL = 0x1D,
  HSM_DATA_ALREADY_RETRIEVED = 0x1F,
  HSM_CRC_CHECK_ERR = 0xB9,
  HSM_OEM_CLOSED_LC_SIGNED_MSG_VERIFICATION_FAIL = 0xF0,
  HSM_OEM_OPEN_LC_SIGNED_MSG_VERIFICATION_FAIL = 0xF0,
  HSM_FATAL_FAILURE = 0x29,
  HSM_SERVICES_DISABLED = 0xF4,
  HSM_UNKNOWN_WARNING = 0xFC,
  HSM_SIGNATURE_INVALID = 0xFD,
  HSM_UNKNOWN_ERROR = 0xFE,
  HSM_GENERAL_ERROR = 0xFF }

3.21.1 Detailed description
3.21.2 Enumeration type documentation
3.21.2.1 hsm_err_t enum hsm_err_t

Error codes returned by HSM functions.
Enumerator

API requirements.
HSM_UNKNOWN_ID| The provided identifier is not known.
HSM_INVALID_PARAM| One of the parameters provided in the command is invalid.
HSM_NVM_ERROR| NVM generic issue.
HSM_OUT_OF_MEMORY| There is not enough memory to handle the requested operation.
HSM_UNKNOWN_HANDLE| Unknown session/service handle.
HSM_UNKNOWN_KEY_STORE| The key store identified by the provided “key store Id” does not exist and the “create” flag is not set.
HSM_KEY_STORE_AUTH| Key store authentication fails.
HSM_KEY_STORE_ERROR| An error occurred in the key store internal processing.
HSM_ID_CONFLICT| An element (key store, key…) with the provided ID already exists.
HSM_RNG_NOT_STARTED| The internal RNG is not started.
HSM_CMD_NOT_SUPPORTED| The functionality is not supported for the current session/ service/key store configuration.
HSM_INVALID_LIFECYCLE| Invalid lifecycle for requested operation.
HSM_KEY_STORE_CONFLICT| A key store with the same attributes already exists.
HSM_KEY_STORE_COUNTER| The current key store reaches the maximum number of monotonic counter updates. Updates are still allowed but monotonic counter will not be blown.
HSM_FEATURE_NOT_SUPPORTED| The requested feature is not supported by the firwware.
HSM_SELF_TEST_FAILURE| Self-tests report an issue.
HSM_NOT_READY_RATING| The HSM is not ready to handle the current request.
HSM_FEATURE_DISABLED| The required service/operation is disabled.
HSM_KEY_GROUP_FULL| Not enough space to store the key in the key group.
HSM_CANNOT_RETRIEVE_KEY_GROUP| Impossible to retrieve key group.
HSM_KEY_NOT_SUPPORTED| Key not supported.
HSM_CANNOT_DELETE_PERMANENT_KEY| Trying to delete a permanent key.
HSM_OUT_TOO_SMALL| Output buffer size is too small.
HSM_DATA_ALREADY_RETRIEVED| Data is Read Once, and has already been retrieved.
HSM_CRC_CHECK_ERR| Command CRC check error.
HSM_OEM_CLOSED_LC_SIGNED_MSGVERIFICATION FAIL| In OEM closed lifecycle, Signed message signature verification failure.
HSM_OEM_OPEN_LC_SIGNED_MSGVERIFICATION FAIL| In OEM open lifecycles, Signed message signature verification failure.
HSM_FATAL_FAILURE| A fatal failure occurs. The HSM goes in unrecoverable error state not replying to further requests.
HSM_SERVICES_DISABLED| Message neither handled by ROM nor FW.
HSM_UNKNOWN_WARNING| Unknown warnings.
HSM_SIGNATURE_INVALID| Failure in verification status of operations such as MAC verification, Signature verification.
HSM_UNKNOWN_ERROR| Unknown errors.
HSM_GENERAL_ERROR| Error in case General Error is received.

3.22 i.MX 8ULP
Ciphering

• HSM_CIPHER_ONE_GO_ALGO_OFB is not supported.
• HSM_AEAD_ALGO_GCM is not supported.
• HSM_AEAD_ALGO_ALL_AEAD is not supported.
• ALGO_RSA_PKCS1_V15_SHA224 is not supported.
• ALGO_RSA_PKCS1_V15_SHA256 is not supported.
• ALGO_RSA_PKCS1_V15_SHA384 is not supported.
• ALGO_RSA_PKCS1_V15_SHA512 is not supported.
• ALGO_RSA_PKCS1_PSS_MGF1 _SHA224 is not supported.
• ALGO_RSA_PKCS1 _PSS_MGF1_SHA256 is not supported.
• ALGO_RSA_PKCS1_PSS_MGF1_SHA384 is not supported.
• ALGO_RSA_PKCS1_PSS_MGF1_SHA512 is not supported.

Note About the Source Code in the Document

Example code shown in this document has the following copyright and BSD-3-Clause license:
Copyright 2023 NXP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3.  Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Revision History

This table provides the revision history.
Revision history

Legal information

Definitions
Draft — A draft status on a document indicates that the content is still under internal review and subject to formal approval, which may result in modifications or additions. NXP Semiconductors does not give any representations or warranties as to the accuracy or completeness of information included in a draft version of a document and shall have no liability for the consequences of use of such information.

Disclaimers
Limited warranty and liability — Information in this document is believed to be accurate and reliable. However, NXP Semiconductors does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information  and shall have no liability for the consequences of use of such information. NXP Semiconductors takes no responsibility for the content in this document if provided by an information source outside of NXP Semiconductors.
In no event shall NXP Semiconductors be liable for any indirect, incidental, punitive, special or consequential damages (including – without limitation lost profits, lost savings, business interruption, costs related to the removal or replacement of any products or rework charges) whether or not such damages are based on tort (including negligence), warranty, breach of contract or any other legal theory.
Notwithstanding any damages that customer might incur for any reason whatsoever, NXP Semiconductors’ aggregate and cumulative liability towards customer for the products described herein shall be limited in accordance with the Terms and conditions of commercial sale of NXP Semiconductors.
Right to make changes — NXP Semiconductors reserves the right to make changes to information published in this document, including without limitation specifications and product descriptions, at any time and without notice. This document supersedes and replaces all information supplied prior to the publication hereof.
Suitability for use — NXP Semiconductors products are not designed, authorized or warranted to be suitable for use in life support, life-critical or safety-critical systems or equipment, nor in applications where failure or malfunction of an NXP Semiconductors product can reasonably be expected to result in personal injury, death or severe property or environmental damage. NXP Semiconductors and its suppliers accept no liability for inclusion and/or use of NXP Semiconductors products in such equipment or applications and therefore such inclusion and/or use is at the customer’s own risk.

Applications — Applications that are described herein for any of these products are for illustrative purposes only. NXP Semiconductors makes no representation or warranty that such applications will be suitable for the specified use without further testing or modification.
Customers are responsible for the design and operation of their applications and products using NXP Semiconductors products, and NXP Semiconductors accepts no liability for any assistance with applications or customer product design. It is customer’s sole responsibility to determine whether the NXP Semiconductors product is suitable and fit for the customer’s applications and products planned, as well as for the planned application and use of customer’s third party customer(s). Customers should provide appropriate design and operating safeguards to minimize the risks associated with their applications and products.
NXP Semiconductors does not accept any liability related to any default, damage, costs or problem which is based on any weakness or default in the customer’s applications or products, or the application or use by customer’s third party customer(s). Customer is responsible for doing all necessary testing for the customer’s applications and products using NXP Semiconductors products in order to avoid a default of the applications and the products or of the application or use by customer’s third party customer(s). NXP does not accept any liability in this respect.
Terms and conditions of commercial sale — NXP Semiconductors products are sold subject to the general terms and conditions of commercial sale, as published at https://www.nxp.com/profile/terms, unless otherwise agreed in a valid written individual agreement. In case an individual agreement is concluded only the terms and conditions of the respective agreement shall apply. NXP Semiconductors hereby expressly objects to applying the customer’s general terms and conditions with regard to the purchase of NXP Semiconductors products by customer.

Export control — This document as well as the item(s) described herein may be subject to export control regulations. Export might require a prior authorization from competent authorities.
Suitability for use in non-automotive qualified products — Unless this document expressly states that this specific NXP Semiconductors product is automotive qualified, the product is not suitable for automotive use. It is neither qualified nor tested in accordance with automotive testing or application requirements. NXP Semiconductors accepts no liability for inclusion and/or use of non-automotive qualified products in automotive equipment or applications.
In the event that customer uses the product for design-in and use in automotive applications to automotive specifications and standards, customer (a) shall use the product without NXP Semiconductors’ warranty of the product for such automotive applications, use and specifications, and (b) whenever customer uses the product for automotive applications beyond NXP Semiconductors’ specifications such use shall be solely at customer’s own risk, and (c) customer fully indemnifies NXP Semiconductors for any liability, damages or failed product claims resulting from customer design and use of the product for automotive applications beyond NXP Semiconductors’ standard warranty and NXP Semiconductors’ product specifications.
Translations — A non-English (translated) version of a document, including the legal information in that document, is for reference only. The English version shall prevail in case of any discrepancy between the translated and English versions.
Security — Customer understands that all NXP products may be subject to unidentified vulnerabilities or may support established security standards or specifications with known limitations. Customer is responsible for the design and operation of its applications and products throughout their lifecycles to reduce the effect of these vulnerabilities on customer’s applications and products. Customer’s responsibility also extends to other open and/or proprietary technologies supported by NXP products for use in customer’s applications. NXP accepts no liability for any vulnerability. Customer should regularly check security updates from NXP and follow up appropriately.
Customer shall select products with security features that best meet rules, regulations, and standards of the intended application and make the ultimate design decisions regarding its products and is solely responsible for compliance with all legal, regulatory, and security related requirements concerning its products, regardless of any information or support that may be provided by NXP.
NXP has a Product Security Incident Response Team (PSIRT) (reachable at PSIRT@nxp.com) that manages the investigation, reporting, and solution release to security vulnerabilities of NXP products.

NXP B.V. — NXP B.V. is not an operating company and it does not distribute or sell products.

Trademarks
Notice: All referenced brands, product names, service names, and trademarks are the property of their respective owners.
NXP — wordmark and logo are trademarks of NXP B.V.

Please be aware that important notices concerning this document and the product(s) described herein, have been included in section ‘Legal information’.

© 2023 NXP B.V.
For more information, please visit: https://www.nxp.com
All rights reserved.
Date of release: 15 December 2023
Document identifier: RM00284

References

• GitHub - nxp-imx/imx-secure-enclave: source code for iMX8 SHE driver

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>