diff --git a/docs/en/api-reference/peripherals/ds.rst b/docs/en/api-reference/peripherals/ds.rst index eb79d8c5f4..fdcbc7d084 100644 --- a/docs/en/api-reference/peripherals/ds.rst +++ b/docs/en/api-reference/peripherals/ds.rst @@ -3,7 +3,6 @@ RSA Digital Signature Peripheral (RSA_DS) :link_to_translation:`zh_CN:[中文]` -<<<<<<< HEAD The RSA Digital Signature Peripheral (RSA_DS) provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. .. only:: SOC_KEY_MANAGER_SUPPORTED @@ -11,9 +10,6 @@ The RSA Digital Signature Peripheral (RSA_DS) provides hardware acceleration of On {IDF_TARGET_NAME}, the RSA Digital Signature Peripheral (RSA_DS) can also use a key stored in the Key Manager instead of an eFuse key block. The AES encryption key can be directly deployed in the Key Manager with the type :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`. Refer to :ref:`key-manager` for more details. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature. -======= -The RSA Digital Signature Peripheral (RSA_DS) provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature. ->>>>>>> 81dc3a427c00 (docs(security): Standardize naming of digital signature hardware modules) For more detailed information on the hardware involved in the signature calculation and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. @@ -55,7 +51,7 @@ The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a p **PSA Crypto driver** -The DS peripheral is also exposed via the **PSA Crypto RSA DS driver**, so you can use standard PSA APIs for signing (PKCS#1 v1.5 or PSS) and RSA decryption (PKCS#1 v1.5 or OAEP). Enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL`` in ``Component config`` > ``mbedTLS``. For using the DS peripheral with ESP-TLS (e.g. TLS client authentication), see :ref:`digital-signature-with-esp-tls` in the ESP-TLS documentation. +The RSA_DS peripheral is also exposed via the **PSA Crypto RSA_DS driver**, so you can use standard PSA APIs for signing (PKCS#1 v1.5 or PSS) and RSA decryption (PKCS#1 v1.5 or OAEP). Enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL`` in ``Component config`` > ``mbedTLS``. For using the RSA_DS peripheral with ESP-TLS (e.g. TLS client authentication), see :ref:`digital-signature-with-esp-tls` in the ESP-TLS documentation. .. _configure-the-ds-peripheral: @@ -73,7 +69,7 @@ For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA D To configure the RSA_DS peripheral for development purposes, you can use the `esp-secure-cert-tool `_. -The encrypted private key parameters obtained after the RSA_DS peripheral configuration should be stored in flash. The application needs to read the RSA_DS data from flash (e.g. through the APIs provided by the `esp_secure_cert_mgr `_ component; see the `component/README `_ for more details). For using the RSA_DS peripheral with ESP-TLS, see :ref:`digital-signature-with-esp-tls`. +The encrypted private key parameters obtained after the RSA_DS peripheral configuration should be stored in flash. The application needs to read the RSA_DS data from flash (e.g., through the APIs provided by the `esp_secure_cert_mgr `_ component; see the `component/README `_ for more details). For using the RSA_DS peripheral with ESP-TLS, see :ref:`digital-signature-with-esp-tls`. Using RSA_DS with PSA Crypto ----------------------------- @@ -120,7 +116,7 @@ To use the RSA_DS peripheral for signing or decryption in application code (outs Example for SSL Mutual Authentication Using RSA_DS --------------------------------------------------- -The SSL mutual authentication example that previously lived under ``examples/protocols/mqtt/ssl_ds`` is now shipped with the standalone `espressif/mqtt `__ component. Follow the component documentation to fetch the SSL DS example and build it together with ESP-MQTT. The example continues to use ``mqtt_client`` (implemented by ESP-MQTT) to connect to ``test.mosquitto.org`` over mutual-authenticated TLS, with the TLS portion handled by ESP-TLS. +The SSL mutual authentication example that previously lived under ``examples/protocols/mqtt/ssl_ds`` is now shipped with the standalone `espressif/mqtt `__ component. Follow the component documentation to fetch the SSL RSA_DS example and build it together with ESP-MQTT. The example continues to use ``mqtt_client`` (implemented by ESP-MQTT) to connect to ``test.mosquitto.org`` over mutual-authenticated TLS, with the TLS portion handled by ESP-TLS. .. only:: SOC_KEY_MANAGER_SUPPORTED diff --git a/docs/en/api-reference/peripherals/hmac.rst b/docs/en/api-reference/peripherals/hmac.rst index 066cd891bc..bed3555eef 100644 --- a/docs/en/api-reference/peripherals/hmac.rst +++ b/docs/en/api-reference/peripherals/hmac.rst @@ -37,7 +37,7 @@ This key can be made completely inaccessible for any resources outside the crypt 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 RSA Digital Signature Peripheral (RSA_DS) module +#. HMAC is used as a key for the RSA Digital Signature Peripheral (RSA_DS) #. 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. @@ -58,7 +58,7 @@ Each key has a corresponding eFuse parameter **key purpose** determining for whi * - 8 - HMAC generated for software use * - 7 - - HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS) module + - HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS) * - 6 - HMAC used for enabling the soft-disabled JTAG interface * - 5 @@ -88,7 +88,7 @@ The HMAC can be used as a key derivation function to decrypt private key paramet Neither the key nor the actual HMAC is ever exposed outside the HMAC module and RSA_DS component. The calculation of the HMAC and its handover to the RSA_DS component happen internally. -For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. .. _hmac_for_enabling_jtag: diff --git a/docs/zh_CN/api-reference/peripherals/ds.rst b/docs/zh_CN/api-reference/peripherals/ds.rst index 22aa2d288d..f7bc334c36 100644 --- a/docs/zh_CN/api-reference/peripherals/ds.rst +++ b/docs/zh_CN/api-reference/peripherals/ds.rst @@ -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 `_。 +如果要以开发为目的配置 RSA_DS 外设，可以使用 `esp-secure-cert-tool `_。 -在完成 DS 外设配置后获得的加密私钥参数应保存在 flash 中。应用需要从 flash 读取 DS 数据（例如，通过 `esp_secure_cert_mgr `_ 组件提供的 API。详情请参阅 `component/README `_）。关于在 ESP-TLS 中使用 DS 外设的方法，请参阅 :ref:`digital-signature-with-esp-tls`。 +在完成 RSA_DS 外设配置后获得的加密私钥参数应保存在 flash 中。应用需要从 flash 读取 RSA_DS 数据（例如，通过 `esp_secure_cert_mgr `_ 组件提供的 API。详情请参阅 `component/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 `__ 组件一同提供。请参照该组件文档获取 SSL DS 示例，并与 ESP-MQTT 一同构建。该示例仍使用 ``mqtt_client`` （由 ESP-MQTT 实现），通过双向认证 TLS 连接至 ``test.mosquitto.org``，其中 TLS 通信层仍由 ESP-TLS 实现。 +此前位于 ``examples/protocols/mqtt/ssl_ds`` 目录下的 SSL 双向认证示例现已随独立的 `espressif/mqtt `__ 组件一同提供。请参照该组件文档获取 SSL RSA_DS 示例，并与 ESP-MQTT 一同构建。该示例仍使用 ``mqtt_client`` （由 ESP-MQTT 实现），通过双向认证 TLS 连接至 ``test.mosquitto.org``，其中 TLS 通信层仍由 ESP-TLS 实现。 .. only:: SOC_KEY_MANAGER_SUPPORTED diff --git a/docs/zh_CN/api-reference/peripherals/ecdsa.rst b/docs/zh_CN/api-reference/peripherals/ecdsa.rst index d1890c0c70..b8315b265b 100644 --- a/docs/zh_CN/api-reference/peripherals/ecdsa.rst +++ b/docs/zh_CN/api-reference/peripherals/ecdsa.rst @@ -1,13 +1,13 @@ -椭圆曲线数字签名算法 (ECDSA) -============================ +ECDSA 数字签名外设 (ECDSA_DS) +==================================== :link_to_translation:`en:[English]` -椭圆曲线数字签名算法 (ECDSA) 是数字签名算法 (DSA) 基于椭圆曲线密码学的变体。 +ECDSA 数字签名外设 (ECDSA_DS) 采用椭圆曲线数字签名算法 (ECDSA)，ECDSA 是数字签名算法 (DSA) 基于椭圆曲线密码学的变体。 -{IDF_TARGET_NAME} 的 ECDSA 外设为计算 ECDSA 签名提供了一个安全高效的环境，不仅能确保签名过程的机密性，防止信息泄露，也提供了快速的计算。在签名过程中使用的 ECDSA 私钥只能由硬件外设访问，软件无法读取。 +{IDF_TARGET_NAME} 的 ECDSA_DS 外设为计算 ECDSA 签名提供了一个安全高效的环境，不仅能确保签名过程的机密性，防止信息泄露，也提供了快速的计算。在签名过程中使用的 ECDSA 私钥只能由硬件外设访问，软件无法读取。 -ECDSA 外设可以为 TLS 双向身份验证等用例建立 **安全设备身份认证**。 +ECDSA_DS 外设可以为 TLS 双向身份验证等用例建立 **安全设备身份认证**。 支持的特性 ---------- @@ -21,14 +21,14 @@ ECDSA 外设可以为 TLS 双向身份验证等用例建立 **安全设备身份 :not SOC_ECDSA_SUPPORT_CURVE_P384: - ECDSA 操作中哈希消息的两种哈希算法，SHA-224 和 SHA-256（FIPS PUB 180-4 规范） -{IDF_TARGET_NAME} 上的 ECDSA ----------------------------- +{IDF_TARGET_NAME} 上的 ECDSA_DS +-------------------------------- -在 {IDF_TARGET_NAME} 上，ECDSA 模块使用烧录到 eFuse 块中的密钥。 +在 {IDF_TARGET_NAME} 上，ECDSA_DS 模块使用烧录到 eFuse 块中的密钥。 .. only:: SOC_KEY_MANAGER_SUPPORTED - 在 {IDF_TARGET_NAME} 上，ECDSA 模块也支持将密钥存储在密钥管理器中，详情请参阅 :ref:`key-manager`。 + 在 {IDF_TARGET_NAME} 上，ECDSA_DS 模块也支持将密钥存储在密钥管理器中，详情请参阅 :ref:`key-manager`。 密码模块外的任何资源都不可访问此密钥（默认模式），从而避免密钥泄露。 @@ -69,13 +69,13 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编 .. note:: - 五个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 8。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。 + 五个物理 eFuse 块可作为 ECDSA_DS 模块的密钥：块 4 ~ 块 8。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。 .. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK .. note:: - 六个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 9。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。 + 六个物理 eFuse 块可作为 ECDSA_DS 模块的密钥：块 4 ~ 块 9。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。 .. only:: SOC_KEY_MANAGER_SUPPORTED @@ -116,11 +116,11 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编 .. only:: esp32h2 - ESP32-H2 的 ECDSA 外设支持 ECDSA-P192 和 ECDSA-P256 两种曲线操作。但从 ESP32-H2 版本 1.2 开始，默认仅启用 ECDSA-P256 操作。可以通过以下配置项启用 ECDSA-P192 操作： + ESP32-H2 的 ECDSA_DS 外设支持 ECDSA-P192 和 ECDSA-P256 两种曲线操作。但从 ESP32-H2 版本 1.2 开始，默认仅启用 ECDSA-P256 操作。可以通过以下配置项启用 ECDSA-P192 操作： .. only:: not esp32h2 - {IDF_TARGET_NAME} 的 ECDSA 外设支持 ECDSA-P192 和 ECDSA-P256 两种曲线操作，但默认仅启用 ECDSA-P256 操作。可以通过以下配置项启用 ECDSA-P192 操作： + {IDF_TARGET_NAME} 的 ECDSA_DS 外设支持 ECDSA-P192 和 ECDSA-P256 两种曲线操作，但默认仅启用 ECDSA-P256 操作。可以通过以下配置项启用 ECDSA-P192 操作： - :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` 启用对 ECDSA-P192 曲线操作的支持，使设备可以同时执行 192 位和 256 位的 ECDSA 曲线操作。但请注意，如果 eFuse 写保护期间已永久禁用 ECDSA-P192 操作，则启用该配置项也无法重新启用该功能。 @@ -131,7 +131,7 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编 生成确定性签名 -------------- - {IDF_TARGET_NAME} 的 ECDSA 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 `_ 第 3.2 节。 + {IDF_TARGET_NAME} 的 ECDSA_DS 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 `_ 第 3.2 节。 生成非确定性签名 ---------------- @@ -139,16 +139,16 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编 对 TRNG 的依赖 ^^^^^^^^^^^^^^ -ECDSA 外设依靠硬件真随机数生成器 (TRNG) 来满足其内部熵要求，从而生成非确定性签名。在创建 ECDSA 签名时，算法需要生成一个随机整数，在 `RFC 6090 `_ 第 5.3.2 节有说明。 +ECDSA_DS 外设依靠硬件真随机数生成器 (TRNG) 来满足其内部熵要求，从而生成非确定性签名。在创建 ECDSA 签名时，算法需要生成一个随机整数，在 `RFC 6090 `_ 第 5.3.2 节有说明。 在应用程序中启动 ECDSA 计算（主要是签名）之前，请确保硬件 :doc:`RNG <../system/random>` 已经启用。 应用程序概述 ------------ -有关如何使用 ECDSA 外设建立 TLS 双向身份验证连接的详细信息，请参阅 :ref:`ecdsa-peri-with-esp-tls` 指南。 +有关如何使用 ECDSA_DS 外设建立 TLS 双向身份验证连接的详细信息，请参阅 :ref:`ecdsa-peri-with-esp-tls` 指南。 -通过覆盖 ECDSA 签名以及验证 API，可以集成 Mbed TLS 堆栈中的 ECDSA 外设。请注意，ECDSA 外设并不支持所有曲线或哈希算法。因此，在不满足硬件要求时，实现会退回到软件。 +通过覆盖 ECDSA 签名以及验证 API，可以集成 Mbed TLS 堆栈中的 ECDSA_DS 外设。请注意，ECDSA_DS 外设并不支持所有曲线或哈希算法。因此，在不满足硬件要求时，实现会退回到软件。 对于特定的 TLS 上下文，可用额外的 API 来填充某些字段（例如私钥 ctx），以区分路由到硬件的路径。ESP-TLS 层在内部集成了这些 API，因此在应用程序层不需要额外的操作。对于自定义用例，请参阅以下 API 详细信息。 diff --git a/docs/zh_CN/api-reference/peripherals/hmac.rst b/docs/zh_CN/api-reference/peripherals/hmac.rst index f723e1e33e..53fb41ed9d 100644 --- a/docs/zh_CN/api-reference/peripherals/hmac.rst +++ b/docs/zh_CN/api-reference/peripherals/hmac.rst @@ -37,7 +37,7 @@ 此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景： #. HMAC 支持软件使用 -#. HMAC 用作数字签名 (DS) 的密钥 +#. HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 #. HMAC 用于启用软禁用的 JTAG 接口 第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。 @@ -58,11 +58,11 @@ HMAC 的 eFuse 密钥 * - 8 - HMAC 支持软件使用 * - 7 - - HMAC 用作数字签名 (DS) 的密钥 + - HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 * - 6 - HMAC 启用软禁用的 JTAG 接口 * - 5 - - HMAC 既用作数字签名 (DS) 的密钥，又用于启用 JTAG 接口 + - HMAC 既用作 RSA 数字签名外设 (RSA_DS) 的密钥，又用于启用 JTAG 接口 这样一来，可以确保密钥用于原定场景。 @@ -79,16 +79,16 @@ HMAC 支持软件使用 :cpp:func:`psa_mac_compute` 用于计算 HMAC，该函数接收一个不透明的 PSA 密钥，该密钥引用了包含密钥机密的 eFuse 密钥块，并且该密钥块的用途被设置为上行模式。 -HMAC 用作数字签名 (DS) 的密钥 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 密钥功能值：7、5 -HMAC 可用作密钥派生函数，解码数字签名模块使用的私钥参数。在此情况下，硬件使用标准信息进行计算。在 HMAC 部分只需提供 eFuse 密钥块和功能；而在数字签名模块则还需要一些额外参数。 +HMAC 可用作密钥派生函数，解码 RSA_DS 模块使用的私钥参数。在此情况下，硬件使用标准信息进行计算。在 HMAC 部分只需提供 eFuse 密钥块和功能；而在 RSA_DS 模块则还需要一些额外参数。 -无论是密钥还是实际的 HMAC，都不会暴露在 HMAC 和数字签名模块之外。对 HMAC 的计算，以及将其传递给数字签名模块的过程，均在内部进行。 +无论是密钥还是实际的 HMAC，都不会暴露在 HMAC 和 RSA_DS 模块之外。对 HMAC 的计算，以及将其传递给 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>`__]。 .. _hmac_for_enabling_jtag: diff --git a/docs/zh_CN/api-reference/protocols/esp_http_client.rst b/docs/zh_CN/api-reference/protocols/esp_http_client.rst index e89b7e9255..06448005d2 100644 --- a/docs/zh_CN/api-reference/protocols/esp_http_client.rst +++ b/docs/zh_CN/api-reference/protocols/esp_http_client.rst @@ -46,10 +46,10 @@ HTTP 基本请求 .. only:: SOC_ECDSA_SUPPORTED - 为 TLS 使用 ECDSA 外设 - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 为 TLS 使用 ECDSA_DS 外设 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ECDSA 外设可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 ` 中的 **在 ESP-TLS 中使用 ECDSA 外设** 小节。可以按如下方式配置 HTTP 客户端以使用 ECDSA 外设： + ECDSA_DS 外设可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 ` 中的 **在 ESP-TLS 中使用 ECDSA_DS 外设** 小节。可以按如下方式配置 HTTP 客户端以使用 ECDSA_DS 外设： .. code-block:: c diff --git a/docs/zh_CN/api-reference/protocols/esp_tls.rst b/docs/zh_CN/api-reference/protocols/esp_tls.rst index 8e11dbef63..5db5fe2be4 100644 --- a/docs/zh_CN/api-reference/protocols/esp_tls.rst +++ b/docs/zh_CN/api-reference/protocols/esp_tls.rst @@ -247,9 +247,9 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须 ESP-TLS 的数字签名 ---------------------------------- - ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用数字签名 (DS)，但只有当 ESP-TLS 以 MbedTLS（默认协议栈）为底层 SSL/TLS 协议栈时，才支持使用 TLS 的数字签名。有关数字签名的详细信息，请参阅 :doc:`数字签名 (DS) `。有关数字签名的技术细节（例如私钥参数计算），请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]。在使用数字签名前，应预先配置数字签名外设，请参阅 :ref:`configure-the-ds-peripheral`。 + ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用 RSA 数字签名外设 (RSA_DS)，但只有当 ESP-TLS 以 MbedTLS（默认协议栈）为底层 SSL/TLS 协议栈时，才支持使用 TLS 的 RSA 数字签名。有关 RSA_DS 的详细信息，请参阅 :doc:`RSA 数字签名外设 (RSA_DS) `。有关 RSA 数字签名的技术细节（例如私钥参数计算），请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]。在使用 RSA 数字签名前，应预先配置 RSA 数字签名外设，请参阅 :ref:`configure-the-ds-peripheral`。 - 数字签名外设必须用所需的加密私钥参数初始化，相应参数在配置数字签名外设时获取。具备所需的数字签名上下文，即数字签名参数时，ESP-TLS 会在内部初始化数字签名外设。要将数字签名上下文传递给 ESP-TLS 上下文，请参阅以下代码段。注意，在删除 TLS 连接之前，不应释放传递给 ESP-TLS 上下文的数字签名上下文。 + RSA 数字签名外设必须用所需的加密私钥参数初始化，相应参数在配置 RSA 数字签名外设时获取。具备所需的数字签名上下文，即数字签名参数时，ESP-TLS 会在内部初始化 RSA 数字签名外设。要将数字签名上下文传递给 ESP-TLS 上下文，请参阅以下代码段。注意，在删除 TLS 连接之前，不应释放传递给 ESP-TLS 上下文的数字签名上下文。 .. code-block:: c @@ -265,20 +265,20 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须 .. note:: - 当使用数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。 + 当使用 RSA 数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。 - * 现有一个基于 DS 外设的双向认证示例，已随独立的 `espressif/mqtt `__ 组件一同提供，其内部依赖 ESP-TLS 建立 TLS 连接。请参照组件文档获取并构建该示例。 + * 现有一个基于 RSA_DS 外设的双向认证示例，已随独立的 `espressif/mqtt `__ 组件一同提供，其内部依赖 ESP-TLS 建立 TLS 连接。请参照组件文档获取并构建该示例。 .. only:: SOC_ECDSA_SUPPORTED .. _ecdsa-peri-with-esp-tls: - 在 ESP-TLS 中使用 ECDSA 外设 - ----------------------------- + 在 ESP-TLS 中使用 ECDSA_DS 外设 + ---------------------------------- - ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用 ECDSA 外设。使用 ECDSA 外设时，ESP-TLS 必须与 MbedTLS 一起作为底层 SSL/TLS 协议栈，并且 ECDSA 的私钥应存储在 eFuse 中。请参考 :doc:`ECDSA 指南 <../peripherals/ecdsa>`，了解如何在 eFuse 中烧写 ECDSA 密钥。 + ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用 ECDSA 数字签名外设 (ECDSA_DS)。使用 ECDSA_DS 外设时，ESP-TLS 必须与 MbedTLS 一起作为底层 SSL/TLS 协议栈，并且 ECDSA 的私钥应存储在 eFuse 中。请参考 :doc:`ECDSA 数字签名外设 (ECDSA_DS) 指南 <../peripherals/ecdsa>`，了解如何在 eFuse 中烧写 ECDSA 密钥。 - 这样就可以使用 ECDSA 外设进行私钥操作。由于客户私钥已经存储在 eFuse 中，因此无需将其传递给 :cpp:type:`esp_tls_cfg_t`。 + 这样就可以使用 ECDSA_DS 外设进行私钥操作。由于客户私钥已经存储在 eFuse 中，因此无需将其传递给 :cpp:type:`esp_tls_cfg_t`。请参见下面的代码片段，了解如何为给定的 ESP-TLS 连接启用 ECDSA_DS 外设。 .. code-block:: c @@ -292,7 +292,7 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须 .. note:: - 在 TLS 中使用 ECDSA 外设时，只支持 ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` 密码套件。如果使用 TLS v1.3，则支持 ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` 密码套件。 + 在 TLS 中使用 ECDSA_DS 外设时，只支持 ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` 密码套件。如果使用 TLS v1.3，则支持 ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` 密码套件。 .. _esp_tls_client_session_tickets: diff --git a/docs/zh_CN/security/secure-boot-v2.rst b/docs/zh_CN/security/secure-boot-v2.rst index 1777d3e21e..8eebce7d97 100644 --- a/docs/zh_CN/security/secure-boot-v2.rst +++ b/docs/zh_CN/security/secure-boot-v2.rst @@ -531,7 +531,7 @@ Secure Boot v2 签名验证也可以在 OTA 更新期间验证数据分区镜像 .. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED - 启用安全启动后，ECDSA 曲线模式将锁定为写保护状态。因此，如果启用前未将曲线模式设置为使用 ECDSA-P192 密钥，那么之后将无法再配置或使用 ECDSA 外设中的 ECDSA-P192 曲线。 + 启用安全启动后，ECDSA 曲线模式将锁定为写保护状态。因此，如果启用前未将曲线模式设置为使用 ECDSA-P192 密钥，那么之后将无法再配置或使用 ECDSA_DS 外设中的 ECDSA-P192 曲线。 烧录读保护密钥 ~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst index eb5b9cf6e5..1d82a8ec58 100644 --- a/docs/zh_CN/security/security.rst +++ b/docs/zh_CN/security/security.rst @@ -3,7 +3,7 @@ {IDF_TARGET_CIPHER_SCHEME:default="RSA", esp32h2="RSA 或 ECDSA", esp32p4="RSA 或 ECDSA", esp32c5="RSA 或 ECDSA", esp32c61="ECDSA", esp32h21="RSA 或 ECDSA"} -{IDF_TARGET_SIG_PERI:default="DS", esp32h2="DS 或 ECDSA", esp32p4="DS 或 ECDSA", esp32c5="DS 或 ECDSA"} +{IDF_TARGET_SIG_PERI:default="RSA_DS", esp32h2="RSA_DS 或 ECDSA_DS", esp32p4="RSA_DS 或 ECDSA_DS", esp32c5="RSA_DS 或 ECDSA_DS", esp32c61="ECDSA_DS"} :link_to_translation:`en:[English]` @@ -85,21 +85,21 @@ flash 加密最佳实践 设备身份 ~~~~~~~~~~~~~~~ - 在 {IDF_TARGET_NAME} 中，数字签名外设借助硬件加速，通过 HMAC 算法生成 RSA 数字签名。RSA 私钥仅限设备硬件访问，软件无法获取，保证了设备上存储密钥的安全性。 + 在 {IDF_TARGET_NAME} 中，RSA 数字签名外设借助硬件加速，通过 HMAC 算法生成 RSA 数字签名。RSA 私钥仅限设备硬件访问，软件无法获取，保证了设备上存储密钥的安全性。 .. only:: SOC_ECDSA_SUPPORTED - {IDF_TARGET_NAME} 还支持 ECDSA 外设，用于生成硬件加速的 ECDSA 数字签名。ECDSA 私钥支持直接编程到 eFuse 块中，并在软件中标记为读保护。 + {IDF_TARGET_NAME} 还支持 ECDSA_DS 外设，用于生成硬件加速的 ECDSA 数字签名。ECDSA 私钥支持直接编程到 eFuse 块中，并在软件中标记为读保护。 {IDF_TARGET_SIG_PERI} 外设可以建立与远程终端之间的 **安全设备身份**，如基于 {IDF_TARGET_CIPHER_SCHEME} 加密算法的 TLS 双向认证。 .. only:: not SOC_ECDSA_SUPPORTED - 详情请参阅 :doc:`../api-reference/peripherals/ds`。 + 详情请参阅 :doc:`RSA 数字签名外设 (RSA_DS) <../api-reference/peripherals/ds>`。 .. only:: SOC_ECDSA_SUPPORTED - 详情请参阅 :doc:`../api-reference/peripherals/ecdsa` 及 :doc:`../api-reference/peripherals/ds`。 + 详情请参阅 :doc:`ECDSA 数字签名外设 (ECDSA_DS) <../api-reference/peripherals/ecdsa>` 及 :doc:`RSA 数字签名外设 (RSA_DS) <../api-reference/peripherals/ds>`。 .. only:: SOC_KEY_MANAGER_SUPPORTED