mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 19:13:21 +00:00
Merge branch 'bugfix/rename_dig_sig_modules' into 'master'
docs(security): Standardize naming of digital signature hardware modules Closes DOC-13873 and DOC-13913 See merge request espressif/esp-idf!46093
This commit is contained in:
Krzysztof Budzynski
@@ -1,17 +1,17 @@
|
|||||||
Digital Signature (DS)
|
RSA Digital Signature Peripheral (RSA_DS)
|
||||||
======================
|
==========================================
|
||||||
|
|
||||||
:link_to_translation:`zh_CN:[中文]`
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
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 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
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
On {IDF_TARGET_NAME}, the Digital Signature (DS) module 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.
|
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 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>`__].
|
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>`__].
|
||||||
|
|
||||||
|
|
||||||
Private Key Parameters
|
Private Key Parameters
|
||||||
@@ -24,14 +24,14 @@ Upon signature calculation invocation, the software only specifies which eFuse k
|
|||||||
Key Generation
|
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, 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.
|
Both the HMAC key and the RSA private key have to be created and stored before the RSA_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.
|
||||||
|
|
||||||
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>`__].
|
You can find instructions on how to calculate and assemble the private key parameters in **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||||
|
|
||||||
Signature Calculation with ESP-IDF
|
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>`__].
|
For more detailed information on the workflow and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
|
||||||
|
|
||||||
Three parameters need to be prepared to calculate the digital signature:
|
Three parameters need to be prepared to calculate the digital signature:
|
||||||
|
|
||||||
@@ -43,38 +43,38 @@ Three parameters need to be prepared to calculate the digital 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.
|
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 the help of the DS peripheral. This signature must be converted to an appropriate format (e.g., PKCS#1 v1.5 or PSS) for use in TLS or other protocols.
|
The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with the help of the RSA_DS peripheral. This signature must be converted to an appropriate format (e.g., PKCS#1 v1.5 or PSS) for use in TLS or other protocols.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
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.
|
This is only the basic RSA_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.
|
||||||
|
|
||||||
**PSA Crypto driver**
|
**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:
|
.. _configure-the-ds-peripheral:
|
||||||
|
|
||||||
Configure the DS Peripheral for a TLS Connection
|
Configure the RSA_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 RSA_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).
|
1) Randomly generate a 256-bit value called the ``Initialization Vector`` (IV).
|
||||||
2) Randomly generate a 256-bit value called the ``HMAC_KEY``.
|
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.
|
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.
|
4) Then burn the 256-bit ``HMAC_KEY`` on the eFuse, which can only be read by the RSA_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** > **RSA Digital Signature Peripheral (RSA_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>`_.
|
To configure the RSA_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 should be stored in flash. The application needs to read the DS data from flash (e.g. through the APIs provided by the `esp_secure_cert_mgr <https://github.com/espressif/esp_secure_cert_mgr>`_ component; see the `component/README <https://github.com/espressif/esp_secure_cert_mgr#readme>`_ for more details). For using the 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 <https://github.com/espressif/esp_secure_cert_mgr>`_ component; see the `component/README <https://github.com/espressif/esp_secure_cert_mgr#readme>`_ for more details). For using the RSA_DS peripheral with ESP-TLS, see :ref:`digital-signature-with-esp-tls`.
|
||||||
|
|
||||||
Using DS with PSA Crypto
|
Using RSA_DS with PSA Crypto
|
||||||
------------------------
|
-----------------------------
|
||||||
|
|
||||||
To use the DS peripheral for signing or decryption in application code (outside of ESP-TLS), enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``. Populate an ``esp_ds_data_ctx_t`` with the encrypted key data (:cpp:type:`esp_ds_data_t`), the eFuse key block ID, and the RSA key length in bits. Ensure the ``rsa_length`` field of :cpp:type:`esp_ds_data_t` is set when the key is created (e.g. via :cpp:func:`esp_ds_encrypt_params` or the DS provisioning tool). Then wrap the context in an ``esp_rsa_ds_opaque_key_t``, import it as a PSA opaque key using ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE``, and call ``psa_sign_hash()`` or ``psa_asymmetric_decrypt()``:
|
To use the RSA_DS peripheral for signing or decryption in application code (outside of ESP-TLS), enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``. Populate an ``esp_ds_data_ctx_t`` with the encrypted key data (:cpp:type:`esp_ds_data_t`), the eFuse key block ID, and the RSA key length in bits. Ensure the ``rsa_length`` field of :cpp:type:`esp_ds_data_t` is set when the key is created (e.g. via :cpp:func:`esp_ds_encrypt_params` or the RSA_DS provisioning tool). Then wrap the context in an ``esp_rsa_ds_opaque_key_t``, import it as a PSA opaque key using ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE``, and call ``psa_sign_hash()`` or ``psa_asymmetric_decrypt()``:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -113,10 +113,10 @@ To use the DS peripheral for signing or decryption in application code (outside
|
|||||||
|
|
||||||
psa_destroy_key(key_id);
|
psa_destroy_key(key_id);
|
||||||
|
|
||||||
Example for SSL Mutual Authentication Using DS
|
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 <https://components.espressif.com/components/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 <https://components.espressif.com/components/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
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
|
|||||||
@@ -1,13 +1,13 @@
|
|||||||
Elliptic Curve Digital Signature Algorithm (ECDSA)
|
ECDSA Digital Signature Peripheral (ECDSA_DS)
|
||||||
==================================================
|
==============================================
|
||||||
|
|
||||||
:link_to_translation:`zh_CN:[中文]`
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
The Elliptic Curve Digital Signature Algorithm (ECDSA) offers a variant of the Digital Signature Algorithm (DSA) which uses elliptic-curve cryptography.
|
The ECDSA Digital Signature Peripheral (ECDSA_DS) implements the Elliptic Curve Digital Signature Algorithm (ECDSA), a variant of the Digital Signature Algorithm (DSA) that uses elliptic-curve cryptography.
|
||||||
|
|
||||||
{IDF_TARGET_NAME}'s ECDSA peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software.
|
{IDF_TARGET_NAME}'s ECDSA_DS peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software.
|
||||||
|
|
||||||
ECDSA peripheral can help to establish **Secure Device Identity** for TLS mutual authentication and similar use-cases.
|
The ECDSA_DS peripheral can help to establish **Secure Device Identity** for TLS mutual authentication and similar use-cases.
|
||||||
|
|
||||||
Supported Features
|
Supported Features
|
||||||
------------------
|
------------------
|
||||||
@@ -21,14 +21,14 @@ Supported Features
|
|||||||
:not SOC_ECDSA_SUPPORT_CURVE_P384: - Two hash algorithms for message hash in the ECDSA operation, namely SHA-224 and SHA-256 (FIPS PUB 180-4 specification)
|
:not SOC_ECDSA_SUPPORT_CURVE_P384: - Two hash algorithms for message hash in the ECDSA operation, namely SHA-224 and SHA-256 (FIPS PUB 180-4 specification)
|
||||||
|
|
||||||
|
|
||||||
ECDSA on {IDF_TARGET_NAME}
|
ECDSA_DS on {IDF_TARGET_NAME}
|
||||||
--------------------------
|
-----------------------------
|
||||||
|
|
||||||
On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFuse block.
|
On {IDF_TARGET_NAME}, the ECDSA_DS module works with a secret key burnt into an eFuse block.
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
On {IDF_TARGET_NAME}, the ECDSA module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details.
|
On {IDF_TARGET_NAME}, the ECDSA_DS module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details.
|
||||||
|
|
||||||
This key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage.
|
This key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage.
|
||||||
|
|
||||||
@@ -70,13 +70,13 @@ Using eFuses to store the ECDSA key:
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Five physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 8. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
|
Five physical eFuse blocks can be used as keys for the ECDSA_DS module: block 4 ~ block 8. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
|
||||||
|
|
||||||
.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
|
.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Six physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
|
Six physical eFuse blocks can be used as keys for the ECDSA_DS module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
@@ -116,11 +116,11 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key
|
|||||||
|
|
||||||
.. only:: esp32h2
|
.. only:: esp32h2
|
||||||
|
|
||||||
The ECDSA peripheral of the ESP32-H2 supports both ECDSA-P192 and ECDSA-P256 operations. However, starting with ESP32-H2 revision 1.2, only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations using the following configuration options:
|
The ECDSA_DS peripheral of the ESP32-H2 supports both ECDSA-P192 and ECDSA-P256 operations. However, starting with ESP32-H2 revision 1.2, only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations using the following configuration options:
|
||||||
|
|
||||||
.. only:: not esp32h2
|
.. only:: not esp32h2
|
||||||
|
|
||||||
The ECDSA peripheral of {IDF_TARGET_NAME} supports both ECDSA-P192 and ECDSA-P256 operations, but only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations through the following configuration options:
|
The ECDSA_DS peripheral of {IDF_TARGET_NAME} supports both ECDSA-P192 and ECDSA-P256 operations, but only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations through the following configuration options:
|
||||||
|
|
||||||
- :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` enables support for ECDSA-P192 curve operations, allowing the device to perform ECDSA operations with both 192-bit and 256-bit curves. However, if ECDSA-P192 operations have already been permanently disabled during eFuse write protection, enabling this option can not re-enable ECDSA-P192 curve operations.
|
- :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` enables support for ECDSA-P192 curve operations, allowing the device to perform ECDSA operations with both 192-bit and 256-bit curves. However, if ECDSA-P192 operations have already been permanently disabled during eFuse write protection, enabling this option can not re-enable ECDSA-P192 curve operations.
|
||||||
|
|
||||||
@@ -131,7 +131,7 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key
|
|||||||
Deterministic Signature Generation
|
Deterministic Signature Generation
|
||||||
-----------------------------------
|
-----------------------------------
|
||||||
|
|
||||||
The ECDSA peripheral of {IDF_TARGET_NAME} also supports generation of deterministic signatures using deterministic derivation of the parameter K as specified in the `RFC 6979 <https://tools.ietf.org/html/rfc6979>`_ section 3.2.
|
The ECDSA_DS peripheral of {IDF_TARGET_NAME} also supports generation of deterministic signatures using deterministic derivation of the parameter K as specified in the `RFC 6979 <https://tools.ietf.org/html/rfc6979>`_ section 3.2.
|
||||||
|
|
||||||
Non-Determinisitic Signature Generation
|
Non-Determinisitic Signature Generation
|
||||||
---------------------------------------
|
---------------------------------------
|
||||||
@@ -139,16 +139,16 @@ Non-Determinisitic Signature Generation
|
|||||||
Dependency on TRNG
|
Dependency on TRNG
|
||||||
^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
ECDSA peripheral relies on the hardware True Random Number Generator (TRNG) for its internal entropy requirement for generating non-deterministic signatures. During ECDSA signature creation, the algorithm requires a random integer to be generated as specified in the `RFC 6090 <https://tools.ietf.org/html/rfc6090>`_ section 5.3.2.
|
The ECDSA_DS peripheral relies on the hardware True Random Number Generator (TRNG) for its internal entropy requirement for generating non-deterministic signatures. During ECDSA signature creation, the algorithm requires a random integer to be generated as specified in the `RFC 6090 <https://tools.ietf.org/html/rfc6090>`_ section 5.3.2.
|
||||||
|
|
||||||
Please ensure that hardware :doc:`RNG <../system/random>` is enabled before starting ECDSA computations (primarily signing) in the application.
|
Please ensure that hardware :doc:`RNG <../system/random>` is enabled before starting ECDSA computations (primarily signing) in the application.
|
||||||
|
|
||||||
Application Outline
|
Application Outline
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use ECDSA peripheral for establishing a mutually authenticated TLS connection.
|
Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use the ECDSA_DS peripheral for establishing a mutually authenticated TLS connection.
|
||||||
|
|
||||||
The ECDSA peripheral in Mbed TLS stack is integrated by overriding the ECDSA signing and verifying APIs. Please note that, the ECDSA peripheral does not support all curves or hash algorithms, and hence for cases where the hardware requirements are not met, the implementation falls back to the software.
|
The ECDSA_DS peripheral in Mbed TLS stack is integrated by overriding the ECDSA signing and verifying APIs. Please note that, the ECDSA_DS peripheral does not support all curves or hash algorithms, and hence for cases where the hardware requirements are not met, the implementation falls back to the software.
|
||||||
|
|
||||||
For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below.
|
For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below.
|
||||||
|
|
||||||
|
|||||||
@@ -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:
|
Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module:
|
||||||
|
|
||||||
#. HMAC is generated for software use
|
#. HMAC is generated for software use
|
||||||
#. HMAC is used as a key for the Digital Signature (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
|
#. 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.
|
||||||
@@ -58,11 +58,11 @@ Each key has a corresponding eFuse parameter **key purpose** determining for whi
|
|||||||
* - 8
|
* - 8
|
||||||
- HMAC generated for software use
|
- HMAC generated for software use
|
||||||
* - 7
|
* - 7
|
||||||
- HMAC used as a key for the Digital Signature (DS) module
|
- HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS)
|
||||||
* - 6
|
* - 6
|
||||||
- HMAC used for enabling the soft-disabled JTAG interface
|
- HMAC used for enabling the soft-disabled JTAG interface
|
||||||
* - 5
|
* - 5
|
||||||
- HMAC both as a key for the DS module and for enabling JTAG
|
- HMAC both as a key for the RSA_DS module and for enabling JTAG
|
||||||
|
|
||||||
This is to prevent the usage of a key for a different function than originally intended.
|
This is to prevent the usage of a key for a different function than originally intended.
|
||||||
|
|
||||||
@@ -79,16 +79,16 @@ In this case, the HMAC is given out to the software, e.g., to authenticate a mes
|
|||||||
|
|
||||||
The API to calculate the HMAC is :cpp:func:`psa_mac_compute`, which takes an opaque PSA key referencing an eFuse key block that contains the secret and has its purpose set to Upstream mode.
|
The API to calculate the HMAC is :cpp:func:`psa_mac_compute`, which takes an opaque PSA key referencing an eFuse key block that contains the secret and has its purpose set to Upstream mode.
|
||||||
|
|
||||||
HMAC for Digital Signature
|
HMAC for RSA Digital Signature
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Key purpose values: 7, 5
|
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. 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.
|
The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the RSA 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 RSA 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.
|
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:
|
.. _hmac_for_enabling_jtag:
|
||||||
|
|
||||||
|
|||||||
@@ -46,10 +46,10 @@ A secure element (ATECC608) can be also used for the underlying TLS connection i
|
|||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
Use ECDSA Peripheral for TLS
|
Use ECDSA Digital Signature Peripheral (ECDSA_DS) for TLS
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
The ECDSA peripheral can be used for the underlying TLS connection in the HTTP client connection. Please refer to the **ECDSA Peripheral with ESP-TLS** section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The HTTP client can be configured to use ECDSA peripheral as follows:
|
The ECDSA Digital Signature Peripheral (ECDSA_DS) can be used for the underlying TLS connection in the HTTP client connection. Please refer to the **ECDSA Digital Signature Peripheral (ECDSA_DS) with ESP-TLS** section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The HTTP client can be configured to use the ECDSA_DS peripheral as follows:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
|||||||
@@ -247,9 +247,9 @@ To enable the secure element support, and use it in your project for TLS connect
|
|||||||
Digital Signature with ESP-TLS
|
Digital Signature with ESP-TLS
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
ESP-TLS provides support for using the Digital Signature (DS) with {IDF_TARGET_NAME}. Use of the DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the :doc:`Digital Signature (DS) </api-reference/peripherals/ds>`. The technical details of Digital Signature such as how to calculate private key parameters can be found in **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The DS peripheral must be configured before it can be used to perform Digital Signature, see :ref:`configure-the-ds-peripheral`.
|
ESP-TLS provides support for using the RSA Digital Signature Peripheral (RSA_DS) with {IDF_TARGET_NAME}. Use of the RSA_DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on the RSA_DS, please refer to the :doc:`RSA Digital Signature Peripheral (RSA_DS) </api-reference/peripherals/ds>`. The technical details such as how to calculate private key parameters can be found in **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The RSA_DS peripheral must be configured before it can be used to perform RSA digital signature, see :ref:`configure-the-ds-peripheral`.
|
||||||
|
|
||||||
The DS peripheral must be initialized with the required encrypted private key parameters, which are obtained when the DS peripheral is configured. ESP-TLS internally initializes the DS peripheral when provided with the required DS context, i.e., DS parameters. Please see the below code snippet for passing the DS context to the ESP-TLS context. The DS context passed to the ESP-TLS context should not be freed till the TLS connection is deleted.
|
The RSA_DS peripheral must be initialized with the required encrypted private key parameters, which are obtained when the RSA_DS peripheral is configured. ESP-TLS internally initializes the RSA_DS peripheral when provided with the required DS context, i.e., DS parameters. Please see the below code snippet for passing the DS context to the ESP-TLS context. The DS context passed to the ESP-TLS context should not be freed till the TLS connection is deleted.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -265,20 +265,20 @@ To enable the secure element support, and use it in your project for TLS connect
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
When using Digital Signature for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL.
|
When using the RSA_DS for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL.
|
||||||
|
|
||||||
* A mutual-authentication example that utilizes the DS peripheral is shipped with the standalone `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ component and internally relies on ESP-TLS for the TLS connection. Follow the component documentation to fetch and build that example.
|
* A mutual-authentication example that utilizes the RSA_DS peripheral is shipped with the standalone `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ component and internally relies on ESP-TLS for the TLS connection. Follow the component documentation to fetch and build that example.
|
||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
.. _ecdsa-peri-with-esp-tls:
|
.. _ecdsa-peri-with-esp-tls:
|
||||||
|
|
||||||
ECDSA Peripheral with ESP-TLS
|
ECDSA Digital Signature Peripheral (ECDSA_DS) with ESP-TLS
|
||||||
-----------------------------
|
-----------------------------------------------------------
|
||||||
|
|
||||||
ESP-TLS provides support for using the ECDSA peripheral with {IDF_TARGET_NAME}. The use of ECDSA peripheral is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. The ECDSA private key should be present in the eFuse for using the ECDSA peripheral. Please refer to :doc:`ECDSA Guide <../peripherals/ecdsa>` for programming the ECDSA key in the eFuse.
|
ESP-TLS provides support for using the ECDSA Digital Signature Peripheral (ECDSA_DS) with {IDF_TARGET_NAME}. The use of the ECDSA_DS peripheral is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. The ECDSA private key should be present in the eFuse for using the ECDSA_DS peripheral. Please refer to :doc:`ECDSA Digital Signature Peripheral (ECDSA_DS) <../peripherals/ecdsa>` for programming the ECDSA key in the eFuse.
|
||||||
|
|
||||||
This will enable the use of ECDSA peripheral for private key operations. As the client private key is already present in the eFuse, it need not be supplied to the :cpp:type:`esp_tls_cfg_t` structure. Please see the below code snippet for enabling the use of ECDSA peripheral for a given ESP-TLS connection.
|
This will enable the use of the ECDSA_DS peripheral for private key operations. As the client private key is already present in the eFuse, it need not be supplied to the :cpp:type:`esp_tls_cfg_t` structure. Please see the below code snippet for enabling the use of the ECDSA_DS peripheral for a given ESP-TLS connection.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -292,7 +292,7 @@ To enable the secure element support, and use it in your project for TLS connect
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
When using ECDSA peripheral with TLS, only ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` ciphersuite is supported. If using TLS v1.3, ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` ciphersuite is supported.
|
When using the ECDSA_DS peripheral with TLS, only ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` ciphersuite is supported. If using TLS v1.3, ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` ciphersuite is supported.
|
||||||
|
|
||||||
|
|
||||||
.. _esp_tls_client_session_tickets:
|
.. _esp_tls_client_session_tickets:
|
||||||
|
|||||||
@@ -531,7 +531,7 @@ Restrictions After Secure Boot Is Enabled
|
|||||||
|
|
||||||
.. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED
|
.. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED
|
||||||
|
|
||||||
When Secure Boot is enabled, the ECDSA curve mode becomes write-protected. This means that if the curve mode was not previously set to use the ECDSA-P192 key before enabling Secure Boot, it will no longer be possible to configure or use the ECDSA-P192 curve on the ECDSA peripheral afterward.
|
When Secure Boot is enabled, the ECDSA curve mode becomes write-protected. This means that if the curve mode was not previously set to use the ECDSA-P192 key before enabling Secure Boot, it will no longer be possible to configure or use the ECDSA-P192 curve on the ECDSA_DS peripheral afterward.
|
||||||
|
|
||||||
Burning read-protected keys
|
Burning read-protected keys
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ Security Overview
|
|||||||
|
|
||||||
{IDF_TARGET_CIPHER_SCHEME:default="RSA", esp32h2="RSA or ECDSA", esp32p4="RSA or ECDSA", esp32c5="RSA or ECDSA", esp32c61="ECDSA", esp32h21="RSA or ECDSA"}
|
{IDF_TARGET_CIPHER_SCHEME:default="RSA", esp32h2="RSA or ECDSA", esp32p4="RSA or ECDSA", esp32c5="RSA or ECDSA", esp32c61="ECDSA", esp32h21="RSA or ECDSA"}
|
||||||
|
|
||||||
{IDF_TARGET_SIG_PERI:default="DS", esp32h2="DS or ECDSA", esp32p4="DS or ECDSA", esp32c5="DS or ECDSA"}
|
{IDF_TARGET_SIG_PERI:default="RSA_DS", esp32h2="RSA_DS or ECDSA_DS", esp32p4="RSA_DS or ECDSA_DS", esp32c5="RSA_DS or ECDSA_DS", esp32c61="ECDSA_DS"}
|
||||||
|
|
||||||
:link_to_translation:`zh_CN:[中文]`
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
@@ -85,21 +85,21 @@ Flash Encryption Best Practices
|
|||||||
Device Identity
|
Device Identity
|
||||||
~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The Digital Signature peripheral in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the assistance of HMAC, without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it.
|
The RSA Digital Signature Peripheral (RSA_DS) in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the assistance of HMAC, without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it.
|
||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
{IDF_TARGET_NAME} also supports ECDSA peripheral for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software.
|
{IDF_TARGET_NAME} also supports the ECDSA Digital Signature Peripheral (ECDSA_DS) for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software.
|
||||||
|
|
||||||
{IDF_TARGET_SIG_PERI} peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the {IDF_TARGET_CIPHER_SCHEME} cipher scheme.
|
{IDF_TARGET_SIG_PERI} peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the {IDF_TARGET_CIPHER_SCHEME} cipher scheme.
|
||||||
|
|
||||||
.. only:: not SOC_ECDSA_SUPPORTED
|
.. only:: not SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
Please refer to the :doc:`../api-reference/peripherals/ds` for detailed documentation.
|
Please refer to the :doc:`RSA Digital Signature Peripheral (RSA_DS) <../api-reference/peripherals/ds>` for detailed documentation.
|
||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
Please refer to the :doc:`../api-reference/peripherals/ecdsa` and :doc:`../api-reference/peripherals/ds` guides for detailed documentation.
|
Please refer to the :doc:`ECDSA Digital Signature Peripheral (ECDSA_DS) <../api-reference/peripherals/ecdsa>` and :doc:`RSA Digital Signature Peripheral (RSA_DS) <../api-reference/peripherals/ds>` guides for detailed documentation.
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
|
|||||||
@@ -1,17 +1,17 @@
|
|||||||
数字签名 (DS)
|
RSA 数字签名外设 (RSA_DS)
|
||||||
=============
|
==========================
|
||||||
|
|
||||||
:link_to_translation:`en:[English]`
|
:link_to_translation:`en:[English]`
|
||||||
|
|
||||||
数字签名 (DS) 模块提供基于 RSA 的消息签名硬件加速，并使用预加密参数来计算签名。这些参数通过 HMAC 作为密钥派生函数进行加密，而 HMAC 则以 eFuse 作为输入密钥。
|
RSA 数字签名外设 (RSA_DS) 提供基于 RSA 的消息签名硬件加速，并使用预加密参数来计算签名。这些参数通过 HMAC 作为密钥派生函数进行加密，而 HMAC 则以 eFuse 作为输入密钥。
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
.. 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 密钥派生函数的输入密钥。
|
以上过程均在硬件中完成，因此在计算签名时，软件无法获取 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 中进行数字签名计算
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
在 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` 来获取签名结果。
|
签名计算需要一些时间，因此 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::
|
.. note::
|
||||||
|
|
||||||
上述为 DS 的基本构件，其消息长度是固定的。为了对任意消息生成签名，通常会将实际消息的哈希值作为输入，并将其填充到所需长度。
|
上述为 RSA_DS 的基本构件，其消息长度是固定的。为了对任意消息生成签名，通常会将实际消息的哈希值作为输入，并将其填充到所需长度。
|
||||||
|
|
||||||
**PSA 密码学驱动程序**
|
**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:
|
.. _configure-the-ds-peripheral:
|
||||||
|
|
||||||
TLS 连接所需的 DS 外设配置
|
TLS 连接所需的 RSA_DS 外设配置
|
||||||
------------------------------
|
------------------------------------
|
||||||
|
|
||||||
在 {IDF_TARGET_NAME} 芯片上使用 TLS 连接之前，必须先配置 DS 外设，具体步骤如下：
|
在 {IDF_TARGET_NAME} 芯片上使用 TLS 连接之前，必须先配置 RSA_DS 外设，具体步骤如下：
|
||||||
|
|
||||||
1) 随机生成一个 256 位的值，作为 ``初始化向量`` (IV)。
|
1) 随机生成一个 256 位的值，作为 ``初始化向量`` (IV)。
|
||||||
2) 随机生成一个 256 位的值，作为 ``HMAC_KEY``。
|
2) 随机生成一个 256 位的值，作为 ``HMAC_KEY``。
|
||||||
3) 使用客户端私钥 (RAS) 和上述步骤生成的参数，计算加密的私钥参数。
|
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
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -113,10 +113,10 @@ TLS 连接所需的 DS 外设配置
|
|||||||
|
|
||||||
psa_destroy_key(key_id);
|
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
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
|
|||||||
@@ -1,13 +1,13 @@
|
|||||||
椭圆曲线数字签名算法 (ECDSA)
|
ECDSA 数字签名外设 (ECDSA_DS)
|
||||||
============================
|
====================================
|
||||||
|
|
||||||
:link_to_translation:`en:[English]`
|
: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 规范）
|
: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
|
.. 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::
|
.. note::
|
||||||
|
|
||||||
五个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 8。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
|
五个物理 eFuse 块可作为 ECDSA_DS 模块的密钥：块 4 ~ 块 8。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
|
||||||
|
|
||||||
.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
|
.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
六个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 9。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
|
六个物理 eFuse 块可作为 ECDSA_DS 模块的密钥：块 4 ~ 块 9。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
|
||||||
|
|
||||||
|
|
||||||
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
@@ -116,11 +116,11 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编
|
|||||||
|
|
||||||
.. only:: esp32h2
|
.. 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
|
.. 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 操作，则启用该配置项也无法重新启用该功能。
|
- :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 <https://tools.ietf.org/html/rfc6979>`_ 第 3.2 节。
|
{IDF_TARGET_NAME} 的 ECDSA_DS 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 <https://tools.ietf.org/html/rfc6979>`_ 第 3.2 节。
|
||||||
|
|
||||||
生成非确定性签名
|
生成非确定性签名
|
||||||
----------------
|
----------------
|
||||||
@@ -139,16 +139,16 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编
|
|||||||
对 TRNG 的依赖
|
对 TRNG 的依赖
|
||||||
^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
ECDSA 外设依靠硬件真随机数生成器 (TRNG) 来满足其内部熵要求，从而生成非确定性签名。在创建 ECDSA 签名时，算法需要生成一个随机整数，在 `RFC 6090 <https://tools.ietf.org/html/rfc6090>`_ 第 5.3.2 节有说明。
|
ECDSA_DS 外设依靠硬件真随机数生成器 (TRNG) 来满足其内部熵要求，从而生成非确定性签名。在创建 ECDSA 签名时，算法需要生成一个随机整数，在 `RFC 6090 <https://tools.ietf.org/html/rfc6090>`_ 第 5.3.2 节有说明。
|
||||||
|
|
||||||
在应用程序中启动 ECDSA 计算（主要是签名）之前，请确保硬件 :doc:`RNG <../system/random>` 已经启用。
|
在应用程序中启动 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 详细信息。
|
对于特定的 TLS 上下文，可用额外的 API 来填充某些字段（例如私钥 ctx），以区分路由到硬件的路径。ESP-TLS 层在内部集成了这些 API，因此在应用程序层不需要额外的操作。对于自定义用例，请参阅以下 API 详细信息。
|
||||||
|
|
||||||
|
|||||||
@@ -37,7 +37,7 @@
|
|||||||
此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景：
|
此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景：
|
||||||
|
|
||||||
#. HMAC 支持软件使用
|
#. HMAC 支持软件使用
|
||||||
#. HMAC 用作数字签名 (DS) 的密钥
|
#. HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥
|
||||||
#. HMAC 用于启用软禁用的 JTAG 接口
|
#. HMAC 用于启用软禁用的 JTAG 接口
|
||||||
|
|
||||||
第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。
|
第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。
|
||||||
@@ -58,11 +58,11 @@ HMAC 的 eFuse 密钥
|
|||||||
* - 8
|
* - 8
|
||||||
- HMAC 支持软件使用
|
- HMAC 支持软件使用
|
||||||
* - 7
|
* - 7
|
||||||
- HMAC 用作数字签名 (DS) 的密钥
|
- HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥
|
||||||
* - 6
|
* - 6
|
||||||
- HMAC 启用软禁用的 JTAG 接口
|
- HMAC 启用软禁用的 JTAG 接口
|
||||||
* - 5
|
* - 5
|
||||||
- HMAC 既用作数字签名 (DS) 的密钥，又用于启用 JTAG 接口
|
- HMAC 既用作 RSA 数字签名外设 (RSA_DS) 的密钥，又用于启用 JTAG 接口
|
||||||
|
|
||||||
这样一来，可以确保密钥用于原定场景。
|
这样一来，可以确保密钥用于原定场景。
|
||||||
|
|
||||||
@@ -79,16 +79,16 @@ HMAC 支持软件使用
|
|||||||
|
|
||||||
:cpp:func:`psa_mac_compute` 用于计算 HMAC，该函数接收一个不透明的 PSA 密钥，该密钥引用了包含密钥机密的 eFuse 密钥块，并且该密钥块的用途被设置为上行模式。
|
:cpp:func:`psa_mac_compute` 用于计算 HMAC，该函数接收一个不透明的 PSA 密钥，该密钥引用了包含密钥机密的 eFuse 密钥块，并且该密钥块的用途被设置为上行模式。
|
||||||
|
|
||||||
HMAC 用作数字签名 (DS) 的密钥
|
HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
密钥功能值：7、5
|
密钥功能值：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:
|
.. _hmac_for_enabling_jtag:
|
||||||
|
|
||||||
|
|||||||
@@ -46,10 +46,10 @@ HTTP 基本请求
|
|||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
为 TLS 使用 ECDSA 外设
|
为 TLS 使用 ECDSA_DS 外设
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
ECDSA 外设可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 **在 ESP-TLS 中使用 ECDSA 外设** 小节。可以按如下方式配置 HTTP 客户端以使用 ECDSA 外设：
|
ECDSA_DS 外设可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 **在 ESP-TLS 中使用 ECDSA_DS 外设** 小节。可以按如下方式配置 HTTP 客户端以使用 ECDSA_DS 外设：
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
|||||||
@@ -247,9 +247,9 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须
|
|||||||
ESP-TLS 的数字签名
|
ESP-TLS 的数字签名
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用数字签名 (DS)，但只有当 ESP-TLS 以 MbedTLS（默认协议栈）为底层 SSL/TLS 协议栈时，才支持使用 TLS 的数字签名。有关数字签名的详细信息，请参阅 :doc:`数字签名 (DS) </api-reference/peripherals/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) </api-reference/peripherals/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
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -265,20 +265,20 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
当使用数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。
|
当使用 RSA 数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。
|
||||||
|
|
||||||
* 现有一个基于 DS 外设的双向认证示例，已随独立的 `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ 组件一同提供，其内部依赖 ESP-TLS 建立 TLS 连接。请参照组件文档获取并构建该示例。
|
* 现有一个基于 RSA_DS 外设的双向认证示例，已随独立的 `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ 组件一同提供，其内部依赖 ESP-TLS 建立 TLS 连接。请参照组件文档获取并构建该示例。
|
||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. only:: SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
.. _ecdsa-peri-with-esp-tls:
|
.. _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
|
.. code-block:: c
|
||||||
|
|
||||||
@@ -292,7 +292,7 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须
|
|||||||
|
|
||||||
.. note::
|
.. 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:
|
.. _esp_tls_client_session_tickets:
|
||||||
|
|||||||
@@ -531,7 +531,7 @@ Secure Boot v2 签名验证也可以在 OTA 更新期间验证数据分区镜像
|
|||||||
|
|
||||||
.. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED
|
.. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED
|
||||||
|
|
||||||
启用安全启动后，ECDSA 曲线模式将锁定为写保护状态。因此，如果启用前未将曲线模式设置为使用 ECDSA-P192 密钥，那么之后将无法再配置或使用 ECDSA 外设中的 ECDSA-P192 曲线。
|
启用安全启动后，ECDSA 曲线模式将锁定为写保护状态。因此，如果启用前未将曲线模式设置为使用 ECDSA-P192 密钥，那么之后将无法再配置或使用 ECDSA_DS 外设中的 ECDSA-P192 曲线。
|
||||||
|
|
||||||
烧录读保护密钥
|
烧录读保护密钥
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|||||||
@@ -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_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]`
|
: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
|
.. 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 双向认证。
|
{IDF_TARGET_SIG_PERI} 外设可以建立与远程终端之间的 **安全设备身份**，如基于 {IDF_TARGET_CIPHER_SCHEME} 加密算法的 TLS 双向认证。
|
||||||
|
|
||||||
.. only:: not SOC_ECDSA_SUPPORTED
|
.. only:: not SOC_ECDSA_SUPPORTED
|
||||||
|
|
||||||
详情请参阅 :doc:`../api-reference/peripherals/ds`。
|
详情请参阅 :doc:`RSA 数字签名外设 (RSA_DS) <../api-reference/peripherals/ds>`。
|
||||||
|
|
||||||
.. only:: SOC_ECDSA_SUPPORTED
|
.. 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
|
.. only:: SOC_KEY_MANAGER_SUPPORTED
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user