#include <idfxx_nvs/include/idfxx/nvs.hpp>

Classes
struct	insecure_t
	Tag type to indicate insecure (non-encrypted) initialization. More...

struct	secure_config
	Key for encryption and decryption. More...

Public Member Functions
	flash ()=delete

Static Public Member Functions
static void	init ()
	Initializes the default NVS partition.

static void	init (const secure_config &cfg)
	Initialize the default NVS partition with encryption.

static void	init (insecure_t)
	Initialize the default NVS partition without encryption.

static void	init (std::string_view partition_label)
	Initialize NVS flash storage for the specified partition.

static void	init (std::string_view partition_label, const secure_config &cfg)
	Initialize NVS flash storage for the specified partition.

static void	init (insecure_t, std::string_view partition_label)
	Initialize NVS flash storage for the specified partition without encryption.

static void	init (const partition &part)
	Initialize NVS flash storage for the specified partition.

static void	init (const partition &part, const secure_config &cfg)
	Initialize NVS flash storage for the specified partition with encryption.

static void	init (insecure_t, const partition &part)
	Initialize NVS flash storage for the specified partition without encryption.

static result< void >	try_init ()
	Initializes the default NVS partition.

static result< void >	try_init (const secure_config &cfg)
	Initialize the default NVS partition with encryption.

static result< void >	try_init (insecure_t)
	Initialize the default NVS partition without encryption.

static result< void >	try_init (std::string_view partition_label)
	Initialize NVS flash storage for the specified partition.

static result< void >	try_init (std::string_view partition_label, const secure_config &cfg)
	Initialize NVS flash storage for the specified partition.

static result< void >	try_init (insecure_t, std::string_view partition_label)
	Initialize NVS flash storage for the specified partition without encryption.

static result< void >	try_init (const partition &part)
	Initialize NVS flash storage for the specified partition.

static result< void >	try_init (const partition &part, const secure_config &cfg)
	Initialize NVS flash storage for the specified partition with encryption.

static result< void >	try_init (insecure_t, const partition &part)
	Initialize NVS flash storage for the specified partition without encryption.

static void	deinit ()
	Deinitialize NVS storage for the default NVS partition.

static void	deinit (std::string_view partition_label)
	Deinitialize NVS storage for the specified partition.

static result< void >	try_deinit ()
	Deinitialize NVS storage for the default NVS partition.

static result< void >	try_deinit (std::string_view partition_label)
	Deinitialize NVS storage for the specified partition.

static void	erase ()
	Erases the default NVS partition.

static void	erase (std::string_view partition_label)
	Erase specified NVS partition.

static void	erase (const partition &part)
	Erase the specified NVS partition.

static secure_config	generate_keys (const partition &key_part)
	Generate NVS encryption keys and store them on a key partition.

static secure_config	read_security_cfg (const partition &key_part)
	Read NVS encryption keys from a key partition.

static result< void >	try_erase ()
	Erases the default NVS partition.

static result< void >	try_erase (std::string_view partition_label)
	Erases the specified NVS partition.

static result< void >	try_erase (const partition &part)
	Erases the specified NVS partition.

static result< secure_config >	try_generate_keys (const partition &key_part)
	Generate NVS encryption keys and store them on a key partition.

static result< secure_config >	try_read_security_cfg (const partition &key_part)
	Read NVS encryption keys from a key partition.

Static Public Attributes
static constexpr size_t	key_size = 32

static constexpr insecure_t	insecure {}
	Insecure (non-encrypted) initialization tag.

Detailed Description

Definition at line 379 of file nvs.hpp.

Constructor & Destructor Documentation

◆ flash()

idfxx::nvs::flash::flash ( )

delete

Member Function Documentation

◆ deinit() [1/2]

static void idfxx::nvs::flash::deinit ( )

inlinestatic

Deinitialize NVS storage for the default NVS partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 661 of file nvs.hpp.

References idfxx::unwrap().

◆ deinit() [2/2]

static void idfxx::nvs::flash::deinit ( std::string_view partition_label )

inlinestatic

Deinitialize NVS storage for the specified partition.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 671 of file nvs.hpp.

References idfxx::unwrap().

◆ erase() [1/3]

static void idfxx::nvs::flash::erase ( )

inlinestatic

Erases the default NVS partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 697 of file nvs.hpp.

References idfxx::unwrap().

◆ erase() [2/3]

static void idfxx::nvs::flash::erase ( const partition & part )

inlinestatic

Erase the specified NVS partition.

Parameters

part	The partition to erase.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 717 of file nvs.hpp.

References idfxx::unwrap().

◆ erase() [3/3]

static void idfxx::nvs::flash::erase ( std::string_view partition_label )

inlinestatic

Erase specified NVS partition.

Parameters

