Lines Matching +full:0 +full:- +full:latest
1 <!--
2 - SPDX-License-Identifier: Apache-2.0
4 - Copyright (c) 2017-2020 Linaro LTD
5 - Copyright (c) 2017-2019 JUUL Labs
6 - Copyright (c) 2019-2024 Arm Limited
8 - Original license:
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
18 - http://www.apache.org/licenses/LICENSE-2.0
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 -->
49 * Built to run from a fixed location (i.e., not position-independent).
51 ## [Image format](#image-format)
56 #define IMAGE_MAGIC 0x96f3b83d
79 #define IMAGE_TLV_INFO_MAGIC 0x6907
80 #define IMAGE_TLV_PROT_INFO_MAGIC 0x6908
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
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
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 */
123 Optional type-length-value records (TLVs) containing image metadata are placed
131 case the value of the `ih_protect_tlv_size` field is 0.
137 ## [Flash map](#flash-map)
148 #define FLASH_AREA_BOOTLOADER 0
168 ## [Image slots](#image-slots)
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
178 contents of the primary slot. The bootloader supports either swap- or
179 overwrite-based image upgrades, but must be configured at build time to choose
182 ### [Swap using scratch](#image-swap-using-scratch)
184 When swap-using-scratch algorithm is used, in addition to the slots of
220 There is no *best* ratio, as the right size is use-case dependent. Factors to
226 swap-using scratch algorithm assumes that the primary and the secondary image
231 maximum-image-size = image-slot-size - image-trailer-size
235 `image-slot-size` is the size of the image slot.
236 `image-trailer-size` is the size of the image trailer.
238 ### [Swap without using scratch](#image-swap-no-scratch)
240 This algorithm is an alternative to the swap-using-scratch algorithm.
245 Beginning from N=0:
246 2. Copies the N-th sector from the secondary slot to the N-th sector of the
248 3. Copies the (N+1)-th sector from the primary slot to the N-th sector of the
254 memory-size-effective slot layout is when the primary slot is exactly one sector
255 larger than the secondary slot, although same-sized slots are allowed as well.
262 maximum-image-size = (N-1) * slot-sector-size - image-trailer-sectors-size
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
270 `image-trailer-sectors-size` will be equal to 2048 B.
279 ### [Equal slots (direct-xip)](#direct-xip)
281 When the direct-xip mode is enabled the active image flag is "moved" between the
294 chain-loads it.
297 read the [corresponding section](#direct-xip-revert).
299 images are not moved between the slots, the on-the-fly image
304 The overwrite and the direct-xip upgrade strategies are substantially simpler to
310 ### [RAM loading](#ram-load)
312 In ram-load mode the slots are equal. Like the direct-xip mode, this mode
316 copied to, is stored in the image header. The ram-load upgrade mode can be
322 execution. Ram-load mode requires the image to be built to be executed from
324 ram-load is enabled then platform must define the following parameters:
341 When ram-load is enabled, the `--load-addr <addr>` option of the `imgtool`
346 When the encryption option is enabled (`MCUBOOT_ENC_IMAGES`) along with ram-load
352 ## [Boot swap types](#boot-swap-types)
354 When the device first boots under normal circumstances, there is an up-to-date
356 chain-load. In this case, no image swaps are necessary. During device upgrades,
360 Upgrading an old image with a new one by swapping can be a two-step process. In
376 device firmware to make test swaps permanent only after performing a self-test
385 - `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the
388 - `BOOT_SWAP_TYPE_TEST`: Boot the contents of the secondary slot by swapping
391 - `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image
394 - `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent;
399 - `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid.
401 - `BOOT_SWAP_TYPE_PANIC`: Swapping encountered an unrecoverable error.
403 The "swap type" is a high-level representation of the outcome of the
405 the bit-level contents of flash.
407 ### [Revert mechanism in direct-xip mode](#direct-xip-revert)
409 The direct-xip mode also supports a "revert" mechanism which is the equivalent
410 of the swap mode's "revert" swap. When the direct-xip mode is selected it can be
412 must also be added to the signed images (the "--pad" option of the `imgtool`
414 [Image Trailer](#image-trailer) section and the [imgtool](imgtool.md)
417 direct-xip mode's "revert" mechanism are the following:
421 + Yes: Did the image mark itself "OK" (was the self-test successful)?
423 - Proceed to step 3.
425 - Erase the image from the slot to prevent it from being selected
427 - Return to step 1 (the bootloader will attempt to select and
430 - Mark the image as "selected" (set the copy_done flag in the trailer).
431 - Proceed to step 3.
434 ## [Image trailer](#image-trailer)
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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
449 ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~
451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
452 | Encryption key 0 (16 octets) [*] |
454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
455 | 0xff padding as needed |
456 | (BOOT_MAX_ALIGN minus 16 octets from Encryption key 0) [*] |
457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
461 | 0xff padding as needed |
463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
466 | 0xff padding as needed |
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 |
477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
480 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
488 ---
491 *"min-write-size" is a property of the flash hardware. If the hardware*
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.*
496 ---
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,
507 - sector data in scratch is copied into the secondary slot
518 The factor of min-write-size is due to the behavior of flash hardware. The factor
521 2. Encryption keys: key-encrypting keys (KEKs). These keys are needed for
531 - Swap type: Stored in bits 0-3. Indicating the type of swap operation in
535 - Image number: Stored in bits 4-7. It has always 0 value at single image
543 | ------------------------- | ----- |
550 complete (0x01=done; 0xff=not done).
553 confirmed as good by the user (0x01=confirmed; 0xff=not confirmed).
555 7. MAGIC: A 16-byte field identifying the image trailer layout. It may assume
574 0x77, 0xc2, 0x95, 0xf3,
575 0x60, 0xd2, 0xef, 0x7f,
576 0x35, 0x52, 0x50, 0x0f,
577 0x2c, 0xb6, 0x79, 0x80
584 14-byte pattern:
590 0x2d, 0xe1,
591 0x5d, 0x29, 0x41, 0x0b,
592 0x8d, 0x77, 0x67, 0x9c,
593 0x11, 0x0f, 0x1f, 0x8a
598 ---
602 could be huge. For example, for 128 slot sectors with a 4-byte alignment,
605 ---
607 ## [Image trailers](#image-trailers)
613 ### [New swaps (non-resumes)](#new-swaps-non-resumes)
624 ---
631 ---
636 -----------------+--------------+----------------|
638 image-ok | Any | Unset |
639 copy-done | Any | Any |
640 -----------------+--------------+----------------'
642 -------------------------------------------------'
647 -----------------+--------------+----------------|
649 image-ok | Any | 0x01 |
650 copy-done | Any | Any |
651 -----------------+--------------+----------------'
653 -------------------------------------------------'
658 -----------------+--------------+----------------|
660 image-ok | 0xff | Any |
661 copy-done | 0x01 | Any |
662 -----------------+--------------+----------------'
664 -------------------------------------------------'
675 -----------------+--------------+----------------|
677 image-ok | Any | Any |
678 copy-done | Any | Any |
679 -----------------+--------------+----------------'
683 -------------------------------------------------'
693 ---
702 ---
704 ### [Resumed swaps](#resumed-swaps)
707 occurred mid-swap), it fully determines the operation to resume by reading the
709 0-3. The set of tables in the previous section are not necessary in the resume
712 ## [High-level operation](#high-level-operation)
715 a high-level overview of the boot process is presented. Then, the following
740 ### [Multiple image boot](#multiple-image-boot)
747 +--------------------+
749 +--------------------+
750 ~~~~~ <- memory might be not contiguous
751 +--------------------+
752 | Image 0 |
754 +--------------------+
755 | Image 0 |
757 +--------------------+
758 ~~~~~ <- memory might be not contiguous
759 +--------------------+
762 +--------------------+
765 +--------------------+
767 +--------------------+
776 iterate over all the firmware images. The high-level overview of the boot
829 + Boot into image in the primary slot of the 0th image position\
832 …# [Multiple image boot for RAM loading and direct-xip](#multiple-image-boot-for-ram-loading-and-di…
834 The operation of the bootloader is different when the ram-load or the
835 direct-xip strategy is chosen. The flash map is very similar to the swap
843 + Copy it to RAM in case of ram-load strategy.
846 slot. (Image must be deleted from RAM too in case of ram-load
855 + Delete the image from RAM in case of ram-load strategy, but
865 + Boot the loaded slot of image 0.
867 ## [Image swapping](#image-swapping)
896 - If this is the last region in the slot, scratch area has a temporary
900 - Else if this is the first swapped region but not the last region in
903 - Else, copy entire region contents.
908 - If this is not the last region in the slot, erase the trailer in the
914 - If this is the last region in the slot, the status is read from
925 ---
932 ---
939 ---
957 primary_slot.image_ok = 0x01)
971 ## [Swap status](#swap-status)
975 series of single-byte records. These records are written independently, and
977 flash hardware. In the below figure, a min-write-size of 1 is assumed for
979 this figure, a min-write-size of 1 is assumed for simplicity.
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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
990 +-+-+-+-+-+-+-+-+ +
994 ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
995 ~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |
996 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1002 enumerate the sectors in a single slot, starting at 0, we would have a list of
1004 correspond to a pair of sectors. For example, sector index 0 corresponds to
1007 `BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is a
1013 0. primary slot: image 0, secondary slot: image 1, scratch: N/A
1014 1. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1)
1015 2. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0)
1016 3. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0)
1026 Each sector-state pair is represented as a set of three records. The record
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
1040 `BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index
1041 count is that it is great enough to account for a maximum-sized image
1049 ---
1053 *sector, it uses at most min-write-size * 3 bytes for its own status area.*
1055 ---
1057 ## [Reset recovery](#reset-recovery)
1075 ----------+--------------+--------------|
1077 copy-done | 0x01 | N/A |
1078 ----------+--------------+--------------'
1080 ----------------------------------------'
1083 ----------+--------------+--------------|
1085 copy-done | 0xff | N/A |
1086 ----------+--------------+--------------'
1088 ----------------------------------------'
1091 ----------+--------------+--------------|
1093 copy-done | Any | N/A |
1094 ----------+--------------+--------------'
1096 ----------------------------------------'
1099 ----------+--------------+--------------|
1101 copy-done | 0xff | N/A |
1102 ----------+--------------+--------------|
1104 ----------------------------------------+------------------------------+
1107 o Mid-revert; status in the primary slot. |
1110 -----------------------------------------------------------------------'
1116 0-3 then resumes the operation. In other words, it applies the procedure defined
1117 in the previous section, moving image 1 into the primary slot and image 0 into
1120 at step e or step h in the area-swap procedure, depending on whether the part
1121 belongs to image 0 or image 1.
1126 ## [Integrity check](#integrity-check)
1137 * 32-bit magic number must be correct (`IMAGE_MAGIC`).
1151 (~1-2 seconds on a arm-cortex-M0), the `MCUBOOT_VALIDATE_PRIMARY_SLOT_ONCE`
1173 ---
1176 *Image encryption is not supported when the direct-xip upgrade strategy*
1179 ---
1181 ### [Using hardware keys for verification](#hw-key-support)
1193 - `MCUBOOT_HW_KEY`: In this case the hash of the public key must be
1195 key-hash from there. For this reason the target must provide a definition
1198 the `full` option for the `--public-key-format` imgtool argument in order to
1202 TLV 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
1215 ## [Protected TLVs](#protected-tlvs)
1230 A +---------------------+
1231 | Header | <- struct image_header
1232 +---------------------+
1234 +---------------------+
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)
1240 B | +-----------------+ |
1241 | | TLV area header | | <- struct image_tlv_info with IMAGE_TLV_INFO_MAGIC
1242 C | +-----------------+ |
1243 | | SHA256 hash | | <- hash from A - B (struct image_tlv)
1244 D | +-----------------+ |
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 +---------------------+
1252 ## [Dependency check](#dependency-check)
1276 ## [Downgrade prevention](#downgrade-prevention)
1283 ### [Software-based downgrade prevention](#sw-downgrade-prevention)
1288 overwrite-based image update strategy is used (i.e. `MCUBOOT_OVERWRITE_ONLY`
1291 ### [Hardware-based downgrade prevention](#hw-downgrade-prevention)
1294 can be added to the image using the `-s` option of the [imgtool](imgtool.md) script.
1297 counter value which must be stored in a non-volatile and trusted component of
1310 ## [Measured boot and data sharing](#boot-data-sharing)
1323 In the shared memory area all data entries are stored in a type-length-value
1353 When enabled, the `--boot_record` argument of the imgtool script must also be
1364 The `sw_type` string that is passed as the `--boot_record` option's parameter
1369 the manifests of the active images (the latest and validated) and copy the CBOR
1386 ## [Testing in CI](#testing-in-ci)
1388 ### [Testing Fault Injection Hardening (FIH)](#testing-fih)
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.
1410 with `-O0` optimisation is more resilient against FI attacks than the code
1411 generated with `-O3` or `-Os` optimizations.
1418 function. For the purpose of this test Trusted-Firmware-M has been selected as
1419 it supports Armv8-M platforms that are also emulated by QEMU.
1429 # Implemented in ci/fih-tests_install.sh
1432 # See details below. Implemented in ci/fih-tests_run.sh.
1471 - The image is corrupted by changing its signature.
1472 - MCUBOOT_FIH_PROFILE_MAX is not tested as it requires TRNG, and the AN521
1477 - The test cases defined in .travis.yml always return `passed`, if they were
1491 $ ./ci/fih-tests_install.sh
1493 ./ci/fih-tests_run.sh
1503 - The docker image needs to be built with `ci/fih-tests_install.sh` as described
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: