alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

doc(esp32c2): Updates Flash Encryption chapter

Browse Source
This commit is contained in:
KonstantinKondrashov 2022-05-24 21:38:56 +08:00 committed by BOT
parent 0b22839925
commit 6e6b5474c3
5 changed files with 363 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/docs_not_updated/esp32c2.txt
View File

@ -170,4 +170,15 @@ api-reference/protocols/esp_tls
api-reference/protocols/mdns
api-reference/protocols/index
api-reference/protocols/asio
security/flash-encryption
get-started/establish-serial-connection
get-started/macos-setup-scratch
get-started/vscode-setup
get-started/linux-setup-scratch
get-started/eclipse-setup
get-started/windows-setup
get-started/toolchain-setup-scratch
get-started/windows-setup-scratch
get-started/linux-setup
get-started/index
get-started/windows-setup-update
get-started/macos-setup

117
docs/en/security/esp32c2_log.inc
View File

@ -3,8 +3,63 @@
.. code-block:: none
Update with ESP32C2 specific info IDF-4208
ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (21) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (21) boot: compile time 19:36:15
I (21) boot: chip revision: 0
I (24) boot.esp32c2: MMU Page Size : 64K
I (29) boot.esp32c2: SPI Speed : 60MHz
I (34) boot.esp32c2: SPI Mode : DIO
I (39) boot.esp32c2: SPI Flash Size : 2MB
I (43) boot: Enabling RNG early entropy source...
I (49) boot: Partition Table:
I (52) boot: ## Label Usage Type ST Offset Length
I (60) boot: 0 nvs WiFi data 01 02 00010000 00006000
I (67) boot: 1 phy_init RF data 01 01 00016000 00001000
I (75) boot: 2 factory factory app 00 00 00020000 00100000
I (82) boot: End of partition table
I (86) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (101) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168) load
I (104) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (120) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (134) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888) load
I (139) boot: Loaded app from partition at offset 0x20000
I (139) boot: Checking flash encryption...
I (142) efuse: Batch mode of writing fields is enabled
I (148) flash_encrypt: Generating new flash encryption key...
I (155) efuse: Writing EFUSE_BLK_KEY0 with purpose 1
W (161) flash_encrypt: Not disabling UART bootloader encryption
I (167) flash_encrypt: Disable UART bootloader cache...
I (175) flash_encrypt: Disable JTAG...
I (190) efuse: BURN BLOCK3
I (195) efuse: BURN BLOCK3 - OK (write block == read block)
I (204) efuse: BURN BLOCK0
I (208) efuse: BURN BLOCK0 - OK (write block == read block)
I (213) efuse: Batch mode. Prepared fields are committed
I (219) esp_image: segment 0: paddr=00000020 vaddr=3fcd6190 size=02a84h ( 10884)
I (229) esp_image: segment 1: paddr=00002aac vaddr=403ae000 size=00830h ( 2096)
I (236) esp_image: segment 2: paddr=000032e4 vaddr=403b0000 size=042a0h ( 17056)
I (679) flash_encrypt: bootloader encrypted successfully
I (731) flash_encrypt: partition table encrypted and loaded successfully
I (731) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (741) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168)
I (745) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632)
I (759) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (774) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888)
I (776) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)...
I (6429) flash_encrypt: Done encrypting
I (6429) efuse: BURN BLOCK0
I (6432) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (6438) flash_encrypt: Flash encryption completed
I (6443) boot: Resetting with flash encryption enabled...
------
@ -12,7 +67,63 @@
.. code-block:: none
Update with ESP32C2 specific info IDF-4208
ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x3 (RTC_SW_SYS_RST),boot:0xc (SPI_FAST_FLASH_BOOT)
Saved PC:0x403b0f9e
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (23) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (23) boot: compile time 19:36:15
I (23) boot: chip revision: 0
I (27) boot.esp32c2: MMU Page Size : 64K
I (32) boot.esp32c2: SPI Speed : 60MHz
I (36) boot.esp32c2: SPI Mode : DIO
I (41) boot.esp32c2: SPI Flash Size : 2MB
I (46) boot: Enabling RNG early entropy source...
I (51) boot: Partition Table:
I (55) boot: ## Label Usage Type ST Offset Length
I (62) boot: 0 nvs WiFi data 01 02 00010000 00006000
I (70) boot: 1 phy_init RF data 01 01 00016000 00001000
I (77) boot: 2 factory factory app 00 00 00020000 00100000
I (85) boot: End of partition table
I (89) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (103) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168) load
I (107) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (123) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (138) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888) load
I (143) boot: Loaded app from partition at offset 0x20000
I (143) boot: Checking flash encryption...
I (146) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)
I (154) boot: Disabling RNG early entropy source...
I (171) cpu_start: Pro cpu up.
I (179) cpu_start: Pro cpu start user code
I (179) cpu_start: cpu freq: 120000000 Hz
I (179) cpu_start: Application information:
I (182) cpu_start: Project name: hello_world
I (187) cpu_start: App version: v5.0-dev-2717-g0d1e015-dirty
I (194) cpu_start: Compile time: May 20 2022 19:35:55
I (200) cpu_start: ELF file SHA256: 04592ac3c9304cdc...
I (206) cpu_start: ESP-IDF: v5.0-dev-2717-g0d1e015-dirty
I (213) heap_init: Initializing. RAM available for dynamic allocation:
I (220) heap_init: At 3FCABCB0 len 0002C350 (176 KiB): D/IRAM
I (226) heap_init: At 3FCD8000 len 0000742C (29 KiB): STACK/DRAM
I (234) spi_flash: detected chip: generic
I (238) spi_flash: flash io: dio
W (242) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)
I (249) sleep: Configure to isolate all GPIO pins in sleep state
I (256) sleep: Enable automatic switching of GPIO sleep configuration
W (263) INT_WDT: ESP32-C2 only has one timer group
I (268) cpu_start: Starting scheduler.
Hello world!
This is esp32c2 chip with 1 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash
Minimum free heap size: 195052 bytes
FLASH_CRYPT_CNT eFuse value is 1
Flash encryption feature is enabled in DEVELOPMENT mode
------

123
docs/en/security/flash-encryption.rst
View File

@ -100,7 +100,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
@ -122,12 +122,38 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
:header-rows: 0
* - **eFuse**
- **Description**
- **Bit Depth**
* - ``XTS_KEY_LENGTH_256``
- Controls actual number of eFuse bits used to derive final 256-bit AES key. Possible values: ``0`` use all 256 bits of the eFuse block for the key, ``1`` use the lower 128 bits of the eFuse block for the key (the higher 128 bits are reserved for Secure Boot key). For 128 bits option, the final AES key is derived as SHA256(EFUSE_KEY0_FE_128BIT).
- 1
* - ``BLOCK_KEY0``
- AES key storage.
- 256 or 128 key block
* - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``
- If set, disables flash encryption when in download bootmodes.
- 1
* - ``{IDF_TARGET_CRYPT_CNT}``
- Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. note::
* R/W access control is available for all the eFuse bits listed in the table above.
* The default value of these bits is 0 afer manufacturing.
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using espefuse.py, use these two commands: read_protect_efuse and write_protect_efuse. Example ``espefuse.py write_protect_efuse DISABLE_DL_ENCRYPT``.
.. only:: esp32c2
.. important::
{IDF_TARGET_NAME} has only one eFuse key block for both keys: Secure Boot and Flash Encryption. The eFuse key block can only be burned once. Therefore these keys should be burned together at the same time. Please note that "Secure Boot" and "Flash Encryption" can not be enabled separately as subsequent writes to eFuse key block shall return an error.
Flash Encryption Process
------------------------
@ -170,7 +196,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
@ -188,6 +214,24 @@ Assuming that the eFuse values are in their default states and the firmware boot
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
2. Firmware bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
3. Firmware bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`) and then writes it into `BLOCK_KEY0` eFuse. The software also updates the ``XTS_KEY_LENGTH_256`` according to the chosen option. The key cannot be accessed via software as the write and read protection bits for `BLOCK_KEY0` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then ``XTS_KEY_LENGTH_256`` is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the RELEASE mode.
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
5. Firmware bootloader sets the first available bit in ``{IDF_TARGET_CRYPT_CNT}`` (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
6. For :ref:`flash-enc-development-mode`, the firmware bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits are NOT write-protected. In addition, the firmware bootloader by default sets the eFuse bits ``DIS_DOWNLOAD_ICACHE``, ``DIS_PAD_JTAG``, and ``DIS_DIRECT_BOOT``.
7. For :ref:`flash-enc-release-mode`, the firmware bootloader sets all the eFuse bits set under development mode as well as ``DIS_DOWNLOAD_MANUAL_ENCRYPT``. It also write-protects the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
During the development stage, there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires that Firmware Download mode is able to load new plaintext images as many times as it might be needed. However, during manufacturing or production stages, Firmware Download mode should not be allowed to access flash contents for security reasons.
Hence, two different flash encryption configurations were created: for development and for production. For details on these configurations, see Section `Flash Encryption Configuration`_.
@ -231,7 +275,7 @@ To test flash encryption process, take the following steps:
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
:esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default. Note that for the esp32 target, the choice is only available when :ref:`CONFIG_ESP32_REV_MIN` level is set to 3 (ESP32 V3)).
:not esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default.)
:esp32s2 or esp32s3: - Set :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`
:esp32s2 or esp32s3 or esp32c2: - Set :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
- Save the configuration and exit.
@ -275,6 +319,11 @@ It is possible to pre-generate a flash encryption key on the host computer and b
This option is not recommended for production, unless a separate key is generated for each individual device.
.. only:: esp32c2
.. note::
Note that {IDF_TARGET_NAME} only has one eFuse key block for both Secure Boot and Flash Encryption keys. Therefore, writing the host-generated Flash Encryption key must be done with Secure Boot key (if used), otherwise Secure Boot cannot be used.
To use a host generated key, take the following steps:
1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
@ -283,6 +332,12 @@ To use a host generated key, take the following steps:
2. Generate a random key by running:
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
@ -298,12 +353,26 @@ To use a host generated key, take the following steps:
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 key derived from 128 bits (SHA256(128 bits)):
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
3. **Before the first encrypted boot**, burn the key into your device's eFuse using the command below. This action can be done **only once**.
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
@ -341,7 +410,7 @@ To use a host generated key, take the following steps:
espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
@ -349,6 +418,27 @@ To use a host generated key, take the following steps:
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
For AES-128 (256-bit key) - ``XTS_AES_128_KEY`` (the ``XTS_KEY_LENGTH_256`` eFuse will be burn to 1):
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
For AES-128 key derived from 128 bits (SHA256(128 bits)) - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``. The FE key will be written in the lower part of eFuse BLOCK_KEY0, the upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the ``For burning both keys together`` section below, the user can write their data to it using any espefuse commands.
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
For burning both keys together (Secure Boot and Flash Encryption):
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
If the key is not burned and the device is started after enabling flash encryption, the {IDF_TARGET_NAME} will generate a random key that software cannot access or modify.
4. In :ref:`project-configuration-menu`, do the following:
@ -707,6 +797,8 @@ Key Points About Flash Encryption
:esp32c3: - Flash memory contents is encrypted using XTS-AES-128. The flash encryption key is 256 bits and stored in one ``BLOCK_KEYN`` eFuse internal to the chip and, by default, is protected from software access.
:esp32c2: - Flash memory contents is encrypted using XTS-AES-128. The flash encryption key is 256 or 128 bits and stored in ``BLOCK_KEY0`` eFuse internal to the chip and, by default, is protected from software access.
- Flash access is transparent via the flash cache mapping feature of {IDF_TARGET_NAME} - any flash regions which are mapped to the address space will be transparently decrypted when read.
Some data partitions might need to remain unencrypted for ease of access or might require the use of flash-friendly update algorithms which are ineffective if the data is encrypted. NVS partitions for non-volatile storage cannot be encrypted since the NVS library is not directly compatible with flash encryption. For details, refer to :ref:`NVS Encryption <nvs_encryption>`.
@ -804,11 +896,11 @@ On the first boot, the flash encryption process burns by default the following e
- ``DIS_DOWNLOAD_MANUAL_ENCRYPT`` which disables flash encryption operation when running in UART bootloader boot mode.
:esp32s2 or esp32s3: - ``DIS_DOWNLOAD_ICACHE`` and ``DIS_DOWNLOAD_DCACHE`` which disables the entire MMU flash cache when running in UART bootloader mode.
:esp32c3: - ``DIS_DOWNLOAD_ICACHE`` which disables the entire MMU flash cache when running in UART bootloader mode.
:esp32c3 or esp32c2: - ``DIS_DOWNLOAD_ICACHE`` which disables the entire MMU flash cache when running in UART bootloader mode.
:esp32s2: - ``HARD_DIS_JTAG`` which disables JTAG.
:esp32c3: - ``DIS_PAD_JTAG`` and ``DIS_USB_JTAG`` which disables JTAG.
:esp32s3: - ``HARD_DIS_JTAG`` and ``DIS_USB_JTAG`` which disables JTAG.
- ``DIS_LEGACY_SPI_BOOT`` which disables Legacy SPI boot mode
- ``DIS_DIRECT_BOOT`` (old name ``DIS_LEGACY_SPI_BOOT``) which disables direct boot mode
However, before the first boot you can choose to keep any of these features enabled by burning only selected eFuses and write-protect the rest of eFuses with unset value 0. For example:
@ -965,7 +1057,7 @@ The following sections provide some reference information about the operation of
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. _flash-encryption-algorithm:
@ -980,3 +1072,18 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in one ``BLOCK_KEYN`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. _flash-encryption-algorithm:
Flash Encryption Algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^
- {IDF_TARGET_NAME} use the XTS-AES block chiper mode with 256 bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).
- XTS-AES is a block chiper mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g. AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
- The flash encryption key is stored in ``BLOCK_KEY0`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.

