Non-volatile Storage Library

Introduction

Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This section introduces some concepts used by NVS.

Underlying Storage

Currently, NVS uses a portion of main flash memory through the esp_partition API. The library uses all the partitions with data type and nvs subtype. The application can choose to use the partition with the label nvs through the nvs_open() API function or any other partition by specifying its name using the nvs_open_from_partition() API function.

Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc.

Note

if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a idf.py erase-flash target to erase all contents of the flash chip.

Note

NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library.

Keys and Values

NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length is currently 15 characters. Values can have one of the following types:

integer types: uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t
zero-terminated string
variable length binary data (blob)

Note

String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited to 508,000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.

Additional types, such as float and double might be added later.

Keys are required to be unique. Assigning a new value to an existing key works as follows:

If the new value is of the same type as the old one, value is updated.
If the new value has a different data type, an error is returned.

Data type check is also performed when reading a value. An error is returned if the data type of the read operation does not match the data type of the value.

Namespaces

To mitigate potential conflicts in key names between different components, NVS assigns each key-value pair to one of namespaces. Namespace names follow the same rules as key names, i.e., the maximum length is 15 characters. Furthermore, there can be no more than 254 different namespaces in one NVS partition. Namespace name is specified in the nvs_open() or nvs_open_from_partition call. This call returns an opaque handle, which is used in subsequent calls to the nvs_get_*, nvs_set_*, and nvs_commit() functions. This way, a handle is associated with a namespace, and key names will not collide with same names in other namespaces. Please note that the namespaces with the same name in different NVS partitions are considered as separate namespaces.

NVS Iterators

Iterators allow to list key-value pairs stored in NVS, based on specified partition name, namespace, and data type.

There are the following functions available:

nvs_entry_find() creates an opaque handle, which is used in subsequent calls to the nvs_entry_next() and nvs_entry_info() functions.
nvs_entry_next() advances an iterator to the next key-value pair.
nvs_entry_info() returns information about each key-value pair

In general, all iterators obtained via nvs_entry_find() have to be released using nvs_release_iterator(), which also tolerates NULL iterators. nvs_entry_find() and nvs_entry_next() will set the given iterator to NULL or a valid iterator in all cases except a parameter error occured (i.e., return ESP_ERR_NVS_NOT_FOUND). In case of a parameter error, the given iterator will not be modified. Hence, it is best practice to initialize the iterator to NULL before calling nvs_entry_find() to avoid complicated error checking before releasing the iterator.

Security, Tampering, and Robustness

NVS is not directly compatible with the ESP32-H2 flash encryption system. However, data can still be stored in encrypted form if NVS encryption is used together with ESP32-H2 flash encryption. Please refer to NVS Encryption for more details.

If NVS encryption is not used, it is possible for anyone with physical access to the flash chip to alter, erase, or add key-value pairs. With NVS encryption enabled, it is not possible to alter or add a key-value pair and get recognized as a valid pair without knowing corresponding NVS encryption keys. However, there is no tamper-resistance against the erase operation.

The library does try to recover from conditions when flash memory is in an inconsistent state. In particular, one should be able to power off the device at any point and time and then power it back on. This should not result in loss of data, except for the new key-value pair if it was being written at the moment of powering off. The library should also be able to initialize properly with any random data present in flash memory.

NVS Encryption

Data stored in NVS partitions can be encrypted using AES-XTS in the manner similar to the one mentioned in disk encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one sector and relative address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as sector-number. The NVS Encryption can be enabled by enabling CONFIG_NVS_ENCRYPTION. The keys required for NVS encryption are stored in yet another partition, which is protected using Flash Encryption. Therefore, enabling Flash Encryption is a prerequisite for NVS encryption.

The NVS Encryption is enabled by default when Flash Encryption is enabled. This is done because Wi-Fi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.

For using NVS encryption, the partition table must contain the NVS Key Partition. Two partition tables containing the NVS Key Partition are provided for NVS encryption under the partition table option (menuconfig > Partition Table). They can be selected with the project configuration menu (idf.py menuconfig). Please refer to the example security/flash_encryption for how to configure and use NVS encryption feature.

