mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-03 03:31:41 +03:00
docs: Update CN translation for name change
This commit is contained in:
Zhang Shuxian
@@ -1,17 +1,17 @@
|
||||
数字签名 (DS)
|
||||
=============
|
||||
RSA 数字签名外设 (RSA_DS)
|
||||
==========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
数字签名 (DS) 模块提供基于 RSA 的消息签名硬件加速，并使用预加密参数来计算签名。这些参数通过 HMAC 作为密钥派生函数进行加密，而 HMAC 则以 eFuse 作为输入密钥。
|
||||
RSA 数字签名外设 (RSA_DS) 提供基于 RSA 的消息签名硬件加速，并使用预加密参数来计算签名。这些参数通过 HMAC 作为密钥派生函数进行加密，而 HMAC 则以 eFuse 作为输入密钥。
|
||||
|
||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||
|
||||
在 {IDF_TARGET_NAME} 上，数字签名 (DS) 模块也可以使用存储在密钥管理器中的密钥，而非 eFuse 密钥块。AES 加密密钥可以通过密钥管理器直接部署，类型为 :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`。详情请参阅 :ref:`key-manager`。
|
||||
在 {IDF_TARGET_NAME} 上，RSA 数字签名外设 (RSA_DS) 也可以使用存储在密钥管理器中的密钥，而非 eFuse 密钥块。AES 加密密钥可以通过密钥管理器直接部署，类型为 :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`。详情请参阅 :ref:`key-manager`。
|
||||
|
||||
以上过程均在硬件中完成，因此在计算签名时，软件无法获取 RSA 参数的解密密钥，也无法获取 HMAC 密钥派生函数的输入密钥。
|
||||
|
||||
签名计算所涉及的硬件信息以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
签名计算所涉及的硬件信息以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
|
||||
私钥参数
|
||||
@@ -24,14 +24,14 @@ RSA 签名的私钥参数存储在 flash 中。为防止发生未经授权的访
|
||||
密钥生成
|
||||
---------
|
||||
|
||||
在使用 DS 外设前，需首先创建并存储 HMAC 密钥和 RSA 私钥，此步骤可在 {IDF_TARGET_NAME} 上通过软件完成，也可在主机上进行。在 ESP-IDF 中，可以使用 :cpp:func:`esp_efuse_write_block` 设置 HMAC 密钥，并使用 :cpp:func:`esp_hmac_calculate` 对 RSA 私钥参数进行加密。
|
||||
在使用 RSA_DS 外设前，需首先创建并存储 HMAC 密钥和 RSA 私钥，此步骤可在 {IDF_TARGET_NAME} 上通过软件完成，也可在主机上进行。在 ESP-IDF 中，可以使用 :cpp:func:`esp_efuse_write_block` 设置 HMAC 密钥，并使用 :cpp:func:`esp_hmac_calculate` 对 RSA 私钥参数进行加密。
|
||||
|
||||
计算并组装私钥参数的详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
计算并组装私钥参数的详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
在 ESP-IDF 中进行数字签名计算
|
||||
----------------------------------
|
||||
|
||||
在 ESP-IDF 中进行数字签名计算的工作流程，以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
在 ESP-IDF 中进行数字签名计算的工作流程，以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
要进行数字签名计算，需要准备以下三个参数：
|
||||
|
||||
@@ -43,38 +43,38 @@ RSA 签名的私钥参数存储在 flash 中。为防止发生未经授权的访
|
||||
|
||||
签名计算需要一些时间，因此 ESP-IDF 提供了两种可用的 API：第一种是 :cpp:func:`esp_ds_sign`，调用此 API 后，程序会在计算完成前保持阻塞状态。如果在计算过程中，软件需要执行其他操作，则可以调用 :cpp:func:`esp_ds_start_sign`，用另一种方式启动签名计算，然后周期性地调用 :cpp:func:`esp_ds_is_busy`，检查计算是否已完成。一旦计算完成，即可调用 :cpp:func:`esp_ds_finish_sign` 来获取签名结果。
|
||||
|
||||
API 函数 :cpp:func:`esp_ds_sign` 和 :cpp:func:`esp_ds_start_sign` 在 DS 外设的帮助下计算原始 RSA 签名。该签名必须转换为合适的格式（例如 PKCS#1 v1.5 或 PSS），以用于 TLS 或其他协议。
|
||||
API 函数 :cpp:func:`esp_ds_sign` 和 :cpp:func:`esp_ds_start_sign` 在 RSA_DS 外设的帮助下计算原始 RSA 签名。该签名必须转换为合适的格式（例如 PKCS#1 v1.5 或 PSS），以用于 TLS 或其他协议。
|
||||
|
||||
.. note::
|
||||
|
||||
上述为 DS 的基本构件，其消息长度是固定的。为了对任意消息生成签名，通常会将实际消息的哈希值作为输入，并将其填充到所需长度。
|
||||
上述为 RSA_DS 的基本构件，其消息长度是固定的。为了对任意消息生成签名，通常会将实际消息的哈希值作为输入，并将其填充到所需长度。
|
||||
|
||||
**PSA 密码学驱动程序**
|
||||
|
||||
DS 外设也通过 **PSA Crypto RSA DS 驱动程序** 对外提供访问接口，因此可以使用标准 PSA API 执行签名（PKCS#1 v1.5 或 PSS）和 RSA 解密（PKCS#1 v1.5 或 OAEP）。在 ``Component config`` > ``mbedTLS`` 中启用 ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``。要在 ESP-TLS 中配合使用 DS 外设（例如 TLS 客户端认证），请参阅 ESP-TLS 文档中的 :ref:`digital-signature-with-esp-tls`。
|
||||
RSA_DS 外设也通过 **PSA Crypto RSA_DS 驱动程序** 对外提供访问接口，因此可以使用标准 PSA API 执行签名（PKCS#1 v1.5 或 PSS）和 RSA 解密（PKCS#1 v1.5 或 OAEP）。在 ``Component config`` > ``mbedTLS`` 中启用 ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``。要在 ESP-TLS 中配合使用 RSA_DS 外设（例如 TLS 客户端认证），请参阅 ESP-TLS 文档中的 :ref:`digital-signature-with-esp-tls`。
|
||||
|
||||
.. _configure-the-ds-peripheral:
|
||||
|
||||
TLS 连接所需的 DS 外设配置
|
||||
------------------------------
|
||||
TLS 连接所需的 RSA_DS 外设配置
|
||||
------------------------------------
|
||||
|
||||
在 {IDF_TARGET_NAME} 芯片上使用 TLS 连接之前，必须先配置 DS 外设，具体步骤如下：
|
||||
在 {IDF_TARGET_NAME} 芯片上使用 TLS 连接之前，必须先配置 RSA_DS 外设，具体步骤如下：
|
||||
|
||||
1) 随机生成一个 256 位的值，作为 ``初始化向量`` (IV)。
|
||||
2) 随机生成一个 256 位的值，作为 ``HMAC_KEY``。
|
||||
3) 使用客户端私钥 (RAS) 和上述步骤生成的参数，计算加密的私钥参数。
|
||||
4) 将 256 位的 ``HMAC_KEY`` 烧录到 eFuse 中，只支持 DS 外设读取。
|
||||
4) 将 256 位的 ``HMAC_KEY`` 烧录到 eFuse 中，只支持 RSA_DS 外设读取。
|
||||
|
||||
更多细节，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
更多细节，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
如果要以开发为目的配置 DS 外设，可以使用 `esp-secure-cert-tool <https://pypi.org/project/esp-secure-cert-tool>`_。
|
||||
如果要以开发为目的配置 RSA_DS 外设，可以使用 `esp-secure-cert-tool <https://pypi.org/project/esp-secure-cert-tool>`_。
|
||||
|
||||
在完成 DS 外设配置后获得的加密私钥参数应保存在 flash 中。应用需要从 flash 读取 DS 数据（例如，通过 `esp_secure_cert_mgr <https://github.com/espressif/esp_secure_cert_mgr>`_ 组件提供的 API。详情请参阅 `component/README <https://github.com/espressif/esp_secure_cert_mgr#readme>`_）。关于在 ESP-TLS 中使用 DS 外设的方法，请参阅 :ref:`digital-signature-with-esp-tls`。
|
||||
在完成 RSA_DS 外设配置后获得的加密私钥参数应保存在 flash 中。应用需要从 flash 读取 RSA_DS 数据（例如，通过 `esp_secure_cert_mgr <https://github.com/espressif/esp_secure_cert_mgr>`_ 组件提供的 API。详情请参阅 `component/README <https://github.com/espressif/esp_secure_cert_mgr#readme>`_）。关于在 ESP-TLS 中使用 RSA_DS 外设的方法，请参阅 :ref:`digital-signature-with-esp-tls`。
|
||||
|
||||
通过 PSA Crypto 使用 DS 外设
|
||||
----------------------------
|
||||
通过 PSA Crypto 使用 RSA_DS 外设
|
||||
------------------------------------
|
||||
|
||||
要在应用代码（不使用 ESP-TLS）中将 DS 外设用于签名或解密，请启用 ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``。使用加密的密钥数据 (:cpp:type:`esp_ds_data_t`)、eFuse 密钥块 ID 以及以 bit 为单位的 RSA 密钥长度填充 ``esp_ds_data_ctx_t``。确保在创建密钥时（例如通过 :cpp:func:`esp_ds_encrypt_params` 或 DS 配置工具）设置 :cpp:type:`esp_ds_data_t` 的 ``rsa_length`` 字段，然后将该上下文封装到 ``esp_rsa_ds_opaque_key_t`` 中，使用 ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE`` 将其作为 PSA 不透明密钥导入，并调用 ``psa_sign_hash()`` 或 ``psa_asymmetric_decrypt()``：
|
||||
要在应用代码（不使用 ESP-TLS）中将 RSA_DS 外设用于签名或解密，请启用 ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``。使用加密的密钥数据 (:cpp:type:`esp_ds_data_t`)、eFuse 密钥块 ID 以及以 bit 为单位的 RSA 密钥长度填充 ``esp_ds_data_ctx_t``。确保在创建密钥时（例如通过 :cpp:func:`esp_ds_encrypt_params` 或 RSA_DS 配置工具）设置 :cpp:type:`esp_ds_data_t` 的 ``rsa_length`` 字段，然后将该上下文封装到 ``esp_rsa_ds_opaque_key_t`` 中，使用 ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE`` 将其作为 PSA 不透明密钥导入，并调用 ``psa_sign_hash()`` 或 ``psa_asymmetric_decrypt()``：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -113,10 +113,10 @@ TLS 连接所需的 DS 外设配置
|
||||
|
||||
psa_destroy_key(key_id);
|
||||
|
||||
使用 DS 外设进行 SSL 双向认证
|
||||
-----------------------------
|
||||
使用 RSA_DS 外设进行 SSL 双向认证
|
||||
------------------------------------
|
||||
|
||||
此前位于 ``examples/protocols/mqtt/ssl_ds`` 目录下的 SSL 双向认证示例现已随独立的 `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ 组件一同提供。请参照该组件文档获取 SSL DS 示例，并与 ESP-MQTT 一同构建。该示例仍使用 ``mqtt_client`` （由 ESP-MQTT 实现），通过双向认证 TLS 连接至 ``test.mosquitto.org``，其中 TLS 通信层仍由 ESP-TLS 实现。
|
||||
此前位于 ``examples/protocols/mqtt/ssl_ds`` 目录下的 SSL 双向认证示例现已随独立的 `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ 组件一同提供。请参照该组件文档获取 SSL RSA_DS 示例，并与 ESP-MQTT 一同构建。该示例仍使用 ``mqtt_client`` （由 ESP-MQTT 实现），通过双向认证 TLS 连接至 ``test.mosquitto.org``，其中 TLS 通信层仍由 ESP-TLS 实现。
|
||||
|
||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||
|
||||
|
||||
Reference in New Issue
Block a user