113 lines
4.2 KiB
ReStructuredText
113 lines
4.2 KiB
ReStructuredText
.. zephyr:code-sample:: esp32-flash-encryption
|
|
:name: Flash Encryption
|
|
|
|
Encrypt/decrypt data stored in flash memory using ESP32 flash encryption feature.
|
|
|
|
Overview
|
|
********
|
|
|
|
Flash encryption is intended for encrypting the contents of the ESP32's off-chip flash memory.
|
|
Once this feature is enabled, firmware is flashed as plaintext and then the data is encrypted
|
|
in place on the first boot. As a result, physical readout of flash will not be sufficient to
|
|
recover most flash contents. This is a hardware feature that can be enabled in MCUboot build process
|
|
and is an additional security measure beyond MCUboot existent features.
|
|
|
|
The following flash encryption modes are available:
|
|
|
|
* Development Mode
|
|
|
|
Recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modification and
|
|
readout of encrypted flash contents.
|
|
|
|
* Release Mode
|
|
|
|
Recommended for manufacturing and production to prevent physical readout of encrypted flash
|
|
contents. When release mode is selected..
|
|
|
|
With flash encryption enabled, the following types of data are encrypted by default:
|
|
|
|
* Bootloader area
|
|
* Application area
|
|
* Storage area
|
|
|
|
For more details, check `ESP32 Flash Encryption`_ and `MCUBoot Readme`_.
|
|
|
|
Software Requirements
|
|
*********************
|
|
|
|
The following Python modules are required when building flash encryption sample:
|
|
|
|
* cryptography
|
|
* imgtool>=1.9.0
|
|
|
|
Setup
|
|
*****
|
|
|
|
This sample code isn't enough to enable flash encryption as it only consists on displaying
|
|
encrypted/decrypted data. It requires MCUBoot bootloader previously configured to enable the
|
|
feature. Follow the instructions provided at `MCUBoot Readme`_ prior to running this sample.
|
|
|
|
.. warning::
|
|
When enabling the Flash Encryption, user can encrypt the content either using a device
|
|
generated key (remains unknown and unreadable) or a host generated key (owner is responsible
|
|
for keeping the key private and safe as .bin file). After the flash encryption gets enabled
|
|
through eFuse burning on the device, all read and write operations are decrypted/encrypted
|
|
in runtime.
|
|
|
|
|
|
Supported SoCs
|
|
**************
|
|
|
|
The following SoCs are supported by this sample code so far:
|
|
|
|
* ESP32
|
|
|
|
Building and Running
|
|
********************
|
|
|
|
Make sure you have your board connected over USB port.
|
|
|
|
.. code-block:: console
|
|
|
|
west build -b esp32_devkitc_wrover samples/boards/espressif/flash_encryption
|
|
west flash
|
|
|
|
Sample Output
|
|
=============
|
|
|
|
To check the output of this sample, run ``west espressif monitor`` or any other serial
|
|
console program (e.g., minicom, putty, screen, etc).
|
|
This example uses ``west espressif monitor``, which automatically detects the serial
|
|
port at ``/dev/ttyUSB0``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ west espressif monitor
|
|
|
|
The sample code writes a known buffer into the storage area defined in DTS file.
|
|
Then, it dumps 32-bytes of the same memory area in plaintext mode. The content is encrypted, meaning
|
|
that a reading attack to the off-chip memory is safe. Last step is to perform the
|
|
memory reading using proper spi_flash call, which decrypts the content as expected.
|
|
|
|
.. code-block:: console
|
|
|
|
*** Booting Zephyr OS build v2.7.99-2729-geb08584393d6 ***
|
|
[00:00:00.453,000] <inf> flash_encryption: Found flash controller FLASH_CTRL.
|
|
|
|
[00:00:00.453,000] <inf> flash_encryption: BUFFER CONTENT
|
|
00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |........ ........
|
|
10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f |........ ........
|
|
[00:00:00.482,000] <inf> flash_encryption: FLASH RAW DATA (Encrypted)
|
|
9a 06 93 76 12 cb 0f 7e ec c5 12 6f 64 db d1 ff |...v...~ ...od...
|
|
08 e6 be 0c cd 06 6d ad 7d 55 3d 57 bf b7 be 0a |......m. }U=W....
|
|
[00:00:00.482,000] <inf> flash_encryption: FLASH DECRYPTED DATA
|
|
00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |........ ........
|
|
10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f |........ ........
|
|
|
|
|
|
.. _ESP32 Flash Encryption:
|
|
https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html
|
|
|
|
.. _MCUBoot Readme:
|
|
https://docs.mcuboot.com/readme-espressif
|