11
docs/en/security/secure-boot-v2.rst
View File

@ -31,11 +31,11 @@ Background
Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that each piece of software that is being booted is signed. On an {IDF_TARGET_NAME}, these pieces of software include the second stage bootloader and each application binary. Note that the first stage bootloader does not require signing as it is ROM code thus cannot be changed.
.. only:: not esp32c2
.. only:: SOC_SECURE_BOOT_V2_RSA
A new RSA based Secure Boot verification scheme (Secure Boot V2) has been introduced on the ESP32 (ECO3 onwards), ESP32-S2, ESP32-S3 and ESP32-C3 (ECO3 onwards).
.. only:: esp32c2
.. only:: SOC_SECURE_BOOT_V2_ECC
A new ECC based Secure Boot verification scheme (Secure Boot V2) has been introduced on the ESP32-C2.
@ -162,7 +162,7 @@ The content of each signature block is shown in the following table:
.. note::
R and M' are used for hardware-assisted Montgomery Multiplication.
.. only:: esp32c2
.. only:: SOC_SECURE_BOOT_V2_ECC
.. list-table:: Content of a Signature Block
:widths: 10 10 40
@ -473,6 +473,11 @@ Secure Boot & Flash Encryption
If Secure Boot is used without :doc:`Flash Encryption <flash-encryption>`, it is possible to launch "time-of-check to time-of-use" attack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together.
.. only:: esp32c2
.. important::
{IDF_TARGET_NAME} has only one eFuse key block, which is used for both keys: Secure Boot and Flash Encryption. The eFuse key block can only be burned once. Therefore these keys should be burned together at the same time. Please note that "Secure Boot" and "Flash Encryption" can not be enabled separately as subsequent writes to eFuse key block shall return an error.
.. _signed-app-verify-v2:
Signed App Verification Without Hardware Secure Boot

