Identity key

The identity key library manages an asymmetric key used for identity services on devices with the Arm CryptoCell and KMU peripherals. It’s used to provision identity keys and can only be used by a Zephyr image in Secure Processing Environment (SPE). It is not supported from images for Non-Secure Processing Environment (NSPE), from a Trusted Firmware-M image, or from MCUboot.

The identity key is equivalent to the Initial Attestation Key (IAK), as described in the ARM Platform Security Model 1.1, when Trusted Firmware-M (TF-M) is enabled. TF-M has access to the identity key using internal APIs and does not need to use this library.

Functionality

This library manages identity keys, which are asymmetric keys intended to provide a unique identity to a device. The identity key is designed to be unique and is provisioned either device-generated or otherwise in a secure manner during production. Two reserved slots of the Key Management Unit (KMU) peripheral are used to store the identity key in order to protect its integrity. The identity key is stored in an encrypted form using a Key Encryption Key (KEK) derived by the Hardware Unique key (HUK) Master Key Encryption Key (MKEK).

Caution

The identity key must not be shared. Leaking this leaks the identity of the device.

Caution

The identity key is stored in the KMU and will therefore be erased by ERASEALL.

Prerequisites

To use the identity key APIs, you must first generate or provision HUK keys on the device.

API documentation

Header file: include/identity_key.h

Source files: modules/lib/identity_key/

group identity_key

API for identity key on CryptoCell devices with KMU.

Defines

IDENTITY_KEY_SIZE_BYTES

Identity key size in bytes, corresponding to ECC secp256r1.

IDENTITY_KEY_ERR_MKEK_MISSING

Error value when MKEK is missing from the KMU.

IDENTITY_KEY_ERR_MISSING

Error value when identity key is missing from the KMU.

IDENTITY_KEY_ERR_READ_FAILED

Error value when identity key can’t be read.

IDENTITY_KEY_ERR_WRITE_FAILED

Error value when identity key can’t be written.

IDENTITY_KEY_ERR_GENERATION_FAILED

Error value when identity key generation failed.

IDENTITY_KEY_SUCCESS

Return code for success.

Functions

bool identity_key_mkek_is_written(void)

Function to check that the MKEK is present.

MKEK is a prerequisite to encrypt and decrypt the identity key.

Returns:

true if MKEK is written, otherwise false

bool identity_key_is_written(void)

Function to check if identity key is written.

Returns:

true if the identity key is written, otherwise false

int identity_key_read(uint8_t key[(32)])

Function to read the identity key from KMU.

The key is read from KMU and decrypted using the Master Key Encryption Key (MKEK).

Parameters:

• key – Buffer to hold the decrypted identity key

Returns:

IDENTITY_KEY_SUCCESS on success, otherwise a negative identity key error code

void identity_key_free(uint8_t key[(32)])

Function to clear out an identity key after usage.

This function will clear out the memory of an identity key. This must be called after the identity key is used to ensure that it is not leaked in the system.

Parameters:

• key – [inout] Key to clear out

int identity_key_write_random(void)

Function to write a random identity key to KMU.

The identity key will be encrypted using the Master Key Encryption Key (MKEK).

Note

This function is generally only used in provisioning of the device and hence is not part of the code running on the end-product.

Returns:

IDENTITY_KEY_SUCCESS on success, otherwise a negative identity key error code

int identity_key_write_key(uint8_t key[(32)])

Function to write a previously generated identity key to the KMU.

The identity key will be encrypted using the Master Key Encryption Key (MKEK).

This function can be used in a scheme where the key is securely provisioned to the device in production.

Note

This function is generally only used in provisioning of the device and hence is not part of the code running on the end-product.

Returns:

IDENTITY_KEY_SUCCESS on success, otherwise a negative identity key error code

int identity_key_write_dummy(void)

Function to write a dummy identity key to KMU.

The identity key will be encrypted using the Master Key Encryption Key (MKEK).

Warning

The dummy identity key is must only be used for debugging and testing purposes. Never use this function in production!

Returns:

IDENTITY_KEY_SUCCESS on success, otherwise a negative identity key error code