mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/add_Chinese_translation_for_api-reference-peripherals/secure_element.rst_and_hmac.rst' into 'master'
docs: provide CN translation for api-reference/peripherals/hmac.rst and... Closes DOC-5811 See merge request espressif/esp-idf!24881
This commit is contained in:
Cai Xin Ying
commit
878c4a32fd
@ -1,44 +1,47 @@
|
||||
Hash-based Message Authentication Code (HMAC)
|
||||
Hash-Based Message Authentication Code (HMAC)
|
||||
=============================================
|
||||
|
||||
The HMAC (Hash-based Message Authentication Code) module provides hardware acceleration for SHA256-HMAC generation using a key burned into an eFuse block.
|
||||
HMACs work with pre-shared secret keys and provide authenticity and integrity to a message.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
For more detailed information on the application workflow and the HMAC calculation process, see *{IDF_TARGET_NAME} Technical Reference Manual* > *HMAC Accelerator (HMAC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
|
||||
Hash-based Message Authentication Code (HMAC) is a secure authentication technique that verifies the authenticity and integrity of a message with a pre-shared key. This module provides hardware acceleration for SHA256-HMAC generation using a key burned into an eFuse block.
|
||||
|
||||
For more detailed information on the application workflow and the HMAC calculation process, see **{IDF_TARGET_NAME} Technical Reference Manual** > **HMAC Accelerator (HMAC)** [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
|
||||
|
||||
Generalized Application Scheme
|
||||
------------------------------
|
||||
Let there be two parties, A and B. They want to verify the authenticity and integrity of messages sent between each other.
|
||||
Before they can start sending messages, they need to exchange the secret key via a secure channel.
|
||||
|
||||
Let there be two parties, A and B. They want to verify the authenticity and integrity of messages sent between each other. Before they can start sending messages, they need to exchange the secret key via a secure channel.
|
||||
|
||||
To verify A's messages, B can do the following:
|
||||
|
||||
- A calculates the HMAC of the message it wants to send.
|
||||
- A sends the message and the HMAC to B.
|
||||
- B calculates HMAC of the received message itself.
|
||||
- B checks wether the received and calculated HMACs match.
|
||||
If they do match, the message is authentic.
|
||||
- B calculates the HMAC of the received message itself.
|
||||
- B checks whether the received and calculated HMACs match.
|
||||
|
||||
However, the HMAC itself isn't bound to this use case.
|
||||
It can also be used for challenge-response protocols supporting HMAC or as a key input for further security modules (see below), etc.
|
||||
If they do match, the message is authentic.
|
||||
|
||||
HMAC on the {IDF_TARGET_NAME}
|
||||
However, the HMAC itself is not bound to this use case. It can also be used for challenge-response protocols supporting HMAC or as a key input for further security modules (see below), etc.
|
||||
|
||||
HMAC on {IDF_TARGET_NAME}
|
||||
-----------------------------
|
||||
On the {IDF_TARGET_NAME}, the HMAC module works with a secret key burnt into the eFuses.
|
||||
This eFuse key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage.
|
||||
|
||||
Furthermore, the {IDF_TARGET_NAME} has three different application scenarios for its HMAC module:
|
||||
On {IDF_TARGET_NAME}, the HMAC module works with a secret key burnt into the eFuses. This eFuse key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage.
|
||||
|
||||
Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module:
|
||||
|
||||
#. HMAC is generated for software use
|
||||
#. HMAC is used as a key for the Digital Signature (DS) module
|
||||
#. HMAC is used for enabling the soft-disabled JTAG interface
|
||||
|
||||
The first mode is called *Upstream* mode, while the last two modes are called *Downstream* modes.
|
||||
The first mode is called **Upstream** mode, while the last two modes are called **Downstream** modes.
|
||||
|
||||
eFuse Keys for HMAC
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
Six physical eFuse blocks can be used as keys for the HMAC module: block 4 up to block 9.
|
||||
The enum :cpp:enum:`hmac_key_id_t` in the API maps them to `HMAC_KEY0 ... HMAC_KEY5`.
|
||||
Each key has a corresponding eFuse parameter *key purpose* determining for which of the three HMAC application scenarios (see below) the key may be used:
|
||||
|
||||
Six physical eFuse blocks can be used as keys for the HMAC module: block 4 ~ block 9. The enum :cpp:enum:`hmac_key_id_t` in the API maps them to ``HMAC_KEY0`` ~ ``HMAC_KEY5``.
|
||||
|
||||
Each key has a corresponding eFuse parameter **key purpose** determining for which of the three HMAC application scenarios (see below) the key may be used:
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 70
|
||||
@ -57,90 +60,99 @@ Each key has a corresponding eFuse parameter *key purpose* determining for which
|
||||
|
||||
This is to prevent the usage of a key for a different function than originally intended.
|
||||
|
||||
To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the *key purpose* (see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]).
|
||||
Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block.
|
||||
The calculation only proceeds if the purpose of the provided key block matches the purpose stored in the eFuses of the key block provided by the ID.
|
||||
To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the **key purpose** (see **{IDF_TARGET_NAME} Technical Reference Manual** > **eFuse Controller (eFuse)** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]).
|
||||
|
||||
Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block. The calculation only proceeds if the purpose of the provided key block matches the purpose stored in the eFuses of the key block provided by the ID.
|
||||
|
||||
HMAC Generation for Software
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Key Purpose value: 8
|
||||
|
||||
In this case, the HMAC is given out to the software (e.g. to authenticate a message).
|
||||
Key purpose value: 8
|
||||
|
||||
The API to calculate the HMAC is :cpp:func:`esp_hmac_calculate`.
|
||||
The input arguments for the function are the message, message length and the eFuse key block ID which contains the secret and has efuse key purpose set to Upstream mode.
|
||||
In this case, the HMAC is given out to the software, e.g., to authenticate a message.
|
||||
|
||||
The API to calculate the HMAC is :cpp:func:`esp_hmac_calculate`. The input arguments for the function are the message, message length, and the eFuse key block ID which contains the secret and has the efuse key purpose set to Upstream mode.
|
||||
|
||||
HMAC for Digital Signature
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Key Purpose values: 7, 5
|
||||
|
||||
The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the Digital Signature module.
|
||||
A standard message is used by the hardware in that case.
|
||||
The user only needs to provide the eFuse key block and purpose on the HMAC side (additional parameters are required for the Digital Signature component in that case).
|
||||
Neither the key nor the actual HMAC are ever exposed to outside the HMAC module and DS component.
|
||||
The calculation of the HMAC and its hand-over to the DS component happen internally.
|
||||
Key purpose values: 7, 5
|
||||
|
||||
For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the Digital Signature module. A standard message is used by the hardware in that case. You only need to provide the eFuse key block and purpose on the HMAC side, additional parameters are required for the Digital Signature component in that case.
|
||||
|
||||
Neither the key nor the actual HMAC is ever exposed outside the HMAC module and DS component. The calculation of the HMAC and its handover to the DS component happen internally.
|
||||
|
||||
For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
|
||||
.. _hmac_for_enabling_jtag:
|
||||
|
||||
HMAC for Enabling JTAG
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
Key Purpose values: 6, 5
|
||||
|
||||
Key purpose values: 6, 5
|
||||
|
||||
The third application is using the HMAC as a key to enable JTAG if it was soft-disabled before.
|
||||
Following is the procedure to re-enable the JTAG
|
||||
|
||||
Setup
|
||||
Following is the procedure to re-enable the JTAG:
|
||||
|
||||
**Stage 1: Setup**
|
||||
|
||||
1. Generate a 256-bit HMAC secret key to use for JTAG re-enable.
|
||||
2. Write the key to an eFuse block with key purpose HMAC_DOWN_ALL (5) or HMAC_DOWN_JTAG (6). This can be done using the ets_efuse_write_key() function in the firmware or using espefuse.py from the host.
|
||||
3. Configure the eFuse key block to be read protected using the esp_efuse_set_read_protect(), so that software cannot read back the value.
|
||||
4. Burn the "soft JTAG disable" bit/bits on {IDF_TARGET_NAME}. This will permanently disable JTAG unless the correct key value is provided by software.
|
||||
2. Write the key to an eFuse block with key purpose HMAC_DOWN_ALL (5) or HMAC_DOWN_JTAG (6). This can be done using the ``esp_efuse_write_key()`` function in the firmware or using ``espefuse.py`` from the host.
|
||||
3. Configure the eFuse key block to be read-protected using the ``esp_efuse_set_read_protect()``, so that software cannot read back the value.
|
||||
4. Burn the ``soft JTAG disable`` bit/bits on {IDF_TARGET_NAME}. This will permanently disable JTAG unless the correct key value is provided by the software.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. note:: The API *esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG)* can be used to burn "soft JTAG disable" bit on {IDF_TARGET_NAME}.
|
||||
.. note::
|
||||
|
||||
The API **esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG)** can be used to burn ``soft JTAG disable`` bit on {IDF_TARGET_NAME}.
|
||||
|
||||
.. only:: not esp32s2
|
||||
|
||||
.. note:: The API *esp_efuse_write_field_cnt(ESP_EFUSE_SOFT_DIS_JTAG, ESP_EFUSE_SOFT_DIS_JTAG[0]->bit_count)* can be used to burn "soft JTAG disable" bits on {IDF_TARGET_NAME}.
|
||||
.. note::
|
||||
|
||||
The API **esp_efuse_write_field_cnt(ESP_EFUSE_SOFT_DIS_JTAG, ESP_EFUSE_SOFT_DIS_JTAG[0]->bit_count)** can be used to burn ``soft JTAG disable`` bits on {IDF_TARGET_NAME}.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. note:: If ``HARD_DIS_JTAG`` eFuse is set, then ``SOFT_DIS_JTAG`` functionality does not work because JTAG is permanently disabled.
|
||||
.. note::
|
||||
|
||||
If ``HARD_DIS_JTAG`` eFuse is set, then ``SOFT_DIS_JTAG`` functionality does not work because JTAG is permanently disabled.
|
||||
|
||||
.. only:: not esp32s2 and not esp32s3
|
||||
|
||||
.. note:: If ``DIS_PAD_JTAG`` eFuse is set, then ``SOFT_DIS_JTAG`` functionality does not work because JTAG is permanently disabled.
|
||||
.. note::
|
||||
|
||||
JTAG enable
|
||||
If ``DIS_PAD_JTAG`` eFuse is set, then ``SOFT_DIS_JTAG`` functionality does not work because JTAG is permanently disabled.
|
||||
|
||||
1. The key to re-enable JTAG is the output of the HMAC-SHA256 function using the secret key in eFuse and 32 0x00 bytes as the message.
|
||||
JTAG enables
|
||||
|
||||
1. The key to re-enable JTAG is the output of the HMAC-SHA256 function using the secret key in eFuse and 32 ``0x00`` bytes as the message.
|
||||
2. Pass this key value when calling the :cpp:func:`esp_hmac_jtag_enable` function from the firmware.
|
||||
3. To re-disable JTAG in the firmware, reset the system or call :cpp:func:`esp_hmac_jtag_disable`.
|
||||
|
||||
For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *HMAC Accelerator (HMAC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
|
||||
For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **HMAC Accelerator (HMAC)** [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
|
||||
|
||||
|
||||
Application Outline
|
||||
-------------------
|
||||
|
||||
Following code is an outline of how to set an eFuse key and then use it to calculate an HMAC for software usage.
|
||||
We use `ets_efuse_write_key` to set physical key block 4 in the eFuse for the HMAC module together with its purpose.
|
||||
`ETS_EFUSE_KEY_PURPOSE_HMAC_UP` (8) means that this key can only be used for HMAC generation for software usage:
|
||||
The following code is an outline of how to set an eFuse key and then use it to calculate an HMAC for software usage.
|
||||
|
||||
We use ``esp_efuse_write_key`` to set physical key block 4 in the eFuse for the HMAC module together with its purpose. ``ESP_EFUSE_KEY_PURPOSE_HMAC_UP`` (8) means that this key can only be used for HMAC generation for software usage:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "{IDF_TARGET_PATH_NAME}/rom/efuse.h"
|
||||
#include "esp_efuse.h"
|
||||
|
||||
const uint8_t key_data[32] = { ... };
|
||||
|
||||
int ets_status = ets_efuse_write_key(ETS_EFUSE_BLOCK_KEY4,
|
||||
ETS_EFUSE_KEY_PURPOSE_HMAC_UP,
|
||||
esp_err_t status = esp_efuse_write_key(EFUSE_BLK_KEY4,
|
||||
ESP_EFUSE_KEY_PURPOSE_HMAC_UP,
|
||||
key_data, sizeof(key_data));
|
||||
|
||||
if (ets_status == ESP_OK) {
|
||||
if (status == ESP_OK) {
|
||||
// written key
|
||||
} else {
|
||||
// writing key failed, maybe written already
|
||||
|
||||
@ -1,24 +1,28 @@
|
||||
ESP32-WROOM-32SE (Secure Element)
|
||||
=================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32-WROOM-32SE has integrated Microchip's ATECC608A cryptoauth chip in the module. ATECC608A is secure element
|
||||
which would generate and store ECC private key in the hardware.The ECC private key can be used to enhance security
|
||||
to connect to IoT cloud services with use of X.509 based mutual authentication.
|
||||
The application example demonstrates ECDSA sign and verify functions using ECC private key stored in ATECC608A
|
||||
ESP32-WROOM-32SE integrates Microchip's ATECC608A cryptoauth chip in the module. ATECC608A is a secure element, which would generate and store ECC private key in the hardware. The ECC private key can be used to enhance security to connect to IoT cloud services with the use of X.509-based mutual authentication.
|
||||
|
||||
The application example demonstrates ECDSA sign and verify functions using ECC private key stored in ATECC608A.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Secure Element ECDSA Sign/Verify example: :example:`peripherals/secure_element/atecc608_ecdsa`.
|
||||
|
||||
How to configure and provision ESP32-WROOM-32SE for TLS
|
||||
How to Configure and Provision ESP32-WROOM-32SE for TLS
|
||||
-------------------------------------------------------
|
||||
To configure and provision ATECC608A chip on ESP32-WROOM-32SE please visit `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_
|
||||
|
||||
How to use ATECC608A of ESP32-WROOM-32SE for TLS
|
||||
To configure and provision ATECC608A chip on ESP32-WROOM-32SE please visit `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_.
|
||||
|
||||
How to Use ATECC608A of ESP32-WROOM-32SE for TLS
|
||||
------------------------------------------------
|
||||
|
||||
ATECC608A can be used for TLS connections using ESP-TLS.
|
||||
To configure ESP-TLS for using secure element please refer `ATECC608A with ESP-TLS` in :doc:`ESP-TLS documentation.<../protocols/esp_tls>`
|
||||
|
||||
To configure ESP-TLS for using a secure element, please refer to **ATECC608A (Secure Element) with ESP-TLS** in :doc:`../protocols/esp_tls`.
|
||||
|
||||
@ -1,2 +1,183 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/hmac.rst
|
||||
哈希消息认证码 (HMAC)
|
||||
=============================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
哈希消息认证码 (HMAC) 是一种安全的身份认证技术，支持使用预共享的密钥验证消息的真实性和完整性。利用烧录在 eFuse 块中的密钥，HMAC 可以为生成 SHA256-HMAC 提供硬件加速。
|
||||
|
||||
更多有关应用操作流程，及 HMAC 计算过程的详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **HMAC 加速器 (HMAC)** [`PDF <{IDF_TARGET_TRM_CN_URL}#hmac>`__]。
|
||||
|
||||
通用应用方案
|
||||
-------------------
|
||||
|
||||
现有 A、B 双方，他们都需要验证对方发送消息的真实性和完整性。那么在开始发送消息前，双方应通过安全通道交换密钥。
|
||||
|
||||
要验证来自 A 的信息，B 可遵循以下步骤：
|
||||
|
||||
- A 计算要发送的消息的 HMAC。
|
||||
- A 将消息及消息的 HMAC 一并发送给 B。
|
||||
- B 自行计算所接收消息的 HMAC。
|
||||
- B 检查接收到的 HMAC 是否与计算得出的 HMAC 匹配。
|
||||
|
||||
若两个 HMAC 匹配，消息为真。
|
||||
|
||||
但 HMAC 本身还可以应用于更多场景，如支持 HMAC 的挑战-应答协议，或作为更多安全模块（详见下文）的密钥输入等。
|
||||
|
||||
{IDF_TARGET_NAME} 上的 HMAC
|
||||
-----------------------------
|
||||
|
||||
在 {IDF_TARGET_NAME} HMAC 模块的 eFuse 中会烧录一个密钥，可将该 eFuse 密钥设置为禁止所有外部资源访问，避免密钥泄露。
|
||||
|
||||
此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景：
|
||||
|
||||
#. HMAC 支持软件使用
|
||||
#. HMAC 用作数字签名 (DS) 的密钥
|
||||
#. HMAC 用于启用软禁用的 JTAG 接口
|
||||
|
||||
第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。
|
||||
|
||||
HMAC 的 eFuse 密钥
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在 {IDF_TARGET_NAME} 中，有六个物理 eFuse 块可用作 HMAC 的密钥，分别是块 4 到块 9。在 API 中，枚举类型 :cpp:enum:`hmac_key_id_t` 将这些块映射为 ``HMAC_KEY0`` ~ ``HMAC_KEY5``。
|
||||
|
||||
每个密钥都有相应的 eFuse 参数 **密钥功能 (key purpose)**，决定密钥应用于 HMAC 的哪种应用场景。
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 70
|
||||
:header-rows: 1
|
||||
|
||||
* - 密钥功能
|
||||
- 应用场景
|
||||
* - 8
|
||||
- HMAC 支持软件使用
|
||||
* - 7
|
||||
- HMAC 用作数字签名 (DS) 的密钥
|
||||
* - 6
|
||||
- HMAC 启用软禁用的 JTAG 接口
|
||||
* - 5
|
||||
- HMAC 既用作数字签名 (DS) 的密钥，又用于启用 JTAG 接口
|
||||
|
||||
这样一来，可以确保密钥用于原定场景。
|
||||
|
||||
要计算 HMAC，软件必须同时提供包含密钥的密钥块 ID，以及 **密钥功能** （详情请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **eFuse 控制器 (eFuse)** [`PDF <{IDF_TARGET_TRM_CN_URL}#efuse>`__])。
|
||||
|
||||
在进行 HMAC 密钥计算前，HMAC 会验证软件所提供密钥块的功能。在软件所提供 ID 的对应密钥块中，eFuse 存储了密钥块的功能。只有当软件所提供密钥块的功能与 eFuse 中存储的密钥块功能匹配，才会继续进行计算。
|
||||
|
||||
HMAC 支持软件使用
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
密钥功能值：8
|
||||
|
||||
在此情况下，HMAC 支持软件使用，如验证消息真实性等。
|
||||
|
||||
API :cpp:func:`esp_hmac_calculate` 用于计算 HMAC。输入参数包括消息、消息长度以及包含密钥的 eFuse 密钥块 ID，且该密钥块的 eFuse 密钥功能设置为上行模式。
|
||||
|
||||
HMAC 用作数字签名 (DS) 的密钥
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
密钥功能值：7、5
|
||||
|
||||
HMAC 可用作密钥派生函数，解码数字签名模块使用的私钥参数。在此情况下，硬件使用标准信息进行计算。在 HMAC 部分只需提供 eFuse 密钥块和功能；而在数字签名模块则还需要一些额外参数。
|
||||
|
||||
无论是密钥还是实际的 HMAC，都不会暴露在 HMAC 和数字签名模块之外。对 HMAC 的计算，以及将其传递给数字签名模块的过程，均在内部进行。
|
||||
|
||||
详情请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
.. _hmac_for_enabling_jtag:
|
||||
|
||||
HMAC 启用 JTAG 接口
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
密钥功能值：6、5
|
||||
|
||||
HMAC 的第三种应用场景是将其作为密钥，启用软禁用的 JTAG 接口。
|
||||
|
||||
重新启用 JTAG 接口的步骤如下：
|
||||
|
||||
**第一步：设置**
|
||||
|
||||
1. 生成一个 256 位的 HMAC 密钥，用于重新启用 JTAG。
|
||||
2. 将步骤 1 获得的密钥写入 eFuse 块，且 eFuse 块的密钥功能参数应为 HMAC_DOWN_ALL (5) 或 HMAC_DOWN_JTAG (6)。为此，可以使用固件中的 ``esp_efuse_write_key()`` 函数，或使用主机上的 ``espefuse.py`` 完成操作。
|
||||
3. 使用 ``esp_efuse_set_read_protect()`` 将 eFuse 密钥块配置为读保护，防止软件读取写入到 eFuse 密钥块中的 HMAC 密钥值。
|
||||
4. 在烧录到 {IDF_TARGET_NAME} 上时，将特定的位或位组设置为 ``soft JTAG disable``。这样可以永久禁用 JTAG 接口，除非软件提供正确的密钥值进行验证。
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. note::
|
||||
|
||||
API **esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG)** 支持在 {IDF_TARGET_NAME} 上烧录 ``soft JTAG disable`` 位。
|
||||
|
||||
.. only:: not esp32s2
|
||||
|
||||
.. note::
|
||||
|
||||
API **esp_efuse_write_field_cnt(ESP_EFUSE_SOFT_DIS_JTAG, ESP_EFUSE_SOFT_DIS_JTAG[0]->bit_count)** 支持在 {IDF_TARGET_NAME} 上烧录 ``soft JTAG disable`` 位。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. note::
|
||||
|
||||
置位 ``HARD_DIS_JTAG`` eFuse 时，JTAG 处于永久禁用状态，``SOFT_DIS_JTAG`` 功能将失效。
|
||||
|
||||
.. only:: not esp32s2 and not esp32s3
|
||||
|
||||
.. note::
|
||||
|
||||
置位 ``DIS_PAD_JTAG`` eFuse 时，JTAG 处于永久禁用状态，``SOFT_DIS_JTAG`` 功能将失效。
|
||||
|
||||
启用 JTAG
|
||||
|
||||
1. 以 eFuse 中的密钥和 32 个 ``0x00`` 字节为输入，经过 HMAC-SHA256 函数处理，得到的函数输出结果即重新启用 JTAG 的密钥。
|
||||
2. 从固件调用 :cpp:func:`esp_hmac_jtag_enable` 函数时，传递上一步获取的密钥值。
|
||||
3. 要在固件中重新禁用 JTAG，可以重置系统，或调用 :cpp:func:`esp_hmac_jtag_disable`。
|
||||
|
||||
更多有关详情，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **HMAC 加速器 (HMAC)** [`PDF <{IDF_TARGET_TRM_CN_URL}#hmac>`__]。
|
||||
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
以下为针对特定应用场景的实例代码，可用于设置 eFuse 密钥，并将其用于计算支持软件使用的 HMAC。
|
||||
|
||||
``esp_efuse_write_key`` 可以设置 eFuse 中的物理密钥块 4，并设置其功能。``ESP_EFUSE_KEY_PURPOSE_HMAC_UP`` (8) 表明，该密钥仅适用于生成支持软件使用的 HMAC。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_efuse.h"
|
||||
|
||||
const uint8_t key_data[32] = { ... };
|
||||
|
||||
esp_err_t status = esp_efuse_write_key(EFUSE_BLK_KEY4,
|
||||
ESP_EFUSE_KEY_PURPOSE_HMAC_UP,
|
||||
key_data, sizeof(key_data));
|
||||
|
||||
if (status == ESP_OK) {
|
||||
// 密钥写入成功
|
||||
} else {
|
||||
// 密钥写入失败，可能已写入过
|
||||
}
|
||||
|
||||
接下来可以使用已存储的密钥来计算 HMAC，供软件使用。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_hmac.h"
|
||||
|
||||
uint8_t hmac[32];
|
||||
|
||||
const char *message = "Hello, HMAC!";
|
||||
const size_t msg_len = 12;
|
||||
|
||||
esp_err_t result = esp_hmac_calculate(HMAC_KEY4, message, msg_len, hmac);
|
||||
|
||||
if (result == ESP_OK) {
|
||||
// HMAC 已写入 hmac 数组
|
||||
} else {
|
||||
// 计算 HMAC 失败
|
||||
}
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_hmac.inc
|
||||
|
||||
@ -1 +1,28 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/secure_element.rst
|
||||
ESP32-WROOM-32SE（安全元件）
|
||||
=================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
ESP32-WROOM-32SE 模组集成了 Microchip 的 ATECC608A 加密认证芯片。ATECC608A 安全元件可以在硬件中生成并存储 ECC 私钥。通过使用基于 X.509 的双向认证，ECC 私钥可增强设备与物联网云服务连接的安全性。
|
||||
|
||||
有关如何使用存储在 ATECC608A 中的 ECC 私钥进行 ECDSA 签名和验证，请参阅以下应用示例。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
请参阅安全元件 ECDSA 签名/验证示例 :example:`peripherals/secure_element/atecc608_ecdsa`。
|
||||
|
||||
对 ESP32-WROOM-32SE 配置并配网以进行 TLS 连接
|
||||
-------------------------------------------------------
|
||||
|
||||
要在 ESP32-WROOM-32SE 上配置 ATECC608A 芯片，并对其进行配网，请参阅 `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_。
|
||||
|
||||
使用 ESP32-WROOM-32SE 的 ATECC608A 进行 TLS 连接
|
||||
------------------------------------------------------
|
||||
|
||||
通过使用 ESP-TLS，ATECC608A 可实现 TLS 连接。
|
||||
|
||||
要配置 ESP-TLS 以使用安全元件，请参阅 :doc:`../protocols/esp_tls` 中的 **ESP-TLS 中的 ATECC608A（安全元件）** 一节。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user