### Start mcuboot FIH Test Docker Image Source: https://docs.mcuboot.com/design.html Use this command to start the Docker image for FIH testing. The `-i` flag keeps STDIN open and the `-t` flag allocates a pseudo-TTY, enabling an interactive session. ```bash docker run -i -t mcuboot/fih-test ``` -------------------------------- ### Install Dependencies Source: https://docs.mcuboot.com/imgtool.html Installs the necessary Python libraries for the imgtool.py script using pip3. ```bash pip3 install --user -r scripts/requirements.txt ``` -------------------------------- ### Install and Confirm Images for Swap Test Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load images into slot 0 and slot 1, upload the slot 1 image, list images, and confirm the slot 1 image. This prepares for testing swap with random failures. ```bash newt create-image k64f_slinky 1.0.1 key_rsa.pem newt load k64f_slinky newt create-image k64f_slinky2 1.0.2 key_rsa.pem newtmgr image upload k64f_slinky2 newtmgr image list newtmgr image confirm ``` -------------------------------- ### Start MCUboot Execution Source: https://docs.mcuboot.com/PORTING.html Call this function from your target OS application to initiate the MCUboot process. It requires a pointer to a `boot_rsp` structure to return execution information. ```c int boot_go(struct boot_rsp *rsp); ``` -------------------------------- ### DTS Configuration for Swap-Using-Scratch Source: https://docs.mcuboot.com/readme-zephyr.html Example Device Tree Source (DTS) configuration for defining boot, slot0, slot1, and scratch partitions. This is necessary when using the swap-using-scratch flash algorithm. ```dts boot_partition: partition@0 { compatible = "zephyr,mapped-partition"; label = "mcuboot"; reg = <0x00000000 0xc000>; }; slot0_partition: partition@c000 { compatible = "zephyr,mapped-partition"; label = "image-0"; reg = <0x0000C000 0x37000>; }; slot1_partition: partition@43000 { compatible = "zephyr,mapped-partition"; label = "image-1"; reg = <0x00043000 0x37000>; }; scratch_partition: partition@7a000 { compatible = "zephyr,mapped-partition"; label = "image-scratch"; reg = <0x0007a000 0x00006000>; }; ``` -------------------------------- ### Build and Run Test Target Source: https://docs.mcuboot.com/testplan-zephyr.html Invoke `make` with a specific test target to build and run tests. Example shown for `test-good-rsa`. ```bash $ make test-good-rsa ``` -------------------------------- ### Install MCUmgr CLI Tool Source: https://docs.mcuboot.com/serial_recovery.html Installs the MCUmgr command-line tool, which is used as an SMP client for evaluation purposes. ```bash go install github.com/apache/mynewt-mcumgr-cli/mcumgr@latest ``` -------------------------------- ### Install MCUboot Dependencies Source: https://docs.mcuboot.com/readme-zephyr.html Installs the Python packages required for MCUboot development. Navigate to the MCUboot directory before running this command. ```bash cd ~/zephyrproject-rtos/bootloader/mcuboot # or to your directory where MCUboot is pip3 install --user -r scripts/requirements.txt ``` -------------------------------- ### Sign Application Image Manually Source: https://docs.mcuboot.com/readme-zephyr.html Use the imgtool.py script to manually sign application images. Refer to samples/zephyr/Makefile for usage examples. ```python scripts/imgtool.py sign --key --format --version --slot-size -o ``` -------------------------------- ### Implement RAM Region Info Function for Multiple Images Source: https://docs.mcuboot.com/design.html For systems utilizing multiple RAM regions for image loading, implement this function to provide MCUboot with the execution start address and size for a given image ID. This is required when the MULTIPLE_EXECUTABLE_RAM_REGIONS flag is defined. ```c int boot_get_image_exec_ram_info(uint32_t image_id, uint32_t *exec_ram_start, uint32_t *exec_ram_size) ``` -------------------------------- ### MCUboot Custom Crypto Header Example Source: https://docs.mcuboot.com/custom_crypto.html This header file acts as a dispatcher for custom crypto implementations. Ensure your custom header is included before MCUboot's crypto headers and that the directory containing this file is in the include path. ```c #ifndef MCUBOOT_CUSTOM_CRYPTO_H #define MCUBOOT_CUSTOM_CRYPTO_H #include "my_sha.h" #include "my_ecdsa.h" #if defined(MCUBOOT_ENC_IMAGES) #include "my_hmac_sha256.h" #include "my_aes_ctr.h" #include "my_ecdh_p256.h" #endif #endif /* MCUBOOT_CUSTOM_CRYPTO_H */ ``` -------------------------------- ### Flash First Image (hello1) Source: https://docs.mcuboot.com/testplan-zephyr.html After the bootloader is programmed, flash the first image, 'hello1'. This tests the initial image loading. ```bash $ make flash_hello1 ``` -------------------------------- ### Image Signing and Preparation with imgtool Source: https://docs.mcuboot.com/imgtool.html This command demonstrates the basic usage of imgtool for signing an image. It requires a private key, version information, flash alignment, header size, and the input image file. Options for compression, encryption, and padding can also be specified. ```bash imgtool sign --key privkey.pem --version 1.2.3 --align 8 --header-size 128 --pad-header --output signed.img input.img ``` -------------------------------- ### Flash Second Image (hello2) Source: https://docs.mcuboot.com/testplan-zephyr.html Flash the second image, 'hello2', to test the upgrade process. This should trigger a specific swap type message. ```bash $ make flash_hello2 ``` -------------------------------- ### Development Phase Secure Boot Configurations Source: https://docs.mcuboot.com/readme-espressif.html Recommended configurations for the development phase to keep debugging enabled and avoid unrecoverable state changes. This includes eFuse emulation. ```kconfig CONFIG_SECURE_BOOT_ALLOW_JTAG=1 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=1 CONFIG_EFUSE_VIRTUAL=1 CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1 CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000 CONFIG_EFUSE_VIRTUAL_SIZE=0x2000 ``` -------------------------------- ### Create and Upload Image for Multi-Key Test Source: https://docs.mcuboot.com/testplan-mynewt.html Create an image for slot 1, upload it, list images, and mark one for testing. This is used to verify swap behavior with different signing keys or no signing when multiple keys are supported. ```bash newt create-image k64f_blinky2 1.0.2 newtmgr image upload k64f_blinky2 newtmgr image list newtmgr image test ``` -------------------------------- ### Linking Commit to GitHub Issue Example Source: https://docs.mcuboot.com/SubmittingPatches.html Use this format in your commit message to link the commit to a specific GitHub issue. This aids in tracking. ```git commit message Keyword #GH_issue_number ``` -------------------------------- ### Create and Upload Image to Slot 1 for Testing Source: https://docs.mcuboot.com/testplan-mynewt.html Create an image for slot 1, upload it, list images, and mark one for testing. This is used to verify swap behavior with different signing keys or no signing. ```bash newt create-image k64f_blinky2 1.0.2 newtmgr image upload k64f_blinky2 newtmgr image list newtmgr image test ``` -------------------------------- ### Signed-off-by Line Example Source: https://docs.mcuboot.com/SubmittingPatches.html Include this line at the end of your commit message, separated by a blank line, to certify agreement with the Developer Certificate of Origin. ```git commit message Signed-off-by: Developer Name ``` -------------------------------- ### Local FIH Testing Commands Source: https://docs.mcuboot.com/design.html Commands to run FIH tests on a local machine using Docker. Ensure you have git and docker installed and are in the MCUboot source directory. ```bash $ mkdir docker $ ./ci/fih-tests_install.sh $ FIH_LEVEL=MEDIUM BUILD_TYPE=RELEASE SKIP_SIZE=2 DAMAGE_TYPE=SIGNATURE \ ./ci/fih-tests_run.sh ``` -------------------------------- ### Decompress LZMA Stream (No Filter) Source: https://docs.mcuboot.com/compression_format.html Decompresses a raw LZMA stream without an ARM thumb filter. This command-line example uses `unlzma` to extract the compressed data. ```bash unlzma --lzma2 --format=raw --suffix=.lzma raw.lzma ``` -------------------------------- ### Create and Load Signed Image to Slot 0 Source: https://docs.mcuboot.com/testplan-mynewt.html Create a signed image with a specified key and load it into slot 0. ```bash newt create-image k64f_blinky 1.0.1 key_.pem newt load k64f_blinky ``` -------------------------------- ### Flash MCUboot and Application Source: https://docs.mcuboot.com/readme-riot.html Flash both the MCUboot bootloader and the compiled application to the target device. ```bash make flash-mcuboot ``` -------------------------------- ### Decompress LZMA Stream (ARM Thumb Filter) Source: https://docs.mcuboot.com/compression_format.html Decompresses a raw LZMA stream with an ARM thumb filter. This command-line example uses `unlzma` to extract the compressed data, applying specific ARM instructions. ```bash unlzma --armthumb --lzma2 --format=raw --suffix=.lzma raw.lzma ``` -------------------------------- ### Image Padding and Slot Size Source: https://docs.mcuboot.com/imgtool.html Use the --pad argument to add a trailer indicating an upgrade. The --slot-size argument is required to prevent firmware overflow into the swap status area. Use --overwrite-only if swap upgrades are not used. ```bash imgtool --pad --slot-size 0x10000 input.img ``` ```bash imgtool --overwrite-only input.img ``` -------------------------------- ### Enable Secure Boot V2 Source: https://docs.mcuboot.com/readme-espressif.html Enable the core Secure Boot V2 functionality and signed-on-boot features. These are essential for ensuring only authorized code executes. ```kconfig CONFIG_SECURE_BOOT=1 CONFIG_SECURE_BOOT_V2_ENABLED=1 CONFIG_SECURE_SIGNED_ON_BOOT=1 ``` -------------------------------- ### ESP32-H2 Memory Map Diagram Source: https://docs.mcuboot.com/readme-espressif.html This diagram illustrates the IRAM and DRAM address ranges for the ESP32-H2. It shows the starting and ending addresses for various memory segments, including free memory, OS-claimable RAM, and segments specifically used by the bootloader. ```text IRAM ADDR / DRAM ADDR * +--------+--------------+------+ 0x40800000 / 0x40800000 - HP SRAM START * | ^ | * | | | * | | | * | | FREE | *CLAIMABLE BY OS RAM * | | | * | | | * | v | * +--------+--------------+------+ 0x4082D3D0 / 0x4082D3D0 * | ^ | * | | | * | | | * | | dram_seg | *CLAIMABLE BY OS RAM * | | | (length 0xB000) * | | | * | v | * +------------------------------+ 0x408383D0 / 0x408383D0 * | ^ | * | | | * | | | * | | iram_seg | *CLAIMABLE BY OS RAM (length 0xF000) * | | | * | | | * | v | * +------------------------------+ 0x408473D0 / 0x408473D0 * | ^ | * | | | *** SHOULD NOT BE OVERLAPPED *** * | | dram_loader_seg | *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP *** * | | | (length 0x1800) * | v | * +------------------------------+ 0x40848BD0 / 0x40848BD0 * | ^ | * | | | * | | | * | | iram_loader_seg | *** SHOULD NOT BE OVERLAPPED *** * | | | *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP *** * | | | * | v | * +--------+--------------+------+ 0x4084AFD0 / 0x4084AFD0 * | ^ | * | | | * | | FREE | above `BOOTLOADER_RAM_END` * | | | *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP *** * | v | * +--------+--------------+------+ 0x4084FFFF / 0x4084FFFF - HP SRAM END ``` -------------------------------- ### Build and Load MCUboot for Swap with Random Failures Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load MCUboot to test swap functionality under random failure conditions. ```bash newt build k64f_boot_rsa newt load k64f_boot_rsa ``` -------------------------------- ### Enable RSA Signing Scheme Source: https://docs.mcuboot.com/readme-espressif.html Configure the RSA signing scheme for Secure Boot, applicable to most supported chips except ESP32-C2 and ESP32-C61. Ensure RSA support is enabled. ```kconfig CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME=1 CONFIG_SECURE_BOOT_SUPPORTS_RSA=1 ``` -------------------------------- ### Build and Load MCUboot for Multi-Key Signing Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load MCUboot when testing images signed with more than one key. ```bash newt build k64f_boot_rsa_ec newt load k64f_boot_rsa_ec ``` -------------------------------- ### Flash Signed Bootloader Source: https://docs.mcuboot.com/readme-espressif.html Flash the signed bootloader binary to the device using `esptool.py`. Use the `--after no_reset` flag to ensure the device is not reset until you are ready. Match flash parameters carefully. ```bash esptool.py -p -b 2000000 --after no_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` -------------------------------- ### Test Slot 0 Validation with Valid Key Source: https://docs.mcuboot.com/testplan-mynewt.html Build an image signed with a valid key, load it, and reset. The image should run, validating the slot 0 protection. ```bash newt create-image k64f_blinky 1.0.1 key_rsa.pem newt load k64f_blinky ``` -------------------------------- ### Build and Load MCUboot with Signing Algorithm Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load MCUboot for a specific signing algorithm (rsa, ec, ec256). ```bash newt build k64f_boot_ newt load k64f_boot_ ``` -------------------------------- ### Configure EC256 Signing Algorithm Source: https://docs.mcuboot.com/readme-espressif.html Enable EC256 signing and specify the key file. Uses Tinycrypt library. ```kconfig CONFIG_ESP_SIGN_EC256=y # Use Tinycrypt lib for EC256 or ED25519 signing CONFIG_ESP_USE_TINYCRYPT=y CONFIG_ESP_SIGN_KEY_FILE= ``` -------------------------------- ### Flash Images for Mark OK Test Source: https://docs.mcuboot.com/testplan-zephyr.html Repeat flashing 'hello1' and 'hello2' to prepare for testing the 'mark OK' functionality. ```bash $ make flash_hello1 $ make flash_hello2 ``` -------------------------------- ### MCUboot Response Structure Source: https://docs.mcuboot.com/PORTING.html This structure is populated by `boot_go` and provides details about the image to be executed, including its header and flash location. ```c struct boot_rsp { /** A pointer to the header of the image to be executed. */ const struct image_header *br_hdr; /** * The flash offset of the image to execute. Indicates the position of * the image header. */ uint8_t br_flash_id; uint32_t br_image_addr; }; ``` -------------------------------- ### Configure ED25519 Signing Algorithm Source: https://docs.mcuboot.com/readme-espressif.html Enable ED25519 signing and specify the key file. Uses Tinycrypt library. ```kconfig CONFIG_ESP_SIGN_ED25519=y # Use Tinycrypt lib for EC256 or ED25519 signing CONFIG_ESP_USE_TINYCRYPT=y CONFIG_ESP_SIGN_KEY_FILE= ``` -------------------------------- ### Build MCUboot and Application with Sysbuild Source: https://docs.mcuboot.com/readme-zephyr.html Builds MCUboot and a Zephyr application (e.g., hello_world) together using Zephyr's sysbuild. This method integrates MCUboot configuration automatically. ```bash cd samples/hello_world west build -b --sysbuild -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y ``` -------------------------------- ### Configure Bootutil Dependencies in pkg.yml Source: https://docs.mcuboot.com/signed_images.html Includes the necessary `bootutil` dependency in the `pkg.yml` file for image signing functionality. ```yaml pkg.name: libs/mykeys pkg.deps: - "@apache-mynewt-core/boot/bootutil" ``` -------------------------------- ### Multiple Image Boot Memory Layout Source: https://docs.mcuboot.com/design.html Illustrates the memory partitioning for multiple executable images in MCUboot, including primary and secondary slots for each image, and a scratch area. ```text +--------------------+ | MCUboot | +--------------------+ ~~~~~ <- memory might be not contiguous +--------------------+ | Image 0 | | primary slot | +--------------------+ | Image 0 | | secondary slot | +--------------------+ ~~~~~ <- memory might be not contiguous +--------------------+ | Image N | | primary slot | +--------------------+ | Image N | | secondary slot | +--------------------+ | Scratch | +--------------------+ ``` -------------------------------- ### ESP32 Memory Map Diagram Source: https://docs.mcuboot.com/readme-espressif.html Illustrates the memory organization for the ESP32, showing bootloader segments and OS reclaimable RAM. Addresses and sizes are defined in `boot/espressif/port/include//memory.h` and the linker script is `boot/espressif/port//ld/bootloader.ld`. ```text SRAM0 IRAM ADDR / DRAM ADDR * +--------+--------------+------+ 0x40070000 / --------- - SRAM0 START * | ^ | * | | PRO CPU Cache | *NOT CLAIMABLE BY OS RAM (first 0x8000 of `SRAM0_CACHE_SIZE`) * | v | * +--------+--------------+------+ 0x40078000 / ---------- * | ^ | * | | | *NOT CLAIMABLE BY OS RAM * | | iram_loader_seg | *Region usable as iram_loader_seg during boot * | | (APP CPU Cache) | as APP CPU is not initialized yet * | | | * | v | * +--------+--------------+------+ 0x4007A800 / ---------- * | ^ | * | | FREE | *CLAIMABLE BY OS RAM (tail of 64 KiB cache window) * | v | * +------------------------------+ 0x40080000 / ---------- * | ^ | * | | FREE | *CLAIMABLE BY OS RAM * | v | * +------------------------------+ 0x40090000 / ---------- * | ^ | * | | iram_seg | *CLAIMABLE BY OS RAM (length 0xE800) * | | | * | v | * +--------+--------------+------+ 0x4009E800 / ---------- * | | FREE | *CLAIMABLE BY OS RAM * +------------------------------+ 0x4009FFFF / ---------- - SRAM0 END SRAM1 IRAM ADDR / DRAM ADDR * +------------------------------+ 0x400A0000 / 0x3FFFFFFF - SRAM1 START * | ^ | * | | | *** SHOULD NOT BE OVERLAPPED *** * | | dram_loader_seg | *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP *** * | | | (length 0x1800; IRAM 0x400A0000-0x400A1800, * | | | DRAM 0x3FFFE800-0x3FFFFFFF) * | v | * +--------+--------------+------+ 0x400A1800 / 0x3FFFE800 * | ^ | * | | | * | | dram_seg | *CLAIMABLE BY OS RAM * | | | (length 0xC800; DRAM 0x3FFF2000-0x3FFFE800) * | v | * +--------+--------------+------+ 0x400AE000 / 0x3FFF2000 * | ^ | * | | | * | | FREE | *CLAIMABLE BY OS RAM * | | | * | v | * +--------+--------------+------+ 0x400BFFFF / 0x3FFE0000 - SRAM1 END SRAM2 IRAM ADDR / DRAM ADDR * +--------+--------------+------+ ---------- / 0x3FFAE000 - SRAM2 START * | | FREE | *CLAIMABLE BY OS RAM * +--------+--------------+------+ ---------- / 0x3FFDFFFF - SRAM2 END ``` -------------------------------- ### Implement SHA Context and Functions Source: https://docs.mcuboot.com/custom_crypto.html Define the SHA context type and the init, drop, update, and finish functions for image hashing. The implementation must match the hash algorithm selected in your MCUboot configuration. ```c /* Context type */ typedef bootutil_sha_context; static inline int bootutil_sha_init(bootutil_sha_context *ctx); static inline int bootutil_sha_drop(bootutil_sha_context *ctx); static inline int bootutil_sha_update(bootutil_sha_context *ctx, const void *data, uint32_t data_len); static inline int bootutil_sha_finish(bootutil_sha_context *ctx, uint8_t *output); ``` -------------------------------- ### Sign Application Image Source: https://docs.mcuboot.com/readme-espressif.html Use this command to sign an application image with MCUboot headers and trailers. Ensure to replace placeholders like , , and with your specific values. For Zephyr images, the --pad-header option is not required. ```bash imgtool.py sign --align 4 -v 0 -H 32 --pad-header -S ``` -------------------------------- ### Implement HMAC-SHA256 Helper Functions Source: https://docs.mcuboot.com/custom_crypto.html Define the HMAC-SHA256 context type and the init, drop, set_key, update, and finish functions. These are optional helpers used by the stock image encryption implementation. ```c typedef bootutil_hmac_sha256_context; static inline void bootutil_hmac_sha256_init( bootutil_hmac_sha256_context *ctx); static inline void bootutil_hmac_sha256_drop( bootutil_hmac_sha256_context *ctx); static inline int bootutil_hmac_sha256_set_key( bootutil_hmac_sha256_context *ctx, const uint8_t *key, uint32_t key_len); static inline int bootutil_hmac_sha256_update( bootutil_hmac_sha256_context *ctx, const void *data, uint32_t data_len); static inline int bootutil_hmac_sha256_finish( bootutil_hmac_sha256_context *ctx, uint8_t *output, uint32_t output_len); ``` -------------------------------- ### Image Compression Options Source: https://docs.mcuboot.com/imgtool.html Enable image compression using LZMA2. The tool will automatically fall back to no compression if compression increases the image size. ```bash imgtool --compression lzma2 input.img ``` -------------------------------- ### Flash Signed Application Source: https://docs.mcuboot.com/readme-espressif.html Flash the signed application image to the target device using esptool.py. Replace , , , , , , and with your device's specific parameters. ```bash esptool.py -p -b --before default_reset --after hard_reset --chip write_flash --flash_mode dio --flash_size --flash_freq ``` -------------------------------- ### Upload Image via Serial Bootloader Source: https://docs.mcuboot.com/readme-mynewt.html Upload a new image using the serial bootloader, specifying the serial port and MTU. Ensure MTU is 256 or less. ```bash newtmgr --conntype serial --connstring "dev=/dev/ttyUSB0,mtu=256" image upload -e blinky.img ``` -------------------------------- ### Build MCUboot Bootloader Source: https://docs.mcuboot.com/readme-zephyr.html Build the MCUboot bootloader using the west build command. Ensure you are in the correct directory and specify your target board. ```bash cd boot/zephyr west build -b ``` -------------------------------- ### Sign Bootloader Image Source: https://docs.mcuboot.com/readme-espressif.html Sign the bootloader binary using the generated signing key with the `espsecure.py` tool. This ensures the integrity and authenticity of the bootloader. ```bash espsecure.py sign_data --version 2 --keyfile -o ``` -------------------------------- ### Define Bootloader Signing Keys in C Source: https://docs.mcuboot.com/signed_images.html Defines an array of signing keys for the bootloader, using the C array generated from the public key DER file. ```c #include #include "image_sign_pub.c.import" const struct bootutil_key bootutil_keys[] = { [0] = { .key = image_sign_pub_der, .len = &image_sign_pub_der_len, } }; const int bootutil_key_cnt = sizeof(bootutil_keys) / sizeof(bootutil_keys[0]); ``` -------------------------------- ### Extract Public Key in C Source Format with imgtool Source: https://docs.mcuboot.com/encrypted_images.md Extract the public key from a generated private key file in C source code format. The encoding defaults to lang-c. ```bash imgtool getpub -k -e ``` -------------------------------- ### Sign Image with imgtool Source: https://docs.mcuboot.com/imgtool.html The `imgtool sign` command prepares binary or Intel HEX images by adding headers and trailers for bootloader compatibility. It supports various options for customization, including vendor/class identifiers, hashing algorithms, and signature formats. ```bash Usage: imgtool sign [OPTIONS] INFILE OUTFILE Create a signed or unsigned image INFILE and OUTFILE are parsed as Intel HEX if the params have .hex extension, otherwise binary format is used Options: --vid TEXT Unique vendor identifier, format: (| --cid TEXT Unique image class identifier, format: (|) --vector-to-sign [payload|digest] send to OUTFILE the payload or payloads digest instead of complied image. These data can be used for external image signing --hmac-sha [auto|256|512] sha algorithm used in HKDF/HMAC in ECIES key exchange TLV --sha [auto|256|384|512] selected sha algorithm to use; defaults to "auto" which is 256 if no cryptographic signature is used, or default for signature type --sig-out filename Path to the file to which signature will be written. The image signature will be encoded as base64 formatted string --pure Expected Pure variant of signature; the Pure variant is expected to be signature done over an image rather than hash of that image. --fix-sig-pubkey filename public key relevant to fixed signature --fix-sig filename fixed signature for the image. It will be used instead of the signature calculated using the public key -k, --key filename --public-key-format [hash|full] In what format to add the public key to the image manifest: full key or hash of the key. --max-align [8|16|32] Maximum flash alignment. Set if flash alignment of the primary and secondary slot differ and any of them is larger than 8. --align [1|2|4|8|16|32] Alignment used by swap update modes. Set if flash alignment of the primary and secondary slot differ and any of them is larger than 8. -v, --version TEXT [required] -s, --security-counter TEXT Specify the value of security counter. Use the `auto` keyword to automatically generate it from the image version. -d, --dependencies TEXT Add dependence on another image, format: "(,), ... " --pad-sig Add 0-2 bytes of padding to ECDSA signature (for mcuboot <1.5) -H, --header-size INTEGER [required] --pad-header Add --header-size zeroed bytes at the beginning of the image -S, --slot-size INTEGER Size of the slot. If the slots have different sizes, use the size of the secondary slot. [required] --pad Pad image to --slot-size bytes, adding trailer magic --test When padding the image, mark it for a test swap (implies --pad) --confirm When padding the image, mark it as confirmed (implies --pad) -M, --max-sectors INTEGER When padding allow for this amount of sectors (defaults to 128) --boot-record sw_type Create CBOR encoded boot record TLV. The sw_type represents the role of the software component (e.g. CoFM for coprocessor firmware). [max. 12 characters] --overwrite-only Use overwrite-only instead of swap upgrades -e, --endian [little|big] Select little or big endian -c, --clear Output a non-encrypted image with encryption ``` -------------------------------- ### Build and Load MCUboot for Overwrite Functionality Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load MCUboot specifically for testing the overwrite-only functionality. ```bash newt build k64f_boot_rsa_noswap newt load k64f_boot_rsa_noswap ``` -------------------------------- ### Extract Public Key in PEM Format with imgtool Source: https://docs.mcuboot.com/encrypted_images.md Extract the public key from a generated private key file in PEM format. ```bash imgtool getpub -k -e pem ``` -------------------------------- ### List Images on Device Source: https://docs.mcuboot.com/serial_recovery.html Lists all images currently present on the device, including their versions, bootable status, flags, and hashes, using the 'serial_1' connection. This command requires the connection to be established first. ```bash mcumgr image list -c serial_1 ``` -------------------------------- ### Build and Load MCUboot for Slot 0 Validation Source: https://docs.mcuboot.com/testplan-mynewt.html Build and load MCUboot to test the slot 0 validation feature. ```bash newt build k64f_boot_rsa_validate0 newt load k64f_boot_rsa_validate0 ``` -------------------------------- ### Test Slot 0 Validation with Non-Signed Image Source: https://docs.mcuboot.com/testplan-mynewt.html Build a non-signed image, load it, and reset. No image should run, validating the slot 0 protection. ```bash newt create-image k64f_blinky 1.0.1 newt load k64f_blinky ``` -------------------------------- ### Default Image Trailer Magic (8-byte Align) Source: https://docs.mcuboot.com/design.html Specifies the 16-byte magic value for the image trailer when BOOT_MAX_ALIGN is 8 bytes. ```c const union boot_img_magic_t boot_img_magic = { .val = { 0x77, 0xc2, 0x95, 0xf3, 0x60, 0xd2, 0xef, 0x7f, 0x35, 0x52, 0x50, 0x0f, 0x2c, 0xb6, 0x79, 0x80 } }; ``` -------------------------------- ### Generate Bootloader Signing Key Source: https://docs.mcuboot.com/readme-espressif.html Generate a new signing key for the bootloader using the `espsecure.py` tool. This key is essential for signing the bootloader image. ```bash espsecure.py generate_signing_key --version 2 ``` -------------------------------- ### Create a signed Git tag for release candidate Source: https://docs.mcuboot.com/release.html Create a signed tag for release candidates using `git tag -s`. Ensure your Git client is configured for signing and your public key is trusted. ```git git tag -s va.b.c-rcn ``` -------------------------------- ### Configure RSA Signing Algorithm Source: https://docs.mcuboot.com/readme-espressif.html Enable RSA signing (2048 or 3072 bits) and specify the key file. Uses Mbed TLS library. ```kconfig CONFIG_ESP_SIGN_RSA=y # RSA_LEN is 2048 or 3072 CONFIG_ESP_SIGN_RSA_LEN= # Use Mbed TLS lib for RSA image signing CONFIG_ESP_USE_MBEDTLS=y CONFIG_ESP_SIGN_KEY_FILE= ``` -------------------------------- ### Generate RSA-2048 Keypair with imgtool Source: https://docs.mcuboot.com/readme-zephyr.html Use this command to generate a new RSA-2048 key pair using the `imgtool.py` script. The `-k` option specifies the output filename for the key pair. ```bash $ ./scripts/imgtool.py keygen -k mykey.pem -t rsa-2048 ``` -------------------------------- ### Sign MCUboot Image with imgtool Source: https://docs.mcuboot.com/readme-espressif.html Sign the binary image using imgtool.py with specified parameters. The `--pad-header` option is not needed for Zephyr images. ```bash imgtool.py sign -k --pad --pad-sig --align 4 -v 0 -H 32 --pad-header -S 0x00100000 ``` -------------------------------- ### FIH Testing Sequence in CI Source: https://docs.mcuboot.com/design.html This pseudocode outlines the sequence of operations for testing FIH in the CI environment, including Docker image generation, compilation, image corruption, and QEMU-based fault injection testing. ```pseudocode fn main() # Implemented in ci/fih-tests_install.sh generate_docker_image(Dockerfile) # See details below. Implemented in ci/fih-tests_run.sh. # Calling the function with different parameters is done by Travis CI based on # the values provided in the .travis.yaml start_docker_image(skip_sizes, build_type, damage_type, fih_level) fn start_docker_image(skip_sizes, build_type, damage_type, fih_level) # implemented in ci/fih_test_docker/execute_test.sh compile_mcuboot(build_type) # implemented in ci/fih_test_docker/damage_image.py damage_image(damage_type) # implemented in ci/fih_test_docker/run_fi_test.sh ranges = generate_address_ranges() for s in skip_sizes for r in ranges do_skip_in_qemu(s, r) # See details below evaluate_logs() fn do_skip_in_qemu(size, range) for a in r run_qemu(a, size) # See details below # this part is implemented in ci/fih_test_docker/fi_tester_gdb.sh fn run_qemu(a, size) script = create_debugger_script(a, size) start_qemu_in_bacground() # logs serial out to a file gdb_attach_to_qemu(script) kill_qemu() # This checks the debugger and the quemu logs, and decides whether the tets # was executed successfully, and whether the image is booted or not. Then # emits a yaml fragment on the standard out to be processed by the caller # script evaluate_run(qemu_log_file) ```