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

Docs: Update CN trans for components/nvs_flash/nvs_partition_generator/README.rst

Browse Source
This commit is contained in:
Mo Fei Fei 2023-10-26 12:19:25 +08:00
parent ca32e5268b
commit 4f24d3a39c
3 changed files with 379 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
components/nvs_flash/nvs_partition_generator/README.rst
View File

@ -6,7 +6,7 @@ NVS Partition Generator Utility
Introduction
------------
The utility :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` creates a binary file, compatible with the NVS architecture defined in :doc:`Non-Volatile Storage </api-reference/storage/nvs_flash>`, based on the key-value pairs provided in a CSV file.
The utility :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` creates a binary file, compatible with the NVS architecture defined in :doc:`nvs_flash`, based on the key-value pairs provided in a CSV file.
This utility is ideally suited for generating a binary blob, containing data specific to ODM/OEM, which can be flashed externally at the time of device manufacturing. This allows manufacturers to generate many instances of the same application firmware with customized parameters for each device, such as a serial number.
@ -81,7 +81,7 @@ By default, binary blobs are allowed to span over multiple pages and are written
Encryption-Decryption Support
-----------------------------
The NVS Partition Generator utility also allows you to create an encrypted binary file and decrypt an encrypted one. The utility uses the XTS-AES encryption. Please refer to :doc:`NVS Encryption <nvs_encryption>` for more details.
The NVS Partition Generator utility also allows you to create an encrypted binary file and decrypt an encrypted one. The utility uses the XTS-AES encryption. Please refer to :ref:`nvs_encryption` for more details.
Running the Utility
@ -93,27 +93,40 @@ Running the Utility
**Optional Arguments**:
+-----+------------------------+---------------------------------------------------------------+
| No. | Parameter | Description |
+=====+========================+===============================================================+
| 1 | ``-h`` \ ``--help`` | Show the help message and exit |
+-----+------------------------+---------------------------------------------------------------+
.. list-table::
:widths: 20 40 40
:header-rows: 1
**Commands**::
* - No.
- Parameter
- Description
* - 1
- ``-h`` / ``--help``
- Show the help message and exit
Run nvs_partition_gen.py {command} -h for additional help
**Commands**:
+-----+---------------------+---------------------------------------------------------------+
| No. | Parameter | Description |
+=====+=====================+===============================================================+
| 1 | ``generate`` | Generate NVS partition |
+-----+---------------------+---------------------------------------------------------------+
| 2 | ``generate-key`` | Generate keys for encryption |
+-----+---------------------+---------------------------------------------------------------+
| 3 | ``encrypt`` | Generate NVS encrypted partition |
+-----+---------------------+---------------------------------------------------------------+
| 4 | ``decrypt`` | Decrypt NVS encrypted partition |
+-----+---------------------+---------------------------------------------------------------+
Run ``nvs_partition_gen.py {command} -h`` for additional help
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - No.
- Parameter
- Description
* - 1
- ``generate``
- Generate NVS partition
* - 2
- ``generate-key``
- Generate keys for encryption
* - 3
- ``encrypt``
- Generate NVS encrypted partition
* - 4
- ``decrypt``
- Decrypt NVS encrypted partition
Generate NVS Partition (Default)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -124,22 +137,25 @@ Generate NVS Partition (Default)
**Positional Arguments**:
+--------------+---------------------------------------------------------------+
| Parameter | Description |
+==============+===============================================================+
| ``input`` | Path to CSV file to parse |
+--------------+---------------------------------------------------------------+
| ``output`` | Path to output NVS binary file |
+--------------+---------------------------------------------------------------+
| ``size`` | Size of NVS partition in bytes (must be multiple of 4096) |
+--------------+---------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``input``
- Path to CSV file to parse
* - ``output``
- Path to output NVS binary file
* - ``size``
- Size of NVS partition in bytes (must be multiple of 4096)
**Optional Arguments**:
+------------------------+----------------------------------------------------------------------+
| Parameter | Description |
+========================+======================================================================+
| ``-h`` \ ``--help`` | Show the help message and exit |
| ``-h`` / ``--help`` | Show the help message and exit |
+------------------------+----------------------------------------------------------------------+
| ``--version {1,2}`` | Set multipage blob version (Default: Version 2) |
| | |
@ -174,33 +190,37 @@ Generate Encryption Keys Partition
**Optional Arguments**:
+---------------------------------------------+-----------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===================================================================================+
| ``-h`` \ ``--help`` | Show the help message and exit |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--keyfile KEYFILE`` | Path to output encryption keys file |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store files created. (Default: current directory) |
+---------------------------------------------+-----------------------------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``-h`` / ``--help``
- Show the help message and exit
* - ``--keyfile KEYFILE``
- Path to output encryption keys file
* - ``--outdir OUTDIR``
- Output directory to store files created. (Default: current directory)
.. only:: SOC_HMAC_SUPPORTED
**Optional Arguments (HMAC scheme-specific)**:
+---------------------------------------------+-----------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===================================================================================+
| ``--key_protect_hmac`` | If set, the NVS encryption key protection scheme based on HMAC |
| | peripheral is used; else the default scheme based on Flash Encryption |
| | is used |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_keygen`` | Generate the HMAC key for HMAC-based encryption scheme |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_keyfile KP_HMAC_KEYFILE`` | Path to output HMAC key file |
+---------------------------------------------+-----------------------------------------------------------------------------------+
| ``--kp_hmac_inputkey KP_HMAC_INPUTKEY`` | File having the HMAC key for generating the NVS encryption keys |
+---------------------------------------------+-----------------------------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``--key_protect_hmac``
- If set, the NVS encryption key protection scheme based on HMAC peripheral is used; else the default scheme based on flash encryption is used
* - ``--kp_hmac_keygen``
- Generate the HMAC key for HMAC-based encryption scheme
* - ``--kp_hmac_keyfile KP_HMAC_KEYFILE``
- Path to output the HMAC key file
* - ``--kp_hmac_inputkey KP_HMAC_INPUTKEY``
- File having the HMAC key for generating the NVS encryption keys
You can run the utility to generate only the encryption key partition using the command below::
@ -216,7 +236,7 @@ You can run the utility to generate only the encryption key partition using the
.. note:: Encryption key of the format ``<outdir>/keys/keys-<timestamp>.bin`` and HMAC key of the format ``<outdir>/keys/hmac-keys-<timestamp>.bin`` are created.
- Generate the NVS encryption keys, given the HMAC-key::
- Generate the NVS encryption keys, given the HMAC key::
python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin
@ -246,22 +266,25 @@ Generate Encrypted NVS Partition
**Positional Arguments**:
+--------------+---------------------------------------------------------------+
| Parameter | Description |
+==============+===============================================================+
| ``input`` | Path to CSV file to parse |
+--------------+---------------------------------------------------------------+
| ``output`` | Path to output NVS binary file |
+--------------+---------------------------------------------------------------+
| ``size`` | Size of NVS partition in bytes (must be multiple of 4096) |
+--------------+---------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``input``
- Path to CSV file to parse
* - ``output``
- Path to output NVS binary file
* - ``size``
- Size of NVS partition in bytes (must be multiple of 4096)
**Optional Arguments**:
+---------------------------------------------+-------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===============================================================================+
| ``-h`` \ ``--help`` | Show the help message and exit |
| ``-h`` / ``--help`` | Show the help message and exit |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--version {1,2}`` | Set multipage blob version (Default: Version 2) |
| | |
@ -282,19 +305,20 @@ Generate Encrypted NVS Partition
**Optional Arguments (HMAC scheme-specific)**:
+---------------------------------------------+-------------------------------------------------------------------------------+
| Parameter | Description |
+=============================================+===============================================================================+
| ``--key_protect_hmac`` | If set, the NVS encryption key protection scheme based on HMAC |
| | peripheral is used; else the default scheme based on Flash Encryption |
| | is used |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_keygen`` | Generate the HMAC key for HMAC-based encryption scheme |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_keyfile KP_HMAC_KEYFILE`` | Path to output HMAC key file |
+---------------------------------------------+-------------------------------------------------------------------------------+
| ``--kp_hmac_inputkey KP_HMAC_INPUTKEY`` | File having the HMAC key for generating the NVS encryption keys |
+---------------------------------------------+-------------------------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``--key_protect_hmac``
- If set, the NVS encryption key protection scheme based on HMAC peripheral is used; else the default scheme based on flash encryption is used
* - ``--kp_hmac_keygen``
- Generate the HMAC key for HMAC-based encryption scheme
* - ``--kp_hmac_keyfile KP_HMAC_KEYFILE``
- Path to output HMAC key file
* - ``--kp_hmac_inputkey KP_HMAC_INPUTKEY``
- File having the HMAC key for generating the NVS encryption keys
You can run the utility to encrypt NVS partition using the command below. A sample CSV file is provided with the utility:
@ -306,7 +330,7 @@ You can run the utility to encrypt NVS partition using the command below. A samp
.. only:: SOC_HMAC_SUPPORTED
- To generate an encrypted partition using the HMAC-based scheme, the above command can be used alongwith some additional parameters.
- To generate an encrypted partition using the HMAC-based scheme, the above command can be used along with some additional parameters.
- Encrypt by allowing the utility to generate encryption keys and the HMAC-key::
@ -343,33 +367,39 @@ Decrypt Encrypted NVS Partition
**Positional Arguments**:
+--------------+---------------------------------------------------------------+
| Parameter | Description |
+==============+===============================================================+
| ``input`` | Path to encrypted NVS partition file to parse |
+--------------+---------------------------------------------------------------+
| ``key`` | Path to file having keys for decryption |
+--------------+---------------------------------------------------------------+
| ``output`` | Path to output decrypted binary file |
+--------------+---------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``input``
- Path to encrypted NVS partition file to parse
* - ``key``
- Path to file having keys for decryption
* - ``output``
- Path to output decrypted binary file
**Optional Arguments**:
+------------------------+----------------------------------------------------------------------+
| Parameter | Description |
+========================+======================================================================+
| ``-h`` / ``--help`` | Show the help message and exit |
+------------------------+----------------------------------------------------------------------+
| ``--outdir OUTDIR`` | Output directory to store file created (Default: current directory) |
+------------------------+----------------------------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - ``-h`` / ``--help``
- Show the help message and exit
* - ``--outdir OUTDIR``
- Output directory to store files created. (Default: current directory)
You can run the utility to decrypt encrypted NVS partition using the command below::
python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin
You can also provide the format version number:
- Multipage Blob Support Disabled (Version 1)
- Multipage Blob Support Enabled (Version 2)
- Multipage blob support disabled (Version 1)
- Multipage blob support enabled (Version 2)
Multipage Blob Support Disabled (Version 1)

