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 nvs encryption cn trans

Browse Source
This commit is contained in:
intern 2022-07-07 17:30:16 +08:00
parent 1a7dfa42e6
commit 4866e91398
4 changed files with 241 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,43 +6,46 @@ NVS Partition Generator Utility
Introduction
------------
The utility :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` creates a binary file based on key-value pairs provided in a CSV file. The binary file is compatible with NVS architecture defined in :doc:`Non-Volatile Storage </api-reference/storage/nvs_flash>`.
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.
The utility :component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py` creates a binary file based on key-value pairs provided in a CSV file. The binary file is compatible with NVS architecture defined in :doc:`Non-Volatile Storage </api-reference/storage/nvs_flash>`. 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.
Prerequisites
-------------
To use this utility in encryption mode, install the following packages:
- cryptography package
All the required packages are included in `requirements.txt` in the root of the esp-idf directory.
CSV file format
CSV File Format
---------------
Each line of a .csv file should contain 4 parameters, separated by a comma. The table below provides the description for each of these parameters.
Each line of a CSV file should contain 4 parameters, separated by a comma. The table below provides the description for each of these parameters.
+-----+-----------+----------------------------------------------------------------------+-----------------------------------------------------+
| No. | Parameter | Description | Notes |
+=====+===========+======================================================================+=====================================================+
| 1 | Key | Key of the data. The data can be accessed later from | |
| | | an application using this key. | |
+-----+-----------+----------------------------------------------------------------------+-----------------------------------------------------+
| 2 | Type | Supported values are ``file``, ``data`` and ``namespace``. | |
+-----+-----------+----------------------------------------------------------------------+-----------------------------------------------------+
| 3 | Encoding | Supported values are: ``u8``, ``i8``, ``u16``, ``i16``, ``u32``, | As of now, for the ``file`` type, |
| | | ``i32``, ``u64``, ``i64``, ``string``, ``hex2bin``, ``base64`` | only ``hex2bin``, ``base64``, ``string``, |
| | | and ``binary``. | and ``binary`` encoding is supported. |
| | | This specifies how actual data values are encoded in the | |
| | | resulting binary file. The difference between the ``string`` | |
| | | and ``binary`` encoding is that ``string`` data is terminated | |
| | | with a NULL character, whereas ``binary`` data is not. | |
+-----+-----------+----------------------------------------------------------------------+-----------------------------------------------------+
| 4 | Value | Data value. | Encoding and Value cells for the ``namespace`` |
| | | | field type should be empty. Encoding and Value |
| | | | of ``namespace`` is fixed and is not configurable. |
| | | | Any values in these cells are ignored. |
+-----+-----------+----------------------------------------------------------------------+-----------------------------------------------------+
.. list-table::
:widths: 10 20 35 35
:header-rows: 1
* - No.
- Parameter
- Description
- Notes
* - 1
- Key
- Key of the data. The data can be accessed later from an application using this key.
-
* - 2
- Type
- Supported values are ``file``, ``data``, and ``namespace``.
-
* - 3
- Encoding
- Supported values are: ``u8``, ``i8``, ``u16``, ``i16``, ``u32``, ``i32``, ``u64``, ``i64``, ``string``, ``hex2bin``, ``base64``, and ``binary``. This specifies how actual data values are encoded in the resulting binary file. The difference between the ``string`` and ``binary`` encoding is that ``string`` data is terminated with a NULL character, whereas ``binary`` data is not.
- As of now, for the ``file`` type, only ``hex2bin``, ``base64``, ``string``, and ``binary`` encoding is supported.
* - 4
- Value
- Data value
- ``Encoding`` and ``Value`` cells for the ``namespace`` field type should be empty. ``Encoding`` and ``Value`` of ``namespace`` are fixed and are not configurable. Any values in these cells are ignored.
.. note:: The first line of the CSV file should always be the column header and it is not configurable.
Below is an example dump of such a CSV file::
@ -59,7 +62,7 @@ Below is an example dump of such a CSV file::
- at the end of each line in a CSV file
NVS Entry and Namespace association
NVS Entry and Namespace Association
-----------------------------------
When a namespace entry is encountered in a CSV file, each following entry will be treated as part of that namespace until the next namespace entry is found. At this point, all the following entries will be treated as part of the new namespace.
@ -70,8 +73,7 @@ When a namespace entry is encountered in a CSV file, each following entry will b
Multipage Blob Support
----------------------
By default, binary blobs are allowed to span over multiple pages and are written in the format mentioned in Section :ref:`structure_of_entry`.
If you intend to use an older format, the utility provides an option to disable this feature.
By default, binary blobs are allowed to span over multiple pages and are written in the format mentioned in Section :ref:`structure_of_entry`. If you intend to use an older format, the utility provides an option to disable this feature.
Encryption Support
@ -84,147 +86,152 @@ Decryption Support
-------------------
This utility allows you to decrypt an encrypted NVS binary file. The utility uses an NVS binary file encrypted using AES-XTS encryption. Please refer to :ref:`nvs_encryption` for more details.
Running the utility
Running the Utility
-------------------
**Usage**::
python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...
python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...
Optional Arguments:
+-----+------------+----------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+============+======================================================================+
| 1 | -h, --help | show this help message and exit |
+-----+------------+----------------------------------------------------------------------+
**Optional Arguments**:
Commands:
Run nvs_partition_gen.py {command} -h for additional help
+-----+--------------+--------------------------------------------------------------------+
| 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 |
+-----+--------------+--------------------------------------------------------------------+
+-----+------------+----------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+============+======================================================================+
| 1 | -h, --help | Show this help message and exit |
+-----+------------+----------------------------------------------------------------------+
To generate NVS partition (Default):
**Commands**::
Run nvs_partition_gen.py {command} -h for additional help
+-----+--------------+--------------------------------------------------------------------+
| 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 |
+-----+--------------+--------------------------------------------------------------------+
To Generate NVS Partition (Default):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**::
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
**Usage**::
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
input output size
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) |
+--------------+----------------------------------------------------------------------+
**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) |
+--------------+----------------------------------------------------------------------+
**Optional Arguments**:
Optional Arguments:
+-----------------+--------------------------------------------------------------------+
| Parameter | Description |
+=================+====================================================================+
| -h, --help | show this help message and exit |
+-----------------+--------------------------------------------------------------------+
| --version {1,2} | Set multipage blob version. |
| | Version 1 - Multipage blob support disabled. |
| | Version 2 - Multipage blob support enabled. |
| | Default: Version 2 |
| | |
+-----------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+-----------------+--------------------------------------------------------------------+
+-----------------+--------------------------------------------------------------------+
| Parameter | Description |
+=================+====================================================================+
| -h, --help | Show this help message and exit |
+-----------------+--------------------------------------------------------------------+
| --version {1,2} | Set multipage blob version |
| | Version 1 - Multipage blob support disabled |
| | Version 2 - Multipage blob support enabled |
| | Default: Version 2 |
| | |
+-----------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+-----------------+--------------------------------------------------------------------+
You can run the utility to generate NVS partition using the command below:
A sample CSV file is provided with the utility::
You can run the utility to generate NVS partition using the command below. A sample CSV file is provided with the utility::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000
To generate only encryption key partition:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**::
To Generate Only Encryption Key Partition:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
**Usage**::
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
[--outdir OUTDIR]
Optional Arguments:
+--------------------+----------------------------------------------------------------------+
| Parameter | Description |
+====================+======================================================================+
| -h, --help | show this help message and exit |
+--------------------+----------------------------------------------------------------------+
| --keyfile KEYFILE | Path to output encryption key partition file |
+--------------------+----------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store file created. |
| | (Default: current directory) |
+--------------------+----------------------------------------------------------------------+
**Optional Arguments**:
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
* - -h, --help
- Show this help message and exit
* - --keyfile KEYFILE
- Path to output encryption key partition file
* - --outdir OUTDIR
- Output directory to store file created (Default: current directory)
You can run the utility to generate only the encryption key partition using the command below::
python nvs_partition_gen.py generate-key
To generate encrypted NVS partition:
To Generate Encrypted NVS Partition:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**::
**Usage**::
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
input output size
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) |
+--------------+----------------------------------------------------------------------+
**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) |
+--------------+----------------------------------------------------------------------+
Optional Arguments:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | show this help message and exit |
| | |
+---------------------+--------------------------------------------------------------------+
| --version {1,2} | Set multipage blob version. |
| | Version 1 - Multipage blob support disabled. |
| | Version 2 - Multipage blob support enabled. |
| | Default: Version 2 |
+---------------------+--------------------------------------------------------------------+
| --keygen | Generates key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --keyfile KEYFILE | Path to output encryption keys file |
+---------------------+--------------------------------------------------------------------+
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+---------------------+--------------------------------------------------------------------+
**Optional Arguments**:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | Show this help message and exit |
| | |
+---------------------+--------------------------------------------------------------------+
| --version {1,2} | Set multipage blob version |
| | Version 1 - Multipage blob support disabled |
| | Version 2 - Multipage blob support enabled |
| | Default: Version 2 |
+---------------------+--------------------------------------------------------------------+
| --keygen | Generates key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --keyfile KEYFILE | Path to output encryption keys file |
+---------------------+--------------------------------------------------------------------+
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
+---------------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+---------------------+--------------------------------------------------------------------+
You can run the utility to encrypt NVS partition using the command below:
A sample CSV file is provided with the utility:
You can run the utility to encrypt NVS partition using the command below. A sample CSV file is provided with the utility:
- Encrypt by allowing the utility to generate encryption keys::
@ -243,34 +250,35 @@ A sample CSV file is provided with the utility:
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
To decrypt encrypted NVS partition:
To Decrypt Encrypted NVS Partition:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Usage**::
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
**Usage**::
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
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 |
+--------------+----------------------------------------------------------------------+
**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 |
+--------------+----------------------------------------------------------------------+
Optional Arguments:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | show this help message and exit |
+---------------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+---------------------+--------------------------------------------------------------------+
**Optional Arguments**:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | Show this 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::
@ -284,8 +292,7 @@ You can also provide the format version number:
Multipage Blob Support Disabled (Version 1):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run the utility in this format by setting the version parameter to 1, as shown below.
A sample CSV file is provided with the utility::
You can run the utility in this format by setting the version parameter to 1, as shown below. A sample CSV file is provided with the utility::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
@ -293,12 +300,10 @@ A sample CSV file is provided with the utility::
Multipage Blob Support Enabled (Version 2):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run the utility in this format by setting the version parameter to 2, as shown below.
A sample CSV file is provided with the utility::
You can run the utility in this format by setting the version parameter to 2, as shown below. A sample CSV file is provided with the utility::
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
.. note:: *Minimum NVS Partition Size needed is 0x3000 bytes.*
.. note:: *When flashing the binary onto the device, make sure it is consistent with the application's sdkconfig.*
@ -306,7 +311,7 @@ A sample CSV file is provided with the utility::
Caveats
-------
- Utility does not check for duplicate keys and will write data pertaining to both keys. You need to make sure that the keys are distinct.
- Once a new page is created, no data will be written in the space left on the previous page. Fields in the CSV file need to be ordered in such a way as to optimize memory.
- 64-bit datatype is not yet supported.

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

