feat(examples): Extend the bootloader_nvs example to support encrypted NVS reads

Author: Harshal5

examples/storage/.build-test-rules.yml

@@ -16,6 +16,15 @@ examples/storage/emmc:
     - if: IDF_TARGET == "esp32s3"
       reason: only support on esp32s3
 
+examples/storage/nvs_bootloader:
+  depends_components:
+    - nvs_flash
+    - nvs_sec_provider
+  disable:
+    - if: CONFIG_NAME == "nvs_enc_flash_enc" and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)
+    - if: CONFIG_NAME == "nvs_enc_hmac" and (SOC_HMAC_SUPPORTED != 1 or (SOC_HMAC_SUPPORTED == 1 and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)))
+      reason: As of now in such cases, we do not have any way to perform AES operations in the bootloader build
+
 examples/storage/nvs_rw_blob:
   depends_components:
     - nvs_flash

examples/storage/nvs_bootloader/README.md

@@ -3,7 +3,9 @@
 
 # NVS Bootloader
 
-The purpose of this example is to show how to use the simplified, read-only API of NVS flash that can be used as a part of bootloader
+The purpose of this example is to show how to use the simplified, read-only API of NVS flash that can be used as a part of bootloader.
+
+A very practical application of being able to access the NVS in the bootloader build would be faster device restoration, where-in the application stores the device's current state/configurations and post a reset it would read the NVS to restore the device's last state, without waiting for application to boot-up.
 
 ## Usage of this example:
 
@@ -123,3 +125,116 @@ Below is a short explanation of files in the project folder.
 The example creates request/response array `read_list[]`, populates it with identifiers of the data to be read.
 Function `nvs_bootloader_read()` tries to find respective data in the partition (here `"nvs"`) and if the data is found, it populates the request/response array with data. For nvs entries either not found or not matching are indicated in response array as well.
 Function `log_nvs_bootloader_read_list()`is used before and after reading from nvs to show request/response data to the console.