NVS Key Partition

An application requiring NVS encryption support needs to be compiled with a key-partition of the type data and subtype key. This partition should be marked as encrypted and its size should be the minimum partition size (4KB). Refer to Partition Tables for more details. Two additional partition tables which contain the NVS Key Partition are provided under the partition table option (menuconfig > Partition Table). They can be directly used for NVS Encryption. The structure of these partitions is depicted below.

+-----------+--------------+-------------+----+
|              XTS encryption key (32)        |
+---------------------------------------------+
|              XTS tweak key (32)             |
+---------------------------------------------+
|                  CRC32 (4)                  |
+---------------------------------------------+

The XTS encryption keys in the NVS Key Partition can be generated in one of the following two ways.

Generate the keys on the ESP chip:
When NVS encryption is enabled the nvs_flash_init() API function can be used to initialize the encrypted default NVS partition. The API function internally generates the XTS encryption keys on the ESP chip. The API function finds the first NVS Key Partition. Then the API function automatically generates and stores the NVS keys in that partition by making use of the nvs_flash_generate_keys() API function provided by nvs_flash/include/nvs_flash.h. New keys are generated and stored only when the respective key partition is empty. The same key partition can then be used to read the security configurations for initializing a custom encrypted NVS partition with help of nvs_flash_secure_init_partition().

The API functions nvs_flash_secure_init() and nvs_flash_secure_init_partition() do not generate the keys internally. When these API functions are used for initializing encrypted NVS partitions, the keys can be generated after startup using the nvs_flash_generate_keys() API function provided by nvs_flash.h. The API function will then write those keys onto the key-partition in encrypted form.
Note

Please note that nvs_keys partition must be completely erased before you start the application in this approach. Otherwise the application may generate ESP_ERR_NVS_CORRUPT_KEY_PART error code assuming that nvs_keys partition is not empty and contains malformatted data. You can use the following command for this:
parttool.py --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys
Use pre-generated key partition:
This option will be required by the user when keys in the NVS Key Partition are not generated by the application. The NVS Key Partition containing the XTS encryption keys can be generated with the help of NVS Partition Generator Utility. Then the user can store the pre generated key partition on the flash with help of the following two commands:

i) Build and flash the partition table
idf.py partition-table partition-table-flash
ii) Store the keys in the NVS Key Partition (on the flash) with the help of parttool.py (see Partition Tool section in partition-tables for more details)
parttool.py --port PORT --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE
Note

If the device is encrypted in flash encryption development mode and you want to renew the NVS key partition, you need to tell parttool.py to encrypt the NVS key partition and you also need to give it a pointer to the unencrypted partition table in your build directory (build/partition_table) since the partition table on the device is encrypted, too. You can use the following command:
parttool.py --esptool-write-args encrypt --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET write_partition --partition-name="name of nvs_key partition" --input NVS_KEY_PARTITION_FILE

Since the key partition is marked as encrypted and Flash Encryption is enabled, the bootloader will encrypt this partition using flash encryption key on the first boot.

It is possible for an application to use different keys for different NVS partitions and thereby have multiple key-partitions. However, it is a responsibility of the application to provide correct key-partition/keys for the purpose of encryption/decryption.

Encrypted Read/Write

The same NVS API functions nvs_get_* or nvs_set_* can be used for reading of, and writing to an encrypted nvs partition as well.

Encrypt the default NVS partition: To enable encryption for the default NVS partition no additional steps are necessary. When CONFIG_NVS_ENCRYPTION is enabled, the nvs_flash_init() API function internally performs some additional steps using the first NVS Key Partition found to enable encryption for the default NVS partition (refer to the API documentation for more details). Alternatively, nvs_flash_secure_init() API function can also be used to enable encryption for the default NVS partition.

Encrypt a custom NVS partition: To enable encryption for a custom NVS partition, nvs_flash_secure_init_partition() API function is used instead of nvs_flash_init_partition().

