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