| .. _flash_encryption_test: |
| |
| Espressif ESP32 Flash Encryption Test |
| ##################################### |
| |
| 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/esp32/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 |