bl_storage.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef BL_STORAGE_H_
#define BL_STORAGE_H_
 
#include <string.h>
#include <zephyr/types.h>
#include <zephyr/autoconf.h>
#include <nrfx.h>
#if defined(CONFIG_NRFX_NVMC)
#include <nrfx_nvmc.h>
#elif defined(CONFIG_NRFX_RRAMC)
#include <nrfx_rramc.h>
#else
#error "No NRFX storage technology supported backend selected"
#endif
#include <errno.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(CONFIG_NRFX_NVMC)
typedef uint16_t counter_t;
typedef uint16_t lcs_data_t;
typedef uint16_t lcs_reserved_t;
#elif defined(CONFIG_NRFX_RRAMC)
/* nRF54L15 only supports word writes */
typedef uint32_t counter_t;
typedef uint32_t lcs_data_t;
typedef uint32_t lcs_reserved_t;
#endif
 
#define EHASHFF 113 /* A hash contains too many 0xFs. */
#define EREADLCS 114 /* LCS field of OTP is in an invalid state */
#define EINVALIDLCS 115 /* Invalid LCS*/
 
/* We truncate the 32 byte sha256 down to 16 bytes before storing it */
#define SB_PUBLIC_KEY_HASH_LEN 16
 
/* Supported collection types. */
enum collection_type {
        BL_COLLECTION_TYPE_MONOTONIC_COUNTERS = 1,
        BL_COLLECTION_TYPE_VARIABLE_DATA = 0x9312,
};
 
/* Counter used by NSIB to check the firmware version */
#define BL_MONOTONIC_COUNTERS_DESC_NSIB 0x1
 
/* Counter used by MCUBOOT to check the firmware version. Suffixed
 * with ID0 as we might support checking the version of multiple
 * images in the future.
 */
#define BL_MONOTONIC_COUNTERS_DESC_MCUBOOT_ID0 0x2
 
struct life_cycle_state_data {
        lcs_data_t provisioning;
        lcs_data_t secure;
        /* Pad to end the alignment at a 4-byte boundary as some devices
         * are only supporting 4-byte UICR->OTP reads. We place the reserved
         * padding in the middle of the struct in case we ever need to support
         * another state.
         */
        lcs_reserved_t reserved_for_padding;
        lcs_data_t decommissioned;
};
 
struct monotonic_counter {
        /* Counter description. What the counter is used for. See
         * BL_MONOTONIC_COUNTERS_DESC_x.
         */
        uint16_t description;
        /* Number of entries in 'counter_slots' list. */
        uint16_t num_counter_slots;
        counter_t counter_slots[];
};
 
struct collection {
        uint16_t type;
        uint16_t count;
};
 
struct counter_collection {
        struct collection collection;  /* Type must be BL_COLLECTION_TYPE_MONOTONIC_COUNTERS */
        struct monotonic_counter counters[];
};
 
/* Variable data types. */
enum variable_data_type {
        BL_VARIABLE_DATA_TYPE_PSA_CERTIFICATION_REFERENCE = 0x1
};
struct variable_data {
        uint8_t type;
        uint8_t length;
        uint8_t data[];
};
 
/* The third data structure in the provision page. It has unknown length since
 * 'variable_data' is repeated. The collection starts immediately after the
 * counter collection. As the counter collection has unknown length, the start
 * of the variable data collection must be calculated dynamically. Similarly,
 * the entries in the variable data collection have unknown length, so they
 * cannot be accessed through array indices.
 */
struct variable_data_collection {
        struct collection collection; /* Type must be BL_COLLECTION_TYPE_VARIABLE_DATA */
        struct variable_data variable_data[];
};
 
struct bl_storage_data {
        /* NB: When placed in OTP, reads must be 4 bytes and 4 byte aligned */
        struct life_cycle_state_data lcs;
        uint8_t implementation_id[32];
        uint32_t s0_address;
        uint32_t s1_address;
        uint32_t num_public_keys; /* Number of entries in 'key_data' list. */
        struct {
                uint32_t valid;
                uint8_t hash[SB_PUBLIC_KEY_HASH_LEN];
        } key_data[];
 
        /* Monotonic counter collection:
         * uint16_t type;
         * uint16_t count;
         * struct {
         *      uint16_t description;
         *      uint16_t num_counter_slots;
         *      counter_t counter_slots[];
         * } counters[];
         */
 
        /* Variable data collection:
         * uint16_t type;
         * uint16_t count;
         * struct {
         *      uint8_t type;
         *      uint8_t length;
         *      uint8_t data[];
         * } variable_data[];
         * uint8_t padding[];  // Padding to align to 4 bytes
         */
};
 
extern const volatile struct bl_storage_data *const BL_STORAGE;
 
/* This must be 32 bytes according to the IETF PSA token specification */
#define BL_STORAGE_IMPLEMENTATION_ID_SIZE 32
 
uint32_t s0_address_read(void);
 
uint32_t s1_address_read(void);
 
uint32_t num_public_keys_read(void);
 
int verify_public_keys(void);
 
int public_key_data_read(uint32_t key_idx, uint8_t *p_buf);
 
void invalidate_public_key(uint32_t key_idx);
 
int num_monotonic_counter_slots(uint16_t counter_desc, uint16_t *counter_slots);
 
int get_monotonic_counter(uint16_t counter_desc, counter_t *counter_value);
 
int set_monotonic_counter(uint16_t counter_desc, counter_t new_counter);
 
int is_monotonic_counter_update_possible(uint16_t counter_desc);
 
enum bl_storage_lcs {
        BL_STORAGE_LCS_UNKNOWN = 0,
        BL_STORAGE_LCS_ASSEMBLY = 1,
        BL_STORAGE_LCS_PROVISIONING = 2,
        BL_STORAGE_LCS_SECURED = 3,
        BL_STORAGE_LCS_DECOMMISSIONED = 4,
};
 
int read_life_cycle_state(enum bl_storage_lcs *lcs);
 
int update_life_cycle_state(enum bl_storage_lcs next_lcs);
 
void read_implementation_id_from_otp(uint8_t *buf);
 
int read_variable_data(enum variable_data_type data_type, uint8_t *buf, uint32_t *buf_len);
 
#ifdef __cplusplus
}
#endif
 
#endif /* BL_STORAGE_H_ */