@ -6,7 +6,7 @@ NVS 分区生成程序
介绍
------------
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 分区生成程序 (: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 分区。
准备工作
-------------
@ -16,31 +16,37 @@ NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_p
根目录下的 `requirements.txt` 包含必需 python 包，请预先安装。
CSV 文件格式
---------------
.csv 文件每行需包含四个参数，以逗号隔开。具体参数描述见下表：
CSV 文件每行需包含四个参数，以逗号隔开。具体参数描述见下表：
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
| 序号 | 参数 | 描述 | 说明 |
+======+==========+==============================================================+=================================================================+
| 1 | Key | 主键，应用程序可通过查询此键来获取数据。 | |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
| 2 | Type | 支持 ``file``、``data`` 和 ``namespace``。 | |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
| 3 | Encoding | 支持 ``u8``、``i8``、``u16``、``u32``、 | ``file`` |
| | | ``i32``、``string``、``hex2bin``、``base64`` 和 ``binary``。 | 类型当前仅支持 |
| | | 决定二进制 ``bin`` 文件中 value 被编码成的类型。 | ``hex2bin``、``base64``、 |
| | | ``string`` 和 ``binary`` 编码的区别在于， | ``string`` 和 ``binary`` 编码。 |
| | | ``string`` 数据以 NULL 字符结尾，``binary`` 数据则不是。 | |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
| 4 | Value | Data value | ``namespace`` 字段的 ``encoding`` 和 ``value`` 应为空。 |
| | | | ``namespace`` 的 ``encoding`` 和 ``value`` 为固定值，不可设置。 |
| | | | 这些单元格中的所有值都会被忽视。 |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
.. list-table::
:widths: 10 20 35 35
:header-rows: 1
.. note:: CSV 文件的第一行应为列标题，不可设置。
* - 序号
- 参数
- 描述
- 说明
* - 1
- Key
- 主键，应用程序可通过查询此键来获取数据。
-
* - 2
- Type
- 支持 ``file``、``data`` 和 ``namespace``。
-
* - 3
- Encoding
- 支持 ``u8``、``i8``、``u16``、``i16``、``u32``、``i32``、``u64``、``i64``、``string``、``hex2bin``、``base64`` 和 ``binary``。决定二进制 ``bin`` 文件中 value 被编码成的类型。``string`` 和 ``binary`` 编码的区别在于，``string`` 数据以 NULL 字符结尾，``binary`` 数据则不是。
- ``file`` 类型当前仅支持 ``hex2bin``、``base64``、 ``string`` 和 ``binary`` 编码。
* - 4
- Value
- Data value
- ``namespace`` 字段的 ``encoding`` 和 ``value`` 应为空。 ``namespace`` 的 ``encoding`` 和 ``value`` 为固定值，不可设置。这些单元格中的所有值都会被忽视。
.. note:: CSV 文件的第一行应始终为列标题，不可设置。
此类 CSV 文件的 Dump 示例如下::
@ -49,15 +55,15 @@ CSV 文件格式
key1,data,u8,1
key2,file,string,/path/to/file
.. note::
请确保：
- 逗号 ',' 前后无空格；
- CSV 文件每行末尾无空格。
NVS 条目和命名空间 (namespace)
-----------------------------------
NVS 条目和命名空间 (namespace) 的关联
-----------------------------------------
如 CSV 文件中出现命名空间条目，后续条目均会被视为该命名空间的一部分，直至找到下一个命名空间条目。找到新命名空间条目后，后续所有条目都会被视为新命名空间的一部分。
@ -75,6 +81,7 @@ NVS 条目和命名空间 (namespace)
NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
支持解密
-------------------
如果 NVS 二进制文件采用了 AES-XTS 加密，该程序还可对此类文件进行解密，更多信息详见 :ref:`nvs_encryption`。
@ -110,9 +117,8 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
| 4 | decrypt | 解密 NVS 分区 |
+------+--------------+---------------+
生成 NVS 分区（默认模式）
----------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**使用方法**::
@ -146,31 +152,37 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
| --outdir OUTDIR | 输出目录，用于存储创建的文件。（默认当前目录） |
+-----------------+------------------------------------------------+
运行如下命令创建 NVS 分区，该程序同时会提供 CSV 示例文件::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000
仅生成加密密钥
-----------------------
仅生成加密密钥分区
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**使用方法**::
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
[--outdir OUTDIR]
**可选参数**：
**可选参数**:
+-------------------+------------------------------------------------+
| 参数 | 描述 |
+-------------------+------------------------------------------------+
| -h, --help | 显示帮助信息并退出 |
+-------------------+------------------------------------------------+
| --keyfile KEYFILE | 加密密钥文件的输出路径 |
+-------------------+------------------------------------------------+
| --outdir OUTDIR | 输出目录，用于存储创建的文件。（默认当前目录） |
+-------------------+------------------------------------------------+
运行以下命令仅生成加密密钥::
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - -h, --help
- 显示帮助信息并退出
* - --keyfile KEYFILE
- 加密密钥分区文件的输出路径
* - --outdir OUTDIR
- 输出目录，用于存储创建的文件（默认当前目录）
运行以下命令仅生成加密密钥分区::
python nvs_partition_gen.py generate-key
@ -243,7 +255,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
**使用方法**::
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
**位置参数**：
@ -273,10 +285,10 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin
您可以自定义格式版本号：
- 版本 1：禁用多页 Blob
- 版本 2：启用多页 Blob
版本 1：禁用多页 Blob
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -284,6 +296,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
版本 2：启用多页 Blob
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

26
docs/en/api-reference/storage/nvs_flash.rst
View File

@ -1,4 +1,4 @@
Non-volatile storage library
Non-volatile Storage Library
============================
:link_to_translation:`zh_CN:[中文]`
@ -8,7 +8,7 @@ Introduction
Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This section introduces some concepts used by NVS.
Underlying storage
Underlying Storage
^^^^^^^^^^^^^^^^^^
Currently, NVS uses a portion of main flash memory through the :ref:`esp_partition <flash-partition-apis>` API. The library uses all the partitions with ``data`` type and ``nvs`` subtype. The application can choose to use the partition with the label ``nvs`` through the :cpp:func:`nvs_open` API function or any other partition by specifying its name using the :cpp:func:`nvs_open_from_partition` API function.
@ -20,7 +20,7 @@ Future versions of this library may have other storage backends to keep data in
.. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library.
Keys and values
Keys and Values
^^^^^^^^^^^^^^^
NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length is currently 15 characters. Values can have one of the following types:
@ -48,7 +48,7 @@ Namespaces
To mitigate potential conflicts in key names between different components, NVS assigns each key-value pair to one of namespaces. Namespace names follow the same rules as key names, i.e., the maximum length is 15 characters. Namespace name is specified in the :cpp:func:`nvs_open` or :cpp:type:`nvs_open_from_partition` call. This call returns an opaque handle, which is used in subsequent calls to the ``nvs_get_*``, ``nvs_set_*``, and :cpp:func:`nvs_commit` functions. This way, a handle is associated with a namespace, and key names will not collide with same names in other namespaces. Please note that the namespaces with the same name in different NVS partitions are considered as separate namespaces.
NVS iterators
NVS Iterators
^^^^^^^^^^^^^
Iterators allow to list key-value pairs stored in NVS, based on specified partition name, namespace, and data type.
@ -63,7 +63,7 @@ In general, all iterators obtained via :cpp:func:`nvs_entry_find` have to be rel
:cpp:func:`nvs_entry_find` and :cpp:func:`nvs_entry_next` will set the given iterator to ``NULL`` or a valid iterator in all cases except a parameter error occured (i.e., return ``ESP_ERR_NVS_NOT_FOUND``). In case of a parameter error, the given iterator will not be modified. Hence, it is best practice to initialize the iterator to ``NULL`` before calling :cpp:func:`nvs_entry_find` to avoid complicated error checking before releasing the iterator.
Security, tampering, and robustness
Security, Tampering, and Robustness
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NVS is not directly compatible with the {IDF_TARGET_NAME} flash encryption system. However, data can still be stored in encrypted form if NVS encryption is used together with {IDF_TARGET_NAME} flash encryption. Please refer to :ref:`nvs_encryption` for more details.
@ -86,7 +86,7 @@ For using NVS encryption, the partition table must contain the :ref:`nvs_key_par
.. _nvs_key_partition:
NVS key partition
NVS Key Partition
^^^^^^^^^^^^^^^^^
An application requiring NVS encryption support needs to be compiled with a key-partition of the type `data` and subtype `key`. This partition should be marked as `encrypted` and its size should be the minimum partition size (4KB). Refer to :doc:`Partition Tables <../../api-guides/partition-tables>` for more details. Two additional partition tables which contain the :ref:`nvs_key_partition` are provided under the partition table option (menuconfig->Partition Table). They can be directly used for :ref:`nvs_encryption`. The structure of these partitions is depicted below.
@ -125,7 +125,7 @@ The XTS encryption keys in the :ref:`nvs_key_partition` can be generated in one
parttool.py --port PORT --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
.. note:: If the device is encrypted in flash encryption development mode and you want to renew the NVS key partition, you need to advice :component_file:`parttool.py<partition_table/parttool.py>` to encrypt the NVS key partition and you also need to give it a pointer to the unencrypted partition table in your build directory (build/partition_table) since the partition table on the device is encrypted, too. You can use the following command:
.. note:: If the device is encrypted in flash encryption development mode and you want to renew the NVS key partition, you need to tell :component_file:`parttool.py <partition_table/parttool.py>` to encrypt the NVS key partition and you also need to give it a pointer to the unencrypted partition table in your build directory (build/partition_table) since the partition table on the device is encrypted, too. You can use the following command:
::
parttool.py --esptool-write-args encrypt --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
@ -188,12 +188,12 @@ You can find code examples in the :example:`storage` directory of ESP-IDF exampl
Internals
---------
Log of key-value pairs
Log of Key-Value Pairs
^^^^^^^^^^^^^^^^^^^^^^
NVS stores key-value pairs sequentially, with new key-value pairs being added at the end. When a value of any given key has to be updated, a new key-value pair is added at the end of the log and the old key-value pair is marked as erased.
Pages and entries
Pages and Entries
^^^^^^^^^^^^^^^^^
NVS library uses two main entities in its operation: pages and entries. Page is a logical structure which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages which are in use have a *sequence number* associated with them. Sequence numbers impose an ordering on pages. Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following states:
@ -230,7 +230,7 @@ Mapping from flash sectors to logical pages does not have any particular order.
| Sector 3 | | Sector 0 | | Sector 2 | | Sector 1 | <- physical sectors
+----------+ +----------+ +----------+ +----------+
Structure of a page
Structure of a Page
^^^^^^^^^^^^^^^^^^^
For now, we assume that flash sector size is 4096 bytes and that {IDF_TARGET_NAME} flash encryption hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g., via menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in the system, e.g., SPI flash driver and SPI flash cache can support these other sizes).
@ -266,7 +266,7 @@ CRC32 value in the header is calculated over the part which does not include a s
The following sections describe the structure of entry state bitmap and entry itself.
Entry and entry state bitmap
Entry and Entry State Bitmap
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each entry can be in one of the following three states represented with two bits in the entry state bitmap. The final four bits in the bitmap (256 - 2 * 126) are not used.
@ -283,7 +283,7 @@ Erased (2'b00)
.. _structure_of_entry:
Structure of entry
Structure of Entry
^^^^^^^^^^^^^^^^^^
For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one key-value pair. For string and blob types, entry holds part of the whole key-value pair. For strings, in case when a key-value pair spans multiple entries, all entries are stored in the same page. Blobs are allowed to span over multiple pages by dividing them into smaller chunks. For tracking these chunks, an additional fixed length metadata entry is stored called "blob index". Earlier formats of blobs are still supported (can be read and modified). However, once the blobs are modified, they are stored using the new format.
@ -370,7 +370,7 @@ As mentioned above, each key-value pair belongs to one of the namespaces. Namesp
+-------------------------------------------+
Item hash list
Item Hash List
^^^^^^^^^^^^^^
To reduce the number of reads from flash memory, each member of the Page class maintains a list of pairs: item index; item hash. This list makes searches much quicker. Instead of iterating over all entries, reading them from flash one at a time, `Page::findItem` first performs a search for the item hash in the hash list. This gives the item index within the page if such an item exists. Due to a hash collision, it is possible that a different item will be found. This is handled by falling back to iteration over items in flash.

11
docs/zh_CN/api-reference/storage/nvs_flash.rst
View File

@ -70,7 +70,7 @@ NVS 与 {IDF_TARGET_NAME} flash 加密系统不直接兼容。但如果 NVS 加
如果未启用 NVS 加密，任何对 flash 芯片有物理访问权限的用户都可以修改、擦除或添加键值对。NVS 加密启用后，如果不知道相应的 NVS 加密密钥，则无法修改或添加键值对并将其识别为有效键值对。但是，针对擦除操作没有相应的防篡改功能。
当 flash 处于不一致状态时，NVS 库会尝试恢复。在任何时间点关闭设备电源，然后重新打开电源，不会导致数据丢失；但如果关闭设备电源时正在写入新的键值对，这一键值对可能会丢失。该库还应当能对 flash 中的任意数据进行正确初始化。
当 flash 处于不一致状态时，NVS 库会尝试恢复。在任何时间点关闭设备电源，然后重新打开电源，不会导致数据丢失；但如果关闭设备电源时正在写入新的键值对，这一键值对可能会丢失。该库还应该能够在 flash 中存在任何随机数据的情况下正常初始化。
.. _nvs_encryption:
@ -80,7 +80,7 @@ NVS 加密
NVS 分区内存储的数据可使用 AES-XTS 进行加密，类似于 IEEE P1619 磁盘加密标准中提到的加密方式。为了实现加密，每个条目被均视为一个扇区，并将条目相对地址（相对于分区开头）传递给加密算法，用作扇区号。可通过 :ref:`CONFIG_NVS_ENCRYPTION` 启用 NVS 加密。NVS 加密所需的密钥存储于其他分区，并且被 :doc:`Flash 加密 <../../security/flash-encryption>` 保护。因此，在使用 NVS 加密前应先启用 :doc:`Flash 加密 <../../security/flash-encryption>`。
启用 :doc:`Flash 加密 <../../security/flash-encryption>` 时，默认启用 NVS 加密。这是因为 Wi-Fi 驱动在默认的 NVS 分区中存储了凭证（如 SSID 和密码）。启用平台级加密后，仍需将它们作为默认选项进行加密。
启用 :doc:`Flash 加密 <../../security/flash-encryption>` 时，默认启用 NVS 加密。这是因为 Wi-Fi 驱动在默认的 NVS 分区中存储了凭证（如 SSID 和密码）。如已启用平台级加密，那么同时默认启用 NVS 加密有其必要性。
使用 NVS 加密，分区表必须包含 :ref:`nvs_key_partition`。在分区表选项 (menuconfig->Partition Table) 下，为 NVS 加密提供了两个包含 :ref:`nvs_key_partition` 的分区表，您可以通过工程配置菜单 (``idf.py menuconfig``) 进行选择。请参考 :example:`security/flash_encryption` 中的例子，了解如何配置和使用 NVS 加密功能。
@ -121,9 +121,14 @@ NVS 密钥分区
idf.py partition-table partition-table-flash
ii) 调用 :component_file:`parttool.py<partition_table/parttool.py>`，将密钥存储在 flash 上的 :ref:`nvs_key_partition` 中。详见 :doc:` 分区表 </api-guides/partition-tables>` 的分区工具部分。
::
parttool.py --port PORT --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
.. note:: 如需在设备处于 flash 加密开发模式时更新 NVS 密钥分区，请调用 :component_file:`parttool.py <partition_table/parttool.py>` 对 NVS 密钥分区进行加密。同时，由于设备上的分区表也已加密，您还需要在构建目录（build/partition_table）中提供一个指向未加密分区表的指针。您可以使用如下命令：
::
parttool.py --port /dev/ttyUSB0 --partition-table-offset "nvs_key partition offset" write_partition --partition-name="name of nvs_key partition" --input "nvs_key partition"
parttool.py --esptool-write-args encrypt --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
由于分区已标记为 `已加密`，而且启用了 :doc:`Flash 加密 <../../security/flash-encryption>`，引导程序在首次启动时将使用 flash 加密对密钥分区进行加密。