Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: Adds a migration guide entry for HMAC peripheral's PSA interface

Browse Source 
Co-authored-by: Zhang Shu Xian <zhangshuxian@espressif.com>
This commit is contained in:
harshal.patil
2026-03-17 10:28:39 +08:00
committed by Ashish Sharma
co-authored by Zhang Shu Xian
parent 9618e5cd77
commit 96e8b85577
4 changed files with 84 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/peripherals/ds.rst
+4 -4
View File
@@ -37,7 +37,7 @@ 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.
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 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::
@@ -45,7 +45,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 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.
.. _configure-the-ds-peripheral:
@@ -63,7 +63,7 @@ For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digit
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. 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 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`.
Using DS with PSA Crypto
------------------------
@@ -110,7 +110,7 @@ To use the DS peripheral for signing or decryption in application code (outside
Example for SSL Mutual Authentication Using 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 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.
API Reference
-------------
docs/en/migration-guides/release-6.x/6.0/security.rst
+8 -1
View File
@@ -103,7 +103,7 @@ Note that the new AES functions return error codes for better error handling, un
.. only:: SOC_DIG_SIGN_SUPPORTED
Digital Signature (DS) peripheral
Digital Signature (DS) Peripheral
---------------------------------
The DS peripheral is now used via the **PSA Crypto RSA DS driver** instead of the legacy Mbed TLS RSA sign/decrypt alternates. The application-facing flow (obtain DS context from secure cert/NVS, pass to ESP-TLS or use for signing/decryption) is unchanged; only the internal implementation uses the PSA driver.
@@ -115,6 +115,13 @@ Note that the new AES functions return error codes for better error handling, un
* **For TLS (ESP-TLS):** Enable ``CONFIG_ESP_TLS_USE_DS_PERIPHERAL`` and pass ``esp_ds_data_ctx_t`` as ``ds_data`` in :cpp:type:`esp_tls_cfg_t`. See :ref:`digital-signature-with-esp-tls` in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>`.
* **For direct use (signing/decryption in application code):** Enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``, import ``esp_rsa_ds_opaque_key_t`` with ``psa_import_key()`` using ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE``, then use ``psa_sign_hash()`` or ``psa_asymmetric_decrypt()``. See the :doc:`Digital Signature (DS) </api-reference/peripherals/ds>` documentation, section **Using DS with PSA Crypto**.
.. only:: SOC_HMAC_SUPPORTED
HMAC Peripheral
---------------
The HMAC peripheral is now used via the **PSA Crypto HMAC driver** instead of the legacy :cpp:func:`esp_hmac_calculate` API. The applications are expected to populate the :cpp:type:`esp_hmac_opaque_key_t` structure and import it via :cpp:func:`psa_import_key` API using the ``PSA_KEY_LIFETIME_ESP_HMAC`` lifetime attribute. Then, they can use the :cpp:func:`psa_mac_compute` API to compute HMAC.
BluFi
-----