Lines Matching +full:check +full:- +full:signed +full:- +full:off +full:- +full:by
1 # [Building and using MCUboot with Espressif's chips](#building-and-using-mcuboot-with-espressifs-c…
3 The MCUBoot Espressif's port depends on HAL (Hardware Abstraction Layer) sources based on ESP-IDF
4 or 3rd party frameworks as such as Zephyr-RTOS (`zephyrproject-rtos/hal_espressif/`) or NuttX RTOS
5 (`espressif/esp-hal-3rdparty`). Building the MCUboot Espressif's port and its features is platform
7 standalone build version means that ESP-IDF and its toolchain are used as source. For 3rd parties
13 ## [SoC support availability](#soc-support-availability)
17 | | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 |
18 | :----: | :-----: | :-----: | :-----: | :-----: | :---------: | :-----: | :-----: |
24 [Memory map organization for OS compatibility](#memory-map-organization-for-os-compatibility).
26 ## [Installing requirements and dependencies](#installing-requirements-and-dependencies)
37 pip3 install --user -r scripts/requirements.txt
40 2. Update the Mbed TLS submodule required by MCUboot:
43 git submodule update --init --recursive ext/mbedtls
46 3. If ESP-IDF is the chosen option for use as HAL layer and the system already have ESP-IDF
57 ---
60 *If desirable, instructions for ESP-IDF installation can be found
61 …[here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#manual-i…
63 ---
65 ---
68 *The other HALs mentioned above like `hal_espressif` from Zephyr RTOS or `esp-hal-3rdparty`
73 ---
75 4. If ESP-IDF is not installed and will not be used, install `esptool`:
81 ## [Building the bootloader itself](#building-the-bootloader-itself)
83 The MCUboot Espressif port bootloader is built using the toolchain and tools provided by Espressif.
86 `-DMCUBOOT_CONFIG_FILE` argument on the first step below.
88 ---
93 ---
98 …e -DCMAKE_TOOLCHAIN_FILE=tools/toolchain-<TARGET>.cmake -DMCUBOOT_TARGET=<TARGET> -DESP_HAL_PATH=<…
102 ninja -C build/
105 ---
108 *If using ESP-IDF as HAL layer source, `ESP_HAL_PATH` can be ommited.*
115 ---
120 ninja -C build/ flash
129 …sptool.py -p <PORT> -b <BAUD> --before default_reset --after no_reset --chip <TARGET> write_flash …
132 ---
142 esptool.py -p <PORT> -b <BAUD> flash_id
153 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 |
154 | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: |
157 ---
161 ## [Signing and flashing an application](#signing-and-flashing-an-application)
163 1. Images can be regularly signed with the `scripts/imgtool.py` script:
166 imgtool.py sign --align 4 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNED_BIN>
169 ---
176 For Zephyr images, `--pad-header` is not needed as it already has the padding for MCUboot
179 ---
185 section [MCUboot image signature verification](#mcuboot-image-signature-verification) below.*
187 ---
189 2. Flash the signed application:
192 …tool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET> write_flash…
195 # [Downgrade prevention](#downgrade-prevention)
207 Version number is added to the image when signing it with `imgtool` (`-v` parameter, e.g.
208 `-v 1.0.0`).
210 ### [Downgrade prevention with security counter](#downgrade-prevention-with-security-counter)
213 `imgtool` (`-s` parameter), apart from version number. This allows image downgrade at some extent,
221 E.g.: if the current image was signed using `-s 1` parameter, an eventual update image must have
222 been signed using security counter `-s 1` or greater.
224 # [Security Chain on Espressif port](#security-chain-on-espressif-port)
227 external storage is available (see [Threat model](encrypted_images.md#threat-model)) since by
229 Espressif chips have off-chip flash memory, so to ensure a security chain along with MCUboot image
230 signature verification, the hardware-assisted Secure Boot and Flash Encryption were made available
233 ## [MCUboot image signature verification](#mcuboot-image-signature-verification)
235 The image that MCUboot is booting can be signed with 4 types of keys: RSA-2048, RSA-3072, EC256 and
239 ---
245 ---
283 is not supported by Espressif port.
285 ### [Signing the image](#signing-the-image)
287 Now you need to sign the **image binary**, use the `imgtool` with `-k` parameter:
290 imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 4 -v 0 -H 32 --pad-header -S 0x00…
293 If signing a Zephyr image, the `--pad-header` is not needed, as it already have the padding for
297 ## [Secure Boot](#secure-boot)
300 …Secure Boot V2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v…
301 is hardware-assisted and RSA based - except ESP32-C2 that uses ECDSA signing scheme - and has the
303 bootloader signature checking by the ROM bootloader.
308 ### [Building bootloader with Secure Boot](#building-bootloader-with-secure-boot)
318 For the currently supported chips, with exception of ESP32-C2, enable RSA signing scheme:
325 For ESP32-C2, enable ECDSA signing scheme and, if working with Flash Encryption too, enable the
334 ---
348 ---
350 ---
353 *You can disable UART Download Mode by adding the following configuration:*
371 ---
373 Once the **bootloader image** is built, the resulting binary file is required to be signed with
379 espsecure.py generate_signing_key --version 2 <BOOTLOADER_SIGNING_KEY.pem>
385 espsecure.py sign_data --version 2 --keyfile <BOOTLOADER_SIGNING_KEY.pem> -o <BOOTLOADER_BIN_OUT> <…
388 ---
395 ---
397 Flash the bootloader as following, with `--after no_reset` flag, so you can reset the device only
401 esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --f…
404 ### [Secure Boot Process](#secure-boot-process)
407 authenticity. The signature block contains the RSA-3072 signature of that image and the RSA-3072
416 2. Bootloader calculates the SHA-256 hash digest of the public key and writes the result to eFuse.
429 1. Compare the SHA-256 hash digest of the public key embedded in the bootloader’s signature
433 3. Use the public key to verify the signature of the bootloader image, using RSA-PSS with the
439 ## [Flash Encryption](#flash-encryption)
441 The Espressif Flash Encryption is hardware-assisted, transparent to the MCUboot process and is an
444 [IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html)
445 and is intended for encrypting off-chip flash memory contents, so it is protected against physical
453 ### [Building bootloader with Flash Encryption](#building-bootloader-with-flash-encryption)
471 ---
487 ---
489 ---
492 *Unless the recommended flags for __DEVELOPMENT MODE__ were enabled, the actions made by Flash
500 *In the same way as Secure Boot feature, you can disable UART Download Mode by adding the following
519 ---
521 …ning the image when working with Flash Encryption](#signing-the-image-when-working-with-flash-encr…
523 When enabling flash encryption, it is required to signed the image using 32-byte alignment:
524 `--align 32 --max-align 32`.
529 imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 32 --max-align 32 -v 0 -H 32 --pa…
532 ### [Device generated key](#device-generated-key)
538 esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --f…
542 esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --f…
548 2. Encrypt flash in-place including bootloader, image primary/secondary slot and scratch.
552 ### [Host generated key](#host-generated-key)
555 the SPI Flash. Also ensure that the **UART ROM Download Mode is not disabled** - or that the
566 ---
572 ---
574 - ESP32
577 espefuse.py --port PORT burn_key flash_encryption <FLASH_ENCRYPTION_KEY.bin>
580 - ESP32S2, ESP32C3 and ESP32S3
583 espefuse.py --port PORT burn_key BLOCK <FLASH_ENCRYPTION_KEY.bin> <KEYPURPOSE>
597 esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --f…
601 esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --f…
606 1. Encrypt flash in-place including bootloader, image primary/secondary slot and scratch using the
613 - ESP32
616 espsecure.py encrypt_flash_data --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --out…
619 - ESP32-S2, ESP32-C3 and ESP32-S3
622 espsecure.py encrypt_flash_data --aes_xts --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFF…
625 ---
630 pre-encrypted data is sent for an OTA update, it would be wrongly double-encrypted when the update
636 ---
638 ## [Security Chain scheme](#security-chain-scheme)
642 in the off-chip flash are protected against undesirable reading.
651 ### [Size Limitation](#size-limitation)
655 MCUboot image signing. The issue <https://github.com/mcu-tools/mcuboot/issues/1262> was created to
658 ## [Multi image](#multi-image)
661 (each one has its own primary and secondary slot) by MCUboot.
665 ### [Host OS boots second image](#host-os-boots-second-image)
693 ### [Multi boot](#multi-boot)
698 only supported by Espressif multi core chips - currently only ESP32 is implemented.
700 ---
705 ---
734 ### [Image version dependency](#image-version-dependency)
736 MCUboot allows version dependency check between the images when updating them. As `imgtool.py`
741 imgtool.py sign --align 4 -v <VERSION> -d "(<IMAGE_INDEX>, <VERSION_DEPENDENCY>)" -H 32 --pad-heade…
744 - `<VERSION>` defines the version of the image being signed.
745 - `"(<IMAGE_INDEX>, <VERSION_DEPENDENCY>)"` defines the minimum version and from which image is
748 ---
752 imgtool.py sign --align 4 -v 1.0.0 -d "(1, 0.0.1+0)" -H 32 --pad-header -S 0x100000 image0.bin imag…
755 Supposing that the image 0 is being signed, its version is 1.0.0 and it depends on image 1 with
758 ---
760 ## [Serial recovery mode](#serial-recovery-mode)
763 <https://github.com/apache/mynewt-mcumgr-cli>) for communicating and uploading a firmware to the
774 # GPIO input type (0 for Pull-down, 1 for Pull-up)
797 ### [Serial Recovery through USB JTAG Serial port](#serial-recovery-through-usb-jtag-serial-port)
799 Some chips, like ESP32-C3 and ESP32-S3 have an integrated USB JTAG Serial Controller that
803 - ESP32-C3: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jt…
804 - ESP32-S3: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/usb-serial-jt…
805 - ESP32-C6: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-guides/usb-serial-jt…
806 - ESP32-H2: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-guides/usb-serial-jt…
818 # GPIO input type (0 for Pull-down, 1 for Pull-up)
826 ---
832 ---
834 ### [MCUMGR image upload example](#mcumgr-image-upload-example)
845 mcumgr -c esp image upload <IMAGE_BIN>
850 mcumgr -c esp reset
853 ---
859 ---
861 ## [Memory map organization for OS compatibility](#memory-map-organization-for-os-compatibility)
866 unavailable, it is reclaimable by the OS after boot as heap.
870 ---
874 ammount: IRAM (accessed by the instruction bus) and DRAM (accessed by the data bus), which means
875 that they need to be accessed by different addresses ranges depending on type, but refer to the
877 [Espressif TRMs](https://www.espressif.com/en/support/documents/technical-documents?keys=&field_dow…
879 ---
892 * +--------+--------------+------+ 0x40070000 / --------- - SRAM0 START
894 * | | PRO CPU Cache | *NOT CLAIMABLE BY OS RAM
896 * +--------+--------------+------+ 0x40078000 / ----------
898 * | | | *NOT CLAIMABLE BY OS RAM
903 * +--------+--------------+------+ 0x40080000 / ----------
905 * | | FREE | *CLAIMABLE BY OS RAM
907 * +------------------------------+ 0x40090000 / ----------
909 * | | iram_seg | *CLAIMABLE BY OS RAM
912 * +--------+--------------+------+ 0x40099000 / ----------
913 * | | FREE | *CLAIMABLE BY OS RAM
914 * +------------------------------+ 0x4009FFFF / ---------- - SRAM0 END
918 * +------------------------------+ 0x400A0000 / 0x3FFFFFFF - SRAM1 START
923 * +--------+--------------+------+ 0x400AB900 / 0x3FFF4700
927 * | | FREE | *CLAIMABLE BY OS RAM
931 * +--------+--------------+------+ 0x400BFFFF / 0x3FFE0000 - SRAM1 END
938 * +--------+--------------+------+ ---------- / 0x3FFAE000 - SRAM2 START
939 * | | FREE | *CLAIMABLE BY OS RAM
940 * +--------+--------------+------+ ---------- / 0x3FFDFFFF - SRAM2 END
946 ([Multi boot](#multi-boot)) since APP CPU Cache region cannot be used for `iram_loader_seg` region
953 * +--------+--------------+------+ 0x40070000 / --------- - SRAM0 START
956 * | | Cache | *Used by PRO CPU and APP CPU as Cache
959 * +--------+--------------+------+ 0x40080000 / ----------
961 * | | FREE | *CLAIMABLE BY OS RAM
963 * +------------------------------+ 0x40090000 / ----------
965 * | | iram_seg | *CLAIMABLE BY OS RAM
968 * +--------+--------------+------+ 0x40099000 / ----------
969 * | | FREE | *CLAIMABLE BY OS RAM
970 * +------------------------------+ 0x4009FFFF / ---------- - SRAM0 END
974 * +------------------------------+ 0x400A0000 / 0x3FFFFFFF - SRAM1 START
979 * +--------+--------------+------+ 0x400AB900 / 0x3FFF4700
985 * +------------------------------+ 0x400B1E00 / 0x3FFEE200
988 * | | FREE | *CLAIMABLE BY OS RAM
991 * +--------+--------------+------+ 0x400BFFFF / 0x3FFE0000 - SRAM1 END
998 * +--------+--------------+------+ ---------- / 0x3FFAE000 - SRAM2 START
999 * | | FREE | *CLAIMABLE BY OS RAM
1000 * +--------+--------------+------+ ---------- / 0x3FFDFFFF - SRAM2 END
1003 ### ESP32-S2
1008 * +--------+--------------+------+ 0x40020000 / 0x3FFB0000 - SRAM0 START
1009 * | | FREE | *CLAIMABLE BY OS RAM
1010 * +--------+--------------+------+ 0x40027FFF / 0x3FFB7FFF - SRAM0 END
1014 * +--------+--------------+------+ 0x40028000 / 0x3FFB8000 - SRAM1 START
1017 * | | FREE | *CLAIMABLE BY OS RAM
1020 * +--------+--------------+------+ 0x40047000 / 0x3FFD7000
1024 * | | iram_seg | *CLAIMABLE BY OS RAM
1028 * +------------------------------+ 0x40050000 / 0x3FFE0000
1036 * +------------------------------+ 0x40056000 / 0x3FFE6000
1042 * +--------+--------------+------+ 0x4006FFFF / 0x3FFFFFFF - SRAM1 END
1045 ### ESP32-S3
1050 * +--------+--------------+------+ 0x40370000 / ---------- - SRAM0 START
1051 * | | FREE | *CLAIMABLE BY OS RAM
1052 * +--------+--------------+------+ 0x40377FFF / ---------- - SRAM0 END
1056 * +--------+--------------+------+ 0x40378000 / 0x3FC88000 - SRAM1 START
1059 * | | FREE | *CLAIMABLE BY OS RAM
1062 * +--------+--------------+------+ 0x403B0000 / 0x3FCC0000
1066 * | | iram_seg | *CLAIMABLE BY OS RAM
1070 * +------------------------------+ 0x403BA000 / 0x3FCCA000
1078 * +------------------------------+ 0x403C0000 / 0x3FCD0000
1084 * +--------+--------------+------+ 0x403DFFFF / 0x3FCEFFFF - SRAM1 END
1088 * +--------+--------------+------+ ---------- / 0x3FCF0000 - SRAM2 START
1089 * | | FREE | *CLAIMABLE BY OS RAM
1090 * +--------+--------------+------+ ---------- / 0x3FCFFFFF - SRAM2 END
1093 ### ESP32-C2
1098 * +--------+--------------+------+ 0x4037C000 / ---------- - SRAM0 START
1099 * | | FREE | *CLAIMABLE BY OS RAM
1100 * +--------+--------------+------+ 0x4037FFFF / ---------- - SRAM0 END
1104 * +--------+--------------+------+ 0x40380000 / 0x3FCA0000 - SRAM1 START
1108 * | | FREE | *CLAIMABLE BY OS RAM
1112 * +--------+--------------+------+ 0x403A1370 / 0x3FCC1370
1116 * | | iram_seg | *CLAIMABLE BY OS RAM
1120 * +------------------------------+ 0x403A9B70 / 0x3FCC9B70
1128 * +------------------------------+ 0x403B0B70 / 0x3FCD0B70
1134 * +--------+--------------+------+ 0x403BFFFF / 0x3FCDFFFF - SRAM1 END
1137 ### ESP32-C3
1142 * +--------+--------------+------+ 0x4037C000 / ---------- - SRAM0 START
1143 * | | FREE | *CLAIMABLE BY OS RAM
1144 * +--------+--------------+------+ 0x4037FFFF / ---------- - SRAM0 END
1148 * +--------+--------------+------+ 0x40380000 / 0x3FC80000 - SRAM1 START
1152 * | | FREE | *CLAIMABLE BY OS RAM
1156 * +--------+--------------+------+ 0x403C7000 / 0x3FCC7000
1160 * | | iram_seg | *CLAIMABLE BY OS RAM
1164 * +------------------------------+ 0x403D0000 / 0x3FCD0000
1172 * +------------------------------+ 0x403D5400 / 0x3FCD5400
1178 * +--------+--------------+------+ 0x403DFFFF / 0x3FCDFFFF - SRAM1 END
1181 ### ESP32-C6
1185 * +--------+--------------+------+ 0x40800000 / 0x40800000 - HP SRAM START
1189 * | | FREE | *CLAIMABLE BY OS RAM
1193 * +--------+--------------+------+ 0x40860610 / 0x40860610
1197 * | | iram_seg | *CLAIMABLE BY OS RAM
1201 * +------------------------------+ 0x40869610 / 0x40869610
1209 * +------------------------------+ 0x40870610 / 0x40870610
1215 * +--------+--------------+------+ 0x4087FFFF / 0x4087FFFF - HP SRAM END
1218 ### ESP32-H2
1222 * +--------+--------------+------+ 0x40800000 / 0x40800000 - HP SRAM START
1226 * | | FREE | *CLAIMABLE BY OS RAM
1230 * +--------+--------------+------+ 0x408317D0 / 0x408317D0
1234 * | | iram_seg | *CLAIMABLE BY OS RAM
1238 * +------------------------------+ 0x40839FD0 / 0x40839FD0
1246 * +------------------------------+ 0x40840FD0 / 0x40840FD0
1252 * +--------+--------------+------+ 0x4084FFFF / 0x4084FFFF - HP SRAM END