boot: Add MCUboot manifest TLV

Add a possibility to attach a basic manifest with expected digests to an
image.
Alter the image verification logic, so only digests specified by the
manifest are allowed on the device.

Signed-off-by: Tomasz Chyrowicz <[email protected]>

Author: tomchy

boot/bootutil/include/bootutil/image.h

@@ -134,6 +134,7 @@ extern "C" {
 #define IMAGE_TLV_COMP_DEC_SIZE     0x73    /* Compressed decrypted image size */
 #define IMAGE_TLV_UUID_VID          0x74    /* Vendor unique identifier */
 #define IMAGE_TLV_UUID_CID          0x75    /* Device class unique identifier */
+#define IMAGE_TLV_MANIFEST          0x76    /* Transaction manifest */
                                             /*
                                              * vendor reserved TLVs at xxA0-xxFF,
                                              * where xx denotes the upper byte

boot/bootutil/include/bootutil/mcuboot_manifest.h

@@ -0,0 +1,96 @@
+/*
+ *  Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef __MCUBOOT_MANIFEST_H__
+#define __MCUBOOT_MANIFEST_H__
+
+/**
+ * @file mcuboot_manifest.h
+ *
+ * @note This file is only used when MCUBOOT_MANIFEST_UPDATES is enabled.
+ */
+
+#include <stdint.h>
+#include "bootutil/bootutil.h"
+#include "bootutil/crypto/sha.h"
+
+#ifndef __packed
+#define __packed __attribute__((__packed__))
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Manifest structure for image updates. */
+struct mcuboot_manifest {
+        uint32_t format;
+        uint32_t image_count;
+        /* Skip a digest of the MCUBOOT_MANIFEST_IMAGE_NUMBER image. */
+        uint8_t image_hash[BOOT_IMAGE_NUMBER - 1][IMAGE_HASH_SIZE];
+} __packed;
+
+/**
+ * @brief Check if the specified manifest has the correct format.
+ *
+ * @param[in] manifest  The reference to the manifest structure.
+ *
+ * @return true on success.
+ */
+static inline bool bootutil_verify_manifest(const struct mcuboot_manifest *manifest)
+{
+    if (manifest == NULL) {
+        return false;
+    }
+
+    /* Currently only the simplest manifest format is supported */
+    if (manifest->format != 0x1) {
+        return false;
+    }
+
+    if (manifest->image_count != BOOT_IMAGE_NUMBER - 1) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * @brief Get the image hash from the manifest.
+ *
+ * @param[in] manifest     The reference to the manifest structure.
+ * @param[in] image_index  The index of the image to get the hash for.
+ *                         Must be in range <0, BOOT_IMAGE_NUMBER - 1>, but
+ *                         must not be equal to MCUBOOT_MANIFEST_IMAGE_NUMBER.
+ *
+ * @return A pointer to the image hash, or NULL if the image_index is out of range
+ *         of allowed values.
+ */
+static inline const uint8_t *bootutil_get_image_hash(const struct mcuboot_manifest *manifest,
+                                                     uint32_t image_index)
+{
+    if (!bootutil_verify_manifest(manifest)) {
+        return NULL;
+    }
+
+    if (image_index >= BOOT_IMAGE_NUMBER) {
+        return NULL;
+    }
+
+    if (image_index < MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        return manifest->image_hash[image_index];
+    } else if (image_index > MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        return manifest->image_hash[image_index - 1];
+    }
+
+    return NULL;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __MCUBOOT_MANIFEST_H__ */

boot/bootutil/src/bootutil_priv.h

@@ -43,6 +43,10 @@
 #include "bootutil/enc_key.h"
 #endif
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+#include "bootutil/mcuboot_manifest.h"
+#endif /* MCUBOOT_MANIFEST_UPDATES */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -287,6 +291,11 @@ struct boot_loader_state {
 #endif
     } slot_usage[BOOT_IMAGE_NUMBER];
 #endif /* MCUBOOT_DIRECT_XIP || MCUBOOT_RAM_LOAD */
+
+#if defined(MCUBOOT_MANIFEST_UPDATES)
+    struct mcuboot_manifest manifest[BOOT_NUM_SLOTS];
+    bool manifest_valid[BOOT_NUM_SLOTS];
+#endif
 };
 
 struct boot_sector_buffer {

boot/bootutil/src/image_validate.c

@@ -50,6 +50,10 @@ BOOT_LOG_MODULE_DECLARE(mcuboot);
 #include "bootutil/mcuboot_uuid.h"
 #endif /* MCUBOOT_UUID_VID || MCUBOOT_UUID_CID */
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+#include "bootutil/mcuboot_manifest.h"
+#endif /* MCUBOOT_MANIFEST_UPDATES */
+
 #if defined(MCUBOOT_DECOMPRESS_IMAGES)
 #include <nrf_compress/implementation.h>
 #include <compression/decompression.h>
@@ -212,7 +216,7 @@ bootutil_img_validate(struct boot_loader_state *state,
 {
 #if (defined(EXPECTED_KEY_TLV) && defined(MCUBOOT_HW_KEY)) || defined(MCUBOOT_HW_ROLLBACK_PROT) \
     || defined(MCUBOOT_UUID_VID) || defined(MCUBOOT_UUID_CID) || defined(MCUBOOT_DECOMPRESS_IMAGES) \
-    || defined(MCUBOOT_BUILTIN_KEY)
+    || defined(MCUBOOT_BUILTIN_KEY) || defined(MCUBOOT_MANIFEST_UPDATES)
     int image_index = (state == NULL ? 0 : BOOT_CURR_IMG(state));
 #endif
     uint32_t off;
@@ -258,6 +262,12 @@ bootutil_img_validate(struct boot_loader_state *state,
         goto out;
     }
 #endif
+#ifdef MCUBOOT_MANIFEST_UPDATES
+    bool manifest_found = false;
+    bool manifest_valid = false;
+    uint8_t slot = (flash_area_get_id(fap) == FLASH_AREA_IMAGE_SECONDARY(image_index) ? 1 : 0);
+    const uint8_t *image_hash = NULL;
+#endif
 #ifdef MCUBOOT_UUID_VID
     struct image_uuid img_uuid_vid = {0x00};
     FIH_DECLARE(uuid_vid_valid, FIH_FAILURE);
@@ -431,6 +441,41 @@ bootutil_img_validate(struct boot_loader_state *state,
                 goto out;
             }
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+            /* If manifest is present, verify that the image hash matches the
+             * one in the manifest.
+             */
+            if (!state->manifest_valid[slot]) {
+                /* Manifest TLV must be processed before any of the image's hash TLV. */
+                BOOT_LOG_INF("bootutil_img_validate: image rejected, no valid manifest for slot %d",
+                             slot);
+                rc = -1;
+                goto out;
+            }
+
+            if (image_index == MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+                /* Manifest image does not have hash in the manifest. */
+                image_hash_valid = 1;
+                break;
+            }
+
+            /* Any image, not described by the manifest is considered as invalid. */
+            image_hash = bootutil_get_image_hash(&state->manifest[slot], image_index);
+            if (image_hash == NULL) {
+                /* Manifest TLV must be processed before any of the image's hash TLV. */
+                BOOT_LOG_INF("bootutil_img_validate: image rejected, no valid manifest for image %d slot %d",
+                             image_index, slot);
+                rc = -1;
+                goto out;
+            }
+
+            FIH_CALL(boot_fih_memequal, fih_rc, hash, image_hash, sizeof(hash));
+            if (FIH_NOT_EQ(fih_rc, FIH_SUCCESS)) {
+                BOOT_LOG_INF("bootutil_img_validate: image rejected, hash does not match manifest contents");
+                FIH_SET(fih_rc, FIH_FAILURE);
+                goto out;
+            }
+#endif
             image_hash_valid = 1;
             break;
         }
@@ -568,6 +613,39 @@ bootutil_img_validate(struct boot_loader_state *state,
             break;
         }
 #endif /* MCUBOOT_HW_ROLLBACK_PROT */
+#ifdef MCUBOOT_MANIFEST_UPDATES
+        case IMAGE_TLV_MANIFEST:
+        {
+            /* There can be only one manifest and must be a part of image with specific index. */
+            if (manifest_found || image_index != MCUBOOT_MANIFEST_IMAGE_NUMBER ||
+                len != sizeof(struct mcuboot_manifest) || state->manifest_valid[slot]) {
+                BOOT_LOG_INF("bootutil_img_validate: image %d slot %d rejected, unexpected manifest TLV",
+                              image_index, slot);
+                rc = -1;
+                goto out;
+            }
+
+            manifest_found = true;
+
+            rc = LOAD_IMAGE_DATA(hdr, fap, off, &state->manifest[slot], sizeof(struct mcuboot_manifest));
+            if (rc) {
+                BOOT_LOG_INF("bootutil_img_validate: slot %d rejected, unable to load manifest", slot);
+                goto out;
+            }
+
+            manifest_valid = bootutil_verify_manifest(&state->manifest[slot]);
+            if (!manifest_valid) {
+                BOOT_LOG_INF("bootutil_img_validate: slot %d rejected, invalid manifest contents", slot);
+                rc = -1;
+                goto out;
+            }
+
+            /* The image's manifest has been successfully verified. */
+            state->manifest_valid[slot] = true;
+            BOOT_LOG_INF("bootutil_img_validate: slot %d manifest verified", slot);
+            break;
+        }
+#endif
 #ifdef MCUBOOT_UUID_VID
         case IMAGE_TLV_UUID_VID:
         {
@@ -654,6 +732,13 @@ bootutil_img_validate(struct boot_loader_state *state,
 skip_security_counter_check:
 #endif
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+    if (image_index == MCUBOOT_MANIFEST_IMAGE_NUMBER && (!manifest_found || !manifest_valid)) {
+        BOOT_LOG_INF("bootutil_img_validate: slot %d rejected, manifest missing or invalid", slot);
+        rc = -1;
+        goto out;
+    }
+#endif
 #ifdef MCUBOOT_UUID_VID
     if (FIH_NOT_EQ(uuid_vid_valid, FIH_SUCCESS)) {
         rc = -1;

boot/zephyr/Kconfig

@@ -1159,6 +1159,34 @@ config MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_LIMITED
 
 endchoice
 
+config MCUBOOT_MANIFEST_UPDATES
+	bool "Enable transactional updates"
+	imply LOAD_AND_VALIDATE_IMAGES_HOOKS
+	help
+	  If y, enables support for transactional updates using manifests.
+	  This allows multiple images to be updated atomically. The manifest
+	  is a separate TLV which contains a list of images to update and
+	  their expected hash values. The manifest TLV is a part of an image
+	  that is signed to prevent tampering.
+	  The manifest must be transferred as part of the image with index 0.
+	  It can be a dedicated image, or part of an existing image.
+	  If the second option is selected, all updates must contain an update
+	  for image 0.
+
+if MCUBOOT_MANIFEST_UPDATES
+
+config MCUBOOT_MANIFEST_IMAGE_NUMBER
+	int "Number of image that must include manifest"
+	default 0
+	range 0 UPDATEABLE_IMAGE_NUMBER
+	help
+	  Specifies the index of the image that must include the manifest.
+	  If MCUBOOT_MANIFEST_USE_DEDICATED_IMAGE is selected, this index
+	  specifies the index of the dedicated image that contains only
+	  the manifest.
+
+endif # MCUBOOT_MANIFEST_UPDATES
+
 config MCUBOOT_UUID_VID
 	bool "Expect vendor unique identifier in image's TLV"
 	help

boot/zephyr/include/mcuboot_config/mcuboot_config.h

@@ -243,6 +243,14 @@
 #define MCUBOOT_HW_ROLLBACK_PROT_COUNTER_LIMITED
 #endif
 
+#ifdef CONFIG_MCUBOOT_MANIFEST_UPDATES
+#define MCUBOOT_MANIFEST_UPDATES
+
+#ifdef CONFIG_MCUBOOT_MANIFEST_IMAGE_NUMBER
+#define MCUBOOT_MANIFEST_IMAGE_NUMBER CONFIG_MCUBOOT_MANIFEST_IMAGE_NUMBER
+#endif /* CONFIG_MCUBOOT_MANIFEST_IMAGE_NUMBER */
+#endif /* CONFIG_MCUBOOT_MANIFEST_UPDATES */
+
 #ifdef CONFIG_MCUBOOT_UUID_VID
 #define MCUBOOT_UUID_VID
 #endif

docs/design.md

@@ -150,8 +150,9 @@ struct image_tlv {
                                              * ...
                                              * 0xffa0 - 0xfffe
                                              */
-#define IMAGE_TLV_UUID_VID          0x80    /* Vendor unique identifier */
-#define IMAGE_TLV_UUID_CID          0x81    /* Device class unique identifier */
+#define IMAGE_TLV_UUID_VID          0x74    /* Vendor unique identifier */
+#define IMAGE_TLV_UUID_CID          0x75    /* Device class unique identifier */
+#define IMAGE_TLV_MANIFEST          0x76    /* Transaction manifest */
 ```
 
 Optional type-length-value records (TLVs) containing image metadata are placed