feat(esp_ds): Support using the AES key used by DS peripheral for encrypting params

components/esp_security/include/esp_ds.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -40,6 +40,12 @@ extern "C" {
         + ESP_DS_SIGNATURE_L_BIT_LEN   \
         + ESP_DS_SIGNATURE_PADDING_BIT_LEN) / 8))
 
+typedef enum {
+    ESP_DS_KEY_HMAC,
+    ESP_DS_KEY_AES,
+    ESP_DS_KEY_MAX,
+} esp_ds_key_type_t;
+
 /**
  * @brief Context object used for non-blocking digital signature operations
  *
@@ -223,7 +229,7 @@ esp_err_t esp_ds_finish_sign(void *signature, esp_ds_context_t *esp_ds_ctx);
  * @param p_data Pointer to input plaintext key data. The expectation is this data will be deleted after this process
  *        is done and 'data' is stored.
  * @param key Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the
- *        corresponding HMAC key will be stored to efuse and then permanently erased.
+ *        corresponding HMAC key will be stored to efuse and then permanently erased for ESP_DS_KEY_HMAC.
  *
  * @note
  * The numbers Y, M, Rb which are a part of esp_ds_data_t should be provided in little endian format
@@ -241,6 +247,40 @@ esp_err_t esp_ds_encrypt_params(esp_ds_data_t *data,
                                 const esp_ds_p_data_t *p_data,
                                 const void *key);
 
+/**
+ * @brief Encrypt the private key parameters.
+ *
+ * The encryption is a prerequisite step before any signature operation can be done.
+ * It is not strictly necessary to use this encryption function, the encryption could also happen on an external
+ * device.
+ *
+ * @param data Output buffer to store encrypted data, suitable for later use generating signatures.
+ * @param iv Pointer to 16 byte IV buffer, will be copied into 'data'. Should be randomly generated bytes each time.
+ * @param p_data Pointer to input plaintext key data. The expectation is this data will be deleted after this process
+ *        is done and 'data' is stored.
+ * @param key Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the
+ *        corresponding HMAC key will be stored to efuse and then permanently erased for ESP_DS_KEY_HMAC.
+ *        or the AES key will be used by the the DS peripheral (internally) to decrypt the encrypted RSA private key
+ *        parameters for ESP_DS_KEY_AES.
+ * @param key_type The type of key parameter (either ESP_DS_KEY_HMAC or ESP_DS_KEY_AES).
+ *
+ * @note
+ * The numbers Y, M, Rb which are a part of esp_ds_data_t should be provided in little endian format
+ * and should be of length equal to the RSA private key bit length
+ * The message length in bits should also be equal to the RSA private key bit length.
+ * No padding is applied to the message automatically, Please ensure the message is appropriate padded before
+ * calling the API.
+ *
+ * @return
+ *      - ESP_OK if successful, the ds operation has been finished and the result is written to signature.
+ *      - ESP_ERR_INVALID_ARG if one of the parameters is NULL or p_data->rsa_length is too long
+ */
+esp_err_t esp_ds_encrypt_params_using_key_type(esp_ds_data_t *data,
+                                               const void *iv,
+                                               const esp_ds_p_data_t *p_data,
+                                               const void *key,
+                                               esp_ds_key_type_t key_type);
+
 #ifdef __cplusplus
 }
 #endif