boot: Add MCUboot manifest TLV

tomchy · tomchy · commit cf83a56ac275 · 2025-11-13T14:42:38.000+01:00
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 &lt;tomasz.chyrowicz@nordicsemi.no&gt;
diff --git a/boot/bootutil/include/bootutil/image.h b/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
diff --git a/boot/bootutil/include/bootutil/mcuboot_manifest.h b/boot/bootutil/include/bootutil/mcuboot_manifest.h
@@ -0,0 +1,99 @@
+/*
+ *  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[MCUBOOT_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 != MCUBOOT_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, MCUBOOT_IMAGE_NUMBER - 1>, but
+ *                         must not be equal to MCUBOOT_MANIFEST_IMAGE_NUMBER.
+ *
+ * @return true if hash matches with the manifest, false otherwise.
+ */
+static inline bool bootutil_verify_manifest_image_hash(const struct mcuboot_manifest *manifest,
+                                                       const uint8_t *exp_hash, uint32_t image_index)
+{
+    if (!bootutil_verify_manifest(manifest)) {
+        return false;
+    }
+
+    if (image_index >= MCUBOOT_IMAGE_NUMBER) {
+        return false;
+    }
+
+    if (image_index < MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        if (memcmp(exp_hash, manifest->image_hash[image_index], IMAGE_HASH_SIZE) == 0) {
+            return true;
+        }
+    } else if (image_index > MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        if (memcmp(exp_hash, manifest->image_hash[image_index - 1], IMAGE_HASH_SIZE) == 0) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __MCUBOOT_MANIFEST_H__ */
diff --git a/boot/bootutil/src/bootutil_priv.h b/boot/bootutil/src/bootutil_priv.h
@@ -44,6 +44,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
@@ -271,6 +275,14 @@ 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];
+#if defined(MCUBOOT_SWAP_USING_SCRATCH) || defined(MCUBOOT_SWAP_USING_MOVE) || defined(MCUBOOT_SWAP_USING_OFFSET)
+    enum boot_slot matching_manifest[BOOT_IMAGE_NUMBER][BOOT_NUM_SLOTS];
+#endif
+#endif
 };
 
 struct boot_sector_buffer {
diff --git a/boot/bootutil/src/image_validate.c b/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 */
+
 #ifdef MCUBOOT_ENC_IMAGES
 #include "bootutil/enc_key.h"
 #endif
@@ -206,7 +210,7 @@ bootutil_img_validate(struct boot_loader_state *state,
 {
 #if (defined(EXPECTED_KEY_TLV) && defined(MCUBOOT_HW_KEY)) || \
     (defined(EXPECTED_SIG_TLV) && defined(MCUBOOT_BUILTIN_KEY)) || \
-    defined(MCUBOOT_HW_ROLLBACK_PROT) || \
+    defined(MCUBOOT_HW_ROLLBACK_PROT) || defined(MCUBOOT_MANIFEST_UPDATES) || \
     defined(MCUBOOT_UUID_VID) || defined(MCUBOOT_UUID_CID)
     int image_index = (state == NULL ? 0 : BOOT_CURR_IMG(state));
 #endif
@@ -244,6 +248,11 @@ bootutil_img_validate(struct boot_loader_state *state,
     uint32_t img_security_cnt = 0;
     FIH_DECLARE(security_counter_valid, FIH_FAILURE);
 #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);
+#endif
 #ifdef MCUBOOT_UUID_VID
     struct image_uuid img_uuid_vid = {0x00};
     FIH_DECLARE(uuid_vid_valid, FIH_FAILURE);
@@ -357,6 +366,69 @@ bootutil_img_validate(struct boot_loader_state *state,
                 goto out;
             }
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+            if (image_index == MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+                if (!state->manifest_valid[slot]) {
+                    /* Manifest TLV must be processed before any of the image's hash TLV. */
+                    BOOT_LOG_ERR("bootutil_img_validate: image rejected, manifest not found before "
+                        "image %d hash", image_index);
+                    rc = -1;
+                    goto out;
+                }
+                /* Manifest image does not have hash in the manifest. */
+                image_hash_valid = 1;
+                break;
+            }
+#if defined(MCUBOOT_SWAP_USING_SCRATCH) || defined(MCUBOOT_SWAP_USING_MOVE) || \
+    defined(MCUBOOT_SWAP_USING_OFFSET)
+            state->matching_manifest[image_index][slot] = BOOT_SLOT_NONE;
+            /* Try to match with the primary manifest first. */
+            if (state->manifest_valid[BOOT_SLOT_PRIMARY]) {
+                if (bootutil_verify_manifest_image_hash(&state->manifest[BOOT_SLOT_PRIMARY], hash,
+                                                        image_index)) {
+                    state->matching_manifest[image_index][slot] = BOOT_SLOT_PRIMARY;
+                }
+            }
+
+            /* Try to match with the secondary manifest if not matched with the primary. */
+            if(state->matching_manifest[image_index][slot] == BOOT_SLOT_NONE &&
+               state->manifest_valid[BOOT_SLOT_SECONDARY]) {
+                if (bootutil_verify_manifest_image_hash(&state->manifest[BOOT_SLOT_SECONDARY], hash,
+                                                        image_index)) {
+                    state->matching_manifest[image_index][slot] = BOOT_SLOT_SECONDARY;
+                }
+            }
+
+            /* No matching manifest found. */
+            if (state->matching_manifest[image_index][slot] == BOOT_SLOT_NONE) {
+                BOOT_LOG_ERR(
+                    "bootutil_img_validate: image rejected, no valid manifest for image %d slot %d",
+                    image_index, slot);
+                rc = -1;
+                goto out;
+            } else {
+                BOOT_LOG_INF("bootutil_img_validate: image %d slot %d matches manifest in slot %d",
+                             image_index, slot, state->matching_manifest[image_index][slot]);
+            }
+#else /* MCUBOOT_SWAP_USING_SCRATCH || MCUBOOT_SWAP_USING_MOVE || MCUBOOT_SWAP_USING_OFFSET */
+            /* Manifest image for a given slot must precede any of other images. */
+            if (!state->manifest_valid[slot]) {
+                /* Manifest TLV must be processed before any of the image's hash TLV. */
+                BOOT_LOG_ERR("bootutil_img_validate: image rejected, no valid manifest for slot %d",
+                             slot);
+                rc = -1;
+                goto out;
+            }
+
+            /* Any image, not described by the manifest is considered as invalid. */
+            if (!bootutil_verify_manifest_image_hash(&state->manifest[slot], hash, image_index)) {
+                BOOT_LOG_ERR(
+                    "bootutil_img_validate: image rejected, hash does not match manifest contents");
+                FIH_SET(fih_rc, FIH_FAILURE);
+                goto out;
+            }
+#endif /* MCUBOOT_SWAP_USING_SCRATCH || MCUBOOT_SWAP_USING_MOVE || MCUBOOT_SWAP_USING_OFFSET */
+#endif /* MCUBOOT_MANIFEST_UPDATES */
             image_hash_valid = 1;
             break;
         }
@@ -485,6 +557,43 @@ 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)) {
+                BOOT_LOG_ERR(
+                    "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_ERR("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_ERR("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:
         {
@@ -565,6 +674,13 @@ bootutil_img_validate(struct boot_loader_state *state,
     }
 #endif
 
+#ifdef MCUBOOT_MANIFEST_UPDATES
+    if (image_index == MCUBOOT_MANIFEST_IMAGE_NUMBER && (!manifest_found || !manifest_valid)) {
+        BOOT_LOG_ERR("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;
diff --git a/boot/zephyr/Kconfig b/boot/zephyr/Kconfig
@@ -1083,6 +1083,31 @@ config MCUBOOT_HW_DOWNGRADE_PREVENTION_LOCK
 
 endchoice
 
+config MCUBOOT_MANIFEST_UPDATES
+	bool "Enable transactional updates"
+	select EXPERIMENTAL
+	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.
+
+endif # MCUBOOT_MANIFEST_UPDATES
+
 config MCUBOOT_UUID_VID
 	bool "Expect vendor unique identifier in image's TLV"
 	help
diff --git a/boot/zephyr/include/mcuboot_config/mcuboot_config.h b/boot/zephyr/include/mcuboot_config/mcuboot_config.h
@@ -237,6 +237,14 @@
 #define MCUBOOT_HW_ROLLBACK_PROT_LOCK
 #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
diff --git a/docs/design.md b/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