partition_label Label of the partition which should be erased

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 707 of file nvs.hpp.

References idfxx::unwrap().

◆ generate_keys()

static secure_config idfxx::nvs::flash::generate_keys ( const partition & key_part )

inlinestatic

Generate NVS encryption keys and store them on a key partition.

Parameters

key_part The NVS key partition to generate keys on.

Returns: The generated security configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 729 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [1/9]

static void idfxx::nvs::flash::init ( )

inlinestatic

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

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 425 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [2/9]

static void idfxx::nvs::flash::init ( const partition & part )

inlinestatic

Initialize NVS flash storage for the specified partition.

Parameters

part	The partition to initialize NVS storage on.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 492 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [3/9]

static void idfxx::nvs::flash::init	(	const partition &	part,
		const secure_config &	cfg
	)

inlinestatic

Initialize NVS flash storage for the specified partition with encryption.

Parameters

part	The partition to initialize NVS storage on.
cfg	Security configuration (keys) to be used for NVS encryption/decryption.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 503 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [4/9]

static void idfxx::nvs::flash::init ( const secure_config & cfg )

inlinestatic

Initialize the default NVS partition with encryption.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled "nvs" in the partition table.

Parameters

cfg	Security configuration (keys) to be used for NVS encryption/decryption.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 438 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [5/9]

static void idfxx::nvs::flash::init ( insecure_t )

inlinestatic

Initialize the default NVS partition without encryption.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled "nvs" in the partition table.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 449 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [6/9]

static void idfxx::nvs::flash::init	(	insecure_t	,
		const partition &	part
	)

inlinestatic

Initialize NVS flash storage for the specified partition without encryption.

Parameters

part	The partition to initialize NVS storage on.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 513 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [7/9]

static void idfxx::nvs::flash::init	(	insecure_t	,
		std::string_view	partition_label
	)

inlinestatic

Initialize NVS flash storage for the specified partition without encryption.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 482 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [8/9]

static void idfxx::nvs::flash::init ( std::string_view partition_label )

inlinestatic

Initialize NVS flash storage for the specified partition.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 459 of file nvs.hpp.

References idfxx::unwrap().

◆ init() [9/9]

static void idfxx::nvs::flash::init	(	std::string_view	partition_label,
		const secure_config &	cfg
	)

inlinestatic

Initialize NVS flash storage for the specified partition.

Parameters

partition_label	Label of the partition. Must be no longer than 16 characters.
cfg	Security configuration (keys) to be used for NVS encryption/decryption

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 470 of file nvs.hpp.

References idfxx::unwrap().

◆ read_security_cfg()

static secure_config idfxx::nvs::flash::read_security_cfg ( const partition & key_part )

inlinestatic

Read NVS encryption keys from a key partition.

Parameters

key_part The NVS key partition to read keys from.

Returns: The security configuration read from the partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 743 of file nvs.hpp.

References idfxx::unwrap().

◆ try_deinit() [1/2]

static result< void > idfxx::nvs::flash::try_deinit ( )

static

Deinitialize NVS storage for the default NVS partition.

Returns: Success, or an error.

Return values

nvs::errc::not_initialized if the storage was not initialized prior to this call.

◆ try_deinit() [2/2]

static result< void > idfxx::nvs::flash::try_deinit ( std::string_view partition_label )

static

Deinitialize NVS storage for the specified partition.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Returns: Success, or an error.

Return values

nvs::errc::not_initialized if the storage was not initialized prior to this call.

◆ try_erase() [1/3]

static result< void > idfxx::nvs::flash::try_erase ( )

static

Erases the default NVS partition.

Returns: Success, or an error.

Return values

nvs::errc::not_found if there is no NVS partition labeled "nvs" in the partition table.

◆ try_erase() [2/3]

static result< void > idfxx::nvs::flash::try_erase ( const partition & part )

static

Erases the specified NVS partition.

Parameters

part	The partition to erase.

Returns: Success, or an error.

◆ try_erase() [3/3]

static result< void > idfxx::nvs::flash::try_erase ( std::string_view partition_label )

static

Erases the specified NVS partition.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Returns: Success, or an error.

Return values

nvs::errc::not_found if specified partition is not found in the partition table.

◆ try_generate_keys()

static result< secure_config > idfxx::nvs::flash::try_generate_keys ( const partition & key_part )

static

Generate NVS encryption keys and store them on a key partition.

Parameters

key_part The NVS key partition to generate keys on.

Returns: The generated security configuration, or an error.

Return values

nvs::errc::xts_cfg_failed if key generation fails.

◆ try_init() [1/9]

static result< void > idfxx::nvs::flash::try_init ( )

static

Initializes 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 partition obtained in the previous step is empty, generate and store new keys in that NVS key partition.
Internally call "nvs::flash::try_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: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::part_not_found	if no partition with label "nvs" is found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_init() [2/9]

