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