mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: update CN trans for external-ram and flash-encryption
This commit is contained in:
daiziyan
parent
250cc815bd
commit
e79b8c1b6a
@ -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
|
||||
.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:`堆内存分配器 </api-reference/system/mem_alloc>` 里携带 ``MALLOC_CAP_SPIRAM`` 的标志
|
||||
启用上述选项后，片外 RAM 被映射到地址 0x3F800000，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 </api-reference/system/mem_alloc>` 。
|
||||
|
||||
程序如果想从片外存储器分配存储空间，则需要调用 ``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 <dma-capable-memory>` 和 ``MALLOC_CAP_INTERNAL`` 旗标从该池中分配存储器。
|
||||
由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部内存池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA <dma-capable-memory>` 和 ``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 加密 </security/flash-encryption>`。
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
@ -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 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-256（512 位密钥），则需要使用 `XTS_AES_256_KEY_1` 和 `XTS_AES_256_KEY_2`。espsecure 不支持 512 位密钥，但可以变通一下。
|
||||
如果 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 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 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 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 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 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:`项目配置菜单 <project-configuration-menu>` 中进行如下设置：
|
||||
|
||||
@ -367,7 +369,7 @@ Flash 加密设置
|
||||
.. note::
|
||||
|
||||
这个命令不包括任何应该被写入 flash 分区的用户文件。请在运行此命令前手动写入这些文件，否则在写入前应单独对这些文件进行加密。
|
||||
|
||||
|
||||
该命令将向 flash 写入未加密的镜像：固件引导加载程序、分区表和应用程序。烧录完成后，{IDF_TARGET_NAME} 将重置。在下一次启动时，固件引导加载程序会加密：固件引导加载程序、应用程序分区和标记为 ``加密`` 的分区，然后复位。就地加密可能需要时间，对于大的分区来说可能耗时一分钟。之后，应用程序在运行时被解密并执行。
|
||||
|
||||
如果使用开发模式，那么更新和重新烧录二进制文件最简单的方法是 :ref:`encrypt-partitions`。
|
||||
@ -412,7 +414,7 @@ Flash 加密设置
|
||||
|
||||
- :ref:`启动时使能 flash 加密 <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
||||
:esp32: - :ref:`选择发布模式 <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` （注意一旦选择了发布模式，``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件）
|
||||
:esp32: - :ref:`选择 UART ROM 下载模式（推荐永久性禁用）<CONFIG_SECURE_UART_ROM_DL_MODE>` （注意该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。）默认选项是保持启用 UART ROM 下载模式，然而建议永久禁用该模式，以减少攻击者可用的选项。
|
||||
:esp32: - :ref:`选择 UART ROM 下载模式（推荐永久性禁用）<CONFIG_SECURE_UART_ROM_DL_MODE>` （注意该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。）默认选项是保持启用 UART ROM 下载模式，然而建议永久禁用该模式，以减少攻击者可用的选项。
|
||||
:not esp32: - :ref:`选择发布模式 <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` （注意一旦选择了发布模式，``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件。）
|
||||
:not esp32: - :ref:`选择 UART ROM 下载（推荐永久性的切换到安全模式）<CONFIG_SECURE_UART_ROM_DL_MODE>`。这是默认且推荐使用的选项。如果不需要该模式，也可以改变此配置设置永久地禁用 UART ROM 下载模式。
|
||||
- :ref:`选择适当详细程度的引导加载程序日志 <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
||||
@ -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 方案 <updating-encrypted-flash-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 加密 <nvs_encryption>`。
|
||||
|
||||
为便于访问，某些数据分区最好保持未加密状态，或者也可使用对已加密数据无效的 flash 友好型更新算法。由于 NVS 库无法与 flash 加密直接兼容，因此无法加密非易失性存储器的 NVS 分区。详情可参见 :ref:`NVS 加密 <nvs_encryption>`。
|
||||
|
||||
- 如果以后可能需要启用 flash 加密，则编程人员在编写 :ref:`使用加密 flash <reading-writing-content>` 代码时需小心谨慎。
|
||||
|
||||
- 如果已启用安全启动，重新烧录加密设备的引导加载程序则需要“可重新烧录”的安全启动摘要（可参考 :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 <https://ieeexplore.ieee.org/document/4493450>`_。
|
||||
- XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_。
|
||||
|
||||
- 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 <https://ieeexplore.ieee.org/document/4493450>`_。
|
||||
- XTS-AES 是一种专门为光盘加密设计的块密码模式，它解决了其它潜在模式如 AES-CTR 在此使用情景下的不足。有关 XTS-AES 算法的详细描述，请参考 `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_。
|
||||
|
||||
- Flash 加密的密钥存储于一个 ``BLOCK_KEYN`` eFuse 中，默认受保护防止进一步写入或软件读取。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user