From d43dd9246f36913007f1c775352ada1602f0d8af Mon Sep 17 00:00:00 2001 From: Chip Weinberger Date: Mon, 19 Dec 2022 21:30:03 -0800 Subject: [PATCH] [Docs] specify Digital Signature byte order, and esp_ds_sign() clarification --- components/esp_hw_support/include/esp_ds.h | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/components/esp_hw_support/include/esp_ds.h b/components/esp_hw_support/include/esp_ds.h index 4259f8d7025..449ef628287 100644 --- a/components/esp_hw_support/include/esp_ds.h +++ b/components/esp_hw_support/include/esp_ds.h @@ -84,6 +84,9 @@ typedef struct esp_digital_signature_data { * This is only used for encrypting the RSA parameters by calling esp_ds_encrypt_params(). * Afterwards, the result can be stored in flash or in other persistent memory. * The encryption is a prerequisite step before any signature operation can be done. + * + * @note + * Y, M, Rb, & M_Prime must all be in little endian format. */ typedef struct { uint32_t Y[ESP_DS_SIGNATURE_MAX_BIT_LEN / 32]; //!< RSA exponent @@ -108,7 +111,9 @@ typedef struct { * @note * Please see note section of \c esp_ds_start_sign() for more details about the input parameters. * - * @param message the message to be signed; its length should be (data->rsa_length + 1)*4 bytes + * @param message the message to be signed; its length should be (data->rsa_length + 1)*4 bytes, and those + bytes must be in little endian format. It is your responsibility to apply your hash function + and padding before calling this function, if required. (e.g. message = padding(hash(inputMsg))) * @param data the encrypted signing key data (AES encrypted RSA key + IV) * @param key_id the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the * signing key data @@ -149,7 +154,9 @@ esp_err_t esp_ds_sign(const void *message, * No padding is applied to the message automatically, Please ensure the message is appropriate padded before * calling the API. * - * @param message the message to be signed; its length should be (data->rsa_length + 1)*4 bytes + * @param message the message to be signed; its length should be (data->rsa_length + 1)*4 bytes, and those + bytes must be in little endian format. It is your responsibility to apply your hash function + and padding before calling this function, if required. (e.g. message = padding(hash(inputMsg))) * @param data the encrypted signing key data (AES encrypted RSA key + IV) * @param key_id the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the * signing key data @@ -177,7 +184,8 @@ bool esp_ds_is_busy(void); /** * @brief Finish the signing process. * - * @param signature the destination of the signature, should be (data->rsa_length + 1)*4 bytes long + * @param signature the destination of the signature, should be (data->rsa_length + 1)*4 bytes long, + the resultant signature bytes shall be written in little endian format. * @param esp_ds_ctx the context object retreived by \c esp_ds_start_sign() * * @return