docs: adds RSA DS docs for PSA Migration

docs/en/api-reference/peripherals/ds.rst

@@ -33,13 +33,19 @@ Three parameters need to be prepared to calculate the digital signature:
 #. The location of the encrypted private key parameters
 #. The message to be signed
 
+**Low-level API (plain RSA)**
+
 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 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.
+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::
 
-    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.
+
+**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.
 
 .. _configure-the-ds-peripheral:
 
@@ -57,11 +63,49 @@ 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. 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 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 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.
+Using DS with PSA Crypto
+------------------------
 
-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.
+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()``:
+
+.. code-block:: c
+
+    #include "psa/crypto.h"
+    #include "psa_crypto_driver_esp_rsa_ds.h"
+
+    // ds_ctx points to esp_ds_data_ctx_t (e.g. from secure cert or NVS)
+    esp_ds_data_ctx_t *ds_ctx = ...;
+    esp_rsa_ds_opaque_key_t rsa_ds_opaque_key = {
+        .ds_data_ctx = ds_ctx,
+    };
+
+    psa_key_attributes_t attrs = PSA_KEY_ATTRIBUTES_INIT;
+    psa_set_key_type(&attrs, PSA_KEY_TYPE_RSA_KEY_PAIR);
+    psa_set_key_bits(&attrs, ds_ctx->rsa_length_bits);
+    psa_set_key_usage_flags(&attrs, PSA_KEY_USAGE_SIGN_HASH);
+    psa_set_key_algorithm(&attrs, PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_SHA_256));
+    psa_set_key_lifetime(&attrs, PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE);
+
+    psa_key_id_t key_id;
+    psa_status_t status = psa_import_key(&attrs,
+                                         (const uint8_t *)&rsa_ds_opaque_key,
+                                         sizeof(rsa_ds_opaque_key),
+                                         &key_id);
+    psa_reset_key_attributes(&attrs);
+    if (status != PSA_SUCCESS) {
+        // handle error
+    }
+
+    // Sign a hash (e.g. SHA-256 of your message)
+    uint8_t hash[32] = { ... };
+    uint8_t signature[256];
+    size_t sig_len;
+    status = psa_sign_hash(key_id, PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_SHA_256),
+                           hash, sizeof(hash), signature, sizeof(signature), &sig_len);
+
+    psa_destroy_key(key_id);
 
 Example for SSL Mutual Authentication Using DS
 ----------------------------------------------

docs/en/migration-guides/release-6.x/6.0/security.rst

@@ -102,6 +102,20 @@ The following deprecated functions have been removed:
 
 Note that the new AES functions return error codes for better error handling, unlike the old void functions.
 
+.. only:: SOC_DIG_SIGN_SUPPORTED
+
+    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.
+
+    - **Breaking change**: The legacy DS integration has been removed and replaced by the PSA RSA DS driver.
+
+    - **Migration**:
+
+      * **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**.
+
 BluFi
 -----