From d4ad53aaef673d2faee58f5fb60a6ad3a5f8a4f2 Mon Sep 17 00:00:00 2001 From: Konstantin Kondrashov Date: Wed, 8 Jul 2026 15:24:37 +0300 Subject: [PATCH] fix(docs): Update bootloader anti-rollback documentation --- docs/en/api-guides/bootloader.rst | 24 ++++++---- docs/zh_CN/api-guides/bootloader.rst | 68 ++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 10 deletions(-) diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 643584d5a71..49011a3c2a6 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -236,22 +236,26 @@ If the bootloader grows too large then it can collide with the partition table, I (67) boot: Partition Table: ... - Anti-Rollback Feature - ^^^^^^^^^^^^^^^^^^^^^ + .. only:: SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED - The anti-rollback feature prevents downgrading to an older, potentially vulnerable bootloader version. The bootloader header includes a security version, defined by ``CONFIG_BOOTLOADER_SECURE_VERSION``. When ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` is set, the ROM bootloader checks this version against the value stored in ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION``. Only bootloaders with a version greater than or equal to the eFuse value are allowed to boot. + Anti-Rollback Feature + ^^^^^^^^^^^^^^^^^^^^^ - - The ROM bootloader can update the secure version in eFuse if ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` is set. - - The secure version value is incremented as new bootloader versions are deployed, and cannot be decreased. - - If the secure version in eFuse is not updated in the ROM bootloader, then the application can update it using the :cpp:func:`esp_efuse_write_field_blob` function. + The anti-rollback feature prevents downgrading to an older, potentially vulnerable bootloader version. The bootloader header includes a security version, defined by ``CONFIG_BOOTLOADER_SECURE_VERSION``. When ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` is set, the ROM bootloader checks this version against the value stored in ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION``. Only bootloaders with a version greater than or equal to the eFuse value are allowed to boot. + + - The ROM bootloader can update the secure version in eFuse if ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` is set. + - The secure version value is incremented as new bootloader versions are deployed, and cannot be decreased. + - If the secure version in eFuse is not updated in the ROM bootloader, then the application can update it using the :cpp:func:`esp_efuse_write_field_blob` function. Relevant eFuses ^^^^^^^^^^^^^^^ - - ``EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` (12 bits): Flash sector address for the recovery bootloader. Default value is 0 (disabled), set any other value to enable, 0xFFF to permanently disable. - - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` (1 bit): Enables anti-rollback check in the ROM bootloader. - - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` (4 bits): Secure version for anti-rollback protection. The value increases as bits are set - 0x0, 0x1, 0x3, 0x7, 0xF. - - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` (1 bit): Allows the ROM bootloader to update the secure version in eFuse. + .. list:: + + - ``EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` (12 bits): Flash sector address for the recovery bootloader. Default value is 0 (disabled), set any other value to enable, 0xFFF to permanently disable. + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` (1 bit): Enables anti-rollback check in the ROM bootloader. + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` (4 bits): Secure version for anti-rollback protection. The value increases as bits are set - 0x0, 0x1, 0x3, 0x7, 0xF. + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` (1 bit): Allows the ROM bootloader to update the secure version in eFuse. .. note:: diff --git a/docs/zh_CN/api-guides/bootloader.rst b/docs/zh_CN/api-guides/bootloader.rst index 67286a0d8c1..28d60265efa 100644 --- a/docs/zh_CN/api-guides/bootloader.rst +++ b/docs/zh_CN/api-guides/bootloader.rst @@ -192,3 +192,71 @@ ESP-IDF 二级引导加载程序位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_O * :example:`storage/nvs/nvs_bootloader` 如果引导加载程序过大，则可能与内存中的分区表重叠，分区表默认烧录在偏移量 0x8000 处。增加 :ref:`分区表偏移量 ` ，将分区表放在 flash 中靠后的区域，这样可以增加引导加载程序的可用空间。 + +.. only:: SOC_RECOVERY_BOOTLOADER_SUPPORTED + + 恢复引导加载程序 + ---------------- + + {IDF_TARGET_NAME} 引入了恢复引导加载程序 (Recovery Bootloader) 和防回滚引导加载程序 (Anti-rollback Bootloader) 功能，这些功能在 ROM 引导加载程序中实现，用于提升设备在 OTA 升级过程中的安全性和可靠性。 + + 恢复引导加载程序功能可在 OTA 升级失败时为引导加载程序提供安全回退机制。eFuse 字段 ``ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` 将指定恢复引导加载程序的 flash（以扇区为单位）地址。如果位于 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 的主引导加载程序加载失败，ROM 引导加载程序会尝试从指定地址加载恢复引导加载程序。 + + - 可以使用 ``espefuse`` 或在用户应用程序中调用 :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` 来设置 eFuse。 + - 该地址可通过 ``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 进行设置，且必须为 flash 扇区大小（0x1000 字节）的整数倍。此 Kconfig 选项有助于确保恢复引导加载程序不会与现有分区重叠。 + - 注意，eFuse 字段存储的是以扇区为单位的偏移量。将其设置为最大值 ``0xFFF`` 可禁用恢复引导加载程序功能。 + - 默认情况下，``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 处的恢复引导加载程序镜像不会被烧录，但可以作为 OTA 升级流程的一部分进行写入。 + + 下方示例展示了主引导加载程序加载失败后，恢复引导加载程序被加载时的引导日志。 + + .. code-block:: none + + ESP-ROM:esp32c5-eco2-20250121 + Build:Jan 21 2025 + rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT) + invalid header: 0xffffffff + invalid header: 0xffffffff + invalid header: 0xffffffff + PRIMARY - FAIL + Loading RECOVERY Bootloader... + SPI mode:DIO, clock div:1 + load:0x408556b0,len:0x17cc + load:0x4084bba0,len:0xdac + load:0x4084e5a0,len:0x3140 + entry 0x4084bbaa + + I (46) boot: ESP-IDF v6.0-dev-172-g12c5d730097-dirty 2nd stage bootloader + I (46) boot: compile time May 22 2025 12:41:59 + I (47) boot: chip revision: v1.0 + I (48) boot: efuse block revision: v0.1 + I (52) boot.esp32c5: SPI Speed : 80MHz + I (55) boot.esp32c5: SPI Mode : DIO + I (59) boot.esp32c5: SPI Flash Size : 4MB + I (63) boot: Enabling RNG early entropy source... + I (67) boot: Partition Table: + ... + + .. only:: SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED + + 防回滚功能 + ^^^^^^^^^^ + + 防回滚功能可防止降级到可能存在安全漏洞的旧版引导加载程序。引导加载程序头部包含安全版本号，由 ``CONFIG_BOOTLOADER_SECURE_VERSION`` 定义。设置 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` 后，ROM 引导加载程序会将该安全版本号与 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` 中存储的值进行比对。只有版本号大于或等于 eFuse 值的引导加载程序才允许启动。 + + - 如果设置了 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM``，ROM 引导加载程序可以更新 eFuse 中的安全版本号。 + - 随着新引导加载程序版本的发布，安全版本号会递增，且不能降低。 + - 如果 ROM 引导加载程序未更新 eFuse 中的安全版本号，则应用程序可以通过 :cpp:func:`esp_efuse_write_field_blob` 函数进行更新。 + + 相关 eFuse + ^^^^^^^^^^ + + .. list:: + + - ``EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` （12 位）：恢复引导加载程序的 flash 扇区地址。默认值为 0（禁用），设置为其他值则启用，设置为 0xFFF 时永久禁用。 + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` （1 位）：在 ROM 引导加载程序中启用防回滚检查。 + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` （4 位）：防回滚保护的安全版本号。该值随位数增加而递增 - 0x0、0x1、0x3、0x7、0xF。 + :SOC_BOOTLOADER_ANTI_ROLLBACK_SUPPORTED: - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` （1 位）：允许 ROM 引导加载程序更新 eFuse 中的安全版本号。 + + .. note:: + + 建议使用以上功能提升设备在 OTA 升级过程中的安全性和可靠性。请谨慎规划 eFuse 的烧录，因为这些设置是永久性的，可能影响未来的升级策略。