Add identity key support for PSA attestation

CODEOWNERS

@@ -108,6 +108,7 @@ Kconfig*                                  @tejlmand
 /lib/date_time/                           @trantanen @tokangas
 /lib/wave_gen/                            @MarekPieta
 /lib/hw_unique_key/                       @oyvindronningstad @Vge0rge
+/lib/identity_key/                        @frkv @Vge0rge
 /lib/modem_jwt/                           @jayteemo @SeppoTakalo
 /lib/modem_attest_token/                  @jayteemo
 /lib/qos/                                 @simensrostad
@@ -131,6 +132,8 @@ Kconfig*                                  @tejlmand
 /samples/event_manager_proxy/             @rakons
 /samples/gazell/                          @leewkb4567
 /samples/keys/random_hw_unique_key/       @oyvindronningstad @Vge0rge
+/samples/keys/identity_key_generation/    @frkv @Vge0rge
+/samples/keys/identity_key_usage/         @frkv @Vge0rge
 /samples/mpsl/                            @rugeGerritsen
 /samples/nfc/                             @grochu
 /samples/nrf_rpc/                         @doki-nordic @KAGA164

doc/nrf/libraries/others/identity_key.rst

@@ -0,0 +1,45 @@
+.. _lib_identity_key:
+
+Identity key
+############
+
+.. contents::
+   :local:
+   :depth: 2
+
+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 the secure domain.
+It is not supported from non-secure images, 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: :file:`include/identity_key.h`
+| Source files: :file:`modules/lib/identity_key/`
+
+.. doxygengroup:: identity_key
+   :project: nrf
+   :members:

doc/nrf/releases/release-notes-changelog.rst

@@ -530,6 +530,10 @@ Other samples
 
   * Added :ref:`configuration<sensor_stub_config>` for the Sensor stub driver.
 
+* Added :ref:`identity_key_generate` sample to show generation of an identity key that is stored in the Key Management Unit (KMU).
+
+* Added :ref:`identity_key_usage` sample to show how to make use of a Key Management Unit (KMU) stored identity key.
+
 Devicetree configuration
 ========================
 
@@ -779,6 +783,7 @@ Other libraries
 * Added:
 
   * :ref:`nrf_rpc_ipc_readme` library.
+  * :ref:`lib_identity_key` library.
 
 * :ref:`lib_flash_patch` library:
 
@@ -917,6 +922,10 @@ Release notes for 0.5.0 and 0.5.1 can be found in :file:`ncs/nrf/modules/lib/zcb
 Trusted Firmware-M
 ==================
 
+* Added:
+
+  * Added support for an identity key that can be used as a PSA attestation key
+
 * Fixed:
 
   * |no_changes_yet_note|

include/identity_key.h

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef IDENTITY_KEY_H_
+#define IDENTITY_KEY_H_
+
+#include <stdint.h>
+
+/**
+ * @file
+ * @defgroup identity_key Identity key APIs
+ * @{
+ *
+ * @brief API for identity key on CryptoCell devices with KMU
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Identity key size in bytes, corresponding to ECC secp256r1 */
+#define IDENTITY_KEY_SIZE_BYTES                 (32)
+
+/** @brief Error value when MKEK is missing from the KMU */
+#define ERR_IDENTITY_KEY_MKEK_MISSING           (0x15501)
+
+/** @brief Error value when identity key is missing from the KMU */
+#define ERR_IDENTITY_KEY_MISSING                (0x15502)
+
+/** @brief Error value when identity key can't be read */
+#define ERR_IDENTITY_KEY_READ_FAILED            (0x15503)
+
+/**
+ * @brief Function to check that the MKEK is present
+ *
+ * MKEK is a prerequisite to encrypt and decrypt the identity key.
+ *
+ * @return true if MKEK is written, otherwise false
+ */
+bool identity_key_mkek_is_written(void);
+
+/**
+ * @brief Function to check if identity key is written
+ *
+ * @return true if the identity key is written, otherwise false
+ */
+bool identity_key_is_written(void);
+
+/**
+ * @brief Function to read the identity key from KMU
+ *
+ * @details The key is read from KMU and decrypted using
+ *          the Master Key Encryption Key (MKEK).
+ *
+ * @param key   Buffer to hold the decrypted identity key
+ *
+ * @return Zero on success, otherwise a non-zero error code
+ */
+int identity_key_read(uint8_t key[IDENTITY_KEY_SIZE_BYTES]);
+
+/**
+ * @brief 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_random(void);
+
+/**
+ * @brief 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_key(uint8_t key[IDENTITY_KEY_SIZE_BYTES]);
+
+/**
+ * @brief 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!
+ *
+ * @note A panic-function that does not return will be called on write-failure.
+ */
+void identity_key_write_dummy(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* IDENTITY_KEY_H_ */

lib/CMakeLists.txt

@@ -36,3 +36,4 @@ add_subdirectory_ifdef(CONFIG_LOCATION location)
 add_subdirectory_ifdef(CONFIG_AT_SHELL at_shell)
 add_subdirectory_ifdef(CONFIG_MODEM_ANTENNA modem_antenna)
 add_subdirectory_ifdef(CONFIG_QOS qos)
+add_subdirectory_ifdef(CONFIG_IDENTITY_KEY identity_key)

lib/Kconfig

@@ -37,5 +37,6 @@ rsource "location/Kconfig"
 rsource "at_shell/Kconfig"
 rsource "modem_antenna/Kconfig"
 rsource "qos/Kconfig"
+rsource "identity_key/Kconfig"
 
 endmenu

lib/identity_key/CMakeLists.txt

@@ -0,0 +1,17 @@
+#
+# Copyright (c) 2022 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+zephyr_library()
+
+zephyr_library_sources(identity_key.c)
+
+if (CONFIG_IDENTITY_KEY_DUMMY)
+  message(WARNING "
+      ----------------------------------------------------------
+      --- WARNING: A dummy identity key will be written to   ---
+      --- the KMU. DO NOT USE THIS KEY IN PRODUCTION!        ---
+      ----------------------------------------------------------")
+endif()

lib/identity_key/Kconfig

@@ -0,0 +1,28 @@
+#
+# Copyright (c) 2022 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+menuconfig IDENTITY_KEY
+	bool "Identity key support"
+	depends on NRF_CC3XX_PLATFORM
+	depends on NRF_SECURITY
+	depends on !TRUSTED_EXECUTION_NONSECURE
+	depends on MAIN_STACK_SIZE >= 2048
+	depends on ASSERT
+	help
+	  This option adds support for an identity key stored in the KMU.
+	  The key is stored in an encrypted form and is decrypted
+	  by the identity key APIs.
+
+if IDENTITY_KEY
+
+config IDENTITY_KEY_DUMMY
+	bool "Write a dummy identity key (not for production)"
+	help
+	  This option adds support for writing a dummy identity key in an encrypted
+	  form in the KMU. This option should only be enabled for debugging and
+	  testing purposes.
+
+endif # IDENTITY_KEY