+
+# Encrypted NVS Bootloader
+
+This example is extended to support reading encrypted NVS partition when NVS encryption is enabled.
+
+## Usage of this example:
+
+Enable NVS encryption using your preferred scheme. Please find more details regarding the `flash encryption based NVS encryption scheme` and the `HMAC based NVS encryption scheme` in the [NVS encryption documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_encryption.html).
+
+(Note: In case you select the `HMAC based NVS encryption scheme`, make sure that you burn the below mentioned [HMAC key](./main/nvs_enc_hmac_key.bin) in the efuses.)
+
+For generating the encrypted NVS partitions, we shall use [NVS partition generator](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_partition_gen.html#nvs-partition-generator-utility).
+We shall use the [nvs_partition_gen.py](../../../components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py) script for the operations.
+
+Along with the above mentioned file structure, the project folder also contains pre-generated encrypted partitions and the partition corresponding to the selected NVS encryption scheme is flashed along with the build artefacts using the `main/CMakeLists.txt`.
+
+In case the data in `nvs_data.csv` is modified, these encrypted NVS partitions can be re-generated using the following commands:
+
+1. NVS Encryption using the flash encryption scheme
+
+```
+python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_encrypted.bin 0x6000 --inputkey $IDF_PATH/examples/storage/nvs_bootloader/main/encryption_keys.bin
+```
+
+2. NVS Encryption using the HMAC scheme
+
+```
+python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_encrypted_hmac.bin 0x6000 --keygen --key_protect_hmac --kp_hmac_inputkey $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_enc_hmac_key.bin
+```
+
+Build the application using configurations corresponding to the NVS encryption scheme that you have selected:
+
+```
+idf.py set-target <target>
+
+# For NVS encryption using flash encryption scheme
+cat sdkconfig.ci.nvs_enc_flash_enc >> sdkconfig
+
+OR
+
+# For NVS encryption using the HMAC scheme
+cat sdkconfig.ci.nvs_enc_hmac >> sdkconfig
+
+idf.py build
+```
+
+Then flash it and open the monitor with the following command:
+```
+idf.py flash monitor
+```
+
+If everything went well, the console output should contain the same three blocks of log messages that are mentioned above.
+
+### Running the example using QEMU
+
+You could quickly try out this example using QEMU. Refer this [link](https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md#choose-your-target) to know which targets are currently supported in QEMU.
+
+#### Using the NVS encryption's flash encryption scheme
+
+1. Configure the application with the corresponding configurations
+
+```
+idf.py set-target <qemu-supported-targets>
+
+cat sdkconfig.ci.nvs_enc_flash_enc >> sdkconfig
+
+# Disable the below config as it was enabled as a CI related configuration, thus enabling flash encryption during boot-up in QEMU
+echo "CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=n" >> sdkconfig
+
+```
+
+2. Building the app
+
+```
+idf.py build
+```
+
+3. Running the app
+
+```
+idf.py qemu monitor
+```
+
+#### Using the NVS encryption's HMAC scheme
+
+1. Build the application using the corresponding configurations
+
+```
+idf.py set-target <qemu-supported-targets>
+
+cat sdkconfig.ci.nvs_enc_hmac >> sdkconfig
+
+# Disable the below config as it was enabled as a CI related configuration, thus enabling flash encryption during boot-up in QEMU
+echo "CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=n" >> sdkconfig
+```
+
+2. Building the app
+
+```
+idf.py build
+```
+
+3. Burn the related HMAC key in the efuses
+
+```
+idf.py qemu efuse-burn-key BLOCK_KEY0 main/nvs_enc_hmac_key.bin HMAC_UP
+```
+
+4. Running the app
+
+```
+idf.py qemu monitor
+```

examples/storage/nvs_bootloader/bootloader_components/nvs_bootloader_example/CMakeLists.txt

@@ -1,6 +1,6 @@
-idf_component_register( SRCS "src/nvs_bootloader_example.c" "src/nvs_bootloader_example_utils.c"
+idf_component_register(SRCS "src/nvs_bootloader_example.c" "src/nvs_bootloader_example_utils.c"
                         INCLUDE_DIRS "include"
-                        REQUIRES "nvs_flash" )
+                        REQUIRES "nvs_flash" "nvs_sec_provider")
 
 # We need to force GCC to integrate this static library into the
 # bootloader link. Indeed, by default, as the hooks in the bootloader are weak,

examples/storage/nvs_bootloader/bootloader_components/nvs_bootloader_example/src/nvs_bootloader_example.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -8,6 +8,8 @@
 #include "nvs_bootloader.h"
 #include "nvs_bootloader_example_utils.h"
 
+#include "nvs_sec_provider.h"
+
 static const char* TAG = "nvs_bootloader_example";
 
 // Function used to tell the linker to include this file
@@ -21,14 +23,11 @@ void bootloader_before_init(void) {
 }
 
 
-void log_request_call_read_evaluate_output(const char* nvs_partition_label, nvs_bootloader_read_list_t read_list[], const size_t read_list_count) {
-    // log the request structure before the read to see the requested keys and namespaces
-    // with the ESP_ERR_NOT_FINISHED return code we are just telling the log function to show the request data and omit printing the result data
-    // it is useful for debugging the request structure
-    log_nvs_bootloader_read_list(ESP_ERR_NOT_FINISHED, read_list, read_list_count);
-
+void log_request_call_read_evaluate_output(const char* nvs_partition_label, nvs_bootloader_read_list_t read_list[], const size_t read_list_count, const nvs_sec_cfg_t* sec_cfg)
+{
+    esp_err_t ret = ESP_FAIL;
     // call the read function
-    esp_err_t ret = nvs_bootloader_read(nvs_partition_label, read_list_count, read_list);
+    ret = nvs_bootloader_read(nvs_partition_label, read_list_count, read_list);
 
     // Error code ESP_OK means that the read function was successful and individual, per record results are stored in the read_list
     if (ret == ESP_OK) {
@@ -62,10 +61,48 @@ void bootloader_after_init(void) {
     // we are going to read from the default nvs partition labelled 'nvs'
     const char* nvs_partition_label = "nvs";
 
-    #define STR_BUFF_LEN 10+1       // 10 characters + null terminator
-    char str_buff[STR_BUFF_LEN];
+    #define STR_BUFF_LEN_10 10+1       // 10 characters + null terminator
+    #define STR_BUFF_LEN_66 66+1       // 66 characters + null terminator
+    char str_buff_10[STR_BUFF_LEN_10];
+    char str_buff_66[STR_BUFF_LEN_66];
+
+    nvs_sec_cfg_t* sec_cfg = NULL;
+
+#if CONFIG_NVS_ENCRYPTION
+    nvs_sec_cfg_t cfg = {};
+    nvs_sec_scheme_t *sec_scheme_handle = NULL;
+#if CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC
+    nvs_sec_config_hmac_t sec_scheme_cfg = NVS_SEC_PROVIDER_CFG_HMAC_DEFAULT();
+    if (nvs_sec_provider_register_hmac(&sec_scheme_cfg, &sec_scheme_handle) != ESP_OK) {
+        ESP_EARLY_LOGE(TAG, "Registering the HMAC scheme failed");
+        return;
+    }
+#elif CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC
+    nvs_sec_config_flash_enc_t sec_scheme_cfg = NVS_SEC_PROVIDER_CFG_FLASH_ENC_DEFAULT();
+    if (sec_scheme_cfg.nvs_keys_part == NULL) {
+        ESP_EARLY_LOGE(TAG, "partition with subtype \"nvs_keys\" not found");
+    }
+
+    if (nvs_sec_provider_register_flash_enc(&sec_scheme_cfg, &sec_scheme_handle) != ESP_OK) {
+        ESP_EARLY_LOGE(TAG, "Registering the Flash Encryption scheme failed");
+        return;
+    }
+#endif /* CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC */
+
+    if (nvs_bootloader_read_security_cfg(sec_scheme_handle, &cfg) != ESP_OK) {
+        ESP_EARLY_LOGE(TAG, "Reading the NVS security configuration failed");
+        return;
+    }
+
+    if (nvs_bootloader_secure_init(&cfg) != ESP_OK) {
+        ESP_LOGE(TAG, "Secure initialization of NVS failed");
+        return;
+    }
+#endif /* CONFIG_NVS_ENCRYPTION*/
 
     // --- This is the request structure for the read function showing validation errors - function will return ESP_ERR_INVALID_ARG ---
+    ESP_EARLY_LOGI(TAG, "Trying to read the NVS partition by passing invalid arguments");
+
     nvs_bootloader_read_list_t bad_read_list_indicate_problems[] = {
         { .namespace_name = "sunny_day",           .key_name = "u8",                .value_type = NVS_TYPE_U8 },    // ESP_ERR_NVS_NOT_FOUND
                                                                                                                     // this is correct request, not found is expected default result code
@@ -75,37 +112,42 @@ void bootloader_after_init(void) {
                                                                                                                     // too long key name
         { .namespace_name = "clowny_day",          .key_name = "blobeee",           .value_type = NVS_TYPE_BLOB },  // ESP_ERR_INVALID_ARG
                                                                                                                     // not supported data type
-        { .namespace_name = "sunny_day",  .key_name = "string_10_chars",            .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff, .buff_len = 0 } },
+        { .namespace_name = "sunny_day",  .key_name = "string_10_chars",            .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff_10, .buff_len = 0 } },
                                                                                                                     // ESP_ERR_INVALID_SIZE
                                                                                                                     // buffer size is 0
-        { .namespace_name = "sunny_day",  .key_name = "string_10_chars",            .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = NULL, .buff_len = 10 } }
+        { .namespace_name = "sunny_day",  .key_name = "string_66_chars",            .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = NULL, .buff_len = 66 } }
                                                                                                                     // ESP_ERR_INVALID_SIZE
                                                                                                                     // buffer pointer is invalid
     };
 
     size_t bad_read_list_indicate_problems_count = sizeof(bad_read_list_indicate_problems) / sizeof(bad_read_list_indicate_problems[0]);
-    log_request_call_read_evaluate_output(nvs_partition_label, bad_read_list_indicate_problems, bad_read_list_indicate_problems_count);
+    log_request_call_read_evaluate_output(nvs_partition_label, bad_read_list_indicate_problems, bad_read_list_indicate_problems_count, sec_cfg);
 
     // --- This is the request structure for the read function showing runtime errors - function will return ESP_OK ---
     // but some records will have result_code set to ESP_ERR_NVS_NOT_FOUND, ESP_ERR_NVS_TYPE_MISMATCH, ESP_ERR_INVALID_SIZE
+    ESP_EARLY_LOGI(TAG, "Trying to read the NVS partition by expecting incorrect data");
+
     nvs_bootloader_read_list_t good_read_list_bad_results[] = {
         { .namespace_name = "sunny_day",  .key_name = "u8",  .value_type = NVS_TYPE_I8 },   // ESP_ERR_NVS_TYPE_MISMATCH
                                                                                             // data in the partition is of different type (NVS_TYPE_U8)
         { .namespace_name = "sunny_day",  .key_name = "i32_", .value_type = NVS_TYPE_I32 }, // ESP_ERR_NVS_NOT_FOUND
                                                                                             // data in the partition won't be found, because there is a typo in the key name
         { .namespace_name = "clowny_day", .key_name = "i8",  .value_type = NVS_TYPE_I8 },   // ESP_ERR_NVS_NOT_FOUND
                                                                                             // data in the partition won't be found, because there is typo in namespace name
-        { .namespace_name = "sunny_day",  .key_name = "string_10_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff, .buff_len = 2 } },
+        { .namespace_name = "sunny_day",  .key_name = "string_10_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff_10, .buff_len = 2 } },
                                                                                             // ESP_ERR_INVALID_SIZE
                                                                                             // buffer is too small
         { .namespace_name = "sunny_day",  .key_name = "u32", .value_type = NVS_TYPE_U32 },  // ESP_OK
                                                                                             // this value will be read correctly
-        { .namespace_name = "sunny_day",  .key_name = "u32", .value_type = NVS_TYPE_U32 }   // ESP_ERR_NVS_NOT_FOUND
+        { .namespace_name = "sunny_day",  .key_name = "u32", .value_type = NVS_TYPE_U32 },   // ESP_ERR_NVS_NOT_FOUND
                                                                                             // this value won't be read as function doesn't support duplicate readings
+        { .namespace_name = "sunny_day",  .key_name = "string_66_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff_66, .buff_len = 65 } }
+                                                                                            // ESP_ERR_INVALID_SIZE
+                                                                                            // buffer is just small
     };
 
     size_t good_read_list_bad_results_count = sizeof(good_read_list_bad_results) / sizeof(good_read_list_bad_results[0]);
-    log_request_call_read_evaluate_output(nvs_partition_label, good_read_list_bad_results, good_read_list_bad_results_count);
+    log_request_call_read_evaluate_output(nvs_partition_label, good_read_list_bad_results, good_read_list_bad_results_count, sec_cfg);
 
 
     // --- This is the request structure for the read function showing all records found---
@@ -116,16 +158,23 @@ void bootloader_after_init(void) {
     // For NVS_TYPE_STR the value field is a structure with a pointer to the buffer and the buffer length is povided
     // In this case, the buffer is a stack allocated array of 10 characters plus space for the null terminator
 
+    ESP_EARLY_LOGI(TAG, "Trying to read the NVS partition correctly");
+
     nvs_bootloader_read_list_t good_read_list[] = {
         { .namespace_name = "sunny_day",  .key_name = "u8",  .value_type = NVS_TYPE_U8 },
         { .namespace_name = "sunny_day",  .key_name = "i32", .value_type = NVS_TYPE_I32 },
         { .namespace_name = "cloudy_day", .key_name = "i8",  .value_type = NVS_TYPE_I8 },  // mixed in different namespace
         { .namespace_name = "sunny_day",  .key_name = "u16", .value_type = NVS_TYPE_U16 },
-        { .namespace_name = "sunny_day",  .key_name = "string_10_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff, .buff_len = STR_BUFF_LEN } }
+        { .namespace_name = "sunny_day",  .key_name = "string_10_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff_10, .buff_len = STR_BUFF_LEN_10 } },
+        { .namespace_name = "sunny_day",  .key_name = "string_66_chars", .value_type = NVS_TYPE_STR, .value.str_val = { .buff_ptr = str_buff_66, .buff_len = STR_BUFF_LEN_66 } }
     };
 
     size_t good_read_list_count = sizeof(good_read_list) / sizeof(good_read_list[0]);
-    log_request_call_read_evaluate_output(nvs_partition_label, good_read_list, good_read_list_count);
+    log_request_call_read_evaluate_output(nvs_partition_label, good_read_list, good_read_list_count, sec_cfg);
+
+#if CONFIG_NVS_ENCRYPTION
+    nvs_bootloader_secure_deinit();
+#endif /* CONFIG_NVS_ENCRYPTION */
 
     ESP_LOGI(TAG, "Finished bootloader part");
 }

examples/storage/nvs_bootloader/main/CMakeLists.txt

@@ -1,3 +1,13 @@
 idf_component_register(SRCS "bootloader_hooks_example_main.c"
                     INCLUDE_DIRS ".")
-nvs_create_partition_image(nvs ../nvs_data.csv FLASH_IN_PROJECT)
+
+if(NOT CONFIG_NVS_ENCRYPTION)
+    nvs_create_partition_image(nvs ../nvs_data.csv FLASH_IN_PROJECT)
+else()
+    if(CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC)
+        esptool_py_flash_to_partition(flash "nvs_key" ${PROJECT_DIR}/main/encryption_keys.bin)
+        esptool_py_flash_to_partition(flash "nvs" ${PROJECT_DIR}/main/nvs_encrypted.bin)
+    else()  # NVS Encryption using HMAC (CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC)
+        esptool_py_flash_to_partition(flash "nvs" ${PROJECT_DIR}/main/nvs_encrypted_hmac.bin)
+    endif()
+endif()