NVS 加密

概述

本文档主要介绍 NVS 加密功能，这一功能有助于实现设备在 flash 中的安全存储。

存储在 NVS 分区中的数据可以用 XTS-AES 进行加密，与磁盘加密标准 IEEE P1619 中提到的加密方式类似。加密时，每个条目都被视作一个 sector，而条目的相对地址（相对于分区起始位置）作为 sector-number 输入加密算法。

NVS 加密：基于 flash 加密的方案

在这个方案中，NVS 加密所需的密钥存储在另一个分区中，该分区用 flash 加密进行保护。因此，使用该方案时，必须先启用 flash 加密。

启用 flash 加密时，默认启用 NVS 加密。这是因为 Wi-Fi 驱动程序会将凭据（如 SSID 和密码）储存在默认的 NVS 分区中。如已启用平台级加密，那么则需要同时默认启用 NVS 加密。

要用这一方案进行 NVS 加密，分区表中必须包含 NVS 密钥分区。在分区表选项 ( menuconfig > Partition Table ) 中，有两个包含 NVS 密钥分区的分区表，可通过项目配置菜单 ( idf.py menuconfig) 进行选择。要了解如何配置和使用 NVS 加密功能，请参考示例 security/flash_encryption。

NVS 密钥分区

应用如果要使用 NVS 加密（使用基于 flash 加密的方案）编译时，须使用类型为 data 和子类型为 key 的密钥分区。该分区应被标记为 encrypted 且最小为 4 KB （最小分区大小）。参考分区表了解详情。在分区表选项 ( menuconfig > Partition Table) 中，有两个包含 NVS 密钥分区的额外分区表，可以直接用于 NVS 加密。分区的结构如下所示：

+-----------+--------------+-------------+----+
|              XTS encryption key (32)        |
+---------------------------------------------+
|              XTS tweak key (32)             |
+---------------------------------------------+
|                  CRC32 (4)                  |
+---------------------------------------------+

可以通过以下两种方式之一生成 NVS 密钥分区中的 XTS 加密密钥：

在 ESP32 芯片上生成密钥

启用 NVS 加密时，可使用 API 函数 nvs_flash_init() 来初始化加密的默认 NVS 分区。该 API 函数会内部生成 ESP 芯片的 XTS 加密密钥，并找到第一个 NVS 密钥分区。
然后，该 API 函数使用 nvs_flash/include/nvs_flash.h 提供的 nvs_flash_generate_keys() API 函数，自动生成 NVS 密钥并存储到该分区。只有当相应的密钥分区为空时，才会生成和存储新密钥。然后，就可以利用 nvs_flash_secure_init_partition() 用此密钥分区来读取安全配置，以初始化自定义的加密 NVS 分区。
API 函数 nvs_flash_secure_init() 和 nvs_flash_secure_init_partition() 不会内部生成密钥。如果要使用这两个 API 函数初始化加密的 NVS 分区，可以在启动后使用 nvs_flash.h 提供的 nvs_flash_generate_keys() API 函数生成密钥，然后由该 API 函数将生成的密钥以加密形式写入密钥分区中。

备注
请注意，在使用此方法启动应用程序前，必须完全擦除 nvs_keys 分区。否则，应用程序可能会生成 ESP_ERR_NVS_CORRUPT_KEY_PART 错误代码，该代码假设 nvs_keys 分区不为空并且包含格式错误的数据。可以使用以下命令来实现：
parttool.py --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys

使用预生成的 NVS 密钥分区

如果 NVS 密钥分区中的密钥不是由应用程序生成，则需要使用预先生成的密钥分区。可以使用 NVS 分区生成程序生成包含 XTS 加密密钥的 NVS 密钥分区。然后使用以下两个命令将预生成的密钥分区存储到 flash 上：
1. 构建并烧写分区表
idf.py partition-table partition-table-flash
2. 使用 parttool.py （参见分区表中分区工具相关章节）将密钥存储在 flash 上的 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
备注
如果设备是在 flash 加密开发模式下加密的，那么要更新 NVS 密钥分区就需要使用 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="nvs_key 分区名称" --input NVS_KEY_PARTITION_FILE

