Lines Matching +full:fih +full:- +full:tests_run
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)
110 #define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output - Not supported anymore */
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 */
123 Optional type-length-value records (TLVs) containing image metadata are placed
137 ## [Flash map](#flash-map)
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.
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)
447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
449 ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~
451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 | ------------------------- | ----- |
555 7. MAGIC: A 16-byte field identifying the image trailer layout. It may assume
584 14-byte pattern:
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 +--------------------+
754 +--------------------+
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
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
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 ---
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.
984 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
986 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
988 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
990 +-+-+-+-+-+-+-+-+ +
994 ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
996 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1007 `BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is 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 --------+------+------+------
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
1120 at step e or step h in the area-swap procedure, depending on whether the part
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
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: