hw_unique_key.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef HW_UNIQUE_KEY_H_
#define HW_UNIQUE_KEY_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdbool.h>
 
#if defined(__NRF_TFM__)
#include <autoconf.h>
#endif
#include <zephyr/devicetree.h>
 
#if DT_HAS_COMPAT_STATUS_OKAY(nordic_nrf_kmu) || defined(CONFIG_CRACEN_HW_PRESENT)
#define HUK_HAS_KMU
#endif
#if defined(CONFIG_HAS_HW_NRF_CC310)
#define HUK_HAS_CC310
#endif
#if defined(CONFIG_HAS_HW_NRF_CC312)
#define HUK_HAS_CC312
#endif
 
#if defined(HUK_HAS_CC310)
#define HUK_SIZE_WORDS 4
#elif defined(HUK_HAS_CC312)
#define HUK_SIZE_WORDS 8
#elif defined(CONFIG_CRACEN_HW_PRESENT)
#define HUK_SIZE_WORDS 12
#else
#error "This library requires CryptoCell or Cracen to be available."
#endif
 
#define HUK_SIZE_BYTES (HUK_SIZE_WORDS * 4)
 
#define HW_UNIQUE_KEY_ERR_MISSING               (0x16501)
 
#define HW_UNIQUE_KEY_ERR_WRITE_FAILED          (0x16502)
 
#define HW_UNIQUE_KEY_ERR_GENERATION_FAILED     (0x16503)
 
#define HW_UNIQUE_KEY_ERR_DERIVE_FAILED         (0x16504)
 
#define HW_UNIQUE_KEY_ERR_GENERIC_ERROR         (0x16505)
 
#define HW_UNIQUE_KEY_SUCCESS                   (0x0)
 
/* The available slots. KDR is always available, while the MKEK and MEXT
 * keys are only stored when there is a KMU, since without a key, the key
 * store must be locked after booting, and the KDR is the only key that can
 * live in the CC HW for the entire boot cycle of the device.
 */
enum hw_unique_key_slot {
#ifndef HUK_HAS_KMU
        HUK_KEYSLOT_KDR  = 0, /* Device Root Key */
#else
        HUK_KEYSLOT_MKEK = 2, /* Master Key Encryption Key */
        HUK_KEYSLOT_MEXT = 4, /* Master External Storage Encryption Key */
#endif
};
 
#define KMU_SELECT_SLOT(KEYSLOT) (uint32_t)((KEYSLOT) + 1) /* NRF_KMU KEYSLOT are 1-indexed. */
 
int hw_unique_key_write(enum hw_unique_key_slot key_slot, const uint8_t *key);
 
int hw_unique_key_write_random(void);
 
bool hw_unique_key_is_written(enum hw_unique_key_slot key_slot);
 
bool hw_unique_key_are_any_written(void);
 
int hw_unique_key_load_kdr(void);
 
int hw_unique_key_derive_key(enum hw_unique_key_slot key_slot,
        const uint8_t *context, size_t context_size,
        uint8_t const *label, size_t label_size,
        uint8_t *output, uint32_t output_size);
 
#ifdef __cplusplus
}
#endif
 
#endif /* HW_UNIQUE_KEY_H_ */