mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
fix(docs): Disable the NVS encryption HMAC scheme section for unsupported SoCs
This commit is contained in:
Laukik Hase
Linda
parent
e925665f94
commit
81665b27c3
@ -86,18 +86,18 @@ It is possible for an application to use different keys for different NVS partit
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
NVS Encryption: HMAC Peripheral-Based Scheme
|
||||
--------------------------------------------
|
||||
NVS Encryption: HMAC Peripheral-Based Scheme
|
||||
--------------------------------------------
|
||||
|
||||
In this scheme, the XTS keys required for NVS encryption are derived from an HMAC key programmed in eFuse with the purpose :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`. Since the encryption keys are derived at runtime, they are not stored anywhere in the flash. Thus, this feature does not require a separate :ref:`nvs_encr_key_partition`.
|
||||
In this scheme, the XTS keys required for NVS encryption are derived from an HMAC key programmed in eFuse with the purpose :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`. Since the encryption keys are derived at runtime, they are not stored anywhere in the flash. Thus, this feature does not require a separate :ref:`nvs_encr_key_partition`.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
This scheme enables us to achieve secure storage on {IDF_TARGET_NAME} **without enabling flash encryption**.
|
||||
This scheme enables us to achieve secure storage on {IDF_TARGET_NAME} **without enabling flash encryption**.
|
||||
|
||||
.. important::
|
||||
.. important::
|
||||
|
||||
Please take note that this scheme uses one eFuse block for storing the HMAC key required for deriving the encryption keys.
|
||||
Please take note that this scheme uses one eFuse block for storing the HMAC key required for deriving the encryption keys.
|
||||
|
||||
- When NVS encryption is enabled, the :cpp:func:`nvs_flash_init` API function can be used to initialize the encrypted default NVS partition. The API function first checks whether an HMAC key is present at :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`.
|
||||
|
||||
@ -146,37 +146,37 @@ Alternatively, :cpp:func:`nvs_flash_secure_init` API function can also be used t
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
* For the HMAC-based scheme
|
||||
* For the HMAC-based scheme
|
||||
|
||||
- Set the scheme-specific config data with :cpp:type:`nvs_sec_config_hmac_t` and register the HMAC-based scheme with the API :cpp:func:`nvs_sec_provider_register_hmac` which will also populate the scheme-specific handle (see :cpp:type:`nvs_sec_scheme_t`).
|
||||
- Populate the :cpp:type:`nvs_sec_cfg_t` struct using the :cpp:func:`nvs_flash_read_security_cfg_v2` or :cpp:func:`nvs_flash_generate_keys_v2` API functions.
|
||||
- Set the scheme-specific config data with :cpp:type:`nvs_sec_config_hmac_t` and register the HMAC-based scheme with the API :cpp:func:`nvs_sec_provider_register_hmac` which will also populate the scheme-specific handle (see :cpp:type:`nvs_sec_scheme_t`).
|
||||
- Populate the :cpp:type:`nvs_sec_cfg_t` struct using the :cpp:func:`nvs_flash_read_security_cfg_v2` or :cpp:func:`nvs_flash_generate_keys_v2` API functions.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
nvs_sec_cfg_t cfg = {};
|
||||
nvs_sec_scheme_t *sec_scheme_handle = NULL;
|
||||
nvs_sec_cfg_t cfg = {};
|
||||
nvs_sec_scheme_t *sec_scheme_handle = NULL;
|
||||
|
||||
nvs_sec_config_hmac_t sec_scheme_cfg = {};
|
||||
hmac_key_id_t hmac_key = HMAC_KEY0;
|
||||
sec_scheme_cfg.hmac_key_id = hmac_key;
|
||||
nvs_sec_config_hmac_t sec_scheme_cfg = {};
|
||||
hmac_key_id_t hmac_key = HMAC_KEY0;
|
||||
sec_scheme_cfg.hmac_key_id = hmac_key;
|
||||
|
||||
ret = nvs_sec_provider_register_hmac(&sec_scheme_cfg, &sec_scheme_handle);
|
||||
if (ret != ESP_OK) {
|
||||
return ret;
|
||||
}
|
||||
|
||||
ret = nvs_flash_read_security_cfg_v2(sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
if (ret == ESP_ERR_NVS_SEC_HMAC_KEY_NOT_FOUND) {
|
||||
ret = nvs_flash_generate_keys_v2(&sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to generate NVS encr-keys!");
|
||||
return ret;
|
||||
}
|
||||
ret = nvs_sec_provider_register_hmac(&sec_scheme_cfg, &sec_scheme_handle);
|
||||
if (ret != ESP_OK) {
|
||||
return ret;
|
||||
}
|
||||
|
||||
ret = nvs_flash_read_security_cfg_v2(sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
if (ret == ESP_ERR_NVS_SEC_HMAC_KEY_NOT_FOUND) {
|
||||
ret = nvs_flash_generate_keys_v2(&sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to generate NVS encr-keys!");
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
ESP_LOGE(TAG, "Failed to read NVS security cfg!");
|
||||
return ret;
|
||||
}
|
||||
ESP_LOGE(TAG, "Failed to read NVS security cfg!");
|
||||
return ret;
|
||||
}
|
||||
|
||||
2. Initialise NVS flash partition using the :cpp:func:`nvs_flash_secure_init` or :cpp:func:`nvs_flash_secure_init_partition` API functions.
|
||||
3. Open a namespace using the :cpp:func:`nvs_open` or :cpp:func:`nvs_open_from_partition` API functions.
|
||||
@ -185,8 +185,8 @@ Alternatively, :cpp:func:`nvs_flash_secure_init` API function can also be used t
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
.. note::
|
||||
While using the HMAC-based scheme, the above workflow can be used without enabling any of the config options for NVS encryption - :ref:`CONFIG_NVS_ENCRYPTION`, :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` and :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` to encrypt the default as well as custom NVS partitions with :cpp:func:`nvs_flash_secure_init` API.
|
||||
.. note::
|
||||
While using the HMAC-based scheme, the above workflow can be used without enabling any of the config options for NVS encryption - :ref:`CONFIG_NVS_ENCRYPTION`, :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` and :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` to encrypt the default as well as custom NVS partitions with :cpp:func:`nvs_flash_secure_init` API.
|
||||
|
||||
|
||||
NVS Security Provider
|
||||
|
||||
@ -69,7 +69,7 @@ NVS 密钥分区
|
||||
|
||||
idf.py partition-table partition-table-flash
|
||||
|
||||
1. 使用 :component_file:`parttool.py<partition_table/parttool.py>` （参见 :doc:`/api-guides/partition-tables` 中分区工具相关章节）将密钥存储在 flash 上的 :ref:`nvs_encr_key_partition` 中
|
||||
2. 使用 :component_file:`parttool.py<partition_table/parttool.py>` （参见 :doc:`/api-guides/partition-tables` 中分区工具相关章节）将密钥存储在 flash 上的 :ref:`nvs_encr_key_partition` 中
|
||||
::
|
||||
|
||||
parttool.py --port PORT --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
|
||||
@ -86,18 +86,18 @@ NVS 密钥分区
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
NVS 加密：基于 HMAC 外设的方案
|
||||
--------------------------------------------
|
||||
NVS 加密：基于 HMAC 外设的方案
|
||||
--------------------------------------------
|
||||
|
||||
此方案中，用于 NVS 加密的 XTS 密钥来自 eFuse 中编程的 HMAC 密钥，其目的是 :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`。由于加密密钥在运行时生成，不存储在 flash 中，因此这个功能不需要单独的 :ref:`nvs_encr_key_partition`。
|
||||
此方案中，用于 NVS 加密的 XTS 密钥来自 eFuse 中编程的 HMAC 密钥，其目的是 :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`。由于加密密钥在运行时生成，不存储在 flash 中，因此这个功能不需要单独的 :ref:`nvs_encr_key_partition`。
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
通过这个方案， **无需启用 flash 加密** 就能在 {IDF_TARGET_NAME} 上实现安全存储。
|
||||
通过这个方案， **无需启用 flash 加密** 就能在 {IDF_TARGET_NAME} 上实现安全存储。
|
||||
|
||||
.. important::
|
||||
.. important::
|
||||
|
||||
注意，此方案使用一个 eFuse 块来存储获取加密密钥所需的 HMAC 密钥。
|
||||
注意，此方案使用一个 eFuse 块来存储获取加密密钥所需的 HMAC 密钥。
|
||||
|
||||
- NVS 加密启用时后，可用 API 函数 :cpp:func:`nvs_flash_init` 来初始化加密的默认 NVS 分区。该 API 函数首先检查 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 处是否存在一个 HMAC 密钥。
|
||||
|
||||
@ -146,37 +146,37 @@ NVS API 函数 ``nvs_get_*`` 或 ``nvs_set_*`` 也可用于读取和写入加密
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
* 对基于 HMAC 的方案
|
||||
* 对基于 HMAC 的方案
|
||||
|
||||
- 用 :cpp:type:`nvs_sec_config_hmac_t` 为设置特定方案配置数据，并使用 API :cpp:func:`nvs_sec_provider_register_hmac` 注册此基于 HMAC 的方案。该 API 也将用于填充特定方案的句柄（参见 :cpp:type:`nvs_sec_scheme_t`）。
|
||||
- 使用 API 函数 :cpp:func:`nvs_flash_read_security_cfg_v2` 或 :cpp:func:`nvs_flash_generate_keys_v2` 填充 :cpp:type:`nvs_sec_cfg_t` 结构体。
|
||||
- 用 :cpp:type:`nvs_sec_config_hmac_t` 为设置特定方案配置数据，并使用 API :cpp:func:`nvs_sec_provider_register_hmac` 注册此基于 HMAC 的方案。该 API 也将用于填充特定方案的句柄（参见 :cpp:type:`nvs_sec_scheme_t`）。
|
||||
- 使用 API 函数 :cpp:func:`nvs_flash_read_security_cfg_v2` 或 :cpp:func:`nvs_flash_generate_keys_v2` 填充 :cpp:type:`nvs_sec_cfg_t` 结构体。
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
nvs_sec_cfg_t cfg = {};
|
||||
nvs_sec_scheme_t *sec_scheme_handle = NULL;
|
||||
nvs_sec_cfg_t cfg = {};
|
||||
nvs_sec_scheme_t *sec_scheme_handle = NULL;
|
||||
|
||||
nvs_sec_config_hmac_t sec_scheme_cfg = {};
|
||||
hmac_key_id_t hmac_key = HMAC_KEY0;
|
||||
sec_scheme_cfg.hmac_key_id = hmac_key;
|
||||
nvs_sec_config_hmac_t sec_scheme_cfg = {};
|
||||
hmac_key_id_t hmac_key = HMAC_KEY0;
|
||||
sec_scheme_cfg.hmac_key_id = hmac_key;
|
||||
|
||||
ret = nvs_sec_provider_register_hmac(&sec_scheme_cfg, &sec_scheme_handle);
|
||||
if (ret != ESP_OK) {
|
||||
ret = nvs_sec_provider_register_hmac(&sec_scheme_cfg, &sec_scheme_handle);
|
||||
if (ret != ESP_OK) {
|
||||
return ret;
|
||||
}
|
||||
|
||||
ret = nvs_flash_read_security_cfg_v2(sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
if (ret == ESP_ERR_NVS_SEC_HMAC_KEY_NOT_FOUND) {
|
||||
ret = nvs_flash_generate_keys_v2(&sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to generate NVS encr-keys!");
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
ESP_LOGE(TAG, "Failed to read NVS security cfg!");
|
||||
return ret;
|
||||
}
|
||||
|
||||
ret = nvs_flash_read_security_cfg_v2(sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
if (ret == ESP_ERR_NVS_SEC_HMAC_KEY_NOT_FOUND) {
|
||||
ret = nvs_flash_generate_keys_v2(&sec_scheme_handle, &cfg);
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to generate NVS encr-keys!");
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
ESP_LOGE(TAG, "Failed to read NVS security cfg!");
|
||||
return ret;
|
||||
}
|
||||
|
||||
2. 使用 API 函数 :cpp:func:`nvs_flash_secure_init` 或 :cpp:func:`nvs_flash_secure_init_partition` 初始化 NVS flash 分区。
|
||||
3. 使用 API 函数 :cpp:func:`nvs_open` 或 :cpp:func:`nvs_open_from_partition` 打开一个命名空间。
|
||||
@ -185,8 +185,8 @@ NVS API 函数 ``nvs_get_*`` 或 ``nvs_set_*`` 也可用于读取和写入加密
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
.. note::
|
||||
在采用基于 HMAC 的方案时，可以在不启用任何 NVS 加密的配置选项的情况下开始上述工作流：:ref:`CONFIG_NVS_ENCRYPTION`，:ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> `CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC` 和 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`，以使用 :cpp:func:`nvs_flash_secure_init` API 加密默认分区及自定义的 NVS 分区。
|
||||
.. note::
|
||||
在采用基于 HMAC 的方案时，可以在不启用任何 NVS 加密的配置选项的情况下开始上述工作流：:ref:`CONFIG_NVS_ENCRYPTION`，:ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> `CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC` 和 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`，以使用 :cpp:func:`nvs_flash_secure_init` API 加密默认分区及自定义的 NVS 分区。
|
||||
|
||||
|
||||
NVS Security Provider
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user