1<!-- 2 - SPDX-License-Identifier: Apache-2.0 3 4 - Copyright (c) 2017-2020 Linaro LTD 5 - Copyright (c) 2017-2019 JUUL Labs 6 - Copyright (c) 2019-2024 Arm Limited 7 8 - Original license: 9 10 - Licensed to the Apache Software Foundation (ASF) under one 11 - or more contributor license agreements. See the NOTICE file 12 - distributed with this work for additional information 13 - regarding copyright ownership. The ASF licenses this file 14 - to you under the Apache License, Version 2.0 (the 15 - "License"); you may not use this file except in compliance 16 - with the License. You may obtain a copy of the License at 17 18 - http://www.apache.org/licenses/LICENSE-2.0 19 20 - Unless required by applicable law or agreed to in writing, 21 - software distributed under the License is distributed on an 22 - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 23 - KIND, either express or implied. See the License for the 24 - specific language governing permissions and limitations 25 - under the License. 26--> 27 28# Bootloader 29 30## [Summary](#summary) 31 32MCUboot comprises two packages: 33 34* The bootutil library (boot/bootutil) 35* The boot application (each port has its own at boot/<port>) 36 37The bootutil library performs most of the functions of a bootloader. In 38particular, the piece that is missing is the final step of actually jumping to 39the main image. This last step is instead implemented by the boot application. 40Bootloader functionality is separated in this manner to enable unit testing of 41the bootloader. A library can be unit tested, but an application can't. 42Therefore, functionality is delegated to the bootutil library when possible. 43 44## [Limitations](#limitations) 45 46The bootloader currently only supports images with the following 47characteristics: 48* Built to run from flash. 49* Built to run from a fixed location (i.e., not position-independent). 50 51## [Image format](#image-format) 52 53The following definitions describe the image format. 54 55``` c 56#define IMAGE_MAGIC 0x96f3b83d 57 58#define IMAGE_HEADER_SIZE 32 59 60struct image_version { 61 uint8_t iv_major; 62 uint8_t iv_minor; 63 uint16_t iv_revision; 64 uint32_t iv_build_num; 65}; 66 67/** Image header. All fields are in little endian byte order. */ 68struct image_header { 69 uint32_t ih_magic; 70 uint32_t ih_load_addr; 71 uint16_t ih_hdr_size; /* Size of image header (bytes). */ 72 uint16_t ih_protect_tlv_size; /* Size of protected TLV area (bytes). */ 73 uint32_t ih_img_size; /* Does not include header. */ 74 uint32_t ih_flags; /* IMAGE_F_[...]. */ 75 struct image_version ih_ver; 76 uint32_t _pad1; 77}; 78 79#define IMAGE_TLV_INFO_MAGIC 0x6907 80#define IMAGE_TLV_PROT_INFO_MAGIC 0x6908 81 82/** Image TLV header. All fields in little endian. */ 83struct image_tlv_info { 84 uint16_t it_magic; 85 uint16_t it_tlv_tot; /* size of TLV area (including tlv_info header) */ 86}; 87 88/** Image trailer TLV format. All fields in little endian. */ 89struct image_tlv { 90 uint8_t it_type; /* IMAGE_TLV_[...]. */ 91 uint8_t _pad; 92 uint16_t it_len; /* Data length (not including TLV header). */ 93}; 94 95/* 96 * Image header flags. 97 */ 98#define IMAGE_F_PIC 0x00000001 /* Not supported. */ 99#define IMAGE_F_ENCRYPTED_AES128 0x00000004 /* Encrypted using AES128. */ 100#define IMAGE_F_ENCRYPTED_AES256 0x00000008 /* Encrypted using AES256. */ 101#define IMAGE_F_NON_BOOTABLE 0x00000010 /* Split image app. */ 102#define IMAGE_F_RAM_LOAD 0x00000020 103 104/* 105 * Image trailer TLV types. 106 */ 107#define IMAGE_TLV_KEYHASH 0x01 /* hash of the public key */ 108#define IMAGE_TLV_SHA256 0x10 /* SHA256 of image hdr and body */ 109#define IMAGE_TLV_RSA2048_PSS 0x20 /* RSA2048 of hash output */ 110#define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output - Not supported anymore */ 111#define IMAGE_TLV_ECDSA_SIG 0x22 /* ECDSA of hash output */ 112#define IMAGE_TLV_RSA3072_PSS 0x23 /* RSA3072 of hash output */ 113#define IMAGE_TLV_ED25519 0x24 /* ED25519 of hash output */ 114#define IMAGE_TLV_ENC_RSA2048 0x30 /* Key encrypted with RSA-OAEP-2048 */ 115#define IMAGE_TLV_ENC_KW 0x31 /* Key encrypted with AES-KW-128 or 116 256 */ 117#define IMAGE_TLV_ENC_EC256 0x32 /* Key encrypted with ECIES-P256 */ 118#define IMAGE_TLV_ENC_X25519 0x33 /* Key encrypted with ECIES-X25519 */ 119#define IMAGE_TLV_DEPENDENCY 0x40 /* Image depends on other image */ 120#define IMAGE_TLV_SEC_CNT 0x50 /* security counter */ 121``` 122 123Optional type-length-value records (TLVs) containing image metadata are placed 124after the end of the image. 125 126The `ih_protect_tlv_size` field indicates the length of the protected TLV area. 127If protected TLVs are present then a TLV info header with magic equal to 128`IMAGE_TLV_PROT_INFO_MAGIC` must be present and the protected TLVs (plus the 129info header itself) have to be included in the hash calculation. Otherwise the 130hash is only calculated over the image header and the image itself. In this 131case the value of the `ih_protect_tlv_size` field is 0. 132 133The `ih_hdr_size` field indicates the length of the header, and therefore the 134offset of the image itself. This field provides for backwards compatibility in 135case of changes to the format of the image header. 136 137## [Flash map](#flash-map) 138 139A device's flash is partitioned according to its _flash map_. At a high 140level, the flash map maps numeric IDs to _flash areas_. A flash area is a 141region of disk with the following properties: 1421. An area can be fully erased without affecting any other areas. 1432. A write to one area does not restrict writes to other areas. 144 145The bootloader uses the following flash area IDs: 146```c 147/* Independent from multiple image boot */ 148#define FLASH_AREA_BOOTLOADER 0 149#define FLASH_AREA_IMAGE_SCRATCH 3 150``` 151```c 152/* If the bootloader is working with the first image */ 153#define FLASH_AREA_IMAGE_PRIMARY 1 154#define FLASH_AREA_IMAGE_SECONDARY 2 155``` 156```c 157/* If the bootloader is working with the second image */ 158#define FLASH_AREA_IMAGE_PRIMARY 5 159#define FLASH_AREA_IMAGE_SECONDARY 6 160``` 161 162The bootloader area contains the bootloader image itself. The other areas are 163described in subsequent sections. The flash could contain multiple executable 164images therefore the flash area IDs of primary and secondary areas are mapped 165based on the number of the active image (on which the bootloader is currently 166working). 167 168## [Image slots](#image-slots) 169 170A portion of the flash memory can be partitioned into multiple image areas, each 171contains two image slots: a primary slot and a secondary slot. 172Normally, the bootloader will only run an image from the primary slot, so 173images must be built such that they can run from that fixed location in flash 174(the exception to this is the [direct-xip](#direct-xip) and the 175[ram-load](#ram-load) upgrade mode). If the bootloader needs to run the 176image resident in the secondary slot, it must copy its contents into the primary 177slot before doing so, either by swapping the two images or by overwriting the 178contents of the primary slot. The bootloader supports either swap- or 179overwrite-based image upgrades, but must be configured at build time to choose 180one of these two strategies. 181 182### [Swap using scratch](#image-swap-using-scratch) 183 184When swap-using-scratch algorithm is used, in addition to the slots of 185image areas, the bootloader requires a scratch area to allow for reliable 186image swapping. The scratch area must have a size 187that is enough to store at least the largest sector that is going to be swapped. 188Many devices have small equally sized flash sectors, eg 4K, while others have 189variable sized sectors where the largest sectors might be 128K or 256K, so the 190scratch must be big enough to store that. The scratch is only ever used when 191swapping firmware, which means only when doing an upgrade. Given that, the main 192reason for using a larger size for the scratch is that flash wear will be more 193evenly distributed, because a single sector would be written twice the number of 194times than using two sectors, for example. To evaluate the ideal size of the 195scratch for your use case the following parameters are relevant: 196 197* the ratio of image size / scratch size 198* the number of erase cycles supported by the flash hardware 199 200The image size is used (instead of slot size) because only the slot's sectors 201that are actually used for storing the image are copied. The image/scratch ratio 202is the number of times the scratch will be erased on every upgrade. The number 203of erase cycles divided by the image/scratch ratio will give you the number of 204times an upgrade can be performed before the device goes out of spec. 205 206``` 207num_upgrades = number_of_erase_cycles / (image_size / scratch_size) 208``` 209 210Let's assume, for example, a device with 10000 erase cycles, an image size of 211150K and a scratch of 4K (usual minimum size of 4K sector devices). This would 212result in a total of: 213 214`10000 / (150 / 4) ~ 267` 215 216Increasing the scratch to 16K would give us: 217 218`10000 / (150 / 16) ~ 1067` 219 220There is no *best* ratio, as the right size is use-case dependent. Factors to 221consider include the number of times a device will be upgraded both in the field 222and during development, as well as any desired safety margin on the 223manufacturer's specified number of erase cycles. In general, using a ratio that 224allows hundreds to thousands of field upgrades in production is recommended. 225 226swap-using scratch algorithm assumes that the primary and the secondary image 227slot areas sizes are equal. 228The maximum image size available for the application 229will be: 230``` 231maximum-image-size = image-slot-size - image-trailer-size 232``` 233 234Where: 235 `image-slot-size` is the size of the image slot. 236 `image-trailer-size` is the size of the image trailer. 237 238### [Swap without using scratch](#image-swap-no-scratch) 239 240This algorithm is an alternative to the swap-using-scratch algorithm. 241It uses an additional sector in the primary slot to make swap possible. 242The algorithm works as follows: 243 244 1. Moves all sectors of the primary slot up by one sector. 245 Beginning from N=0: 246 2. Copies the N-th sector from the secondary slot to the N-th sector of the 247 primary slot. 248 3. Copies the (N+1)-th sector from the primary slot to the N-th sector of the 249 secondary slot. 250 4. Repeats steps 2. and 3. until all the slots' sectors are swapped. 251 252This algorithm is designed so that the higher sector of the primary slot is 253used only for allowing sectors to move up. Therefore the most 254memory-size-effective slot layout is when the primary slot is exactly one sector 255larger than the secondary slot, although same-sized slots are allowed as well. 256The algorithm is limited to support sectors of the same 257sector layout. All slot's sectors should be of the same size. 258 259When using this algorithm the maximum image size available for the application 260will be: 261``` 262maximum-image-size = (N-1) * slot-sector-size - image-trailer-sectors-size 263``` 264 265Where: 266 `N` is the number of sectors in the primary slot. 267 `image-trailer-sectors-size` is the size of the image trailer rounded up to 268 the total size of sectors its occupied. For instance if the image-trailer-size 269 is equal to 1056 B and the sector size is equal to 1024 B, then 270 `image-trailer-sectors-size` will be equal to 2048 B. 271 272The algorithm does two erase cycles on the primary slot and one on the secondary 273slot during each swap. Assuming that receiving a new image by the DFU 274application requires 1 erase cycle on the secondary slot, this should result in 275leveling the flash wear between the slots. 276 277The algorithm is enabled using the `MCUBOOT_SWAP_USING_MOVE` option. 278 279### [Equal slots (direct-xip)](#direct-xip) 280 281When the direct-xip mode is enabled the active image flag is "moved" between the 282slots during image upgrade and in contrast to the above, the bootloader can 283run an image directly from either the primary or the secondary slot (without 284having to move/copy it into the primary slot). Therefore the image update 285client, which downloads the new images must be aware, which slot contains the 286active image and which acts as a staging area and it is responsible for loading 287the proper images into the proper slot. All this requires that the images be 288built to be executed from the corresponding slot. At boot time the bootloader 289first looks for images in the slots and then inspects the version numbers in the 290image headers. It selects the newest image (with the highest version number) and 291then checks its validity (integrity check, signature verification etc.). If the 292image is invalid MCUboot erases its memory slot and starts to validate the other 293image. After a successful validation of the selected image the bootloader 294chain-loads it. 295 296An additional "revert" mechanism is also supported. For more information, please 297read the [corresponding section](#direct-xip-revert). 298Handling the primary and secondary slots as equals has its drawbacks. Since the 299images are not moved between the slots, the on-the-fly image 300encryption/decryption can't be supported (it only applies to storing the image 301in an external flash on the device, the transport of encrypted image data is 302still feasible). 303 304The overwrite and the direct-xip upgrade strategies are substantially simpler to 305implement than the image swapping strategy, especially since the bootloader must 306work properly even when it is reset during the middle of an image swap. For this 307reason, the rest of the document describes its behavior when configured to swap 308images during an upgrade. 309 310### [RAM loading](#ram-load) 311 312In ram-load mode the slots are equal. Like the direct-xip mode, this mode 313also selects the newest image by reading the image version numbers in the image 314headers. But instead of executing it in place, the newest image is copied to the 315RAM for execution. The load address, the location in RAM where the image is 316copied to, is stored in the image header. The ram-load upgrade mode can be 317useful when there is no internal flash in the SoC, but there is a big enough 318internal RAM to hold the images. Usually in this case the images are stored 319in an external storage device. Execution from external storage has some 320drawbacks (lower execution speed, image is exposed to attacks) therefore the 321image is always copied to the internal RAM before the authentication and 322execution. Ram-load mode requires the image to be built to be executed from 323the RAM address range instead of the storage device address range. If 324ram-load is enabled then platform must define the following parameters: 325 326```c 327#define IMAGE_EXECUTABLE_RAM_START <area_base_addr> 328#define IMAGE_EXECUTABLE_RAM_SIZE <area_size_in_bytes> 329``` 330 331For multiple image load if multiple ram regions are used platform must define 332the `MULTIPLE_EXECUTABLE_RAM_REGIONS` flag instead and implement the following 333function: 334 335```c 336int boot_get_image_exec_ram_info(uint32_t image_id, 337 uint32_t *exec_ram_start, 338 uint32_t *exec_ram_size) 339``` 340 341When ram-load is enabled, the `--load-addr <addr>` option of the `imgtool` 342script must also be used when signing the images. This option set the `RAM_LOAD` 343flag in the image header which indicates that the image should be loaded to the 344RAM and also set the load address in the image header. 345 346When the encryption option is enabled (`MCUBOOT_ENC_IMAGES`) along with ram-load 347the image is checked for encryption. If the image is not encrypted, RAM loading 348happens as described above. If the image is encrypted, it is copied in RAM at 349the provided address and then decrypted. Finally, the decrypted image is 350authenticated in RAM and executed. 351 352## [Boot swap types](#boot-swap-types) 353 354When the device first boots under normal circumstances, there is an up-to-date 355firmware image in each primary slot, which MCUboot can validate and then 356chain-load. In this case, no image swaps are necessary. During device upgrades, 357however, new candidate image(s) is present in the secondary slot(s), which 358MCUboot must swap into the primary slot(s) before booting as discussed above. 359 360Upgrading an old image with a new one by swapping can be a two-step process. In 361this process, MCUboot performs a "test" swap of image data in flash and boots 362the new image or it will be executed during operation. The new image can then 363update the contents of flash at runtime to mark itself "OK", and MCUboot will 364then still choose to run it during the next boot. When this happens, the swap is 365made "permanent". If this doesn't happen, MCUboot will perform a "revert" swap 366during the next boot by swapping the image(s) back into its original location(s) 367, and attempting to boot the old image(s). 368 369Depending on the use case, the first swap can also be made permanent directly. 370In this case, MCUboot will never attempt to revert the images on the next reset. 371 372Test swaps are supported to provide a rollback mechanism to prevent devices 373from becoming "bricked" by bad firmware. If the device crashes immediately 374upon booting a new (bad) image, MCUboot will revert to the old (working) image 375at the next device reset, rather than booting the bad image again. This allows 376device firmware to make test swaps permanent only after performing a self-test 377routine. 378 379On startup, MCUboot inspects the contents of flash to decide for each images 380which of these "swap types" to perform; this decision determines how it 381proceeds. 382 383The possible swap types, and their meanings, are: 384 385- `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the 386 contents of the primary slot. 387 388- `BOOT_SWAP_TYPE_TEST`: Boot the contents of the secondary slot by swapping 389 images. Unless the swap is made permanent, revert back on the next boot. 390 391- `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image 392 firmware. 393 394- `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent; 395 swap back to the old image whose data are now in the secondary slot. If the 396 old image marks itself "OK" when it boots, the next boot will have swap type 397 `BOOT_SWAP_TYPE_NONE`. 398 399- `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid. 400 401- `BOOT_SWAP_TYPE_PANIC`: Swapping encountered an unrecoverable error. 402 403The "swap type" is a high-level representation of the outcome of the 404boot. Subsequent sections describe how MCUboot determines the swap type from 405the bit-level contents of flash. 406 407### [Revert mechanism in direct-xip mode](#direct-xip-revert) 408 409The direct-xip mode also supports a "revert" mechanism which is the equivalent 410of the swap mode's "revert" swap. When the direct-xip mode is selected it can be 411enabled with the MCUBOOT_DIRECT_XIP_REVERT config option and an image trailer 412must also be added to the signed images (the "--pad" option of the `imgtool` 413script must be used). For more information on this please read the 414[Image Trailer](#image-trailer) section and the [imgtool](imgtool.md) 415documentation. Making the images permanent (marking them as confirmed in 416advance) is also supported just like in swap mode. The individual steps of the 417direct-xip mode's "revert" mechanism are the following: 418 4191. Select the slot which holds the newest potential image. 4202. Was the image previously selected to run (during a previous boot)? 421 + Yes: Did the image mark itself "OK" (was the self-test successful)? 422 + Yes. 423 - Proceed to step 3. 424 + No. 425 - Erase the image from the slot to prevent it from being selected 426 again during the next boot. 427 - Return to step 1 (the bootloader will attempt to select and 428 possibly boot the previous image if there is one). 429 + No. 430 - Mark the image as "selected" (set the copy_done flag in the trailer). 431 - Proceed to step 3. 4323. Proceed to image validation ... 433 434## [Image trailer](#image-trailer) 435 436For the bootloader to be able to determine the current state and what actions 437should be taken during the current boot operation, it uses metadata stored in 438the image flash areas. While swapping, some of this metadata is temporarily 439copied into and out of the scratch area. 440 441This metadata is located at the end of the image flash areas, and is called an 442image trailer. An image trailer has the following structure: 443 444``` 445 0 1 2 3 446 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 448 ~ ~ 449 ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~ 450 ~ ~ 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 452 | Encryption key 0 (16 octets) [*] | 453 | | 454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 455 | 0xff padding as needed | 456 | (BOOT_MAX_ALIGN minus 16 octets from Encryption key 0) [*] | 457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 458 | Encryption key 1 (16 octets) [*] | 459 | | 460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 461 | 0xff padding as needed | 462 | (BOOT_MAX_ALIGN minus 16 octets from Encryption key 1) [*] | 463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 464 | Swap size (4 octets) | 465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 466 | 0xff padding as needed | 467 | (BOOT_MAX_ALIGN minus 4 octets from Swap size) | 468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 469 | Swap info | 0xff padding (BOOT_MAX_ALIGN minus 1 octet) | 470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 471 | Copy done | 0xff padding (BOOT_MAX_ALIGN minus 1 octet) | 472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 473 | Image OK | 0xff padding (BOOT_MAX_ALIGN minus 1 octet) | 474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 475 | 0xff padding as needed | 476 | (BOOT_MAX_ALIGN minus 16 octets from MAGIC) | 477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 478 | MAGIC (16 octets) | 479 | | 480 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 481``` 482 483[*]: Only present if the encryption option is enabled (`MCUBOOT_ENC_IMAGES`). 484 485The offset immediately following such a record represents the start of the next 486flash area. 487 488--- 489***Note*** 490 491*"min-write-size" is a property of the flash hardware. If the hardware* 492*allows individual bytes to be written at arbitrary addresses, then* 493*min-write-size is 1. If the hardware only allows writes at even addresses,* 494*then min-write-size is 2, and so on.* 495 496--- 497 498An image trailer contains the following fields: 499 5001. Swap status: A series of records which records the progress of an image 501 swap. To swap entire images, data are swapped between the two image areas 502 one or more sectors at a time, like this: 503 504 - sector data in the primary slot is copied into scratch, then erased 505 - sector data in the secondary slot is copied into the primary slot, 506 then erased 507 - sector data in scratch is copied into the secondary slot 508 509As it swaps images, the bootloader updates the swap status field in a way that 510allows it to compute how far this swap operation has progressed for each 511sector. The swap status field can thus used to resume a swap operation if the 512bootloader is halted while a swap operation is ongoing and later reset. The 513`BOOT_MAX_IMG_SECTORS` value is the configurable maximum number of sectors 514MCUboot supports for each image; its value defaults to 128, but allows for 515either decreasing this size, to limit RAM usage, or to increase it in devices 516that have massive amounts of Flash or very small sized sectors and thus require 517a bigger configuration to allow for the handling of all slot's sectors. 518The factor of min-write-size is due to the behavior of flash hardware. The factor 519of 3 is explained below. 520 5212. Encryption keys: key-encrypting keys (KEKs). These keys are needed for 522 image encryption and decryption. See the 523 [encrypted images](encrypted_images.md) document for more information. 524 5253. Swap size: When beginning a new swap operation, the total size that needs 526 to be swapped (based on the slot with largest image + TLVs) is written to 527 this location for easier recovery in case of a reset while performing the 528 swap. 529 5304. Swap info: A single byte which encodes the following information: 531 - Swap type: Stored in bits 0-3. Indicating the type of swap operation in 532 progress. When MCUboot resumes an interrupted swap, it uses this field to 533 determine the type of operation to perform. This field contains one of the 534 following values in the table below. 535 - Image number: Stored in bits 4-7. It has always 0 value at single image 536 boot. In case of multi image boot it indicates, which image was swapped when 537 interrupt happened. The same scratch area is used during in case of all 538 image swap operation. Therefore this field is used to determine which image 539 the trailer belongs to if boot status is found on scratch area when the swap 540 operation is resumed. 541 542| Name | Value | 543| ------------------------- | ----- | 544| `BOOT_SWAP_TYPE_TEST` | 2 | 545| `BOOT_SWAP_TYPE_PERM` | 3 | 546| `BOOT_SWAP_TYPE_REVERT` | 4 | 547 548 5495. Copy done: A single byte indicating whether the image in this slot is 550 complete (0x01=done; 0xff=not done). 551 5526. Image OK: A single byte indicating whether the image in this slot has been 553 confirmed as good by the user (0x01=confirmed; 0xff=not confirmed). 554 5557. MAGIC: A 16-byte field identifying the image trailer layout. It may assume 556 distinct values depending on the maximum supported write alignment 557 (`BOOT_MAX_ALIGN`) of the image, as defined by the following construct: 558 559``` c 560union boot_img_magic_t 561{ 562 struct { 563 uint16_t align; 564 uint8_t magic[14]; 565 }; 566 uint8_t val[16]; 567}; 568``` 569 If `BOOT_MAX_ALIGN` is **8 bytes**, then MAGIC contains the following 16 bytes: 570 571``` c 572const union boot_img_magic_t boot_img_magic = { 573 .val = { 574 0x77, 0xc2, 0x95, 0xf3, 575 0x60, 0xd2, 0xef, 0x7f, 576 0x35, 0x52, 0x50, 0x0f, 577 0x2c, 0xb6, 0x79, 0x80 578 } 579}; 580``` 581 582 In case `BOOT_MAX_ALIGN` is defined to any value different than **8**, then the maximum 583 supported write alignment value is encoded in the MAGIC field, followed by a fixed 584 14-byte pattern: 585 586``` c 587const union boot_img_magic_t boot_img_magic = { 588 .align = BOOT_MAX_ALIGN, 589 .magic = { 590 0x2d, 0xe1, 591 0x5d, 0x29, 0x41, 0x0b, 592 0x8d, 0x77, 0x67, 0x9c, 593 0x11, 0x0f, 0x1f, 0x8a 594 } 595}; 596``` 597 598--- 599***Note*** 600Be aware that the image trailers make the ending area of the image slot 601unavailable for carrying the image data. In particular, the swap status size 602could be huge. For example, for 128 slot sectors with a 4-byte alignment, 603it would become 1536 B. 604 605--- 606 607## [Image trailers](#image-trailers) 608 609At startup, the bootloader determines the boot swap type by inspecting the 610image trailers. When using the term "image trailers" what is meant is the 611aggregate information provided by both image slot's trailers. 612 613### [New swaps (non-resumes)](#new-swaps-non-resumes) 614 615For new swaps, MCUboot must inspect a collection of fields to determine which 616swap operation to perform. 617 618The image trailers records are structured around the limitations imposed by 619flash hardware. As a consequence, they do not have a very intuitive design, and 620it is difficult to get a sense of the state of the device just by looking at the 621image trailers. It is better to map all the possible trailer states to the swap 622types described above via a set of tables. These tables are reproduced below. 623 624--- 625***Note*** 626 627*An important caveat about the tables described below is that they must* 628*be evaluated in the order presented here. Lower state numbers must have a* 629*higher priority when testing the image trailers.* 630 631--- 632 633``` 634 State I 635 | primary slot | secondary slot | 636 -----------------+--------------+----------------| 637 magic | Any | Good | 638 image-ok | Any | Unset | 639 copy-done | Any | Any | 640 -----------------+--------------+----------------' 641 result: BOOT_SWAP_TYPE_TEST | 642 -------------------------------------------------' 643 644 645 State II 646 | primary slot | secondary slot | 647 -----------------+--------------+----------------| 648 magic | Any | Good | 649 image-ok | Any | 0x01 | 650 copy-done | Any | Any | 651 -----------------+--------------+----------------' 652 result: BOOT_SWAP_TYPE_PERM | 653 -------------------------------------------------' 654 655 656 State III 657 | primary slot | secondary slot | 658 -----------------+--------------+----------------| 659 magic | Good | Unset | 660 image-ok | 0xff | Any | 661 copy-done | 0x01 | Any | 662 -----------------+--------------+----------------' 663 result: BOOT_SWAP_TYPE_REVERT | 664 -------------------------------------------------' 665``` 666 667Any of the above three states results in MCUboot attempting to swap images. 668 669Otherwise, MCUboot does not attempt to swap images, resulting in one of the 670other three swap types, as illustrated by State IV. 671 672``` 673 State IV 674 | primary slot | secondary slot | 675 -----------------+--------------+----------------| 676 magic | Any | Any | 677 image-ok | Any | Any | 678 copy-done | Any | Any | 679 -----------------+--------------+----------------' 680 result: BOOT_SWAP_TYPE_NONE, | 681 BOOT_SWAP_TYPE_FAIL, or | 682 BOOT_SWAP_TYPE_PANIC | 683 -------------------------------------------------' 684``` 685 686In State IV, when no errors occur, MCUboot will attempt to boot the contents of 687the primary slot directly, and the result is `BOOT_SWAP_TYPE_NONE`. If the image 688in the primary slot is not valid, the result is `BOOT_SWAP_TYPE_FAIL`. If a 689fatal error occurs during boot, the result is `BOOT_SWAP_TYPE_PANIC`. If the 690result is either `BOOT_SWAP_TYPE_FAIL` or `BOOT_SWAP_TYPE_PANIC`, MCUboot hangs 691rather than booting an invalid or compromised image. 692 693--- 694***Note*** 695 696*An important caveat to the above is the result when a swap is requested* 697*and the image in the secondary slot fails to validate, due to a hashing or* 698*signing error. This state behaves as State IV with the extra action of* 699*marking the image in the primary slot as "OK", to prevent further attempts* 700*to swap.* 701 702--- 703 704### [Resumed swaps](#resumed-swaps) 705 706If MCUboot determines that it is resuming an interrupted swap (i.e., a reset 707occurred mid-swap), it fully determines the operation to resume by reading the 708`swap info` field from the active trailer and extracting the swap type from bits 7090-3. The set of tables in the previous section are not necessary in the resume 710case. 711 712## [High-level operation](#high-level-operation) 713 714With the terms defined, we can now explore the bootloader's operation. First, 715a high-level overview of the boot process is presented. Then, the following 716sections describe each step of the process in more detail. 717 718Procedure: 719 7201. Inspect swap status region; is an interrupted swap being resumed? 721 + Yes: Complete the partial swap operation; skip to step 3. 722 + No: Proceed to step 2. 723 7242. Inspect image trailers; is a swap requested? 725 + Yes: 726 1. Is the requested image valid (integrity and security check)? 727 + Yes. 728 a. Perform swap operation. 729 b. Persist completion of swap procedure to image trailers. 730 c. Proceed to step 3. 731 + No. 732 a. Erase invalid image. 733 b. Persist failure of swap procedure to image trailers. 734 c. Proceed to step 3. 735 736 + No: Proceed to step 3. 737 7383. Boot into image in primary slot. 739 740### [Multiple image boot](#multiple-image-boot) 741 742When the flash contains multiple executable images the bootloader's operation 743is a bit more complex but similar to the previously described procedure with 744one image. Every image can be updated independently therefore the flash is 745partitioned further to arrange two slots for each image. 746``` 747+--------------------+ 748| MCUboot | 749+--------------------+ 750 ~~~~~ <- memory might be not contiguous 751+--------------------+ 752| Image 0 | 753| primary slot | 754+--------------------+ 755| Image 0 | 756| secondary slot | 757+--------------------+ 758 ~~~~~ <- memory might be not contiguous 759+--------------------+ 760| Image N | 761| primary slot | 762+--------------------+ 763| Image N | 764| secondary slot | 765+--------------------+ 766| Scratch | 767+--------------------+ 768``` 769MCUboot is also capable of handling dependencies between images. For example 770if an image needs to be reverted it might be necessary to revert another one too 771(e.g. due to API incompatibilities) or simply to prevent from being updated 772because of an unsatisfied dependency. Therefore all aborted swaps have to be 773completed and all the swap types have to be determined for each image before 774the dependency checks. Dependency handling is described in more detail in a 775following section. The multiple image boot procedure is organized in loops which 776iterate over all the firmware images. The high-level overview of the boot 777process is presented below. 778 779+ Loop 1. Iterate over all images 780 1. Inspect swap status region of current image; is an interrupted swap being 781 resumed? 782 + Yes: 783 + Review the validity of previously determined swap types 784 of other images. 785 + Complete the partial swap operation. 786 + Mark the swap type as `None`. 787 + Skip to next image. 788 + No: Proceed to step 2. 789 790 2. Inspect image trailers in the primary and secondary slot; is an image 791 swap requested? 792 + Yes: Review the validity of previously determined swap types of other 793 images. Is the requested image valid (integrity and security 794 check)? 795 + Yes: 796 + Set the previously determined swap type for the current image. 797 + Skip to next image. 798 + No: 799 + Erase invalid image. 800 + Persist failure of swap procedure to image trailers. 801 + Mark the swap type as `Fail`. 802 + Skip to next image. 803 + No: 804 + Mark the swap type as `None`. 805 + Skip to next image. 806 807+ Loop 2. Iterate over all images 808 1. Does the current image depend on other image(s)? 809 + Yes: Are all the image dependencies satisfied? 810 + Yes: Skip to next image. 811 + No: 812 + Modify swap type depending on what the previous type was. 813 + Restart dependency check from the first image. 814 + No: Skip to next image. 815 816+ Loop 3. Iterate over all images 817 1. Is an image swap requested? 818 + Yes: 819 + Perform image update operation. 820 + Persist completion of swap procedure to image trailers. 821 + Skip to next image. 822 + No: Skip to next image. 823 824+ Loop 4. Iterate over all images 825 1. Validate image in the primary slot (integrity and security check) or 826 at least do a basic sanity check to avoid booting into an empty flash 827 area. 828 829+ Boot into image in the primary slot of the 0th image position\ 830 (other image in the boot chain is started by another image). 831 832### [Multiple image boot for RAM loading and direct-xip](#multiple-image-boot-for-ram-loading-and-direct-xip) 833 834The operation of the bootloader is different when the ram-load or the 835direct-xip strategy is chosen. The flash map is very similar to the swap 836strategy but there is no need for Scratch area. 837 838+ Loop 1. Until all images are loaded and all dependencies are satisfied 839 1. Subloop 1. Iterate over all images 840 + Does any of the slots contain an image? 841 + Yes: 842 + Choose the newer image. 843 + Copy it to RAM in case of ram-load strategy. 844 + Validate the image (integrity and security check). 845 + If validation fails delete the image from flash and try the other 846 slot. (Image must be deleted from RAM too in case of ram-load 847 strategy.) 848 + No: Return with failure. 849 850 2. Subloop 2. Iterate over all images 851 + Does the current image depend on other image(s)? 852 + Yes: Are all the image dependencies satisfied? 853 + Yes: Skip to next image. 854 + No: 855 + Delete the image from RAM in case of ram-load strategy, but 856 do not delete it from flash. 857 + Try to load the image from the other slot. 858 + Restart dependency check from the first image. 859 + No: Skip to next image. 860 861+ Loop 2. Iterate over all images 862 + Increase the security counter if needed. 863 + Do the measured boot and the data sharing if needed. 864 865+ Boot the loaded slot of image 0. 866 867## [Image swapping](#image-swapping) 868 869The bootloader swaps the contents of the two image slots for two reasons: 870 871 * User has issued a "set pending" operation; the image in the secondary slot 872 should be run once (state I) or repeatedly (state II), depending on 873 whether a permanent swap was specified. 874 * Test image rebooted without being confirmed; the bootloader should 875 revert to the original image currently in the secondary slot (state III). 876 877If the image trailers indicates that the image in the secondary slot should be 878run, the bootloader needs to copy it to the primary slot. The image currently 879in the primary slot also needs to be retained in flash so that it can be used 880later. Furthermore, both images need to be recoverable if the bootloader 881resets in the middle of the swap operation. The two images are swapped 882according to the following procedure: 883 8841. Determine if both slots are compatible enough to have their images swapped. 885 To be compatible, both have to have only sectors that can fit into the 886 scratch area and if one of them has larger sectors than the other, it must 887 be able to entirely fit some rounded number of sectors from the other slot. 888 In the next steps we'll use the terminology "region" for the total amount of 889 data copied/erased because this can be any amount of sectors depending on 890 how many the scratch is able to fit for some swap operation. 8912. Iterate the list of region indices in descending order (i.e., starting 892 with the greatest index); only regions that are predetermined to be part of 893 the image are copied; current element = "index". 894 + a. Erase scratch area. 895 + b. Copy secondary_slot[index] to scratch area. 896 - If this is the last region in the slot, scratch area has a temporary 897 status area initialized to store the initial state, because the 898 primary slot's last region will have to be erased. In this case, 899 only the data that was calculated to amount to the image is copied. 900 - Else if this is the first swapped region but not the last region in 901 the slot, initialize the status area in primary slot and copy the 902 full region contents. 903 - Else, copy entire region contents. 904 + c. Write updated swap status (i). 905 + d. Erase secondary_slot[index] 906 + e. Copy primary_slot[index] to secondary_slot[index] according to amount 907 previosly copied at step b. 908 - If this is not the last region in the slot, erase the trailer in the 909 secondary slot, to always use the one in the primary slot. 910 + f. Write updated swap status (ii). 911 + g. Erase primary_slot[index]. 912 + h. Copy scratch area to primary_slot[index] according to amount 913 previously copied at step b. 914 - If this is the last region in the slot, the status is read from 915 scratch (where it was stored temporarily) and written anew in the 916 primary slot. 917 + i. Write updated swap status (iii). 9183. Persist completion of swap procedure to the primary slot image trailer. 919 920The additional caveats in step 2f are necessary so that the secondary slot image 921trailer can be written by the user at a later time. With the image trailer 922unwritten, the user can test the image in the secondary slot 923(i.e., transition to state I). 924 925--- 926***Note*** 927 928*If the region being copied contains the last sector, then swap status is* 929*temporarily maintained on scratch for the duration of this operation, always* 930*using the primary slot's area otherwise.* 931 932--- 933***Note*** 934 935*The bootloader tries to copy only used sectors (based on largest image* 936*installed on any of the slots), minimizing the amount of sectors copied and* 937*reducing the amount of time required for a swap operation.* 938 939--- 940 941The particulars of step 3 vary depending on whether an image is being tested, 942permanently used, reverted or a validation failure of the secondary slot 943happened when a swap was requested: 944 945 * test: 946 o Write primary_slot.copy_done = 1 947 (swap caused the following values to be written: 948 primary_slot.magic = BOOT_MAGIC 949 secondary_slot.magic = UNSET 950 primary_slot.image_ok = Unset) 951 952 * permanent: 953 o Write primary_slot.copy_done = 1 954 (swap caused the following values to be written: 955 primary_slot.magic = BOOT_MAGIC 956 secondary_slot.magic = UNSET 957 primary_slot.image_ok = 0x01) 958 959 * revert: 960 o Write primary_slot.copy_done = 1 961 o Write primary_slot.image_ok = 1 962 (swap caused the following values to be written: 963 primary_slot.magic = BOOT_MAGIC) 964 965 * failure to validate the secondary slot: 966 o Write primary_slot.image_ok = 1 967 968After completing the operations as described above the image in the primary slot 969should be booted. 970 971## [Swap status](#swap-status) 972 973The swap status region allows the bootloader to recover in case it restarts in 974the middle of an image swap operation. The swap status region consists of a 975series of single-byte records. These records are written independently, and 976therefore must be padded according to the minimum write size imposed by the 977flash hardware. In the below figure, a min-write-size of 1 is assumed for 978simplicity. The structure of the swap status region is illustrated below. In 979this figure, a min-write-size of 1 is assumed for simplicity. 980 981``` 982 0 1 2 3 983 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 984 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 985 |sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 | 986 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 987 |sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 | 988 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 989 |sec125,state 2 | | 990 +-+-+-+-+-+-+-+-+ + 991 ~ ~ 992 ~ [Records for indices 124 through 1 ~ 993 ~ ~ 994 ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 995 ~ |sec000,state 0 |sec000,state 1 |sec000,state 2 | 996 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 997``` 998 999The above is probably not helpful at all; here is a description in English. 1000 1001Each image slot is partitioned into a sequence of flash sectors. If we were to 1002enumerate the sectors in a single slot, starting at 0, we would have a list of 1003sector indices. Since there are two image slots, each sector index would 1004correspond to a pair of sectors. For example, sector index 0 corresponds to 1005the first sector in the primary slot and the first sector in the secondary slot. 1006Finally, reverse the list of indices such that the list starts with index 1007`BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is a 1008representation of this reversed list. 1009 1010During a swap operation, each sector index transitions through four separate 1011states: 1012``` 10130. primary slot: image 0, secondary slot: image 1, scratch: N/A 10141. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1) 10152. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0) 10163. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0) 1017``` 1018 1019Each time a sector index transitions to a new state, the bootloader writes a 1020record to the swap status region. Logically, the bootloader only needs one 1021record per sector index to keep track of the current swap state. However, due 1022to limitations imposed by flash hardware, a record cannot be overwritten when 1023an index's state changes. To solve this problem, the bootloader uses three 1024records per sector index rather than just one. 1025 1026Each sector-state pair is represented as a set of three records. The record 1027values map to the above four states as follows 1028 1029``` 1030 | rec0 | rec1 | rec2 1031 --------+------+------+------ 1032 state 0 | 0xff | 0xff | 0xff 1033 state 1 | 0x01 | 0xff | 0xff 1034 state 2 | 0x01 | 0x02 | 0xff 1035 state 3 | 0x01 | 0x02 | 0x03 1036``` 1037 1038The swap status region can accommodate `BOOT_MAX_IMG_SECTORS` sector indices. 1039Hence, the size of the region, in bytes, is 1040`BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index 1041count is that it is great enough to account for a maximum-sized image 1042(i.e., at least as great as the total sector count in an image slot). If a 1043device's image slots have been configured with `BOOT_MAX_IMG_SECTORS: 128` and 1044use less than 128 sectors, the first record that gets written will be somewhere 1045in the middle of the region. For example, if a slot uses 64 sectors, the first 1046sector index that gets swapped is 63, which corresponds to the exact halfway 1047point within the region. 1048 1049--- 1050***Note*** 1051 1052*Since the scratch area only ever needs to record swapping of the last* 1053*sector, it uses at most min-write-size * 3 bytes for its own status area.* 1054 1055--- 1056 1057## [Reset recovery](#reset-recovery) 1058 1059If the bootloader resets in the middle of a swap operation, the two images may 1060be discontiguous in flash. Bootutil recovers from this condition by using the 1061image trailers to determine how the image parts are distributed in flash. 1062 1063The first step is determine where the relevant swap status region is located. 1064Because this region is embedded within the image slots, its location in flash 1065changes during a swap operation. The below set of tables map image trailers 1066contents to swap status location. In these tables, the "source" field 1067indicates where the swap status region is located. In case of multi image boot 1068the images primary area and the single scratch area is always examined in pairs. 1069If swap status found on scratch area then it might not belong to the current 1070image. The swap_info field of swap status stores the corresponding image number. 1071If it does not match then "source: none" is returned. 1072 1073``` 1074 | primary slot | scratch | 1075 ----------+--------------+--------------| 1076 magic | Good | Any | 1077 copy-done | 0x01 | N/A | 1078 ----------+--------------+--------------' 1079 source: none | 1080 ----------------------------------------' 1081 1082 | primary slot | scratch | 1083 ----------+--------------+--------------| 1084 magic | Good | Any | 1085 copy-done | 0xff | N/A | 1086 ----------+--------------+--------------' 1087 source: primary slot | 1088 ----------------------------------------' 1089 1090 | primary slot | scratch | 1091 ----------+--------------+--------------| 1092 magic | Any | Good | 1093 copy-done | Any | N/A | 1094 ----------+--------------+--------------' 1095 source: scratch | 1096 ----------------------------------------' 1097 1098 | primary slot | scratch | 1099 ----------+--------------+--------------| 1100 magic | Unset | Any | 1101 copy-done | 0xff | N/A | 1102 ----------+--------------+--------------| 1103 source: primary slot | 1104 ----------------------------------------+------------------------------+ 1105 This represents one of two cases: | 1106 o No swaps ever (no status to read, so no harm in checking). | 1107 o Mid-revert; status in the primary slot. | 1108 For this reason we assume the primary slot as source, to trigger a | 1109 check of the status area and find out if there was swapping under way. | 1110 -----------------------------------------------------------------------' 1111``` 1112 1113If the swap status region indicates that the images are not contiguous, MCUboot 1114determines the type of swap operation that was interrupted by reading the `swap 1115info` field in the active image trailer and extracting the swap type from bits 11160-3 then resumes the operation. In other words, it applies the procedure defined 1117in the previous section, moving image 1 into the primary slot and image 0 into 1118the secondary slot. If the boot status indicates that an image part is present 1119in the scratch area, this part is copied into the correct location by starting 1120at step e or step h in the area-swap procedure, depending on whether the part 1121belongs to image 0 or image 1. 1122 1123After the swap operation has been completed, the bootloader proceeds as though 1124it had just been started. 1125 1126## [Integrity check](#integrity-check) 1127 1128An image is checked for integrity immediately before it gets copied into the 1129primary slot. If the bootloader doesn't perform an image swap, then it can 1130perform an optional integrity check of the image in the primary slot if 1131`MCUBOOT_VALIDATE_PRIMARY_SLOT` is set, otherwise it doesn't perform an 1132integrity check. 1133 1134During the integrity check, the bootloader verifies the following aspects of 1135an image: 1136 1137 * 32-bit magic number must be correct (`IMAGE_MAGIC`). 1138 * Image must contain an `image_tlv_info` struct, identified by its magic 1139 (`IMAGE_TLV_PROT_INFO_MAGIC` or `IMAGE_TLV_INFO_MAGIC`) exactly following 1140 the firmware (`hdr_size` + `img_size`). If `IMAGE_TLV_PROT_INFO_MAGIC` is 1141 found then after `ih_protect_tlv_size` bytes, another `image_tlv_info` 1142 with magic equal to `IMAGE_TLV_INFO_MAGIC` must be present. 1143 * Image must contain a SHA256 TLV. 1144 * Calculated SHA256 must match SHA256 TLV contents. 1145 * Image *may* contain a signature TLV. If it does, it must also have a 1146 KEYHASH TLV with the hash of the key that was used to sign. The list of 1147 keys will then be iterated over looking for the matching key, which then 1148 will then be used to verify the image contents. 1149 1150For low performance MCU's where the validation is a heavy process at boot 1151(~1-2 seconds on a arm-cortex-M0), the `MCUBOOT_VALIDATE_PRIMARY_SLOT_ONCE` 1152could be used. This option will cache the validation result as described above 1153into the magic area of the primary slot. The next boot, the validation will be 1154skipped if the previous validation was succesfull. This option is reducing the 1155security level since if an attacker could modify the contents of the flash after 1156a good image has been validated, the attacker could run his own image without 1157running validation again. Enabling this option should be done with care. 1158 1159## [Security](#security) 1160 1161As indicated above, the final step of the integrity check is signature 1162verification. The bootloader can have one or more public keys embedded in it 1163at build time. During signature verification, the bootloader verifies that an 1164image was signed with a private key that corresponds to the embedded KEYHASH 1165TLV. 1166 1167For information on embedding public keys in the bootloader, as well as 1168producing signed images, see: [signed_images](signed_images.md). 1169 1170If you want to enable and use encrypted images, see: 1171[encrypted_images](encrypted_images.md). 1172 1173--- 1174***Note*** 1175 1176*Image encryption is not supported when the direct-xip upgrade strategy* 1177*is selected.* 1178 1179--- 1180 1181### [Using hardware keys for verification](#hw-key-support) 1182 1183By default, the whole public key is embedded in the bootloader code and its 1184hash is added to the image manifest as a KEYHASH TLV entry. As an alternative 1185the bootloader can be made independent of the keys (avoiding the incorporation 1186of the public key into the code) by using one of the following options: 1187`MCUBOOT_HW_KEY` or `MCUBOOT_BUILTIN_KEY`. 1188 1189Using any of these options makes MCUboot independent from the public key(s). 1190The key(s) can be provisioned any time and by different parties. 1191 1192Hardware KEYs support options details: 1193- `MCUBOOT_HW_KEY`: In this case the hash of the public key must be 1194provisioned to the target device and MCUboot must be able to retrieve the 1195key-hash from there. For this reason the target must provide a definition 1196for the `boot_retrieve_public_key_hash()` function which is declared in 1197`boot/bootutil/include/bootutil/sign_key.h`. It is also required to use 1198the `full` option for the `--public-key-format` imgtool argument in order to 1199add the whole public key (PUBKEY TLV) to the image manifest instead of its 1200hash (KEYHASH TLV). During boot the public key is validated before using it for 1201signature verification, MCUboot calculates the hash of the public key from the 1202TLV area and compares it with the key-hash that was retrieved from the device. 1203- `MCUBOOT_BUILTIN_KEY`: With this option the whole public key(s) used for 1204signature verification must be provisioned to the target device and the used 1205[cryptographic library](PORTING.md) must support the usage of builtin keys based 1206on key IDs. In this case, neither the code nor the image metadata needs to 1207contain any public key data. During image validation only a key ID is passed to 1208the verifier function. The key handling is entirely the responsibility of the 1209crypto library and the details of the key handling mechanism are abstracted away 1210from the boot code.\ 1211***Note:*** *At the moment the usage of builtin keys is only available with the* 1212*PSA Crypto API based crypto backend (`MCUBOOT_USE_PSA_CRYPTO`) for ECDSA* 1213*signatures.* 1214 1215## [Protected TLVs](#protected-tlvs) 1216 1217If the TLV area contains protected TLV entries, by beginning with a `struct 1218image_tlv_info` with a magic value of `IMAGE_TLV_PROT_INFO_MAGIC` then the 1219data of those TLVs must also be integrity and authenticity protected. Beyond 1220the full size of the protected TLVs being stored in the `image_tlv_info`, 1221the size of the protected TLVs together with the size of the `image_tlv_info` 1222struct itself are also saved in the `ih_protected_size` field inside the 1223header. 1224 1225Whenever an image has protected TLVs the SHA256 has to be calculated over 1226not just the image header and the image but also the TLV info header and the 1227protected TLVs. 1228 1229``` 1230A +---------------------+ 1231 | Header | <- struct image_header 1232 +---------------------+ 1233 | Payload | 1234 +---------------------+ 1235 | TLV area | 1236 | +-----------------+ | struct image_tlv_info with 1237 | | TLV area header | | <- IMAGE_TLV_PROT_INFO_MAGIC (optional) 1238 | +-----------------+ | 1239 | | Protected TLVs | | <- Protected TLVs (struct image_tlv) 1240B | +-----------------+ | 1241 | | TLV area header | | <- struct image_tlv_info with IMAGE_TLV_INFO_MAGIC 1242C | +-----------------+ | 1243 | | SHA256 hash | | <- hash from A - B (struct image_tlv) 1244D | +-----------------+ | 1245 | | Keyhash | | <- indicates which pub. key for sig (struct image_tlv) 1246 | +-----------------+ | 1247 | | Signature | | <- signature from C - D (struct image_tlv), only hash 1248 | +-----------------+ | 1249 +---------------------+ 1250``` 1251 1252## [Dependency check](#dependency-check) 1253 1254MCUboot can handle multiple firmware images. It is possible to update them 1255independently but in many cases it can be desired to be able to describe 1256dependencies between the images (e.g. to ensure API compliance and avoid 1257interoperability issues). 1258 1259The dependencies between images can be described with additional TLV entries in 1260the protected TLV area after the end of an image. There can be more than one 1261dependency entry, but in practice if the platform only supports two individual 1262images then there can be maximum one entry which reflects to the other image. 1263 1264At the phase of dependency check all aborted swaps are finalized if there were 1265any. During the dependency check the bootloader verifies whether the image 1266dependencies are all satisfied. If at least one of the dependencies of an image 1267is not fulfilled then the swap type of that image has to be modified 1268accordingly and the dependency check needs to be restarted. This way the number 1269of unsatisfied dependencies will decrease or remain the same. There is always at 1270least 1 valid configuration. In worst case, the system returns to the initial 1271state after dependency check. 1272 1273For more information on adding dependency entries to an image, 1274see: [imgtool](imgtool.md). 1275 1276## [Downgrade prevention](#downgrade-prevention) 1277 1278Downgrade prevention is a feature which enforces that the new image must have a 1279higher version/security counter number than the image it is replacing, thus 1280preventing the malicious downgrading of the device to an older and possibly 1281vulnerable version of its firmware. 1282 1283### [Software-based downgrade prevention](#sw-downgrade-prevention) 1284 1285During the software based downgrade prevention the image version numbers are 1286compared. This feature is enabled with the `MCUBOOT_DOWNGRADE_PREVENTION` 1287option. In this case downgrade prevention is only available when the 1288overwrite-based image update strategy is used (i.e. `MCUBOOT_OVERWRITE_ONLY` 1289is set). 1290 1291### [Hardware-based downgrade prevention](#hw-downgrade-prevention) 1292 1293Each signed image can contain a security counter in its protected TLV area, which 1294can be added to the image using the `-s` option of the [imgtool](imgtool.md) script. 1295During the hardware based downgrade prevention (alias rollback protection) the 1296new image's security counter will be compared with the currently active security 1297counter value which must be stored in a non-volatile and trusted component of 1298the device. It is beneficial to handle this counter independently from image 1299version number: 1300 1301 * It does not need to increase with each software release, 1302 * It makes it possible to do software downgrade to some extent: if the 1303 security counter has the same value in the older image then it is accepted. 1304 1305It is an optional step of the image validation process and can be enabled with 1306the `MCUBOOT_HW_ROLLBACK_PROT` config option. When enabled, the target must 1307provide an implementation of the security counter interface defined in 1308`boot/bootutil/include/security_cnt.h`. 1309 1310## [Measured boot and data sharing](#boot-data-sharing) 1311 1312MCUboot defines a mechanism for sharing boot status information (also known as 1313measured boot) and an interface for sharing application specific information 1314with the runtime software. If any of these are enabled the target must provide 1315a shared data area between the bootloader and runtime firmware and define the 1316following parameters: 1317 1318```c 1319#define MCUBOOT_SHARED_DATA_BASE <area_base_addr> 1320#define MCUBOOT_SHARED_DATA_SIZE <area_size_in_bytes> 1321``` 1322 1323In the shared memory area all data entries are stored in a type-length-value 1324(TLV) format. Before adding the first data entry, the whole area is overwritten 1325with zeros and a TLV header is added at the beginning of the area during an 1326initialization phase. This TLV header contains a `tlv_magic` field with a value 1327of `SHARED_DATA_TLV_INFO_MAGIC` and a `tlv_tot_len` field which is indicating 1328the total length of shared TLV area including this header. The header is 1329followed by the the data TLV entries which are composed from a 1330`shared_data_tlv_entry` header and the data itself. In the data header there is 1331a `tlv_type` field which identifies the consumer of the entry (in the runtime 1332software) and specifies the subtype of that data item. More information about 1333the `tlv_type` field and data types can be found in the 1334`boot/bootutil/include/bootutil/boot_status.h` file. The type is followed by a 1335`tlv_len` field which indicates the size of the data entry in bytes, not 1336including the entry header. After this header structure comes the actual data. 1337 1338```c 1339/** Shared data TLV header. All fields in little endian. */ 1340struct shared_data_tlv_header { 1341 uint16_t tlv_magic; 1342 uint16_t tlv_tot_len; /* size of whole TLV area (including this header) */ 1343}; 1344 1345/** Shared data TLV entry header format. All fields in little endian. */ 1346struct shared_data_tlv_entry { 1347 uint16_t tlv_type; 1348 uint16_t tlv_len; /* TLV data length (not including this header). */ 1349}; 1350``` 1351 1352The measured boot can be enabled with the `MCUBOOT_MEASURED_BOOT` config option. 1353When enabled, the `--boot_record` argument of the imgtool script must also be 1354used during the image signing process to add a BOOT_RECORD TLV to the image 1355manifest. This TLV contains the following attributes/measurements of the 1356image in CBOR encoded format: 1357 1358 * Software type (role of the software component) 1359 * Software version 1360 * Signer ID (identifies the signing authority) 1361 * Measurement value (hash of the image) 1362 * Measurement type (algorithm used to calculate the measurement value) 1363 1364The `sw_type` string that is passed as the `--boot_record` option's parameter 1365will be the value of the "Software type" attribute in the generated BOOT_RECORD 1366TLV. The target must also define the `MAX_BOOT_RECORD_SZ` macro which indicates 1367the maximum size of the CBOR encoded boot record in bytes. 1368During boot, MCUboot will look for these TLVs (in case of multiple images) in 1369the manifests of the active images (the latest and validated) and copy the CBOR 1370encoded binary data to the shared data area. Preserving all these image 1371attributes from the boot stage for use by later runtime services (such as an 1372attestation service) is known as a measured boot. 1373 1374Setting the `MCUBOOT_DATA_SHARING` option enables the sharing of application 1375specific data using the same shared data area as for the measured boot. For 1376this, the target must provide a definition for the `boot_save_shared_data()` 1377function which is declared in `boot/bootutil/include/bootutil/boot_record.h`. 1378The `boot_add_data_to_shared_area()` function can be used for adding new TLV 1379entries to the shared data area. Alternatively, setting the 1380`MCUBOOT_DATA_SHARING_BOOTINFO` option will provide a default function for 1381this which saves information such as the maximum application size, bootloader 1382version (if available), running slot number, if recovery is part of MCUboot 1383and the signature type. Details of the TLVs for this information can be found 1384in `boot/bootutil/include/bootutil/boot_status.h` with `BLINFO_` prefixes. 1385 1386## [Testing in CI](#testing-in-ci) 1387 1388### [Testing Fault Injection Hardening (FIH)](#testing-fih) 1389 1390The CI currently tests the Fault Injection Hardening feature of MCUboot by 1391executing instruction skip during execution, and looking at whether a corrupted 1392image was booted by the bootloader or not. 1393 1394The main idea is that instruction skipping can be automated by scripting a 1395debugger to automatically execute the following steps: 1396 1397- Set breakpoint at specified address. 1398- Continue execution. 1399- On breakpoint hit increase the Program Counter. 1400- Continue execution. 1401- Detach from target after a timeout reached. 1402 1403Whether or not the corrupted image was booted or not can be decided by looking 1404for certain entries in the log. 1405 1406As MCUboot is deployed on a microcontroller, testing FI would not make much 1407sense in the simulator environment running on a host machine with different 1408architecture than the MCU's, as the degree of hardening depends on compiler 1409behavior. For example, (a bit counterintuitively) the code produced by gcc 1410with `-O0` optimisation is more resilient against FI attacks than the code 1411generated with `-O3` or `-Os` optimizations. 1412 1413To run on a desired architecture in the CI, the tests need to be executed on an 1414emulator (as real devices are not available in the CI environment). For this 1415implementation QEMU is selected. 1416 1417For the tests MCUboot needs a set of drivers and an implementation of a main 1418function. For the purpose of this test Trusted-Firmware-M has been selected as 1419it supports Armv8-M platforms that are also emulated by QEMU. 1420 1421The tests run in a docker container inside the CI VMs, to make it more easy to 1422deploy build and test environment (QEMU, compilers, interpreters). The CI VMs 1423seems to be using quite old Ubuntu (16.04). 1424 1425The sequence of the testing is the following (pseudo code): 1426 1427```sh 1428fn main() 1429 # Implemented in ci/fih-tests_install.sh 1430 generate_docker_image(Dockerfile) 1431 1432 # See details below. Implemented in ci/fih-tests_run.sh. 1433 # Calling the function with different parameters is done by Travis CI based on 1434 # the values provided in the .travis.yaml 1435 start_docker_image(skip_sizes, build_type, damage_type, fih_level) 1436 1437fn start_docker_image(skip_sizes, build_type, damage_type, fih_level) 1438 # implemented in ci/fih_test_docker/execute_test.sh 1439 compile_mcuboot(build_type) 1440 1441 # implemented in ci/fih_test_docker/damage_image.py 1442 damage_image(damage_type) 1443 1444 # implemented in ci/fih_test_docker/run_fi_test.sh 1445 ranges = generate_address_ranges() 1446 for s in skip_sizes 1447 for r in ranges 1448 do_skip_in_qemu(s, r) # See details below 1449 evaluate_logs() 1450 1451fn do_skip_in_qemu(size, range) 1452 for a in r 1453 run_qemu(a, size) # See details below 1454 1455# this part is implemented in ci/fih_test_docker/fi_tester_gdb.sh 1456fn run_qemu(a, size) 1457 script = create_debugger_script(a, size) 1458 start_qemu_in_bacground() # logs serial out to a file 1459 gdb_attach_to_qemu(script) 1460 kill_qemu() 1461 1462 # This checks the debugger and the quemu logs, and decides whether the tets 1463 # was executed successfully, and whether the image is booted or not. Then 1464 # emits a yaml fragment on the standard out to be processed by the caller 1465 # script 1466 evaluate_run(qemu_log_file) 1467``` 1468 1469Further notes: 1470 1471- The image is corrupted by changing its signature. 1472- MCUBOOT_FIH_PROFILE_MAX is not tested as it requires TRNG, and the AN521 1473platform has no support for it. However this profile adds the random 1474execution delay to the code, so should not affect the instruction skip results 1475too much, because break point is placed at exact address. But in practice this 1476makes harder the accurate timing of the attack. 1477- The test cases defined in .travis.yml always return `passed`, if they were 1478executed successfully. A yaml file is created during test execution with the 1479details of the test execution results. A summary of the collected results is 1480printed in the log at the end of the test. 1481 1482An advantage of having the tests running in a docker image is that it is 1483possible to run the tests on a local machine that has git and docker, without 1484installing any additional software. 1485 1486So, running the test on the host looks like the following (The commands below 1487are issued from the MCUboot source directory): 1488 1489```sh 1490$ mkdir docker 1491$ ./ci/fih-tests_install.sh 1492$ FIH_LEVEL=MEDIUM BUILD_TYPE=RELEASE SKIP_SIZE=2 DAMAGE_TYPE=SIGNATURE \ 1493 ./ci/fih-tests_run.sh 1494``` 1495On the travis CI the environment variables in the last command are set based on 1496the configs provided in the `.travis.yaml` 1497 1498This starts the tests, however the shell that it is running in is not 1499interactive, it is not possible to examine the results of the test run. To have 1500an interactive shell where the results can be examined, the following can be 1501done: 1502 1503- The docker image needs to be built with `ci/fih-tests_install.sh` as described 1504 above. 1505- Start the docker image with the following command: 1506 `docker run -i -t mcuboot/fih-test`. 1507- Execute the test with a command similar to the following: 1508 `/root/execute_test.sh 8 RELEASE SIGNATURE MEDIUM`. After the test finishes, 1509 the shell returns, and it is possible to investigate the results. It is also 1510 possible to stop the test with _Ctrl+c_. The parameters to the 1511 `execute_test.sh` are `SKIP_SIZE`, `BUILD_TYPE`, `DAMAGE_TYPE`, `FIH_LEVEL` in 1512 order. 1513
