Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-08-18 06:35:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: update the algorithm and key name from AES-XTS to XTS-AES

Browse Source
This commit is contained in:
Linda
2023-05-15 11:04:22 +08:00
parent ede0786eb0
commit 65ee4992ce
19 changed files with 109 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
components/nvs_flash/Kconfig
View File

@@ -5,7 +5,7 @@ menu "NVS"
default y
depends on SECURE_FLASH_ENC_ENABLED
help
This option enables encryption for NVS. When enabled, AES-XTS is used to encrypt
This option enables encryption for NVS. When enabled, XTS-AES is used to encrypt
the complete NVS data, except the page headers. It requires XTS encryption keys
to be stored in an encrypted partition. This means enabling flash encryption is
a pre-requisite for this feature.

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

@@ -32,11 +32,11 @@ Each line of a CSV file should contain 4 parameters, separated by a comma. The t
* - 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.
@@ -45,7 +45,7 @@ Each line of a CSV file should contain 4 parameters, separated by a comma. The t
- 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::
@@ -79,12 +79,12 @@ By default, binary blobs are allowed to span over multiple pages and are written
Encryption Support
-------------------
The NVS Partition Generator utility also allows you to create an encrypted binary file. The utility uses the AES-XTS encryption. Please refer to :ref:`nvs_encryption` for more details.
The NVS Partition Generator utility also allows you to create an encrypted binary file. The utility uses the XTS-AES encryption. Please refer to :ref:`nvs_encryption` for more details.
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.
This utility allows you to decrypt an encrypted NVS binary file. The utility uses an NVS binary file encrypted using XTS-AES encryption. Please refer to :ref:`nvs_encryption` for more details.
Running the Utility
-------------------
@@ -98,25 +98,25 @@ Running the Utility
+-----+------------+----------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+============+======================================================================+
| 1 | -h, --help | Show this help message and exit |
| 1 | -h, --help | Show this help message and exit |
+-----+------------+----------------------------------------------------------------------+
**Commands**::
Run nvs_partition_gen.py {command} -h for additional help
Run nvs_partition_gen.py {command} -h for additional help
+-----+--------------+--------------------------------------------------------------------+
| No. | Parameter | Description |
+=====+==============+====================================================================+
| 1 | generate | Generate NVS partition |
| 1 | generate | Generate NVS partition |
+-----+--------------+--------------------------------------------------------------------+
| 2 | generate-key | Generate keys for encryption |
| 2 | generate-key | Generate keys for encryption |
+-----+--------------+--------------------------------------------------------------------+
| 3 | encrypt | Generate NVS encrypted partition |
| 3 | encrypt | Generate NVS encrypted partition |
+-----+--------------+--------------------------------------------------------------------+
| 4 | decrypt | Decrypt NVS encrypted partition |
+-----+--------------+--------------------------------------------------------------------+
To Generate NVS Partition (Default):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -124,17 +124,17 @@ To Generate NVS Partition (Default):
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 |
| input | Path to CSV file to parse |
+--------------+----------------------------------------------------------------------+
| output | Path to output NVS binary file |
| output | Path to output NVS binary file |
+--------------+----------------------------------------------------------------------+
| size | Size of NVS partition in bytes (must be multiple of 4096) |
| size | Size of NVS partition in bytes (must be multiple of 4096) |
+--------------+----------------------------------------------------------------------+
**Optional Arguments**:
@@ -142,16 +142,16 @@ To Generate NVS Partition (Default):
+-----------------+--------------------------------------------------------------------+
| Parameter | Description |
+=================+====================================================================+
| -h, --help | Show this help message and exit |
| -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 |
| | |
| | Default: Version 2 |
| | |
+-----------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
| --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::
@@ -166,15 +166,15 @@ To Generate Only Encryption Key Partition:
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
[--outdir OUTDIR]
**Optional Arguments**:
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Description
- Description
* - -h, --help
- Show this help message and exit
* - --keyfile KEYFILE
@@ -185,7 +185,7 @@ To Generate Only Encryption Key Partition:
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:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -195,17 +195,17 @@ To Generate Encrypted NVS Partition:
[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
input output size
**Positional Arguments**:
+--------------+----------------------------------------------------------------------+
| Parameter | Description |
+==============+======================================================================+
| input | Path to CSV file to parse |
| input | Path to CSV file to parse |
+--------------+----------------------------------------------------------------------+
| output | Path to output NVS binary file |
| output | Path to output NVS binary file |
+--------------+----------------------------------------------------------------------+
| size | Size of NVS partition in bytes (must be multiple of 4096) |
| size | Size of NVS partition in bytes (must be multiple of 4096) |
+--------------+----------------------------------------------------------------------+
**Optional Arguments**:
@@ -213,42 +213,42 @@ To Generate Encrypted NVS Partition:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | Show this help message and exit |
| | |
| -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 |
| | 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) |
+---------------------+--------------------------------------------------------------------+
| --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:
- Encrypt by allowing the utility to generate encryption keys::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen
.. note:: Encryption key of the following format ``<outdir>/keys/keys-<timestamp>.bin`` is created.
.. note:: Encryption key of the following format ``<outdir>/keys/keys-<timestamp>.bin`` is created.
- Encrypt by allowing the utility to generate encryption keys and store it in provided custom filename::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
.. note:: Encryption key of the following format ``<outdir>/keys/sample_keys.bin`` is created.
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
.. note:: Encryption key of the following format ``<outdir>/keys/sample_keys.bin`` is created.
.. note:: This newly created file having encryption keys in ``keys/`` directory is compatible with NVS key-partition structure. Refer to :ref:`nvs_key_partition` for more details.
- Encrypt by providing the encryption keys as input binary file::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
To Decrypt Encrypted NVS Partition:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -256,17 +256,17 @@ To Decrypt Encrypted NVS Partition:
**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 |
| input | Path to encrypted NVS partition file to parse |
+--------------+----------------------------------------------------------------------+
| key | Path to file having keys for decryption |
| key | Path to file having keys for decryption |
+--------------+----------------------------------------------------------------------+
| output | Path to output decrypted binary file |
| output | Path to output decrypted binary file |
+--------------+----------------------------------------------------------------------+
**Optional Arguments**:
@@ -274,11 +274,11 @@ To Decrypt Encrypted NVS Partition:
+---------------------+--------------------------------------------------------------------+
| Parameter | Description |
+=====================+====================================================================+
| -h, --help | Show this help message and exit |
+---------------------+--------------------------------------------------------------------+
| --outdir OUTDIR | Output directory to store files created |
| | (Default: current directory) |
+---------------------+--------------------------------------------------------------------+
| -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::
@@ -294,7 +294,7 @@ 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::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
Multipage Blob Support Enabled (Version 2):
@@ -302,7 +302,7 @@ 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::
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
.. note:: *Minimum NVS Partition Size needed is 0x3000 bytes.*

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

