From e79b8c1b6aaf2fd01dc2fca7165c5928a16a30d2 Mon Sep 17 00:00:00 2001 From: daiziyan Date: Wed, 27 Oct 2021 10:59:13 +0800 Subject: [PATCH] docs: update CN trans for external-ram and flash-encryption --- docs/en/api-guides/external-ram.rst | 23 +++--- docs/en/security/flash-encryption.rst | 1 + docs/zh_CN/api-guides/external-ram.rst | 56 ++++++++----- docs/zh_CN/security/flash-encryption.rst | 101 +++++++++++------------ 4 files changed, 98 insertions(+), 83 deletions(-) diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index baf27e64c2..93289d580c 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -1,5 +1,4 @@ - -Support for external RAM +Support for External RAM ************************ :link_to_translation:`zh_CN:[中文]` @@ -16,7 +15,7 @@ Introduction Hardware ======== -{IDF_TARGET_NAME} supports SPI PSRAM connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF currently only supports Espressif branded PSRAM chips (ESP-PSRAM32, ESP-PSRAM64, etc). +{IDF_TARGET_NAME} supports SPI PSRAM (Psuedostatic RAM) connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF currently only supports Espressif branded PSRAM chips (e.g., ESP-PSRAM32, ESP-PSRAM64, etc). .. note:: Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and {IDF_TARGET_NAME} device to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. @@ -30,7 +29,7 @@ For specific details about connecting the SoC or module pins to an external PSRA Configuring External RAM ======================== -ESP-IDF fully supports the use of external memory in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to handle it in several ways: +ESP-IDF fully supports the use of external RAM in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to integrate the external RAM in several ways: .. list:: @@ -42,7 +41,7 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte .. _external_ram_config_memory_map: -Integrate RAM into the {IDF_TARGET_NAME} memory map +Integrate RAM into the {IDF_TARGET_NAME} Memory Map --------------------------------------------------- Select this option by choosing "Integrate RAM into memory map" from :ref:`CONFIG_SPIRAM_USE`. @@ -56,7 +55,7 @@ Applications can manually place data in external memory by creating pointers to .. _external_ram_config_capability_allocator: -Add external RAM to the capability allocator +Add External RAM to the Capability Allocator -------------------------------------------- Select this option by choosing "Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)" from :ref:`CONFIG_SPIRAM_USE`. @@ -68,7 +67,7 @@ To allocate memory from external RAM, a program should call ``heap_caps_malloc(s .. _external_ram_config_malloc: -Provide external RAM via malloc() +Provide External RAM via malloc() --------------------------------- Select this option by choosing "Make RAM allocatable using malloc() as well" from :ref:`CONFIG_SPIRAM_USE`. This is the default option. @@ -90,8 +89,8 @@ Because some buffers can only be allocated in internal memory, a second configur .. _external_ram_config_bss: - Allow .bss segment placed in external memory - -------------------------------------------- + Allow .bss Segment to be Placed in External Memory + ------------------------------------------------------- Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`. This configuration setting is independent of the other three. @@ -107,8 +106,8 @@ Because some buffers can only be allocated in internal memory, a second configur .. _external_ram_config_noinit: - Allow .noinit segment placed in external memory - ----------------------------------------------- + Allow .noinit Segment to be Placed in External Memory + -------------------------------------------------------------- Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, a region of the address space provided in external RAM will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart. @@ -156,4 +155,4 @@ Failure to initialize .. include:: inc/external-ram-esp32-notes.rst .. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf -.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf \ No newline at end of file +.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index e9ac215938..2227c6dcce 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -969,6 +969,7 @@ The following sections provide some reference information about the operation of .. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 + .. _flash-encryption-algorithm: Flash Encryption Algorithm diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 4672106f6f..7c7306b63e 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -9,13 +9,13 @@ 简介 ============ -{IDF_TARGET_NAME} 提供了好几百 KB 的片上 RAM，可以满足大部分需求。但有些场景可能需要更多 RAM，因此 {IDF_TARGET_NAME} 另外提供了高达 4 MB 的片外 SPI RAM 存储器以供用户使用。片外 RAM 被添加到内存映射中，在某些范围内与片上 RAM 使用方式相同。 +{IDF_TARGET_NAME} 提供了好几百 KB 的片上 RAM，可以满足大部分需求。但有些场景可能需要更多 RAM，因此 {IDF_TARGET_NAME} 另外提供了高达 4 MB 的片外 SPI RAM 存储器供用户使用。片外 RAM 已经集成到内存映射中，在某些范围内与片上 RAM 使用方式相同。 硬件 ======== -{IDF_TARGET_NAME} 支持与 SPI Flash 芯片并联的 SPI PSRAM。虽然 {IDF_TARGET_NAME} 支持多种类型的 RAM 芯片，但 ESP-IDF 当前仅支持乐鑫品牌的 PSRAM 芯片，如 ESP-PSRAM32、ESP-PSRAM64 等。 +{IDF_TARGET_NAME} 支持与 SPI Flash 芯片并联的 SPI PSRAM（伪静态随机存储器）。虽然 {IDF_TARGET_NAME} 支持多种类型的 RAM 芯片，但 ESP-IDF 当前仅支持乐鑫品牌的 PSRAM 芯片，如 ESP-PSRAM32、ESP-PSRAM64 等。 .. note:: PSRAM 芯片的工作电压分为 1.8 V 和 3.3 V。其工作电压必须与 flash 的工作电压匹配。请查询您 PSRAM 芯片以及 {IDF_TARGET_NAME} 的技术规格书获取准确的工作电压。对于 1.8 V 的 PSRAM 芯片，请确保在启动时将 MTDI 管脚设置为高电平，或者将 {IDF_TARGET_NAME} 中的 eFuses 设置为始终使用 1.8 V 的 VDD_SIO 电平，否则有可能会损坏 PSRAM 和/或 flash 芯片。 @@ -29,7 +29,7 @@ 配置片外 RAM ======================== -ESP-IDF 完全支持将外部存储器集成到您的应用程序中。在启动并完成片外 RAM 初始化后，可以将 ESP-IDF 配置为以多种方式处理片外 RAM： +ESP-IDF 完全支持将片外 RAM 集成到您的应用程序中。在启动并完成片外 RAM 初始化后，可以将 ESP-IDF 配置为用多种方式处理片外 RAM： .. list:: @@ -37,10 +37,10 @@ ESP-IDF 完全支持将外部存储器集成到您的应用程序中。在启动 * :ref:`external_ram_config_capability_allocator` * :ref:`external_ram_config_malloc` (default) :esp32: * :ref:`external_ram_config_bss` + :esp32: * :ref:`external_ram_config_noinit` .. _external_ram_config_memory_map: - 集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射 ------------------------------------------- @@ -60,7 +60,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)" 选项。 -启用上述选项后，片外 RAM 被映射到地址 0x3F800000，并将这个区域添加到 :doc:`堆内存分配器 ` 里携带 ``MALLOC_CAP_SPIRAM`` 的标志 +启用上述选项后，片外 RAM 被映射到地址 0x3F800000，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 ` 。 程序如果想从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。 @@ -74,7 +74,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 启用此选项后，片外存储器将被添加到内存分配程序（与上一选项相同），同时也将被添加到由标准 ``malloc()`` 函数返回的 RAM 中。 -这允许应用程序使用片外 RAM，无需重写代码就能使用 ``heap_caps_malloc(..., MALLOC_CAP_SPIRAM)``。 +应用程序因此可以使用片外 RAM，无需重写代码就能使用 ``heap_caps_malloc(..., MALLOC_CAP_SPIRAM)``。 如果某次内存分配偏向于片外存储器，您也可以使用 :ref:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL` 设置分配空间的大小阈值，控制分配结果： @@ -83,27 +83,35 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 如果优先考虑的内部或外部存储器中没有可用的存储块，分配程序则会选择其他类型存储。 -由于有些 Buffer 仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部存储池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA ` 和 ``MALLOC_CAP_INTERNAL`` 旗标从该池中分配存储器。 +由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部内存池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA ` 和 ``MALLOC_CAP_INTERNAL`` 标志从该池中分配存储器。 .. only:: esp32 - .. _external_ram_config_bss: + .. _external_ram_config_bss: - 允许 .bss 段放入片外存储器 - ----------------------------- + 允许 .bss 段放入片外存储器 + ----------------------------------- - 通过检查 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项，此选项配置与上面三个选项互不影响。 + 通过勾选 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项，此选项配置与其它三个选项互不影响。 - 启用该选项后，从 0x3F800000 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。 + 启用该选项后，从 0x3F800000 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。 - ``EXT_RAM_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。 + ``EXT_RAM_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。 - 也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。 + 也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。 - 启用此选项可以减少 BSS 段占用的内部静态存储。 + 启用此选项可以减少 BSS 段占用的内部静态存储。 - 剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。 + 剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。 + .. _external_ram_config_noinit: + + 允许 .noinit 段放入片外存储器 + ------------------------------------- + + 通过勾选 :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` 启用该选项。启用该选项后，外部 RAM 中提供的地址空间区域将用于存储未初始化的数据。即使在启动或重新启动期间，放置在该段中的值也不会被初始化或修改。 + + 通过应用 ``EXT_RAM_NOINIT_ATTR`` 宏，可以将数据从内部 NOINIT 段移到片外 RAM。剩余的片外 RAM 也可以通过上述方法添加到堆分配器中，具体请参考 :ref:`external_ram_config_capability_allocator`。 片外 RAM 使用限制 =================== @@ -112,9 +120,9 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 * Flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。出于这个原因，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。 - * 片外 RAM 不能用于储存 DMA 事物描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。 + * 片外 RAM 不能用于储存 DMA 事务描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。 - * 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据可以挤出 flash cache，可能会降低代码执行速度。 + * 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据会挤出 flash cache，可能降低代码执行速度。 * 一般来说，片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。 @@ -129,7 +137,17 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 .. only:: esp32 - 如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，忽略失败的选项将无法使用，这是因为在链接时，链接器已经向片外存储器分配符号。 + 如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，忽略失败的选项将无法使用，这是因为在链接时，链接器已经向片外存储器分配标志符。 + + +.. only:: not esp32 + + 加密 + ========== + + 可以为存储在外部 RAM 中的数据启用自动加密功能。启用该功能后，通过缓存读写的任何数据将被外部存储器加密硬件自动加密/解密。 + + 只要启用了 flash 加密功能，就会启用这个功能。关于如何启用 flash 加密以及其工作原理，请参考 :doc:`Flash 加密 `。 .. only:: esp32 diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index e47bc0a9cf..267e965d51 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -52,7 +52,7 @@ Flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制。以下是这 .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES .. list-table:: Flash 加密过程中使用的 eFuses - :widths: 25 40 10 + :widths: 25 40 10 :header-rows: 0 * - **eFuse** @@ -103,7 +103,7 @@ Flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制。以下是这 .. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 .. list-table:: Flash 加密过程中使用的 eFuses - :widths: 25 40 10 + :widths: 25 40 10 :header-rows: 0 * - **eFuse** @@ -283,63 +283,65 @@ Flash 加密设置 2. 通过运行以下命令生成一个随机密钥： -.. only:: esp32s2 + .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 - 如果 :ref:`生成的 AES-XTS 密钥大小 ` 是 AES-256（512 位密钥），则需要使用 `XTS_AES_256_KEY_1` 和 `XTS_AES_256_KEY_2`。espsecure 不支持 512 位密钥，但可以变通一下。 + 如果 :ref:`生成的 AES-XTS 密钥大小 ` 是 AES-128（256 位密钥）： - .. code-block:: bash + .. code-block:: bash - espsecure.py generate_flash_encryption_key my_flash_encryption_key1.bin + espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin - espsecure.py generate_flash_encryption_key my_flash_encryption_key2.bin + 如果 :ref:`生成的 AES-XTS 密钥大小 ` 是 AES-256（512 位密钥）： - # To use encrypt_flash_data with XTS_AES_256 requires combining the two binary files to one 64 byte file - cat my_flash_encryption_key1.bin my_flash_encryption_key2.bin > my_flash_encryption_key.bin + .. code-block:: bash - 如果 :ref:`生成的 AES-XTS 密钥大小 ` 是 AES-128（256 位密钥），则需要使用 `XTS_AES_128_KEY`。 - - .. code-block:: bash - - espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin + espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin -.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256 + .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256 - .. code-block:: bash + .. code-block:: bash - espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin + espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin 3. **在第一次加密启动前**，使用以下命令将该密钥烧录到设备上，这个操作只能执行 **一次**。 -.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES + .. only:: not SOC_FLASH_ENCRYPTION_XTS_AES - .. code-block:: bash + .. code-block:: bash - espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin + espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin -.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 + .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 - .. code-block:: bash + .. code-block:: bash - espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE - - 其中 ``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的空闲密钥区。而 ``KEYPURPOSE`` 是 ``AES_256_KEY_1``、``XTS_AES_256_KEY_2`` 或 ``XTS_AES_128_KEY``。关于密钥目的的描述清参考 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_。 + espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE - AES-128（256 位密钥）- ``XTS_AES_128_KEY``: + 其中 ``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的空闲密钥区。而 ``KEYPURPOSE`` 是 ``AES_256_KEY_1``、``XTS_AES_256_KEY_2`` 或 ``XTS_AES_128_KEY``。关于密钥用途，请参考 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_。 + + 对于 AES-128（256 位密钥）- ``XTS_AES_128_KEY``: .. code-block:: bash espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY - AES-256（512 位密钥）- ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2``。espefuse.py 和 espsecure.py 中还没有完全支持。需要进行如下操作： + 对于 AES-256（512 位密钥）- ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2``。espefuse.py 支持通过虚拟密钥用途 ``XTS_AES_256_KEY`` 将这两个密钥用途和一个 512 位密钥一起烧录到两个独立的密钥块。使用此功能时，``espefuse.py`` 将把密钥的前 256 位烧录到指定的 ``BLOCK``，并把相应的区块密钥用途烧录到 ``XTS_AES_256_KEY_1``。密钥的后 256 位将被烧录到 ``BLOCK`` 后的第一个空闲密钥块，并把相应的密钥用途烧录到 ``XTS_AES_256_KEY_2``。 .. code-block:: bash - espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key1.bin XTS_AES_256_KEY_1 + espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY - espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key2.bin XTS_AES_256_KEY_2 + 如果您想指定使用哪两个区块，则可以将密钥分成两个 256 位密钥，并分别使用 ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2`` 为密钥用途进行手动烧录： -.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 + .. code-block:: bash + + split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin. + espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1 + 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 .. code-block:: bash @@ -347,7 +349,7 @@ Flash 加密设置 其中 ``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的一个空闲密钥区。 -如果未烧录密钥并在启用 flash 加密后启动设备，{IDF_TARGET_NAME} 将生成随机密钥，该密钥软件无法访问或修改。 + 如果未烧录密钥并在启用 flash 加密后启动设备，{IDF_TARGET_NAME} 将生成一个软件无法访问或修改的随机密钥。 4. 在 :ref:`项目配置菜单 ` 中进行如下设置： @@ -367,7 +369,7 @@ Flash 加密设置 .. note:: 这个命令不包括任何应该被写入 flash 分区的用户文件。请在运行此命令前手动写入这些文件，否则在写入前应单独对这些文件进行加密。 - + 该命令将向 flash 写入未加密的镜像：固件引导加载程序、分区表和应用程序。烧录完成后，{IDF_TARGET_NAME} 将重置。在下一次启动时，固件引导加载程序会加密：固件引导加载程序、应用程序分区和标记为 ``加密`` 的分区，然后复位。就地加密可能需要时间，对于大的分区来说可能耗时一分钟。之后，应用程序在运行时被解密并执行。 如果使用开发模式，那么更新和重新烧录二进制文件最简单的方法是 :ref:`encrypt-partitions`。 @@ -412,7 +414,7 @@ Flash 加密设置 - :ref:`启动时使能 flash 加密 ` :esp32: - :ref:`选择发布模式 ` （注意一旦选择了发布模式，``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件） - :esp32: - :ref:`选择 UART ROM 下载模式（推荐永久性禁用）` （注意该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。）默认选项是保持启用 UART ROM 下载模式，然而建议永久禁用该模式，以减少攻击者可用的选项。 + :esp32: - :ref:`选择 UART ROM 下载模式（推荐永久性禁用）` （注意该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。）默认选项是保持启用 UART ROM 下载模式，然而建议永久禁用该模式，以减少攻击者可用的选项。 :not esp32: - :ref:`选择发布模式 ` （注意一旦选择了发布模式，``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件。） :not esp32: - :ref:`选择 UART ROM 下载（推荐永久性的切换到安全模式）`。这是默认且推荐使用的选项。如果不需要该模式，也可以改变此配置设置永久地禁用 UART ROM 下载模式。 - :ref:`选择适当详细程度的引导加载程序日志 ` @@ -430,10 +432,10 @@ Flash 加密设置 .. note:: 这个命令不包括任何应该被写入 flash 分区的用户文件。请在运行此命令前手动写入这些文件，否则在写入前应单独对这些文件进行加密。 - + 该命令将向 flash 写入未加密的镜像：固件引导加载程序、分区表和应用程序。烧录完成后，{IDF_TARGET_NAME} 将重置。在下一次启动时，固件引导加载程序会加密：固件引导加载程序、应用程序分区和标记为 ``加密`` 的分区，然后复位。就地加密可能需要时间，对于大的分区来说可能耗时一分钟。之后，应用程序在运行时被解密并执行。 -一旦在发布模式下启用 flash 加密，引导加载程序将写保护 ``{IDF_TARGET_CRYPT_CNT}`` eFuse。 +一旦在发布模式下启用 flash 加密，引导加载程序将写保护 ``{IDF_TARGET_CRYPT_CNT}`` eFuse。 请使用 :ref:`OTA 方案 ` 对字段中的明文进行后续更新。 @@ -570,7 +572,7 @@ Flash 加密设置 .. _flash-encryption-status: -{IDF_TARGET_NAME} flash 加密状态 +{IDF_TARGET_NAME} flash 加密状态 ----------------------------------------- 1. 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示的 flash 加密 eFuse 的默认设置。 @@ -660,7 +662,7 @@ OTA 更新 .. _updating-encrypted-flash-serial: -通过串口更新加密 flash +通过串口更新加密 flash ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 通过串行引导加载程序烧录加密设备，需要串行引导加载程序下载接口没有通过 eFuse 被永久禁用。 @@ -700,17 +702,17 @@ Flash 加密的要点 .. list:: :esp32: - 使用 AES-256 加密 flash。Flash 加密密钥存储于芯片内部的 ``flash_encryption`` eFuse 中，并（默认）受保护，防止软件访问。 - + :esp32: - Flash 加密算法采用的是 AES-256，其中密钥随着 flash 的每个 32 字节块的偏移地址“调整”。这意味着，每个 32 字节块（2 个连续的 16 字节 AES 块）使用从 flash 加密密钥中产生的一个特殊密钥进行加密。 :esp32s2 or esp32s3: - 使用 XTS-AES-128 或 XTS-AES-256 加密 flash。Flash 加密密钥分别为 256 位和 512 位，存储于芯片内部一个或两个 ``BLOCK_KEYN`` eFuse 中，并（默认）受保护，防止软件访问。 :esp32c3: - 使用 XTS-AES-128 加密 flash。 Flash 加密密钥为 256 位，存储于芯片内部的 ``BLOCK_KEYN`` eFuse 中，并（默认）受保护，防止软件访问。 - + - 通过 {IDF_TARGET_NAME} 的 flash 缓存映射功能，flash 可支持透明访问——任何映射到地址空间的 flash 区域在读取时都将被透明地解密。 - 为便于访问，某些数据分区最好保持未加密状态，或者也可使用对已加密数据无效的 flash 友好型更新算法。由于 NVS 库无法与 flash 加密直接兼容，因此无法加密非易失性存储器的 NVS 分区。详情可参见 :ref:`NVS 加密 `。 - + 为便于访问，某些数据分区最好保持未加密状态，或者也可使用对已加密数据无效的 flash 友好型更新算法。由于 NVS 库无法与 flash 加密直接兼容，因此无法加密非易失性存储器的 NVS 分区。详情可参见 :ref:`NVS 加密 `。 + - 如果以后可能需要启用 flash 加密，则编程人员在编写 :ref:`使用加密 flash ` 代码时需小心谨慎。 - 如果已启用安全启动，重新烧录加密设备的引导加载程序则需要“可重新烧录”的安全启动摘要（可参考 :ref:`flash-encryption-and-secure-boot`）。 @@ -723,7 +725,7 @@ Flash 加密的要点 .. _flash-encryption-limitations: - + Flash 加密的局限性 -------------------- @@ -810,7 +812,7 @@ Flash 加密的高级功能 :esp32s3: - ``HARD_DIS_JTAG`` 和 ``DIS_USB_JTAG`` 禁用 JTAG。 - ``DIS_LEGACY_SPI_BOOT`` 禁用传统的 SPI 启动模式。 -为了能启用这些功能，可在首次启动前仅烧录部分 eFuse，并用未设置值 0 写保护其他部分。例如: +为了能启用这些功能，可在首次启动前仅烧录部分 eFuse，并用未设置值 0 写保护其他部分。例如: .. only:: esp32 @@ -830,7 +832,7 @@ Flash 加密的高级功能 请注意在写保护前设置所有适当的位！ - 一个位可以控制三个 eFuse 的写保护，这意味着写保护一个 eFuse 位将写保护所有未设置的 eFuse 位。 + 一个位可以控制三个 eFuse 的写保护，这意味着写保护一个 eFuse 位将写保护所有未设置的 eFuse 位。 由于 ``esptool.py`` 目前不支持读取加密 flash，所以对这些 eFuse 进行写保护从而使其保持未设置目前来说并不是很有用。 @@ -875,12 +877,6 @@ JTAG 调试 密钥文件应该是单个原始二进制文件（例如：``key.bin``）。 -.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 - - .. note:: - - 如果使用 AES-XTS-256，那么密钥文件将被生成两部分（``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2``），可通过 ``espefuse.py`` 进行编程。 ``espsecure.py`` 目前仅支持用于加密/解密的单个密钥文件，因此用于 ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2`` 的各个文件应手动合并以创建一个 64 字节长的单个文件。 - 例如，以下是将文件 ``build/my-app.bin`` 进行加密、烧录到偏移量 0x10000 的步骤。运行 ``espsecure.py``，如下所示: .. only:: esp32 @@ -965,7 +961,7 @@ JTAG 调试 - {IDF_TARGET_NAME} 使用 XTS-AES 块密码模式进行 flash 加密，密钥大小为 256 位或 512 位。 - - XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 `_。 + - XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 `_。 - Flash 加密的密钥存储于一个或两个 ``BLOCK_KEYN`` eFuse 中，默认受保护防止进一步写入或软件读取。 @@ -973,6 +969,7 @@ JTAG 调试 .. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 + .. _flash-encryption-algorithm: Flash 加密算法 @@ -980,7 +977,7 @@ JTAG 调试 - {IDF_TARGET_NAME} 使用 XTS-AES 块密码模式进行 flash 加密，密钥大小为 256 位。 - - XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 `_。 + - XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 `_。 - Flash 加密的密钥存储于一个 ``BLOCK_KEYN`` eFuse 中，默认受保护防止进一步写入或软件读取。