kopia lustrzana https://github.com/espressif/esp-idf
docs: Provide CN translation for api-reference/peripherals/ds.rst
Shang Zhou
rodzic
d6a79b5108
commit
57f5343462
|
|
@ -1,83 +1,72 @@
|
|||
Digital Signature (DS)
|
||||
======================
|
||||
|
||||
The Digital Signature (DS) module 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 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.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
For more detailed information on the hardware involved in signature calculation and the registers used, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
The Digital Signature (DS) module 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.
|
||||
|
||||
For more detailed information on the hardware involved in the signature calculation and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
|
||||
|
||||
Private Key Parameters
|
||||
----------------------
|
||||
The private key parameters for the RSA signature are stored in flash.
|
||||
To prevent unauthorized access, they are AES-encrypted.
|
||||
The HMAC module is used as a key-derivation function to calculate the AES encryption key for the private key parameters.
|
||||
In turn, the HMAC module uses a key from the eFuses key block which can be read-protected to prevent unauthorized access as well.
|
||||
|
||||
Upon signature calculation invocation, the software only specifies which eFuse key to use, the corresponding eFuse key purpose, the location of the encrypted RSA parameters and the message.
|
||||
The private key parameters for the RSA signature are stored in flash. To prevent unauthorized access, they are AES-encrypted. The HMAC module is used as a key-derivation function to calculate the AES encryption key for the private key parameters. In turn, the HMAC module uses a key from the eFuses key block which can be read-protected to prevent unauthorized access as well.
|
||||
|
||||
Upon signature calculation invocation, the software only specifies which eFuse key to use, the corresponding eFuse key purpose, the location of the encrypted RSA parameters, and the message.
|
||||
|
||||
Key Generation
|
||||
--------------
|
||||
Both the HMAC key and the RSA private key have to be created and stored before the DS peripheral can be used.
|
||||
This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host.
|
||||
For this context, the IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters.
|
||||
|
||||
You can find instructions on how to calculate and assemble the private key parameters in *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
Both the HMAC key and the RSA private key have to be created and stored before the DS peripheral can be used. This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host. For this context, ESP-IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters.
|
||||
|
||||
Signature Calculation with IDF
|
||||
------------------------------
|
||||
You can find instructions on how to calculate and assemble the private key parameters in **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
|
||||
For more detailed information on the workflow and the registers used, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
Signature Calculation with ESP-IDF
|
||||
----------------------------------
|
||||
|
||||
For more detailed information on the workflow and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
|
||||
Three parameters need to be prepared to calculate the digital signature:
|
||||
|
||||
#. the eFuse key block ID which is used as key for the HMAC,
|
||||
#. the location of the encrypted private key parameters,
|
||||
#. and the message to be signed.
|
||||
#. The eFuse key block ID which is used as the key for the HMAC
|
||||
#. The location of the encrypted private key parameters
|
||||
#. The message to be signed
|
||||
|
||||
Since the signature calculation takes some time, there are two possible API versions to use in IDF.
|
||||
The first one is :cpp:func:`esp_ds_sign` and simply blocks until the calculation is finished.
|
||||
If software needs to do something else during the calculation, :cpp:func:`esp_ds_start_sign` can be called, followed by periodic calls to :cpp:func:`esp_ds_is_busy` to check when the calculation has finished.
|
||||
Once the calculation has finished, :cpp:func:`esp_ds_finish_sign` can be called to get the resulting signature.
|
||||
Since the signature calculation takes some time, there are two possible API versions to use in ESP-IDF. The first one is :cpp:func:`esp_ds_sign` and simply blocks until the calculation is finished. If software needs to do something else during the calculation, :cpp:func:`esp_ds_start_sign` can be called, followed by periodic calls to :cpp:func:`esp_ds_is_busy` to check when the calculation has finished. Once the calculation has finished, :cpp:func:`esp_ds_finish_sign` can be called to get the resulting signature.
|
||||
|
||||
The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with help of the DS peripheral. This signature needs to be converted to appropriate format for further use. For example, MbedTLS SSL stack supports PKCS#1 format. The API :cpp:func:`esp_ds_rsa_sign` can be used to obtain the signature directly in the PKCS#1 v1.5 format. It internally uses :cpp:func:`esp_ds_start_sign` and converts the signature into PKCS#1 v1.5 format.
|
||||
The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with the help of the DS peripheral. This signature needs to be converted to an appropriate format for further use. For example, the MbedTLS SSL stack supports PKCS#1 format. The API :cpp:func:`esp_ds_rsa_sign` can be used to obtain the signature directly in the PKCS#1 v1.5 format. It internally uses :cpp:func:`esp_ds_start_sign` and converts the signature into PKCS#1 v1.5 format.
|
||||
|
||||
.. note::
|
||||
Note that this is only the basic DS building block, the message length is fixed.
|
||||
To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length.
|
||||
An API to do this is planned in the future.
|
||||
|
||||
This is only the basic DS building block, the message length is fixed. To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length. An API to do this is planned in the future.
|
||||
|
||||
.. _configure-the-ds-peripheral:
|
||||
|
||||
Configure the DS peripheral for a TLS connection
|
||||
Configure the DS Peripheral for a TLS Connection
|
||||
------------------------------------------------
|
||||
|
||||
The DS peripheral on {IDF_TARGET_NAME} chip must be configured before it can be used for a TLS connection.
|
||||
The configuration involves the following steps -
|
||||
The DS peripheral on {IDF_TARGET_NAME} chip must be configured before it can be used for a TLS connection. The configuration involves the following steps:
|
||||
|
||||
1) Randomly generate a 256 bit value called the `Initialization Vector` (IV).
|
||||
2) Randomly generate a 256 bit value called the `HMAC_KEY`.
|
||||
3) Calculate the encrypted private key paramters from the client private key (RSA) and the parameters generated in the above steps.
|
||||
4) Then burn the 256 bit `HMAC_KEY` on the efuse, which can only be read by the DS peripheral.
|
||||
1) Randomly generate a 256-bit value called the ``Initialization Vector`` (IV).
|
||||
2) Randomly generate a 256-bit value called the ``HMAC_KEY``.
|
||||
3) Calculate the encrypted private key parameters from the client private key (RSA) and the parameters generated in the above steps.
|
||||
4) Then burn the 256-bit ``HMAC_KEY`` on the eFuse, which can only be read by the DS peripheral.
|
||||
|
||||
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** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||
|
||||
To configure the DS peripheral for development purposes, you can use the `esp-secure-cert-tool <https://pypi.org/project/esp-secure-cert-tool>`_.
|
||||
|
||||
The encrypted private key parameters obtained after the DS peripheral configuration are then to be kept in flash. Furthermore, they are to be passed to the DS peripheral which makes use of those parameters for the Digital Signature operation. The application then needs to read the ds data from the flash which has been done through the API's provided by the `esp_secure_cert_mgr <https://github.com/espressif/esp_secure_cert_mgr>`_ component. Please refer the `component/README. <https://github.com/espressif/esp_secure_cert_mgr#readme>`_ for more details.
|
||||
The encrypted private key parameters obtained after the DS peripheral configuration are then to be kept in flash. Furthermore, they are to be passed to the DS peripheral which makes use of those parameters for the Digital Signature operation. The application then needs to read the DS data from the flash, which has been done through the APIs provided by the `esp_secure_cert_mgr <https://github.com/espressif/esp_secure_cert_mgr>`_ component. Please refer to the `component/README <https://github.com/espressif/esp_secure_cert_mgr#readme>`_ for more details.
|
||||
|
||||
The process of initializing the DS peripheral and then performing the Digital Signature operation is done internally with help of `ESP-TLS`. Please refer to `Digital Signature with ESP-TLS` in :doc:`ESP-TLS <../protocols/esp_tls>` for more details.
|
||||
As mentioned in the `ESP-TLS` documentation, the application only needs to provide the encrypted private key parameters to the esp_tls context (as `ds_data`), which internally performs
|
||||
all necessary operations for initializing the DS peripheral and then performing the DS operation.
|
||||
The process of initializing the DS peripheral and then performing the Digital Signature operation is done internally with the help of `ESP-TLS`. Please refer to :ref:`digital-signature-with-esp-tls` for more details.
|
||||
|
||||
Example for SSL Mutual Authentication using DS
|
||||
As mentioned in the `ESP-TLS` documentation, the application only needs to provide the encrypted private key parameters to the esp_tls context (as `ds_data`), which internally performs all necessary operations for initializing the DS peripheral and then performing the DS operation.
|
||||
|
||||
Example for SSL Mutual Authentication Using DS
|
||||
----------------------------------------------
|
||||
The example :example:`ssl_ds<protocols/mqtt/ssl_ds>` shows how to use the DS peripheral for mutual authentication. The example uses `mqtt_client` (Implemented through `ESP-MQTT`)
|
||||
to connect to broker test.mosquitto.org using ssl transport with mutual authentication. The ssl part is internally performed with `ESP-TLS`.
|
||||
See :example_file:`example README<protocols/mqtt/ssl_ds/README.md>` for more details.
|
||||
|
||||
The example :example:`protocols/mqtt/ssl_ds` shows how to use the DS peripheral for mutual authentication. The example uses `mqtt_client` (Implemented through `ESP-MQTT`) to connect to broker ``test.mosquitto.org`` using SSL transport with mutual authentication. The SSL part is internally performed with `ESP-TLS`. See :example_file:`protocols/mqtt/ssl_ds/README.md` for more details.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
|
|
|||
|
|
@ -1,2 +1,74 @@
|
|||
.. include:: ../../../en/api-reference/peripherals/ds.rst
|
||||
数字签名 (DS)
|
||||
=============
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
数字签名 (DS) 模块利用 RSA 硬件加速器为信息签名。HMAC 作为密钥派生函数，使用 eFuse 作为输入密钥，输出一组加密参数。随后，数字签名模块利用这组预加密的参数，计算出签名。以上过程均在硬件中完成，因此在计算签名时，软件无法获取 RSA 参数的解密密钥，也无法获取 HMAC 密钥派生函数的输入密钥。
|
||||
|
||||
签名计算所涉及的硬件信息以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
|
||||
私钥参数
|
||||
--------
|
||||
|
||||
RSA 签名的私钥参数存储在 flash 中。为防止发生未经授权的访问，这些参数都进行了 AES 加密。此时，HMAC 模块被作为密钥派生函数，用于计算 AES 加密了的私钥参数。同时，HMAC 模块本身使用的来自 eFuse 密钥块的密钥也具有读取保护，可以防止发生未经授权的访问。
|
||||
|
||||
调用签名计算时，软件只需指定使用的 eFuse 密钥、相应的 eFuse 密钥用途、加密的 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>`__]。
|
||||
|
||||
在 ESP-IDF 中进行数字签名计算
|
||||
----------------------------------
|
||||
|
||||
在 ESP-IDF 中进行数字签名计算的工作流程，以及所用寄存器的有关信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
要进行数字签名计算，需要准备以下三个参数：
|
||||
|
||||
#. 用作 HMAC 密钥的 eFuse 密钥块 ID
|
||||
#. 加密私钥参数的位置
|
||||
#. 待签名的数据或信息
|
||||
|
||||
由于签名计算需要一些时间，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 签名。RSA 签名需要转换成合适的格式，以供进一步使用。例如，MbedTLS SSL 栈支持 PKCS#1 格式，使用 API :cpp:func:`esp_ds_rsa_sign` 可以直接获得 PKCS#1 v1.5 格式的签名，该 API 内部调用了 :cpp:func:`esp_ds_start_sign` 函数，并将签名转换成 PKCS#1 v1.5 格式。
|
||||
|
||||
.. note::
|
||||
|
||||
此处只是最基本的 DS 构造块，其消息必须是固定长度。为在任意消息上创建签名，通常会将实际消息的哈希值作为输入，并将其填充到所需长度。乐鑫计划在未来提供一个 API 来实现这个功能。
|
||||
|
||||
.. _configure-the-ds-peripheral:
|
||||
|
||||
TLS 连接所需的 DS 外设配置
|
||||
------------------------------
|
||||
|
||||
在 {IDF_TARGET_NAME} 芯片上使用 TLS 连接之前，必须先配置 DS 外设，具体步骤如下：
|
||||
|
||||
1) 随机生成一个 256 位的值，作为 ``初始化向量`` (IV)。
|
||||
2) 随机生成一个 256 位的值，作为 ``HMAC_KEY``。
|
||||
3) 使用客户端私钥 (RAS) 和上述步骤生成的参数，计算加密的私钥参数。
|
||||
4) 将 256 位的 ``HMAC_KEY`` 烧录到 eFuse 中，只支持 DS 外设读取。
|
||||
|
||||
更多细节，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。
|
||||
|
||||
如果要以开发为目的配置 DS 外设，可以使用 `esp-secure-cert-tool <https://pypi.org/project/esp-secure-cert-tool>`_。
|
||||
|
||||
配置完 DS 外设后获取的加密私钥参数需要保存在 flash 中并传递给 DS 外设，DS 外设将使用这些参数完成数字签名。随后，应用程序需要从 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 仓库内部，`ESP-TLS` 负责完成初始化 DS 外设、执行数字签名的过程。更多细节，请参阅 :ref:`digital-signature-with-esp-tls`。
|
||||
|
||||
如 `ESP-TLS` 文档所述，应用程序只需将加密私钥参数作为 `ds_data` 传递给 esp_tls 上下文，esp_tls 仓库内部就会执行所有必要操作，以初始化 DS 外设，并执行数字签名。
|
||||
|
||||
使用 DS 外设进行 SSL 双向认证
|
||||
-----------------------------
|
||||
|
||||
示例 :example:`protocols/mqtt/ssl_ds` 展示了如何使用 DS 外设进行 SSL 双向认证。在示例中，使用了 `mqtt_client` （通过 `ESP-MQTT` 实现），通过 SSL 传输连接到代理服务器 ``test.mosquitto.org``，并进行 SSL 双向认证。SSL 部分在内部使用 `ESP-TLS` 完成。更多细节，请参阅 :example_file:`protocols/mqtt/ssl_ds/README.md`。
|
||||
|
||||
API 参考
|
||||
--------
|
||||
|
||||
.. include-build-file:: inc/esp_ds.inc
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue