Chapter 2. API Reference
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 Ta-
ble). 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.
1. Generate the keys on the ESP chip:
When NVS encryption is enabled the nvs_flash_init() API function can be used to ini-
tialize the encrypted default NVS partition. The API function internally generates the XTS en-
cryption 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 partiton 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 initial-
izing 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.
2. 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)
Espressif Systems 707
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General