@@ -36,10 +36,10 @@ CSV 文件每行需包含四个参数，以逗号隔开。具体参数描述见
* - 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`` 数据则不是。
- 支持 ``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
@@ -79,12 +79,12 @@ NVS 条目和命名空间 (namespace) 的关联
支持加密
-------------------
NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
支持解密
-------------------
如果 NVS 二进制文件采用了 AES-XTS 加密，该程序还可对此类文件进行解密，更多信息详见 :ref:`nvs_encryption`。
如果 NVS 二进制文件采用了 XTS-AES 加密，该程序还可对此类文件进行解密，更多信息详见 :ref:`nvs_encryption`。
运行程序
-------------------
@@ -166,13 +166,13 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
[--outdir OUTDIR]
**可选参数**:
.. list-table::
:widths: 30 70
:header-rows: 1
* - 参数
- 描述
* - -h, --help
@@ -181,7 +181,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
- 加密密钥分区文件的输出路径
* - --outdir OUTDIR
- 输出目录，用于存储创建的文件（默认当前目录）
运行以下命令仅生成加密密钥分区::
python nvs_partition_gen.py generate-key
@@ -195,7 +195,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
input output size
**位置参数**：
+--------+--------------------------------------+
@@ -236,19 +236,19 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
- 通过 NVS 分区生成程序生成加密密钥来加密::
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``。
- 通过 NVS 分区生成程序生成加密密钥，并将密钥存储于自定义的文件中::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
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_key_partition`。
- 将加密密钥用作二进制输入文件来进行加密::
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
解密 NVS 分区
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -256,7 +256,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
**使用方法**::
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
**位置参数**：
+--------+-------------------------------+
@@ -278,7 +278,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
+-----------------+------------------------------+
| --outdir OUTDIR | 输出目录，用于存储创建的文件 |
| | （默认当前目录） |
+-----------------+------------------------------+
+-----------------+------------------------------+
运行以下命令解密已加密的 NVS 分区::
@@ -286,7 +286,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
您可以自定义格式版本号：
- 版本 1：禁用多页 Blob
- 版本 2：启用多页 Blob
- 版本 2：启用多页 Blob
版本 1：禁用多页 Blob
@@ -294,7 +294,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
如需禁用多页 Blob，请按照如下命令将版本参数设置为 1，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
版本 2：启用多页 Blob
@@ -302,7 +302,7 @@ NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。
如需启用多页 Blob，请按照如下命令将版本参数设置为 2，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
.. note:: NVS 分区最小为 0x3000 字节。

4
components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py
View File

@@ -125,7 +125,7 @@ class Page(object):
self.page_buf[start_idx:end_idx] = self.bitmap_array
def encrypt_entry(self, data_arr, tweak_arr, encr_key):
# Encrypt 32 bytes of data using AES-XTS encryption
# Encrypt 32 bytes of data using XTS-AES encryption
backend = default_backend()
plain_text = codecs.decode(data_arr, 'hex')
tweak = codecs.decode(tweak_arr, 'hex')
@@ -761,7 +761,7 @@ def decrypt_data(data_input, decr_key, page_num, entry_no, entry_size):
if type(data_input) == bytes:
data_input = data_input.decode()
# Decrypt 32 bytes of data using AES-XTS decryption
# Decrypt 32 bytes of data using XTS-AES decryption
backend = default_backend()
plain_text = codecs.decode(data_input, 'hex')
tweak = codecs.decode(tweak_val, 'hex')