1 /* 2 ROM functions for hardware Digital Signature peripheral verification 3 */ 4 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD 5 // 6 // Licensed under the Apache License, Version 2.0 (the "License"); 7 // you may not use this file except in compliance with the License. 8 // You may obtain a copy of the License at 9 10 // http://www.apache.org/licenses/LICENSE-2.0 11 // 12 // Unless required by applicable law or agreed to in writing, software 13 // distributed under the License is distributed on an "AS IS" BASIS, 14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 // See the License for the specific language governing permissions and 16 // limitations under the License. 17 18 #pragma once 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include <stdint.h> 25 #include <stdbool.h> 26 27 #define ETS_DS_IV_LEN 16 28 29 /* Length of parameter 'C' stored in flash */ 30 #define ETS_DS_C_LEN (12672 / 8) 31 32 /* Encrypted ETS data. Recommended to store in flash in this format. 33 */ 34 typedef struct { 35 /* RSA LENGTH register parameters 36 * (number of words in RSA key & operands, minus one). 37 * 38 * Max value 127 (for RSA 4096). 39 * 40 * This value must match the length field encrypted and stored in 'c', 41 * or invalid results will be returned. (The DS peripheral will 42 * always use the value in 'c', not this value, so an attacker can't 43 * alter the DS peripheral results this way, it will just truncate or 44 * extend the message and the resulting signature in software.) 45 */ 46 unsigned rsa_length; 47 48 /* IV value used to encrypt 'c' */ 49 uint8_t iv[ETS_DS_IV_LEN]; 50 51 /* Encrypted Digital Signature parameters. Result of AES-CBC encryption 52 of plaintext values. Includes an encrypted message digest. 53 */ 54 uint8_t c[ETS_DS_C_LEN]; 55 } ets_ds_data_t; 56 57 typedef enum { 58 ETS_DS_OK, 59 ETS_DS_INVALID_PARAM, /* Supplied parameters are invalid */ 60 ETS_DS_INVALID_KEY, /* HMAC peripheral failed to supply key */ 61 ETS_DS_INVALID_PADDING, /* 'c' decrypted with invalid padding */ 62 ETS_DS_INVALID_DIGEST, /* 'c' decrypted with invalid digest */ 63 } ets_ds_result_t; 64 65 void ets_ds_enable(void); 66 67 void ets_ds_disable(void); 68 69 70 /* 71 * @brief Start signing a message (or padded message digest) using the Digital Signature peripheral 72 * 73 * - @param message Pointer to message (or padded digest) containing the message to sign. Should be 74 * (data->rsa_length + 1)*4 bytes long. @param data Pointer to DS data. Can be a pointer to data 75 * in flash. 76 * 77 * Caller must have already called ets_ds_enable() and ets_hmac_calculate_downstream() before calling 78 * this function, and is responsible for calling ets_ds_finish_sign() and then 79 * ets_hmac_invalidate_downstream() afterwards. 80 * 81 * @return ETS_DS_OK if signature is in progress, ETS_DS_INVALID_PARAM if param is invalid, 82 * EST_DS_INVALID_KEY if key or HMAC peripheral is configured incorrectly. 83 */ 84 ets_ds_result_t ets_ds_start_sign(const void *message, const ets_ds_data_t *data); 85 86 87 /* 88 * @brief Returns true if the DS peripheral is busy following a call to ets_ds_start_sign() 89 * 90 * A result of false indicates that a call to ets_ds_finish_sign() will not block. 91 * 92 * Only valid if ets_ds_enable() has been called. 93 */ 94 bool ets_ds_is_busy(void); 95 96 97 /* @brief Finish signing a message using the Digital Signature peripheral 98 * 99 * Must be called after ets_ds_start_sign(). Can use ets_ds_busy() to wait until 100 * peripheral is no longer busy. 101 * 102 * - @param signature Pointer to buffer to contain the signature. Should be 103 * (data->rsa_length + 1)*4 bytes long. 104 * - @param data Should match the 'data' parameter passed to ets_ds_start_sign() 105 * 106 * @param ETS_DS_OK if signing succeeded, ETS_DS_INVALID_PARAM if param is invalid, 107 * ETS_DS_INVALID_DIGEST or ETS_DS_INVALID_PADDING if there is a problem with the 108 * encrypted data digest or padding bytes (in case of ETS_DS_INVALID_PADDING, a 109 * digest is produced anyhow.) 110 */ 111 ets_ds_result_t ets_ds_finish_sign(void *signature, const ets_ds_data_t *data); 112 113 114 /* Plaintext parameters used by Digital Signature. 115 116 Not used for signing with DS peripheral, but can be encrypted 117 in-device by calling ets_ds_encrypt_params() 118 */ 119 typedef struct { 120 uint32_t Y[4096/32]; 121 uint32_t M[4096/32]; 122 uint32_t Rb[4096/32]; 123 uint32_t M_prime; 124 uint32_t length; 125 } ets_ds_p_data_t; 126 127 typedef enum { 128 ETS_DS_KEY_HMAC, /* The HMAC key (as stored in efuse) */ 129 ETS_DS_KEY_AES, /* The AES key (as derived from HMAC key by HMAC peripheral in downstream mode) */ 130 } ets_ds_key_t; 131 132 /* @brief Encrypt DS parameters suitable for storing and later use with DS peripheral 133 * 134 * @param data Output buffer to store encrypted data, suitable for later use generating signatures. 135 * @param iv Pointer to 16 byte IV buffer, will be copied into 'data'. Should be randomly generated bytes each time. 136 * @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. 137 * @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. 138 * @param key_type Type of key stored in 'key' (either the AES-256 DS key, or an HMAC DS key from which the AES DS key is derived using HMAC peripheral) 139 * 140 * @return ETS_DS_INVALID_PARAM if any parameter is invalid, or ETS_DS_OK if 'data' is successfully generated from the input parameters. 141 */ 142 ets_ds_result_t ets_ds_encrypt_params(ets_ds_data_t *data, const void *iv, const ets_ds_p_data_t *p_data, const void *key, ets_ds_key_t key_type); 143 144 145 #ifdef __cplusplus 146 } 147 #endif 148