static result< void > idfxx::nvs::flash::try_init ( const partition & part )

static

Initialize NVS flash storage for the specified partition.

Parameters

part	The partition to initialize NVS storage on.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
Other	error codes from the underlying flash storage driver.

◆ try_init() [3/9]

static result< void > idfxx::nvs::flash::try_init	(	const partition &	part,
		const secure_config &	cfg
	)

static

Initialize NVS flash storage for the specified partition with encryption.

Parameters

part	The partition to initialize NVS storage on.
cfg	Security configuration (keys) to be used for NVS encryption/decryption.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
Other	error codes from the underlying flash storage driver.

◆ try_init() [4/9]

static result< void > idfxx::nvs::flash::try_init ( const secure_config & cfg )

static

Initialize the default NVS partition with encryption.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled "nvs" in the partition table.

Parameters

cfg	Security configuration (keys) to be used for NVS encryption/decryption.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::part_not_found	if no partition with label "nvs" is found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_init() [5/9]

static result< void > idfxx::nvs::flash::try_init ( insecure_t )

static

Initialize the default NVS partition without encryption.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled "nvs" in the partition table.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::part_not_found	if no partition with label "nvs" is found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_init() [6/9]

static result< void > idfxx::nvs::flash::try_init	(	insecure_t	,
		const partition &	part
	)

static

Initialize NVS flash storage for the specified partition without encryption.

Parameters

part	The partition to initialize NVS storage on.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
Other	error codes from the underlying flash storage driver.

◆ try_init() [7/9]

static result< void > idfxx::nvs::flash::try_init	(	insecure_t	,
		std::string_view	partition_label
	)

static

Initialize NVS flash storage for the specified partition without encryption.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::not_found	if specified partition is not found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_init() [8/9]

static result< void > idfxx::nvs::flash::try_init ( std::string_view partition_label )

static

Initialize NVS flash storage for the specified partition.

Parameters

partition_label Label of the partition. Must be no longer than 16 characters.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::not_found	if specified partition is not found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_init() [9/9]

static result< void > idfxx::nvs::flash::try_init	(	std::string_view	partition_label,
		const secure_config &	cfg
	)

static

Initialize NVS flash storage for the specified partition.

Parameters

partition_label	Label of the partition. Must be no longer than 16 characters.
cfg	Security configuration (keys) to be used for NVS encryption/decryption.

Returns: Success, or an error.

Return values

nvs::errc::no_free_pages	if the NVS storage contains no empty pages (which may happen if NVS partition was truncated).
nvs::errc::not_found	if specified partition is not found in the partition table.
Other	error codes from the underlying flash storage driver.

◆ try_read_security_cfg()

static result< secure_config > idfxx::nvs::flash::try_read_security_cfg ( const partition & key_part )

static

Read NVS encryption keys from a key partition.

Parameters

key_part The NVS key partition to read keys from.

Returns: The security configuration read from the partition, or an error.

Return values

nvs::errc::xts_cfg_not_found	if no valid keys are found on the partition.
nvs::errc::corrupt_key_part	if the key partition is corrupt.

Member Data Documentation

◆ insecure

constexpr insecure_t idfxx::nvs::flash::insecure {}

staticconstexpr

Insecure (non-encrypted) initialization tag.

Definition at line 401 of file nvs.hpp.

◆ key_size

constexpr size_t idfxx::nvs::flash::key_size = 32

staticconstexpr

Size of each NVS encryption key in bytes

Definition at line 381 of file nvs.hpp.

The documentation for this class was generated from the following file:

idfxx_nvs/include/idfxx/nvs.hpp

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ flash()

Member Function Documentation

◆ deinit() [1/2]

◆ deinit() [2/2]

◆ erase() [1/3]

◆ erase() [2/3]

◆ erase() [3/3]

◆ generate_keys()

◆ init() [1/9]

◆ init() [2/9]

◆ init() [3/9]

◆ init() [4/9]

◆ init() [5/9]

◆ init() [6/9]

◆ init() [7/9]

◆ init() [8/9]

◆ init() [9/9]

◆ read_security_cfg()

◆ try_deinit() [1/2]

◆ try_deinit() [2/2]

◆ try_erase() [1/3]

◆ try_erase() [2/3]

◆ try_erase() [3/3]

◆ try_generate_keys()

◆ try_init() [1/9]

◆ try_init() [2/9]

◆ try_init() [3/9]

◆ try_init() [4/9]

◆ try_init() [5/9]

◆ try_init() [6/9]

◆ try_init() [7/9]

◆ try_init() [8/9]

◆ try_init() [9/9]

◆ try_read_security_cfg()

Member Data Documentation

◆ insecure

◆ key_size