![]() |
||
---|---|---|
.. | ||
main | ||
CMakeLists.txt | ||
README.md | ||
partitions_example.csv | ||
pytest_nvs_encr_hmac.py | ||
sdkconfig.ci.nvs_encr_hmac | ||
sdkconfig.defaults |
README.md
Supported Targets | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-S2 | ESP32-S3 |
---|
NVS Encryption with HMAC-based encryption key protection scheme
Overview
This example demonstrates NVS encryption using the HMAC peripheral, wherein the encryption keys are derived from the HMAC key burnt in eFuse. Since the derivation of the encryption keys occurs at runtime, they are not stored in the flash. Thus, this feature does not require a separate nvs_keys
partition and also does not require flash encryption enabled.
How to use the example
Hardware Required
This example can be executed on any development board with a supported Espressif SOC chip - possessing a built-in HMAC peripheral (see Supported Targets
table above).
Configure the project
Before the project configuration and build, be sure to set the correct chip target using idf.py set-target <chip_name>
.
Open the project configuration menu (idf.py menuconfig
).
Configure the eFuse key ID storing the HMAC key
-
Set the eFuse key ID storing the HMAC key at
Component config → NVS Security Provider → eFuse key ID storing the HMAC key
. The HMAC key stored at this key block will be used to generate the encryption keys for the default NVS partition (nvs
), initialised withnvs_flash_init()
. Note that the example will fail to build without setting this config option to the correct value (the default value is out of range). -
Users can program their own HMAC key in the configured block before running the example - refer below snippet. The example checks if the configured block is empty or already programmed with an HMAC key - if empty, a new key is generated at runtime and stored in the block, or else the provided key is used. While burning the key prior to flashing the app, please make sure that the config value is set to the eFuse block holding the HMAC key.
# Burning the HMAC-key in eFuse block 0 - key ID 0
espefuse.py -p PORT burn_key BLOCK_KEY0 hmac_key_file.bin HMAC_UP
Build and Flash
Build the project and flash it to the board, then run the monitor tool to view the serial output:
idf.py -p PORT flash monitor
(To exit the serial monitor, type Ctrl-]
.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
Example Output
I (300) nvs_sec_provider: NVS Encryption - Registering HMAC-based scheme...
I (308) app_start: Starting scheduler on CPU0
I (313) main_task: Started on CPU0
I (313) main_task: Calling app_main()
I (313) example: Initialising the default NVS partition
I (333) nvs: NVS partition "nvs" is encrypted.
I (603) example: Initialising the custom NVS partition
I (613) example: NVS partition "custom_nvs" is encrypted.
I (623) example: Key: u8_key | Val: 255
I (623) example: Key: i8_key | Val: -128
I (623) example: Key: u16_key | Val: 65535
I (633) example: Key: u32_key | Val: 4294967295
I (633) example: Key: i32_key | Val: -2147483648
I (643) example: Key: str_key | Val: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Fusce quis risus justo.
Suspendisse egestas in nisi sit amet auctor.
Pellentesque rhoncus dictum sodales.
In justo erat, viverra at interdum eget, interdum vel dui.
I (663) custom_nvs: 0x3ffc5f5c fe ff ff ff 00 00 00 00 fe ff ff ff ff ff ff ff |................|
I (673) custom_nvs: 0x3ffc5f6c ff ff ff ff ff ff ff ff ff ff ff ff 84 2d ba b9 |.............-..|
I (683) custom_nvs: 0x3ffc5f7c aa aa aa fa ff ff ff ff ff ff ff ff ff ff ff ff |................|
I (693) custom_nvs: 0x3ffc5f8c ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
I (703) custom_nvs: 0x3ffc5f9c ca 8b c3 bb 2d c2 33 d6 6b d4 a7 3d 31 0e 9c 36 |....-.3.k..=1..6|
I (713) custom_nvs: 0x3ffc5fac 39 7f bc d4 5c 6d f8 98 de 0a 90 50 21 23 ff 04 |9...\m.....P!#..|
I (723) custom_nvs: 0x3ffc5fbc ce f9 23 6f 2c d6 07 08 2d 0e d2 f2 a5 af 5a 2e |..#o,...-.....Z.|
I (733) custom_nvs: 0x3ffc5fcc c9 61 bd fc 96 fc 12 87 1b 8c cb fb 51 2c ed a2 |.a..........Q,..|
...
...
...
I (1133) custom_nvs: 0x3ffc624c ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
I (1143) main_task: Returned from app_main()