|
| 1 | +/* |
| 2 | + * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD |
| 3 | + * |
| 4 | + * SPDX-License-Identifier: Apache-2.0 |
| 5 | + */ |
| 6 | + |
| 7 | +#pragma once |
| 8 | +#include <stdbool.h> |
| 9 | + |
| 10 | +#include "esp_hmac.h" |
| 11 | +#include "esp_err.h" |
| 12 | +#include "soc/soc_caps.h" |
| 13 | + |
| 14 | +#ifdef __cplusplus |
| 15 | +extern "C" { |
| 16 | +#endif |
| 17 | + |
| 18 | +#define ESP32S3_ERR_HW_CRYPTO_DS_HMAC_FAIL ESP_ERR_HW_CRYPTO_BASE + 0x1 /*!< HMAC peripheral problem */ |
| 19 | +#define ESP32S3_ERR_HW_CRYPTO_DS_INVALID_KEY ESP_ERR_HW_CRYPTO_BASE + 0x2 /*!< given HMAC key isn't correct, |
| 20 | + HMAC peripheral problem */ |
| 21 | +#define ESP32S3_ERR_HW_CRYPTO_DS_INVALID_DIGEST ESP_ERR_HW_CRYPTO_BASE + 0x4 /*!< message digest check failed, |
| 22 | + result is invalid */ |
| 23 | +#define ESP32S3_ERR_HW_CRYPTO_DS_INVALID_PADDING ESP_ERR_HW_CRYPTO_BASE + 0x5 /*!< padding check failed, but result |
| 24 | + is produced anyway and can be read*/ |
| 25 | + |
| 26 | +#define ESP_DS_IV_LEN 16 |
| 27 | + |
| 28 | +/* Length of parameter 'C' stored in flash */ |
| 29 | +#define ESP_DS_C_LEN (12672 / 8) |
| 30 | + |
| 31 | +typedef struct esp_ds_context esp_ds_context_t; |
| 32 | + |
| 33 | +typedef enum { |
| 34 | + ESP_DS_RSA_1024 = (1024 / 32) - 1, |
| 35 | + ESP_DS_RSA_2048 = (2048 / 32) - 1, |
| 36 | + ESP_DS_RSA_3072 = (3072 / 32) - 1, |
| 37 | + ESP_DS_RSA_4096 = (4096 / 32) - 1 |
| 38 | +} esp_digital_signature_length_t; |
| 39 | + |
| 40 | +/** |
| 41 | + * Encrypted private key data. Recommended to store in flash in this format. |
| 42 | + * |
| 43 | + * @note This struct has to match to one from the ROM code! This documentation is mostly taken from there. |
| 44 | + */ |
| 45 | +typedef struct esp_digital_signature_data { |
| 46 | + /** |
| 47 | + * RSA LENGTH register parameters |
| 48 | + * (number of words in RSA key & operands, minus one). |
| 49 | + * |
| 50 | + * Max value 127 (for RSA 4096). |
| 51 | + * |
| 52 | + * This value must match the length field encrypted and stored in 'c', |
| 53 | + * or invalid results will be returned. (The DS peripheral will |
| 54 | + * always use the value in 'c', not this value, so an attacker can't |
| 55 | + * alter the DS peripheral results this way, it will just truncate or |
| 56 | + * extend the message and the resulting signature in software.) |
| 57 | + * |
| 58 | + * @note In IDF, the enum type length is the same as of type unsigned, so they can be used interchangably. |
| 59 | + * See the ROM code for the original declaration of struct \c ets_ds_data_t. |
| 60 | + */ |
| 61 | + esp_digital_signature_length_t rsa_length; |
| 62 | + |
| 63 | + /** |
| 64 | + * IV value used to encrypt 'c' |
| 65 | + */ |
| 66 | + uint8_t iv[ESP_DS_IV_LEN]; |
| 67 | + |
| 68 | + /** |
| 69 | + * Encrypted Digital Signature parameters. Result of AES-CBC encryption |
| 70 | + * of plaintext values. Includes an encrypted message digest. |
| 71 | + */ |
| 72 | + uint8_t c[ESP_DS_C_LEN]; |
| 73 | +} esp_ds_data_t; |
| 74 | + |
| 75 | +/** Plaintext parameters used by Digital Signature. |
| 76 | + * |
| 77 | + * Not used for signing with DS peripheral, but can be encrypted |
| 78 | + * in-device by calling esp_ds_encrypt_params() |
| 79 | + * |
| 80 | + * @note This documentation is mostly taken from the ROM code. |
| 81 | + */ |
| 82 | +typedef struct { |
| 83 | + uint32_t Y[SOC_RSA_MAX_BIT_LEN / 32]; //!< RSA exponent |
| 84 | + uint32_t M[SOC_RSA_MAX_BIT_LEN / 32]; //!< RSA modulus |
| 85 | + uint32_t Rb[SOC_RSA_MAX_BIT_LEN / 32]; //!< RSA r inverse operand |
| 86 | + uint32_t M_prime; //!< RSA M prime operand |
| 87 | + esp_digital_signature_length_t length; //!< RSA length |
| 88 | +} esp_ds_p_data_t; |
| 89 | + |
| 90 | +/** |
| 91 | + * Sign the message. |
| 92 | + * |
| 93 | + * This function is a wrapper around \c esp_ds_finish_sign() and \c esp_ds_start_sign(), so do not use them |
| 94 | + * in parallel. |
| 95 | + * It blocks until the signing is finished and then returns the signature. |
| 96 | + * |
| 97 | + * @note This function locks the HMAC, SHA, AES and RSA components during its entire execution time. |
| 98 | + * |
| 99 | + * @param message the message to be signed; its length is determined by data->rsa_length |
| 100 | + * @param data the encrypted signing key data (AES encrypted RSA key + IV) |
| 101 | + * @param key_id the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the |
| 102 | + * signing key data |
| 103 | + * @param signature the destination of the signature, should be (data->rsa_length + 1)*4 bytes long |
| 104 | + * |
| 105 | + * @return |
| 106 | + * - ESP_OK if successful, the signature was written to the parameter \c signature. |
| 107 | + * - ESP_ERR_INVALID_ARG if one of the parameters is NULL or data->rsa_length is too long or 0 |
| 108 | + * - ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL if there was an HMAC failure during retrieval of the decryption key |
| 109 | + * - ESP_ERR_NO_MEM if there hasn't been enough memory to allocate the context object |
| 110 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_KEY if there's a problem with passing the HMAC key to the DS component |
| 111 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didn't match; the signature is invalid. |
| 112 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the signature can be read though |
| 113 | + * since the message digest matches. |
| 114 | + */ |
| 115 | +esp_err_t esp_ds_sign(const void *message, |
| 116 | + const esp_ds_data_t *data, |
| 117 | + hmac_key_id_t key_id, |
| 118 | + void *signature); |
| 119 | + |
| 120 | +/** |
| 121 | + * Start the signing process. |
| 122 | + * |
| 123 | + * This function yields a context object which needs to be passed to \c esp_ds_finish_sign() to finish the signing |
| 124 | + * process. |
| 125 | + * |
| 126 | + * @note This function locks the HMAC, SHA, AES and RSA components, so the user has to ensure to call |
| 127 | + * \c esp_ds_finish_sign() in a timely manner. |
| 128 | + * |
| 129 | + * @param message the message to be signed; its length is determined by data->rsa_length |
| 130 | + * @param data the encrypted signing key data (AES encrypted RSA key + IV) |
| 131 | + * @param key_id the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the |
| 132 | + * signing key data |
| 133 | + * @param esp_ds_ctx the context object which is needed for finishing the signing process later |
| 134 | + * |
| 135 | + * @return |
| 136 | + * - ESP_OK if successful, the ds operation was started now and has to be finished with \c esp_ds_finish_sign() |
| 137 | + * - ESP_ERR_INVALID_ARG if one of the parameters is NULL or data->rsa_length is too long or 0 |
| 138 | + * - ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL if there was an HMAC failure during retrieval of the decryption key |
| 139 | + * - ESP_ERR_NO_MEM if there hasn't been enough memory to allocate the context object |
| 140 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_KEY if there's a problem with passing the HMAC key to the DS component |
| 141 | + */ |
| 142 | +esp_err_t esp_ds_start_sign(const void *message, |
| 143 | + const esp_ds_data_t *data, |
| 144 | + hmac_key_id_t key_id, |
| 145 | + esp_ds_context_t **esp_ds_ctx); |
| 146 | + |
| 147 | +/** |
| 148 | + * Return true if the DS peripheral is busy, otherwise false. |
| 149 | + * |
| 150 | + * @note Only valid if \c esp_ds_start_sign() was called before. |
| 151 | + */ |
| 152 | +bool esp_ds_is_busy(void); |
| 153 | + |
| 154 | +/** |
| 155 | + * Finish the signing process. |
| 156 | + * |
| 157 | + * @param signature the destination of the signature, should be (data->rsa_length + 1)*4 bytes long |
| 158 | + * @param esp_ds_ctx the context object retreived by \c esp_ds_start_sign() |
| 159 | + * |
| 160 | + * @return |
| 161 | + * - ESP_OK if successful, the ds operation has been finished and the result is written to signature. |
| 162 | + * - ESP_ERR_INVALID_ARG if one of the parameters is NULL |
| 163 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didn't match; the signature is invalid. |
| 164 | + * - ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the signature can be read though |
| 165 | + * since the message digest matches. |
| 166 | + */ |
| 167 | +esp_err_t esp_ds_finish_sign(void *signature, esp_ds_context_t *esp_ds_ctx); |
| 168 | + |
| 169 | +/** |
| 170 | + * Encrypt the private key parameters. |
| 171 | + * |
| 172 | + * @param data Output buffer to store encrypted data, suitable for later use generating signatures. |
| 173 | + * The allocated memory must be in internal memory and word aligned since it's filled by DMA. Both is asserted |
| 174 | + * at run time. |
| 175 | + * @param iv Pointer to 16 byte IV buffer, will be copied into 'data'. Should be randomly generated bytes each time. |
| 176 | + * @param p_data Pointer to input plaintext key data. The expectation is this data will be deleted after this process |
| 177 | + * is done and 'data' is stored. |
| 178 | + * @param key Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the |
| 179 | + * corresponding HMAC key will be stored to efuse and then permanently erased. |
| 180 | + * |
| 181 | + * @return |
| 182 | + * - ESP_OK if successful, the ds operation has been finished and the result is written to signature. |
| 183 | + * - ESP_ERR_INVALID_ARG if one of the parameters is NULL or p_data->rsa_length is too long |
| 184 | + */ |
| 185 | +esp_err_t esp_ds_encrypt_params(esp_ds_data_t *data, |
| 186 | + const void *iv, |
| 187 | + const esp_ds_p_data_t *p_data, |
| 188 | + const void *key); |
| 189 | + |
| 190 | +#ifdef __cplusplus |
| 191 | +} |
| 192 | +#endif |
0 commit comments