由于密钥分区被标记为 encrypted，且 flash 加密已启用，引导程序会在首次启动时使用 flash 加密密钥对此分区进行加密。

一个应用程序可以使用不同的密钥对不同的 NVS 分区进行加密，从而拥有多个密钥分区。应用程序应为加密或解密操作提供正确的密钥分区和密钥信息。

加密读/写

NVS API 函数 nvs_get_* 或 nvs_set_* 也可用于读取和写入加密的 NVS 分区。

加密默认的 NVS 分区

要为默认 NVS 分区启用加密，无需额外的步骤。在启用 CONFIG_NVS_ENCRYPTION 时，API 函数 nvs_flash_init() 会根据使用的方案（由 CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME 设置）在内部执行一些额外步骤，为默认的 NVS 分区启用加密。
在基于 flash 加密的方案中，加密密钥由找到的第一个 NVS 密钥分区生成。在 HMAC 方案中，密钥由 CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID 中烧录的 HMAC 密钥生成（参考 API 文档以了解更多详细信息）。

另外，还可使用 API 函数 nvs_flash_secure_init() 为默认 NVS 分区启用加密。

加密自定义 NVS 分区

要为一个自定义的 NVS 分区启用加密，使用 API 函数 nvs_flash_secure_init_partition() 代替 nvs_flash_init_partition()。
使用 API 函数 nvs_flash_secure_init() 和 nvs_flash_secure_init_partition() 时，为了在启用加密的情况下执行 NVS 读/写操作，应用程序应遵守以下步骤：

