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.

ERR_IDENTITY_KEY_MKEK_MISSING

Error value when MKEK is missing from the KMU.

ERR_IDENTITY_KEY_MISSING

Error value when identity key is missing from the KMU.

ERR_IDENTITY_KEY_READ_FAILED

Error value when identity key can’t be read.

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

Zero on success, otherwise a non-zero error code

void 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

A panic-function that does not return will be called on write-failure.

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.

void 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

A panic-function that does not return will be called on write-failure.

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.

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

Note

A panic-function that does not return will be called on write-failure.

Warning

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