ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide ESP-IDF Programming Guide Edit on GitHub ESP-IDF Programming Guide [中文] This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S, ESP32-C, ESP32-H and ESP32-P Series SoCs. This document describes using ESP-IDF with the ESP32-C2 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. Important The ESP32-C2 SoC series group currently includes only one series, the ESP8684. Therefore, any reference to ESP32-C2 in this document applies to the ESP8684. Get Started API Reference API Guides Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference API Conventions Application Protocols Bluetooth® API Error Codes Reference Networking APIs Peripherals API Provisioning API Storage API FAT Filesystem Support Generating and Parsing FATFS on Host Manufacturing Utility Non-Volatile Storage Library NVS Bootloader NVS Encryption Overview NVS Encryption: Flash Encryption-Based Scheme Encrypted Read/Write NVS Security Provider API Reference NVS Partition Generator Utility NVS Partition Parser Utility SD/SDIO/MMC Driver Partitions API Block Device Layer SPIFFS Filesystem Virtual Filesystem Component Wear Levelling API Storage Security Examples System API Configuration Options Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Reference Storage API NVS Encryption Edit on GitHub NVS Encryption [中文] Overview This guide provides an overview of the NVS encryption feature. NVS encryption helps to achieve secure storage on the device flash memory. Data stored in NVS partitions can be encrypted using XTS-AES 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. NVS Encryption: Flash Encryption-Based Scheme In this scheme, the keys required for NVS encryption are stored in yet another partition, which is protected using Flash Encryption. Therefore, enabling Flash Encryption becomes a prerequisite for NVS encryption here. 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 using this scheme, 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 the NVS encryption feature. NVS Key Partition An application requiring NVS encryption support (using the Flash Encryption-based scheme) needs to be compiled with a key-partition of the type data and subtype nvs_keys. This partition should be marked as encrypted and its size should be the minimum partition size (4 KB). 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 ESP32-C2 chip itself 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 then writes 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 the 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 # If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error: # "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..." parttool.py --port PORT --esptool-erase-args=force --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys Use a pre-generated NVS 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: 1. Build and flash the partition table idf.py partition-table partition-table-flash 2. 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 # If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error: # "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..." parttool.py --port PORT --esptool-erase-args=force --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 # If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force" to suppress the error: # "Active security features detected, erasing flash is disabled as a safety measure. Use --force to override ..." parttool.py --esptool-erase-args=force --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 the correct key-partition and keys for encryption or 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 step is necessary. When CONFIG_NVS_ENCRYPTION is enabled, the nvs_flash_init() API function internally p