mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: update nvs encryption cn trans
This commit is contained in:
intern
parent
1a7dfa42e6
commit
4866e91398
@ -6,42 +6,45 @@ 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.
|
||||
|
||||
@ -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} ...
|
||||
|
||||
Optional Arguments:
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+============+======================================================================+
|
||||
| 1 | -h, --help | show this help message and exit |
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
**Optional Arguments**:
|
||||
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+============+======================================================================+
|
||||
| 1 | -h, --help | Show this help message and exit |
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
|
||||
**Commands**::
|
||||
|
||||
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 | 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):
|
||||
To Generate NVS Partition (Default):
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
**Usage**::
|
||||
|
||||
**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:
|
||||
+-----------------+--------------------------------------------------------------------+
|
||||
| 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) |
|
||||
+-----------------+--------------------------------------------------------------------+
|
||||
**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) |
|
||||
+-----------------+--------------------------------------------------------------------+
|
||||
|
||||
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:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**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**::
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
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"
|
||||
.. note:: 如需在设备处于 flash 加密开发模式时更新 NVS 密钥分区，请调用 :component_file:`parttool.py <partition_table/parttool.py>` 对 NVS 密钥分区进行加密。同时，由于设备上的分区表也已加密，您还需要在构建目录（build/partition_table）中提供一个指向未加密分区表的指针。您可以使用如下命令：
|
||||
::
|
||||
|
||||
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 加密对密钥分区进行加密。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user