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 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/bootloader/Kconfig.projbuild
View File

@ -784,11 +784,11 @@ menu "Security features"
before enabling.
choice SECURE_FLASH_ENCRYPTION_KEYSIZE
bool "Size of generated AES-XTS key"
bool "Size of generated XTS-AES key"
default SECURE_FLASH_ENCRYPTION_AES128
depends on SOC_FLASH_ENCRYPTION_XTS_AES_OPTIONS && SECURE_FLASH_ENC_ENABLED
help
Size of generated AES-XTS key.
Size of generated XTS-AES key.
- AES-128 uses a 256-bit key (32 bytes) derived from 128 bits (16 bytes) burned in half Efuse key block.
Internally, it calculates SHA256(128 bits)

2
components/mbedtls/port/aes/esp_aes_xts.c
View File

@ -177,7 +177,7 @@ static void esp_gf128mul_x_ble( unsigned char r[16],
}
/*
* AES-XTS buffer encryption/decryption
* XTS-AES buffer encryption/decryption
*/
int esp_aes_crypt_xts( esp_aes_xts_context *ctx,
int mode,

2
components/mbedtls/port/include/aes/esp_aes.h
View File

@ -342,7 +342,7 @@ int esp_internal_aes_encrypt( esp_aes_context *ctx, const unsigned char input[16
*/
int esp_internal_aes_decrypt( esp_aes_context *ctx, const unsigned char input[16], unsigned char output[16] );
/** AES-XTS buffer encryption/decryption */
/** XTS-AES buffer encryption/decryption */
int esp_aes_crypt_xts( esp_aes_xts_context *ctx, int mode, size_t length, const unsigned char data_unit[16], const unsigned char *input, unsigned char *output );
/** Deprecated, see esp_aes_internal_decrypt */

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')

2
components/soc/esp32c2/include/soc/hwcrypto_reg.h
View File

@ -27,7 +27,7 @@
#define SHA_H_BASE ((DR_REG_SHA_BASE) + 0x40)
#define SHA_TEXT_BASE ((DR_REG_SHA_BASE) + 0x80)
/* AES-XTS registers */
/* XTS-AES registers */
#define AES_XTS_PLAIN_BASE ((DR_REG_AES_XTS_BASE) + 0x00)
#define AES_XTS_SIZE_REG ((DR_REG_AES_XTS_BASE) + 0x40)
#define AES_XTS_DESTINATION_REG ((DR_REG_AES_XTS_BASE) + 0x44)

2
components/soc/esp32c3/include/soc/hwcrypto_reg.h
View File

@ -137,7 +137,7 @@
#define HMAC_DATE_REG ((DR_REG_HMAC_BASE) + 0xF8)
/* AES-XTS registers */
/* XTS-AES registers */
#define AES_XTS_PLAIN_BASE ((DR_REG_AES_XTS_BASE) + 0x00)
#define AES_XTS_SIZE_REG ((DR_REG_AES_XTS_BASE) + 0x40)
#define AES_XTS_DESTINATION_REG ((DR_REG_AES_XTS_BASE) + 0x44)

2
components/soc/esp32c3/include/soc/soc_caps.h
View File

@ -345,7 +345,7 @@
#define SOC_EFUSE_DIS_DIRECT_BOOT 1
#define SOC_EFUSE_SOFT_DIS_JTAG 1
#define SOC_EFUSE_DIS_ICACHE 1
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // AES-XTS key purpose not supported for this block
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // XTS-AES key purpose not supported for this block
/*-------------------------- Secure Boot CAPS----------------------------*/
#define SOC_SECURE_BOOT_V2_RSA 1

2
components/soc/esp32c6/include/soc/soc_caps.h
View File

@ -410,7 +410,7 @@
#define SOC_EFUSE_DIS_DIRECT_BOOT 1
#define SOC_EFUSE_SOFT_DIS_JTAG 1
#define SOC_EFUSE_DIS_ICACHE 1
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // AES-XTS key purpose not supported for this block
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // XTS-AES key purpose not supported for this block
/*-------------------------- Secure Boot CAPS----------------------------*/
#define SOC_SECURE_BOOT_V2_RSA 1

2
components/soc/esp32h2/include/soc/soc_caps.h
View File

@ -415,7 +415,7 @@
#define SOC_EFUSE_DIS_DIRECT_BOOT 1
#define SOC_EFUSE_SOFT_DIS_JTAG 1
#define SOC_EFUSE_DIS_ICACHE 1
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // AES-XTS and ECDSA key purposes not supported for this block
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // XTS-AES and ECDSA key purposes not supported for this block
/*-------------------------- Secure Boot CAPS----------------------------*/
#define SOC_SECURE_BOOT_V2_RSA 1

2
components/soc/esp32s2/include/soc/hwcrypto_reg.h
View File

@ -149,7 +149,7 @@
#define HMAC_SET_MESSAGE_PAD_REG ((DR_REG_HMAC_BASE) + 0xF0)
#define HMAC_ONE_BLOCK_REG ((DR_REG_HMAC_BASE) + 0xF4)
/* AES-XTS registers */
/* XTS-AES registers */
#define AES_XTS_PLAIN_BASE ((DR_REG_AES_BASE) + 0x100)
#define AES_XTS_SIZE_REG ((DR_REG_AES_BASE) + 0x140)
#define AES_XTS_DESTINATION_REG ((DR_REG_AES_BASE) + 0x144)

2
components/soc/esp32s3/include/soc/hwcrypto_reg.h
View File

@ -112,7 +112,7 @@
#define HMAC_SOFT_JTAG_CTRL BIT((0)
#define HMAC_WR_JTAG_REG ((DR_REG_HMAC_BASE) + 0xFC)
/* AES-XTS registers */
/* XTS-AES registers */
#define AES_XTS_PLAIN_BASE ((DR_REG_EXT_MEM_ENC) + 0x00)
#define AES_XTS_SIZE_REG ((DR_REG_EXT_MEM_ENC) + 0x40)
#define AES_XTS_DESTINATION_REG ((DR_REG_EXT_MEM_ENC) + 0x44)

2
components/soc/esp32s3/include/soc/soc_caps.h
View File

@ -445,7 +445,7 @@
#define SOC_EFUSE_SOFT_DIS_JTAG 1
#define SOC_EFUSE_DIS_DIRECT_BOOT 1
#define SOC_EFUSE_DIS_ICACHE 1
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // AES-XTS key purpose not supported for this block
#define SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK 1 // XTS-AES key purpose not supported for this block
/*-------------------------- Secure Boot CAPS----------------------------*/
#define SOC_SECURE_BOOT_V2_RSA 1

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

@ -78,7 +78,7 @@ The library does try to recover from conditions when flash memory is in an incon
NVS Encryption
--------------
Data stored in NVS partitions can be encrypted using AES-XTS in the manner similar to the one mentioned in disk encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one `sector` and relative address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as `sector-number`. The NVS Encryption can be enabled by enabling :ref:`CONFIG_NVS_ENCRYPTION`. The keys required for NVS encryption are stored in yet another partition, which is protected using :doc:`Flash Encryption <../../security/flash-encryption>`. Therefore, enabling :doc:`Flash Encryption <../../security/flash-encryption>` is a prerequisite for NVS encryption.
Data stored in NVS partitions can be encrypted using XTS-AES in the manner similar to the one mentioned in disk encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one `sector` and relative address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as `sector-number`. The NVS Encryption can be enabled by enabling :ref:`CONFIG_NVS_ENCRYPTION`. The keys required for NVS encryption are stored in yet another partition, which is protected using :doc:`Flash Encryption <../../security/flash-encryption>`. Therefore, enabling :doc:`Flash Encryption <../../security/flash-encryption>` is a prerequisite for NVS encryption.
The NVS Encryption is enabled by default when :doc:`Flash Encryption <../../security/flash-encryption>` is enabled. This is done because Wi-Fi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.

14
docs/en/security/flash-encryption.rst
View File

@ -184,7 +184,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
2. Firmware bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Auto Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
3. Firmware bootloader uses RNG (random) module to generate an 256 bit or 512 bit key, depending on the value of :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and then writes it into respectively one or two `BLOCK_KEYN` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two `BLOCK_KEYN` eFuses are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
3. Firmware bootloader uses RNG (random) module to generate an 256 bit or 512 bit key, depending on the value of :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and then writes it into respectively one or two `BLOCK_KEYN` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two `BLOCK_KEYN` eFuses are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
@ -228,7 +228,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
2. Firmware bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
3. Firmware bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`) and then writes it into `BLOCK_KEY0` eFuse. The software also updates the ``XTS_KEY_LENGTH_256`` according to the chosen option. The key cannot be accessed via software as the write and read protection bits for `BLOCK_KEY0` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then ``XTS_KEY_LENGTH_256`` is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the RELEASE mode.
3. Firmware bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`) and then writes it into `BLOCK_KEY0` eFuse. The software also updates the ``XTS_KEY_LENGTH_256`` according to the chosen option. The key cannot be accessed via software as the write and read protection bits for `BLOCK_KEY0` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then ``XTS_KEY_LENGTH_256`` is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the RELEASE mode.
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
@ -283,7 +283,7 @@ To test flash encryption process, take the following steps:
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default).
:esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default). Note that for the ESP32 target, the choice is only available when :ref:`CONFIG_ESP32_REV_MIN` level is set to 3 (ESP32 V3).
:not esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default).
:esp32s2 or esp32s3 or esp32c2: - Set :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`.
:esp32s2 or esp32s3 or esp32c2: - Set :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`.
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`.
- Save the configuration and exit.
@ -348,13 +348,13 @@ To use a host generated key, take the following steps:
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
If :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
else if :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
.. code-block:: bash
@ -369,13 +369,13 @@ To use a host generated key, take the following steps:
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
If :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
If :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 key derived from 128 bits (SHA256(128 bits)):
else if :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 key derived from 128 bits (SHA256(128 bits)):
.. code-block:: bash

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

@ -78,7 +78,7 @@ NVS 与 {IDF_TARGET_NAME} flash 加密系统不直接兼容。但如果 NVS 加
NVS 加密
--------------
NVS 分区内存储的数据可使用 AES-XTS 进行加密，类似于 IEEE P1619 磁盘加密标准中提到的加密方式。为了实现加密，每个条目被均视为一个扇区，并将条目相对地址（相对于分区开头）传递给加密算法，用作扇区号。可通过 :ref:`CONFIG_NVS_ENCRYPTION` 启用 NVS 加密。NVS 加密所需的密钥存储于其他分区，并且被 :doc:`Flash 加密 <../../security/flash-encryption>` 保护。因此，在使用 NVS 加密前应先启用 :doc:`Flash 加密 <../../security/flash-encryption>`。
NVS 分区内存储的数据可使用 XTS-AES 进行加密，类似于 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 和密码）。如已启用平台级加密，那么同时默认启用 NVS 加密有其必要性。
@ -129,7 +129,7 @@ NVS 密钥分区
::
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）中提供一个指向未加密分区表的指针。您可以使用如下命令：
::

14
docs/zh_CN/security/flash-encryption.rst
View File

@ -184,7 +184,7 @@ flash 的加密过程
2. 固件的引导加载程序将读取 ``{IDF_TARGET_CRYPT_CNT}`` eFuse 值 (``0b000``)。因为该值为 0（偶数位），固件引导加载程序将配置并启用 flash 加密块。关于 flash 加密块的更多信息，请参考 *{IDF_TARGET_NAME} 技术参考手册* > *eFuse 控制器(eFuse)* > *自动加密块* [`PDF <{IDF_TARGET_TRM_CN_URL}#efuse>`__]。
3. 固件的引导加载程序使用 RNG（随机数生成）模块生成 256 位或 512 位密钥，具体取决于 :ref:`生成的 AES-XTS 密钥的大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`，然后分别将其写入一个或两个 `BLOCK_KEYN` eFuses。软件也为存储密钥的块更新了 ``KEY_PURPOSE_N``。由于一或两个 ``BLOCK_KEYN`` eFuse 已设置编写和读取保护位，将无法通过软件访问密钥。``KEY_PURPOSE_N`` 字段也受写保护。flash 加密操作完全在硬件中完成，无法通过软件访问密钥。
3. 固件的引导加载程序使用 RNG（随机数生成）模块生成 256 位或 512 位密钥，具体取决于 :ref:`生成的 XTS-AES 密钥的大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`，然后分别将其写入一个或两个 `BLOCK_KEYN` eFuses。软件也为存储密钥的块更新了 ``KEY_PURPOSE_N``。由于一或两个 ``BLOCK_KEYN`` eFuse 已设置编写和读取保护位，将无法通过软件访问密钥。``KEY_PURPOSE_N`` 字段也受写保护。flash 加密操作完全在硬件中完成，无法通过软件访问密钥。
4. flash 加密块将加密 flash 的内容（固件的引导加载程序、应用程序、以及标有“加密”标志的分区）。就地加密可能会耗些时间（对于大分区最多需要一分钟）。
@ -228,7 +228,7 @@ flash 的加密过程
2. 固件的引导加载程序将读取 ``{IDF_TARGET_CRYPT_CNT}`` eFuse 值 (``0b000``)。因为该值为 0（偶数位），固件引导加载程序将配置并启用 flash 加密块。关于 flash 加密块的更多信息，请参考 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_。
3. 固件的引导加载程序使用 RNG（随机数生成）模块生成 256 位或 128 位密钥（具体位数取决于 :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`），然后将其写入 `BLOCK_KEY0` eFuse。同时，根据所选选项，软件对 ``XTS_KEY_LENGTH_256`` 进行更新。由于 ``BLOCK_KEY0`` eFuse 已设置编写和读取保护位，故无法通过软件访问密钥。flash 加密操作完全在硬件中完成，无法通过软件访问密钥。若使用 128 位 flash 加密密钥，则整个 eFuse 密钥块都受写保护，但只有低 128 位受读保护，高 128 位是可读的，以满足安全启动的需要。如果 flash 加密的密钥是 256 位，那么 ``XTS_KEY_LENGTH_256`` 为 1，否则为 0。为防止意外将 eFuse 从 0 改为 1，RELEASE 模式中设置了一个写保护位。
3. 固件的引导加载程序使用 RNG（随机数生成）模块生成 256 位或 128 位密钥（具体位数取决于 :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`），然后将其写入 `BLOCK_KEY0` eFuse。同时，根据所选选项，软件对 ``XTS_KEY_LENGTH_256`` 进行更新。由于 ``BLOCK_KEY0`` eFuse 已设置编写和读取保护位，故无法通过软件访问密钥。flash 加密操作完全在硬件中完成，无法通过软件访问密钥。若使用 128 位 flash 加密密钥，则整个 eFuse 密钥块都受写保护，但只有低 128 位受读保护，高 128 位是可读的，以满足安全启动的需要。如果 flash 加密的密钥是 256 位，那么 ``XTS_KEY_LENGTH_256`` 为 1，否则为 0。为防止意外将 eFuse 从 0 改为 1，RELEASE 模式中设置了一个写保护位。
4. flash 加密块将加密 flash 的内容（固件的引导加载程序、应用程序、以及标有“加密”标志的分区）。就地加密可能会耗些时间（对于大分区最多需要一分钟）。
@ -283,7 +283,7 @@ flash 加密设置
- :ref:`选择加密模式 <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` （默认是 **开发模式**）。
:esp32: - :ref:`选择 UART ROM 下载模式 <CONFIG_SECURE_UART_ROM_DL_MODE>` （默认是 **启用**）。请注意，对于 ESP32 芯片，该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。
:not esp32: - :ref:`选择 UART ROM 下载模式 <CONFIG_SECURE_UART_ROM_DL_MODE>` （默认是 **启用**）。
:esp32s2 or esp32s3 or esp32c2: - 设置 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`。
:esp32s2 or esp32s3 or esp32c2: - 设置 :ref:`生成的 XTS-AES 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`。
- :ref:`选择适当详细程度的引导加载程序日志 <CONFIG_BOOTLOADER_LOG_LEVEL>`。
- 保存配置并退出。
@ -348,13 +348,13 @@ flash 加密设置
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
如果 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-128（256 位密钥）：
如果 :ref:`生成的 XTS-AES 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-128（256 位密钥）：
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
如果 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-256（512 位密钥）：
如果 :ref:`生成的 XTS-AES 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-256（512 位密钥）：
.. code-block:: bash
@ -369,13 +369,13 @@ flash 加密设置
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
如果 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-128（256 位密钥）:
如果 :ref:`生成的 XTS-AES 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是 AES-128（256 位密钥）:
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
或者如果 :ref:`生成的 AES-XTS 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是由 128 位导出的 AES-128 密钥（SHA256（128 位））:
或者如果 :ref:`生成的 XTS-AES 密钥大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是由 128 位导出的 AES-128 密钥（SHA256（128 位））:
.. code-block:: bash