391
components/nvs_flash/nvs_partition_generator/README_CN.rst
View File

@ -1,23 +1,25 @@
NVS 分区生成程序
===============================
================
:link_to_translation:`en:[English]`
介绍
------------
----
NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py`) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 :doc:`非易失性存储器 (NVS) </api-reference/storage/nvs_flash>` 中定义的 NVS 结构兼容。NVS 分区生成程序适合用于生成二进制数据（Blob），其中包括设备生产时可从外部烧录的 ODM/OEM 数据。这也使得生产制造商在使用同一个应用固件的基础上，通过自定义参数，如序列号，为每个设备生成不同配置的二进制 NVS 分区。
NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py`) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 :doc:`nvs_flash` 中定义的 NVS 结构兼容。
NVS 分区生成程序适合用于生成二进制数据 (blob)，其中包括设备生产时可从外部烧录的 ODM/OEM 数据。这也使得生产制造商在使用同一个应用固件的基础上，通过自定义参数，如序列号，为每个设备生成不同配置的二进制 NVS 分区。
准备工作
-------------
--------
在加密模式下使用该程序，需安装下列软件包：
- cryptography package
- ``cryptography``
根目录下的 `requirements.txt` 包含必需 python 包，请预先安装。
CSV 文件格式
---------------
~~~~~~~~~~~~
CSV 文件每行需包含四个参数，以逗号隔开。具体参数描述见下表：
@ -63,31 +65,27 @@ CSV 文件每行需包含四个参数，以逗号隔开。具体参数描述见
NVS 条目和命名空间 (namespace) 的关联
-----------------------------------------
-------------------------------------
如 CSV 文件中出现命名空间条目，后续条目均会被视为该命名空间的一部分，直至找到下一个命名空间条目。找到新命名空间条目后，后续所有条目都会被视为新命名空间的一部分。
.. note:: CSV 文件中第一个条目应始终为 ``namespace``。
支持多页 Blob
----------------------
支持多页 blob
-------------
默认情况下，二进制 Blob 可跨多页，格式参考 :ref:`structure_of_entry` 章节。如需使用旧版格式，可在程序中禁用该功能。
默认情况下，二进制 blob 可跨多页，格式参考 :ref:`structure_of_entry` 章节。如需使用旧版格式，可在程序中禁用该功能。
支持加密
-------------------
支持加解密
----------
NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件或对此类文件进行解密。更多信息详见 :ref:`nvs_encryption`。
支持解密
-------------------
如果 NVS 二进制文件采用了 XTS-AES 加密，该程序还可对此类文件进行解密，更多信息详见 :ref:`nvs_encryption`。
运行程序
-------------------
--------
**使用方法**::
@ -95,77 +93,100 @@ NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。
**可选参数**：
+------+------------+----------------------+
| 序号 | 参数 | 描述 |
+------+------------+----------------------+
| 1 | -h, --help | 显示帮助信息并退出 |
+------+------------+----------------------+
.. list-table::
:widths: 20 40 40
:header-rows: 1
**命令**::
* - 序号
- 参数
- 描述
* - 1
- ``-h`` / ``--help``
- 显示帮助信息并退出
运行 nvs_partition_gen.py {command} -h 查看更多帮助信息
**命令**:
+------+--------------+---------------+
| 序号 | 参数 | 描述 |
+------+--------------+---------------+
| 1 | generate | 生成 NVS 分区 |
+------+--------------+---------------+
| 2 | generate-key | 生成加密密钥 |
+------+--------------+---------------+
| 3 | encrypt | 加密 NVS 分区 |
+------+--------------+---------------+
| 4 | decrypt | 解密 NVS 分区 |
+------+--------------+---------------+
运行 ``nvs_partition_gen.py {command} -h`` 查看更多帮助信息
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - 序号
- 参数
- 描述
* - 1
- ``generate``
- 生成 NVS 分区
* - 2
- ``generate-key``
- 生成加密密钥
* - 3
- ``encrypt``
- 加密 NVS 分区
* - 4
- ``decrypt``
- 解密 NVS 分区
生成 NVS 分区（默认模式）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
**使用方法**::
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
input output size
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR] input output size
**位置参数**：
+--------+--------------------------------------------------+
| 参数 | 描述 |
+--------+--------------------------------------------------+
| input | 待解析的 CSV 文件路径 |
+--------+--------------------------------------------------+
| output | NVS 二进制文件的输出路径 |
+--------+--------------------------------------------------+
| size | NVS 分区大小（以字节为单位，且为 4096 的整数倍） |
+--------+--------------------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``input``
- 待解析的 CSV 文件路径
* - ``output``
- NVS 二进制文件的输出路径
* - ``size``
- NVS 分区大小（以字节为单位，且为 4096 的整数倍）
**可选参数**：
+-----------------+------------------------------------------------+
| 参数 | 描述 |
+-----------------+------------------------------------------------+
| -h, --help | 显示帮助信息并退出 |
+-----------------+------------------------------------------------+
| --version {1,2} | - 设置多页 Blob 版本。 |
| | - 版本 1：禁用多页 Blob； |
| | - 版本 2：启用多页 Blob； |
| | - 默认版本：版本 2。 |
+-----------------+------------------------------------------------+
| --outdir OUTDIR | 输出目录，用于存储创建的文件。（默认当前目录） |
+-----------------+------------------------------------------------+
+--------------------------+------------------------------------------------+
| 参数 | 描述 |
+--------------------------+------------------------------------------------+
| ``-h`` / ``--help`` | 显示帮助信息并退出 |
+--------------------------+------------------------------------------------+
| ``--version {1,2}`` | - 设置多页 blob 版本，默认为版本 2。 |
| | |
| | - 版本 1：禁用多页 blob； |
| | |
| | - 版本 2：启用多页 blob。 |
+--------------------------+------------------------------------------------+
| ``--outdir OUTDIR`` | 输出目录，用于存储创建的文件。（默认当前目录） |
+--------------------------+------------------------------------------------+
运行如下命令创建 NVS 分区，该程序同时会提供 CSV 示例文件::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000
仅生成加密密钥分区
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
生成加密密钥分区
~~~~~~~~~~~~~~~~
**使用方法**::
.. only:: SOC_HMAC_SUPPORTED
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
[--outdir OUTDIR]
**使用方法**::
python nvs_partition_gen.py generate-key [-h] [--key_protect_hmac] [--kp_hmac_keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
[--keyfile KEYFILE] [--outdir OUTDIR]
.. only:: not SOC_HMAC_SUPPORTED
**使用方法**::
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
**可选参数**:
@ -175,61 +196,129 @@ NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。
* - 参数
- 描述
* - -h, --help
* - ``-h`` / ``--help``
- 显示帮助信息并退出
* - --keyfile KEYFILE
* - ``--keyfile KEYFILE``
- 加密密钥分区文件的输出路径
* - --outdir OUTDIR
* - ``--outdir OUTDIR``
- 输出目录，用于存储创建的文件（默认当前目录）
.. only:: SOC_HMAC_SUPPORTED
**可选参数（仅适用于 HMAC 方案）**:
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``--key_protect_hmac``
- 设置后使用基于 HMAC 的 NVS 加密密钥保护方案，否则使用基于 flash 加密的默认方案
* - ``--kp_hmac_keygen``
- 为基于 HMAC 的加密方案生成 HMAC 密钥
* - ``--kp_hmac_keyfile KP_HMAC_KEYFILE``
- HMAC 密钥文件的输出路径
* - ``--kp_hmac_inputkey KP_HMAC_INPUTKEY``
- 包含 HMAC 密钥的文件，用于生成 NVS 加密密钥
运行以下命令仅生成加密密钥分区::
python nvs_partition_gen.py generate-key
.. only:: SOC_HMAC_SUPPORTED
运行以下命令，为基于 HMAC 的方案生成加密密钥：
- 生成 HMAC 密钥和 NVS 加密密钥::
python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_keygen
.. note:: 上述命令生成 ``<outdir>/keys/keys-<timestamp>.bin`` 格式的加密密钥和 ``<outdir>/keys/hmac-keys-<timestamp>.bin`` 格式的 HMAC 密钥。
- 基于 HMAC 密钥生成 NVS 加密密钥::
python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin
.. note:: 可将自定义文件名作为参数提供给 HMAC 密钥和加密密钥。
生成 NVS 加密分区
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~
**使用方法**::
.. only:: SOC_HMAC_SUPPORTED
**使用方法**::
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR]
[--key_protect_hmac] [--kp_hmac_keygen]
[--kp_hmac_keyfile KP_HMAC_KEYFILE] [--kp_hmac_inputkey KP_HMAC_INPUTKEY]
input output size
.. only:: not SOC_HMAC_SUPPORTED
**使用方法**::
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR]
input output size
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
input output size
**位置参数**：
+--------+--------------------------------------+
| 参数 | 描述 |
+--------+--------------------------------------+
| input | 待解析 CSV 文件的路径 |
+--------+--------------------------------------+
| output | NVS 二进制文件的输出路径 |
+--------+--------------------------------------+
| size | NVS 分区大小 |
| | （以字节为单位，且为 4096 的整数倍） |
+--------+--------------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``input``
- 待解析的 CSV 文件路径
* - ``output``
- NVS 二进制文件的输出路径
* - ``size``
- NVS 分区大小（以字节为单位，且为 4096 的整数倍）
**可选参数**：
+---------------------+------------------------------+
| 参数 | 描述 |
+---------------------+------------------------------+
| -h, --help | 显示帮助信息并退出 |
+---------------------+------------------------------+
| --version {1,2} | - 设置多页 Blob 版本。 |
| | - 版本 1：禁用多页 Blob； |
| | - 版本 2：启用多页 Blob； |
| | - 默认版本：版本 2。 |
+---------------------+------------------------------+
| --keygen | 生成 NVS 分区加密密钥 |
+---------------------+------------------------------+
| --keyfile KEYFILE | 密钥文件的输出路径 |
+---------------------+------------------------------+
| --inputkey INPUTKEY | 内含 NVS 分区加密密钥的文件 |
+---------------------+------------------------------+
| --outdir OUTDIR | 输出目录，用于存储创建的文件 |
| | （默认当前目录） |
+---------------------+------------------------------+
+--------------------------+------------------------------------------------+
| 参数 | 描述 |
+--------------------------+------------------------------------------------+
| ``-h`` / ``--help`` | 显示帮助信息并退出 |
+--------------------------+------------------------------------------------+
| ``--version {1,2}`` | - 设置多页 blob 版本，默认为版本 2。 |
| | |
| | - 版本 1：禁用多页 blob； |
| | |
| | - 版本 2：启用多页 blob。 |
+--------------------------+------------------------------------------------+
| ``--keygen`` | 生成 NVS 分区加密密钥 |
+--------------------------+------------------------------------------------+
| ``--keyfile KEYFILE`` | 密钥文件的输出路径 |
+--------------------------+------------------------------------------------+
| ``--inputkey INPUTKEY`` | 内含 NVS 分区加密密钥的文件 |
+--------------------------+------------------------------------------------+
| ``--outdir OUTDIR`` | 输出目录，用于存储创建的文件。（默认当前目录） |
+--------------------------+------------------------------------------------+
.. only:: SOC_HMAC_SUPPORTED
**可选参数（仅适用于 HMAC 方案）**:
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``--key_protect_hmac``
- 设置后使用基于 HMAC 的 NVS 加密密钥保护方案，否则使用基于 flash 加密的默认方案
* - ``--kp_hmac_keygen``
- 为基于 HMAC 的加密方案生成 HMAC 密钥
* - ``--kp_hmac_keyfile KP_HMAC_KEYFILE``
- HMAC 密钥文件的输出路径
* - ``--kp_hmac_inputkey KP_HMAC_INPUTKEY``
- 包含 HMAC 密钥的文件，用于生成 NVS 加密密钥
运行以下命令加密 NVS 分区，该程序同时会提供一个 CSV 示例文件。
@ -237,21 +326,40 @@ NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
.. only:: SOC_HMAC_SUPPORTED
- 要使用基于 HMAC 的方案生成加密分区，可将上述命令与附加参数搭配使用。
- 通过 NVS 分区生成程序生成加密密钥和 HMAC 密钥，从而进行加密::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --key_protect_hmac --kp_hmac_keygen
.. note:: 上述命令生成 ``<outdir>/keys/keys-<timestamp>.bin`` 格式的加密密钥和 ``<outdir>/keys/hmac-keys-<timestamp>.bin`` 格式的 HMAC 密钥。
- 通过 NVS 分区生成程序使用用户提供的 HMAC 密钥生成加密密钥，从而进行加密::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --key_protect_hmac --kp_hmac_inputkey testdata/sample_hmac_key.bin
.. note:: 可将自定义文件名作为参数提供给 HMAC 密钥和加密密钥。
- 通过 NVS 分区生成程序生成加密密钥，并将密钥存储于自定义的文件中::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
.. note:: 加密密钥存储于新建文件的 ``keys/`` 目录下，与 NVS 密钥分区结构兼容。更多信息请参考 :ref:`nvs_encr_key_partition`。
.. note::
- 创建的加密密钥格式为 ``<outdir>/keys/sample_keys.bin``。
- 加密密钥存储于新建文件的 ``keys/`` 目录下，与 NVS 密钥分区结构兼容。更多信息请参考 :ref:`nvs_encr_key_partition`。
- 将加密密钥用作二进制输入文件来进行加密::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
解密 NVS 分区
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~
**使用方法**::
@ -259,58 +367,65 @@ NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。
**位置参数**：
+--------+-------------------------------+
| 参数 | 描述 |
+--------+-------------------------------+
| input | 待解析的 NVS 加密分区文件路径 |
+--------+-------------------------------+
| key | 含有解密密钥的文件路径 |
+--------+-------------------------------+
| output | 已解密的二进制文件输出路径 |
+--------+-------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``input``
- 待解析的 NVS 加密分区文件路径
* - ``key``
- 含有解密密钥的文件路径
* - ``output``
- 已解密的二进制文件输出路径
**可选参数**：
+-----------------+------------------------------+
| 参数 | 描述 |
+-----------------+------------------------------+
| -h, --help | 显示帮助信息并退出 |
+-----------------+------------------------------+
| --outdir OUTDIR | 输出目录，用于存储创建的文件 |
| | （默认当前目录） |
+-----------------+------------------------------+
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - ``-h`` / ``--help``
- 显示帮助信息并退出
* - ``--outdir OUTDIR``
- 输出目录，用于存储创建的文件（默认当前目录）
运行以下命令解密已加密的 NVS 分区::
python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin
您可以自定义格式版本号：
- 版本 1：禁用多页 Blob
- 版本 2：启用多页 Blob
可以在命令中提供版本参数，选择格式版本号：
- 版本 1：禁用多页 blob
- 版本 2：启用多页 blob
版本 1：禁用多页 Blob
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
版本 1：禁用多页 blob
~~~~~~~~~~~~~~~~~~~~~
如需禁用多页 Blob，请按照如下命令将版本参数设置为 1，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
如需禁用多页 blob，请按照如下命令将版本参数设置为 1，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
版本 2：启用多页 Blob
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
版本 2：启用多页 blob
~~~~~~~~~~~~~~~~~~~~~
如需启用多页 Blob，请按照如下命令将版本参数设置为 2，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
如需启用多页 blob，请按照如下命令将版本参数设置为 2，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
.. note:: NVS 分区最小为 0x3000 字节。
.. note::
.. note:: 将二进制文件烧录至设备时，请确保与应用的 sdkconfig 设置一致。
- NVS 分区最小为 0x3000 字节。
- 将二进制文件烧录至设备时，请确保与应用的 sdkconfig 设置一致。
说明
-------
----
- 分区生成程序不会对重复键进行检查，而将数据同时写入这两个重复键中。请注意不要使用同名的键；
- 新页面创建后，前一页的空白处不会再写入数据。CSV 文件中的字段须按次序排列以优化内存；

2
docs/en/api-reference/storage/nvs_encryption.rst
View File

@ -1,7 +1,7 @@
NVS Encryption
==============
:link_to_translation:`en:[English]`
:link_to_translation:`zh_CN:[中文]`
Overview
--------