When nvs_flash_secure_init() and nvs_flash_secure_init_partition() API functions are used, the applications are expected to follow the steps below in order to perform NVS read/write operations with encryption enabled.

Find key partition and NVS data partition using esp_partition_find* API functions.

Populate the nvs_sec_cfg_t struct using the nvs_flash_read_security_cfg() or nvs_flash_generate_keys() API functions.

Initialise NVS flash partition using the nvs_flash_secure_init() or nvs_flash_secure_init_partition() API functions.

Open a namespace using the nvs_open() or nvs_open_from_partition() API functions.

Perform NVS read/write operations using nvs_get_* or nvs_set_*.

Deinitialise an NVS partition using nvs_flash_deinit().

NVS Partition Generator Utility

This utility helps generate NVS partition binary files which can be flashed separately on a dedicated partition via a flashing utility. Key-value pairs to be flashed onto the partition can be provided via a CSV file. For more details, please refer to NVS Partition Generator Utility.

Application Example

You can find code examples in the storage directory of ESP-IDF examples:

storage/nvs_rw_value

Demonstrates how to read a single integer value from, and write it to NVS.

The value checked in this example holds the number of the ESP32-H2 module restarts. The value's function as a counter is only possible due to its storing in NVS.

The example also shows how to check if a read / write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way.

storage/nvs_rw_blob

Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between ESP32-H2 module restarts.

value - tracks the number of the ESP32-H2 module soft and hard restarts.

blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. A new run time is added to the table on each manually triggered soft restart, and then the added run time is written to NVS. Triggering is done by pulling down GPIO0.

The example also shows how to implement the diagnostic procedure to check if the read / write operation was successful.

storage/nvs_rw_value_cxx

This example does exactly the same as storage/nvs_rw_value, except that it uses the C++ NVS handle class.

Internals

Log of Key-Value Pairs

NVS stores key-value pairs sequentially, with new key-value pairs being added at the end. When a value of any given key has to be updated, a new key-value pair is added at the end of the log and the old key-value pair is marked as erased.

Pages and Entries

NVS library uses two main entities in its operation: pages and entries. Page is a logical structure which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages which are in use have a sequence number associated with them. Sequence numbers impose an ordering on pages. Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following states:

Empty/uninitialized: Flash storage for the page is empty (all bytes are 0xff). Page is not used to store any data at this point and does not have a sequence number.
Active: Flash storage is initialized, page header has been written to flash, page has a valid sequence number. Page has some empty entries and data can be written there. No more than one page can be in this state at any given moment.
Full: Flash storage is in a consistent state and is filled with key-value pairs. Writing new key-value pairs into this page is not possible. It is still possible to mark some key-value pairs as erased.
Erasing: Non-erased key-value pairs are being moved into another page so that the current page can be erased. This is a transient state, i.e., page should never stay in this state at the time when any API call returns. In case of a sudden power off, the move-and-erase process will be completed upon the next power-on.
Corrupted: Page header contains invalid data, and further parsing of page data was canceled. Any items previously written into this page will not be accessible. The corresponding flash sector will not be erased immediately and will be kept along with sectors in uninitialized state for later use. This may be useful for debugging.

Mapping from flash sectors to logical pages does not have any particular order. The library will inspect sequence numbers of pages found in each flash sector and organize pages in a list based on these numbers.

+--------+     +--------+     +--------+     +--------+
| Page 1 |     | Page 2 |     | Page 3 |     | Page 4 |
| Full   +---> | Full   +---> | Active |     | Empty  |   <- states
| #11    |     | #12    |     | #14    |     |        |   <- sequence numbers
+---+----+     +----+---+     +----+---+     +---+----+
    |               |              |             |
    |               |              |             |
    |               |              |             |
+---v------+  +-----v----+  +------v---+  +------v---+
| Sector 3 |  | Sector 0 |  | Sector 2 |  | Sector 1 |    <- physical sectors
+----------+  +----------+  +----------+  +----------+

Structure of a Page