1. 填充 NVS 安全配置结构 [`nvs_sec_cfg_t`](nvs_flash.html#_CPPv413nvs_sec_cfg_t "nvs_sec_cfg_t")

   * 对基于 flash 加密的方案

     * 使用 API 函数 esp_partition_find* 查找密钥分区和 NVS 数据分区。

     * 使用 API 函数 [`nvs_flash_read_security_cfg()`](nvs_flash.html#_CPPv427nvs_flash_read_security_cfgPK15esp_partition_tP13nvs_sec_cfg_t "nvs_flash_read_security_cfg") 或 [`nvs_flash_generate_keys()`](nvs_flash.html#_CPPv423nvs_flash_generate_keysPK15esp_partition_tP13nvs_sec_cfg_t "nvs_flash_generate_keys") 填充 [`nvs_sec_cfg_t`](nvs_flash.html#_CPPv413nvs_sec_cfg_t "nvs_sec_cfg_t") 结构体。

2. 使用 API 函数 [`nvs_flash_secure_init()`](nvs_flash.html#_CPPv421nvs_flash_secure_initP13nvs_sec_cfg_t "nvs_flash_secure_init") 或 [`nvs_flash_secure_init_partition()`](nvs_flash.html#_CPPv431nvs_flash_secure_init_partitionPKcP13nvs_sec_cfg_t "nvs_flash_secure_init_partition") 初始化 NVS flash 分区。

3. 使用 API 函数 [`nvs_open()`](nvs_flash.html#_CPPv48nvs_openPKc15nvs_open_mode_tP12nvs_handle_t "nvs_open") 或 [`nvs_open_from_partition()`](nvs_flash.html#_CPPv423nvs_open_from_partitionPKcPKc15nvs_open_mode_tP12nvs_handle_t "nvs_open_from_partition") 打开一个命名空间。

4. 使用 `nvs_get_*` 或 `nvs_set_*` 执行 NVS 读/写操作。

5. 使用 [`nvs_flash_deinit()`](nvs_flash.html#_CPPv416nvs_flash_deinitv "nvs_flash_deinit") 取消初始化 NVS 分区。

NVS Security Provider

组件 nvs_sec_provider 存储了 NVS 加密方案的所有特定实现代码，并且适用于未来的方案。此组件充当 nvs_flash 组件处理加密密钥的接口。组件 nvs_sec_provider 有自己的配置菜单，选定的安全方案和相应设置基于这一菜单注册到 nvs_flash 组件。

API 参考

Header File

components/nvs_sec_provider/include/nvs_sec_provider.h
This header file can be included with:

#include "nvs_sec_provider.h"

This header file is a part of the API provided by the nvs_sec_provider component. To declare that your component depends on nvs_sec_provider, add the following to your CMakeLists.txt:

REQUIRES nvs_sec_provider

>     PRIV_REQUIRES nvs_sec_provider

Functions

esp_err_t nvs_sec_provider_register_flash_enc(const nvs_sec_config_flash_enc_t *sec_scheme_cfg, nvs_sec_scheme_t **sec_scheme_handle_out)

参数

sec_scheme_cfg -- [in] Security scheme specific configuration data
sec_scheme_handle_out -- [out] Security scheme specific configuration handle

ESP_OK, if sec_scheme_handle_out was populated successfully with the scheme configuration;
ESP_ERR_INVALID_ARG, if scheme_cfg_hmac is NULL;
ESP_ERR_NO_MEM, No memory for the scheme-specific handle sec_scheme_handle_out
ESP_ERR_NOT_FOUND, if no nvs_keys partition is found

esp_err_t nvs_sec_provider_deregister(nvs_sec_scheme_t *sec_scheme_handle)

Deregister the NVS encryption scheme registered with the given handle.

参数

sec_scheme_handle -- [in] Security scheme specific configuration handle

ESP_OK, if the scheme registered with sec_scheme_handle was deregistered successfully
ESP_ERR_INVALID_ARG, if sec_scheme_handle is NULL;

Structures

struct nvs_sec_config_flash_enc_t

Flash encryption-based scheme specific configuration data.

Public Members

const esp_partition_t *nvs_keys_part

Partition of subtype nvs_keys holding the NVS encryption keys

Macros

ESP_ERR_NVS_SEC_BASE

Starting number of error codes

ESP_ERR_NVS_SEC_HMAC_KEY_NOT_FOUND

HMAC Key required to generate the NVS encryption keys not found

ESP_ERR_NVS_SEC_HMAC_KEY_BLK_ALREADY_USED

Provided eFuse block for HMAC key generation is already in use

ESP_ERR_NVS_SEC_HMAC_KEY_GENERATION_FAILED

Failed to generate/write the HMAC key to eFuse

ESP_ERR_NVS_SEC_HMAC_XTS_KEYS_DERIV_FAILED

Failed to derive the NVS encryption keys based on the HMAC-based scheme

NVS_SEC_PROVIDER_CFG_FLASH_ENC_DEFAULT()

Helper for populating the Flash encryption-based scheme specific configuration data.

Enumerations

enum nvs_sec_scheme_id_t

NVS Encryption Keys Protection Scheme.

Values:

enumerator NVS_SEC_SCHEME_FLASH_ENC

Protect NVS encryption keys using Flash Encryption

enumerator NVS_SEC_SCHEME_HMAC

Protect NVS encryption keys using HMAC peripheral

enumerator NVS_SEC_SCHEME_MAX

ESP32

快速入门

H/W 硬件参考

esp32

API 参考

外设 API

存储 API

应用层协议

系统 API

蓝牙 API

连网 API

配网 API

API 指南

esp-ble-mesh

JTAG 调试

工具

性能

安全指南

库与框架

贡献指南

第三方工具

NVS 加密

概述

NVS 加密：基于 flash 加密的方案

NVS 密钥分区

加密读/写

NVS Security Provider

API 参考

Header File

Functions

Structures

Macros

Enumerations

快速入门

H/W 硬件参考

esp32

API 参考

外设 API

存储 API

应用层协议

系统 API

蓝牙 API

连网 API

配网 API

API 指南

esp-ble-mesh

JTAG 调试

工具

性能

安全指南

库与框架

贡献指南

第三方工具

NVS 加密 ​

概述 ​

NVS 加密：基于 flash 加密的方案 ​

NVS 密钥分区 ​

加密读/写 ​

NVS Security Provider ​

API 参考 ​

Header File ​

Functions ​

Structures ​

Macros ​

Enumerations ​

NVS 加密

概述

NVS 加密：基于 flash 加密的方案

NVS 密钥分区

加密读/写

NVS Security Provider

API 参考

Header File

Functions

Structures

Macros

Enumerations