1 // Copyright 2015-2016 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 #ifndef nvs_flash_h 15 #define nvs_flash_h 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include "nvs.h" 22 #include "esp_partition.h" 23 24 25 #define NVS_KEY_SIZE 32 // AES-256 26 27 /** 28 * @brief Key for encryption and decryption 29 */ 30 typedef struct { 31 uint8_t eky[NVS_KEY_SIZE]; /*!< XTS encryption and decryption key*/ 32 uint8_t tky[NVS_KEY_SIZE]; /*!< XTS tweak key */ 33 } nvs_sec_cfg_t; 34 35 /** 36 * @brief Initialize the default NVS partition. 37 * 38 * This API initialises the default NVS partition. The default NVS partition 39 * is the one that is labeled "nvs" in the partition table. 40 * 41 * When "NVS_ENCRYPTION" is enabled in the menuconfig, this API enables 42 * the NVS encryption for the default NVS partition as follows 43 * 1. Read security configurations from the first NVS key 44 * partition listed in the partition table. (NVS key partition is 45 * any "data" type partition which has the subtype value set to "nvs_keys") 46 * 2. If the NVS key partiton obtained in the previous step is empty, 47 * generate and store new keys in that NVS key partiton. 48 * 3. Internally call "nvs_flash_secure_init()" with 49 * the security configurations obtained/generated in the previous steps. 50 * 51 * Post initialization NVS read/write APIs 52 * remain the same irrespective of NVS encryption. 53 * 54 * @return 55 * - ESP_OK if storage was successfully initialized. 56 * - ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages 57 * (which may happen if NVS partition was truncated) 58 * - ESP_ERR_NOT_FOUND if no partition with label "nvs" is found in the partition table 59 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 60 * - one of the error codes from the underlying flash storage driver 61 * - error codes from nvs_flash_read_security_cfg API (when "NVS_ENCRYPTION" is enabled). 62 * - error codes from nvs_flash_generate_keys API (when "NVS_ENCRYPTION" is enabled). 63 * - error codes from nvs_flash_secure_init_partition API (when "NVS_ENCRYPTION" is enabled) . 64 */ 65 esp_err_t nvs_flash_init(void); 66 67 /** 68 * @brief Initialize NVS flash storage for the specified partition. 69 * 70 * @param[in] partition_label Label of the partition. Must be no longer than 16 characters. 71 * 72 * @return 73 * - ESP_OK if storage was successfully initialized. 74 * - ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages 75 * (which may happen if NVS partition was truncated) 76 * - ESP_ERR_NOT_FOUND if specified partition is not found in the partition table 77 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 78 * - one of the error codes from the underlying flash storage driver 79 */ 80 esp_err_t nvs_flash_init_partition(const char *partition_label); 81 82 /** 83 * @brief Initialize NVS flash storage for the partition specified by partition pointer. 84 * 85 * @param[in] partition pointer to a partition obtained by the ESP partition API. 86 * 87 * @return 88 * - ESP_OK if storage was successfully initialized 89 * - ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages 90 * (which may happen if NVS partition was truncated) 91 * - ESP_ERR_INVALID_ARG in case partition is NULL 92 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 93 * - one of the error codes from the underlying flash storage driver 94 */ 95 esp_err_t nvs_flash_init_partition_ptr(const esp_partition_t *partition); 96 97 /** 98 * @brief Deinitialize NVS storage for the default NVS partition 99 * 100 * Default NVS partition is the partition with "nvs" label in the partition table. 101 * 102 * @return 103 * - ESP_OK on success (storage was deinitialized) 104 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage was not initialized prior to this call 105 */ 106 esp_err_t nvs_flash_deinit(void); 107 108 /** 109 * @brief Deinitialize NVS storage for the given NVS partition 110 * 111 * @param[in] partition_label Label of the partition 112 * 113 * @return 114 * - ESP_OK on success 115 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage for given partition was not 116 * initialized prior to this call 117 */ 118 esp_err_t nvs_flash_deinit_partition(const char* partition_label); 119 120 /** 121 * @brief Erase the default NVS partition 122 * 123 * Erases all contents of the default NVS partition (one with label "nvs"). 124 * 125 * @note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to 126 * be initialized again to be used. 127 * 128 * @return 129 * - ESP_OK on success 130 * - ESP_ERR_NOT_FOUND if there is no NVS partition labeled "nvs" in the 131 * partition table 132 * - different error in case de-initialization fails (shouldn't happen) 133 */ 134 esp_err_t nvs_flash_erase(void); 135 136 /** 137 * @brief Erase specified NVS partition 138 * 139 * Erase all content of a specified NVS partition 140 * 141 * @note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to 142 * be initialized again to be used. 143 * 144 * @param[in] part_name Name (label) of the partition which should be erased 145 * 146 * @return 147 * - ESP_OK on success 148 * - ESP_ERR_NOT_FOUND if there is no NVS partition with the specified name 149 * in the partition table 150 * - different error in case de-initialization fails (shouldn't happen) 151 */ 152 esp_err_t nvs_flash_erase_partition(const char *part_name); 153 154 /** 155 * @brief Erase custom partition. 156 * 157 * Erase all content of specified custom partition. 158 * 159 * @note 160 * If the partition is initialized, this function first de-initializes it. 161 * Afterwards, the partition has to be initialized again to be used. 162 * 163 * @param[in] partition pointer to a partition obtained by the ESP partition API. 164 * 165 * @return 166 * - ESP_OK on success 167 * - ESP_ERR_NOT_FOUND if there is no partition with the specified 168 * parameters in the partition table 169 * - ESP_ERR_INVALID_ARG in case partition is NULL 170 * - one of the error codes from the underlying flash storage driver 171 */ 172 esp_err_t nvs_flash_erase_partition_ptr(const esp_partition_t *partition); 173 174 /** 175 * @brief Initialize the default NVS partition. 176 * 177 * This API initialises the default NVS partition. The default NVS partition 178 * is the one that is labeled "nvs" in the partition table. 179 * 180 * @param[in] cfg Security configuration (keys) to be used for NVS encryption/decryption. 181 * If cfg is NULL, no encryption is used. 182 * 183 * @return 184 * - ESP_OK if storage has been initialized successfully. 185 * - ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages 186 * (which may happen if NVS partition was truncated) 187 * - ESP_ERR_NOT_FOUND if no partition with label "nvs" is found in the partition table 188 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 189 * - one of the error codes from the underlying flash storage driver 190 */ 191 esp_err_t nvs_flash_secure_init(nvs_sec_cfg_t* cfg); 192 193 /** 194 * @brief Initialize NVS flash storage for the specified partition. 195 * 196 * @param[in] partition_label Label of the partition. Note that internally, a reference to 197 * passed value is kept and it should be accessible for future operations 198 * 199 * @param[in] cfg Security configuration (keys) to be used for NVS encryption/decryption. 200 * If cfg is null, no encryption/decryption is used. 201 * @return 202 * - ESP_OK if storage has been initialized successfully. 203 * - ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages 204 * (which may happen if NVS partition was truncated) 205 * - ESP_ERR_NOT_FOUND if specified partition is not found in the partition table 206 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 207 * - one of the error codes from the underlying flash storage driver 208 */ 209 esp_err_t nvs_flash_secure_init_partition(const char *partition_label, nvs_sec_cfg_t* cfg); 210 211 /** 212 * @brief Generate and store NVS keys in the provided esp partition 213 * 214 * @param[in] partition Pointer to partition structure obtained using 215 * esp_partition_find_first or esp_partition_get. 216 * Must be non-NULL. 217 * @param[out] cfg Pointer to nvs security configuration structure. 218 * Pointer must be non-NULL. 219 * Generated keys will be populated in this structure. 220 * 221 * 222 * @return 223 * -ESP_OK, if cfg was read successfully; 224 * -ESP_INVALID_ARG, if partition or cfg; 225 * -or error codes from esp_partition_write/erase APIs. 226 */ 227 228 esp_err_t nvs_flash_generate_keys(const esp_partition_t* partition, nvs_sec_cfg_t* cfg); 229 230 231 /** 232 * @brief Read NVS security configuration from a partition. 233 * 234 * @param[in] partition Pointer to partition structure obtained using 235 * esp_partition_find_first or esp_partition_get. 236 * Must be non-NULL. 237 * @param[out] cfg Pointer to nvs security configuration structure. 238 * Pointer must be non-NULL. 239 * 240 * @note Provided partition is assumed to be marked 'encrypted'. 241 * 242 * @return 243 * -ESP_OK, if cfg was read successfully; 244 * -ESP_INVALID_ARG, if partition or cfg; 245 * -ESP_ERR_NVS_KEYS_NOT_INITIALIZED, if the partition is not yet written with keys. 246 * -ESP_ERR_NVS_CORRUPT_KEY_PART, if the partition containing keys is found to be corrupt 247 * -or error codes from esp_partition_read API. 248 */ 249 250 esp_err_t nvs_flash_read_security_cfg(const esp_partition_t* partition, nvs_sec_cfg_t* cfg); 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 257 #endif /* nvs_flash_h */ 258