For now, we assume that flash sector size is 4096 bytes and that ESP32-H2 flash encryption hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g., via menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in the system, e.g., SPI flash driver and SPI flash cache can support these other sizes).

Page consists of three parts: header, entry state bitmap, and entries themselves. To be compatible with ESP32-H2 flash encryption, the entry size is 32 bytes. For integer types, an entry holds one key-value pair. For strings and blobs, an entry holds part of key-value pair (more on that in the entry structure description).

The following diagram illustrates the page structure. Numbers in parentheses indicate the size of each part in bytes.

+-----------+--------------+-------------+-------------------------+
| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) |   Header (32)
+-----------+--------------+-------------+-------------------------+
|                Entry state bitmap (32)                           |
+------------------------------------------------------------------+
|                       Entry 0 (32)                               |
+------------------------------------------------------------------+
|                       Entry 1 (32)                               |
+------------------------------------------------------------------+
/                                                                  /
/                                                                  /
+------------------------------------------------------------------+
|                       Entry 125 (32)                             |
+------------------------------------------------------------------+

Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption feature of ESP32-H2 is used.

Page state values are defined in such a way that changing state is possible by writing 0 into some of the bits. Therefore it is not necessary to erase the page to change its state unless that is a change to the erased state.

The version field in the header reflects the NVS format version used. For backward compatibility reasons, it is decremented for every version upgrade starting at 0xff (i.e., 0xff for version-1, 0xfe for version-2 and so on).

CRC32 value in the header is calculated over the part which does not include a state value (bytes 4 to 28). The unused part is currently filled with 0xff bytes.

The following sections describe the structure of entry state bitmap and entry itself.

Entry and Entry State Bitmap

Each entry can be in one of the following three states represented with two bits in the entry state bitmap. The final four bits in the bitmap (256 - 2 * 126) are not used.

