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