117
docs/zh_CN/security/esp32c2_log.inc
View File

@ -3,8 +3,63 @@
.. code-block:: none
Update with ESP32C2 specific info IDF-4208
ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (21) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (21) boot: compile time 19:36:15
I (21) boot: chip revision: 0
I (24) boot.esp32c2: MMU Page Size : 64K
I (29) boot.esp32c2: SPI Speed : 60MHz
I (34) boot.esp32c2: SPI Mode : DIO
I (39) boot.esp32c2: SPI Flash Size : 2MB
I (43) boot: Enabling RNG early entropy source...
I (49) boot: Partition Table:
I (52) boot: ## Label Usage Type ST Offset Length
I (60) boot: 0 nvs WiFi data 01 02 00010000 00006000
I (67) boot: 1 phy_init RF data 01 01 00016000 00001000
I (75) boot: 2 factory factory app 00 00 00020000 00100000
I (82) boot: End of partition table
I (86) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (101) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168) load
I (104) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (120) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (134) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888) load
I (139) boot: Loaded app from partition at offset 0x20000
I (139) boot: Checking flash encryption...
I (142) efuse: Batch mode of writing fields is enabled
I (148) flash_encrypt: Generating new flash encryption key...
I (155) efuse: Writing EFUSE_BLK_KEY0 with purpose 1
W (161) flash_encrypt: Not disabling UART bootloader encryption
I (167) flash_encrypt: Disable UART bootloader cache...
I (175) flash_encrypt: Disable JTAG...
I (190) efuse: BURN BLOCK3
I (195) efuse: BURN BLOCK3 - OK (write block == read block)
I (204) efuse: BURN BLOCK0
I (208) efuse: BURN BLOCK0 - OK (write block == read block)
I (213) efuse: Batch mode. Prepared fields are committed
I (219) esp_image: segment 0: paddr=00000020 vaddr=3fcd6190 size=02a84h ( 10884)
I (229) esp_image: segment 1: paddr=00002aac vaddr=403ae000 size=00830h ( 2096)
I (236) esp_image: segment 2: paddr=000032e4 vaddr=403b0000 size=042a0h ( 17056)
I (679) flash_encrypt: bootloader encrypted successfully
I (731) flash_encrypt: partition table encrypted and loaded successfully
I (731) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (741) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168)
I (745) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632)
I (759) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (774) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888)
I (776) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)...
I (6429) flash_encrypt: Done encrypting
I (6429) efuse: BURN BLOCK0
I (6432) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (6438) flash_encrypt: Flash encryption completed
I (6443) boot: Resetting with flash encryption enabled...
------
@ -12,7 +67,63 @@
.. code-block:: none
Update with ESP32C2 specific info IDF-4208
ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x3 (RTC_SW_SYS_RST),boot:0xc (SPI_FAST_FLASH_BOOT)
Saved PC:0x403b0f9e
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (23) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (23) boot: compile time 19:36:15
I (23) boot: chip revision: 0
I (27) boot.esp32c2: MMU Page Size : 64K
I (32) boot.esp32c2: SPI Speed : 60MHz
I (36) boot.esp32c2: SPI Mode : DIO
I (41) boot.esp32c2: SPI Flash Size : 2MB
I (46) boot: Enabling RNG early entropy source...
I (51) boot: Partition Table:
I (55) boot: ## Label Usage Type ST Offset Length
I (62) boot: 0 nvs WiFi data 01 02 00010000 00006000
I (70) boot: 1 phy_init RF data 01 01 00016000 00001000
I (77) boot: 2 factory factory app 00 00 00020000 00100000
I (85) boot: End of partition table
I (89) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (103) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h ( 5168) load
I (107) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (123) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (138) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h ( 5888) load
I (143) boot: Loaded app from partition at offset 0x20000
I (143) boot: Checking flash encryption...
I (146) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)
I (154) boot: Disabling RNG early entropy source...
I (171) cpu_start: Pro cpu up.
I (179) cpu_start: Pro cpu start user code
I (179) cpu_start: cpu freq: 120000000 Hz
I (179) cpu_start: Application information:
I (182) cpu_start: Project name: hello_world
I (187) cpu_start: App version: v5.0-dev-2717-g0d1e015-dirty
I (194) cpu_start: Compile time: May 20 2022 19:35:55
I (200) cpu_start: ELF file SHA256: 04592ac3c9304cdc...
I (206) cpu_start: ESP-IDF: v5.0-dev-2717-g0d1e015-dirty
I (213) heap_init: Initializing. RAM available for dynamic allocation:
I (220) heap_init: At 3FCABCB0 len 0002C350 (176 KiB): D/IRAM
I (226) heap_init: At 3FCD8000 len 0000742C (29 KiB): STACK/DRAM
I (234) spi_flash: detected chip: generic
I (238) spi_flash: flash io: dio
W (242) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)
I (249) sleep: Configure to isolate all GPIO pins in sleep state
I (256) sleep: Enable automatic switching of GPIO sleep configuration
W (263) INT_WDT: ESP32-C2 only has one timer group
I (268) cpu_start: Starting scheduler.
Hello world!
This is esp32c2 chip with 1 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash
Minimum free heap size: 195052 bytes
FLASH_CRYPT_CNT eFuse value is 1
Flash encryption feature is enabled in DEVELOPMENT mode
------