Empty (2'b11): Nothing is written into the specific entry yet. It is in an uninitialized state (all bytes are 0xff).
Written (2'b10): A key-value pair (or part of key-value pair which spans multiple entries) has been written into the entry.
Erased (2'b00): A key-value pair in this entry has been discarded. Contents of this entry will not be parsed anymore.

Structure of Entry

For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one key-value pair. For string and blob types, entry holds part of the whole key-value pair. For strings, in case when a key-value pair spans multiple entries, all entries are stored in the same page. Blobs are allowed to span over multiple pages by dividing them into smaller chunks. For tracking these chunks, an additional fixed length metadata entry is stored called "blob index". Earlier formats of blobs are still supported (can be read and modified). However, once the blobs are modified, they are stored using the new format.

+--------+----------+----------+----------------+-----------+---------------+----------+
| NS (1) | Type (1) | Span (1) | ChunkIndex (1) | CRC32 (4) |    Key (16)   | Data (8) |
+--------+----------+----------+----------------+-----------+---------------+----------+

                                         Primitive  +--------------------------------+
                                        +-------->  |     Data (8)                   |
                                        | Types     +--------------------------------+
                   +-> Fixed length --
                   |                    |           +---------+--------------+---------------+-------+
                   |                    +-------->  | Size(4) | ChunkCount(1)| ChunkStart(1) | Rsv(2)|
    Data format ---+                    Blob Index  +---------+--------------+---------------+-------+
                   |
                   |                             +----------+---------+-----------+
                   +->   Variable length   -->   | Size (2) | Rsv (2) | CRC32 (4) |
                        (Strings, Blob Data)     +----------+---------+-----------+

Individual fields in entry structure have the following meanings:

NS

Namespace index for this entry. For more information on this value, see the section on namespaces implementation.

Type

One byte indicating the value data type. See the ItemType enumeration in nvs_flash/include/nvs_handle.hpp for possible values.

Span

Number of entries used by this key-value pair. For integer types, this is equal to 1. For strings and blobs, this depends on value length.

ChunkIndex

Used to store the index of a blob-data chunk for blob types. For other types, this should be 0xff.

CRC32

Checksum calculated over all the bytes in this entry, except for the CRC32 field itself.

Key

Zero-terminated ASCII string containing a key name. Maximum string length is 15 bytes, excluding a zero terminator.

Data

For integer types, this field contains the value itself. If the value itself is shorter than 8 bytes, it is padded to the right, with unused bytes filled with 0xff.

For "blob index" entry, these 8 bytes hold the following information about data-chunks:

Size
(Only for blob index.) Size, in bytes, of complete blob data.
ChunkCount
(Only for blob index.) Total number of blob-data chunks into which the blob was divided during storage.
ChunkStart
(Only for blob index.) ChunkIndex of the first blob-data chunk of this blob. Subsequent chunks have chunkIndex incrementally allocated (step of 1).

For string and blob data chunks, these 8 bytes hold additional data about the value, which are described below:

Size
(Only for strings and blobs.) Size, in bytes, of actual data. For strings, this includes zero terminators.
CRC32
(Only for strings and blobs.) Checksum calculated over all bytes of data.

Variable length values (strings and blobs) are written into subsequent entries, 32 bytes per entry. The Span field of the first entry indicates how many entries are used.

Namespaces

As mentioned above, each key-value pair belongs to one of the namespaces. Namespace identifiers (strings) are stored as keys of key-value pairs in namespace with index 0. Values corresponding to these keys are indexes of these namespaces.

+-------------------------------------------+
| NS=0 Type=uint8_t Key="wifi" Value=1      |   Entry describing namespace "wifi"
+-------------------------------------------+
| NS=1 Type=uint32_t Key="channel" Value=6  |   Key "channel" in namespace "wifi"
+-------------------------------------------+
| NS=0 Type=uint8_t Key="pwm" Value=2       |   Entry describing namespace "pwm"
+-------------------------------------------+
| NS=2 Type=uint16_t Key="channel" Value=20 |   Key "channel" in namespace "pwm"
+-------------------------------------------+

Item Hash List

To reduce the number of reads from flash memory, each member of the Page class maintains a list of pairs: item index; item hash. This list makes searches much quicker. Instead of iterating over all entries, reading them from flash one at a time, Page::findItem first performs a search for the item hash in the hash list. This gives the item index within the page if such an item exists. Due to a hash collision, it is possible that a different item will be found. This is handled by falling back to iteration over items in flash.

Each node in the hash list contains a 24-bit hash and 8-bit item index. Hash is calculated based on item namespace, key name, and ChunkIndex. CRC32 is used for calculation; the result is truncated to 24 bits. To reduce the overhead for storing 32-bit entries in a linked list, the list is implemented as a double-linked list of arrays. Each array holds 29 entries, for the total size of 128 bytes, together with linked list pointers and a 32-bit count field. The minimum amount of extra RAM usage per page is therefore 128 bytes; maximum is 640 bytes.

API Reference

Header File

components/nvs_flash/include/nvs_flash.h

Functions

esp_err_t nvs_flash_init(void)

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

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")
If the NVS key partiton obtained in the previous step is empty, generate and store new keys in that NVS key partiton.
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.

Returns

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_partition(const char *partition_label)

Initialize NVS flash storage for the specified partition.

Parameters

partition_label -- [in] Label of the partition. Must be no longer than 16 characters.

Returns

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_ptr(const esp_partition_t *partition)

Initialize NVS flash storage for the partition specified by partition pointer.

Parameters

partition -- [in] pointer to a partition obtained by the ESP partition API.

Returns

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_deinit(void)

Deinitialize NVS storage for the default NVS partition.

Default NVS partition is the partition with "nvs" label in the partition table.

Returns

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_partition(const char *partition_label)

Deinitialize NVS storage for the given NVS partition.

Parameters

partition_label -- [in] Label of the partition

Returns

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_erase(void)

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.

Returns

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_partition(const char *part_name)

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.

Parameters

part_name -- [in] Name (label) of the partition which should be erased

Returns

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_ptr(const esp_partition_t *partition)

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.

Parameters

partition -- [in] pointer to a partition obtained by the ESP partition API.

Returns

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_secure_init(nvs_sec_cfg_t *cfg)

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.

Parameters

cfg -- [in] Security configuration (keys) to be used for NVS encryption/decryption. If cfg is NULL, no encryption is used.

Returns

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_partition(const char *partition_label, nvs_sec_cfg_t *cfg)

Initialize NVS flash storage for the specified partition.

Parameters

partition_label -- [in] Label of the partition. Note that internally, a reference to passed value is kept and it should be accessible for future operations
cfg -- [in] Security configuration (keys) to be used for NVS encryption/decryption. If cfg is null, no encryption/decryption is used.

Returns

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_generate_keys(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)

Generate and store NVS keys in the provided esp partition.

Parameters

partition -- [in] Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
cfg -- [out] Pointer to nvs security configuration structure. Pointer must be non-NULL. Generated keys will be populated in this structure.

Returns

-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_read_security_cfg(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)

Read NVS security configuration from a partition.

Note

Provided partition is assumed to be marked 'encrypted'.

Parameters

partition -- [in] Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
cfg -- [out] Pointer to nvs security configuration structure. Pointer must be non-NULL.

Returns

-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.

Structures

struct nvs_sec_cfg_t

Key for encryption and decryption.

Public Members

uint8_t eky[NVS_KEY_SIZE]: XTS encryption and decryption key

uint8_t tky[NVS_KEY_SIZE]: XTS tweak key

Macros

NVS_KEY_SIZE

Header File

components/nvs_flash/include/nvs.h

Functions

esp_err_t nvs_set_i8(nvs_handle_t handle, const char *key, int8_t value)

set int8_t value for given key

Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.

Parameters

handle -- [in] Handle obtained from nvs_open function. Handles that were opened read only cannot be used.
key -- [in] Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
value -- [in] The value to set.

Returns

ESP_OK if value was set successfully
ESP_FAIL if there is an internal error; most likely due to corrupted NVS partition (only if NVS assertion checks are disabled)
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value
ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn't fail again.

esp_err_t nvs_set_u8(nvs_handle_t handle, const char *key, uint8_t value)

set uint8_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i16(nvs_handle_t handle, const char *key, int16_t value)

set int16_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u16(nvs_handle_t handle, const char *key, uint16_t value)

set uint16_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i32(nvs_handle_t handle, const char *key, int32_t value)

set int32_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u32(nvs_handle_t handle, const char *key, uint32_t value)

set uint32_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i64(nvs_handle_t handle, const char *key, int64_t value)

set int64_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u64(nvs_handle_t handle, const char *key, uint64_t value)

set uint64_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_str(nvs_handle_t handle, const char *key, const char *value)

set string for given key

Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.

Parameters

handle -- [in] Handle obtained from nvs_open function. Handles that were opened read only cannot be used.
key -- [in] Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
value -- [in] The value to set. For strings, the maximum length (including null character) is 4000 bytes, if there is one complete page free for writing. This decreases, however, if the free space is fragmented.

Returns

ESP_OK if value was set successfully
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value
ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn't fail again.
ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long

esp_err_t nvs_get_i8(nvs_handle_t handle, const char *key, int8_t *out_value)

get int8_t value for given key

These functions retrieve value for the key, given its name. If key does not exist, or the requested variable type doesn't match the type which was used when setting a value, an error is returned.

In case of any error, out_value is not modified.

out_value has to be a pointer to an already allocated variable of the given type.

// Example of using nvs_get_i32:
int32_t max_buffer_size = 4096; // default value
esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
// if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
// have its default value.

Parameters

handle -- [in] Handle obtained from nvs_open function.
key -- [in] Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
out_value -- Pointer to the output value. May be NULL for nvs_get_str and nvs_get_blob, in this case required length will be returned in length argument.

Returns

ESP_OK if the value was retrieved successfully
ESP_FAIL if there is an internal error; most likely due to corrupted NVS partition (only if NVS assertion checks are disabled)
ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data

esp_err_t nvs_get_u8(nvs_handle_t handle, const char *key, uint8_t *out_value)

get uint8_t value for given key