1.. zephyr:code-sample:: esp32-flash-encryption
2   :name: Flash Encryption
3
4   Encrypt/decrypt data stored in flash memory using ESP32 flash encryption feature.
5
6Overview
7********
8
9Flash encryption is intended for encrypting the contents of the ESP32's off-chip flash memory.
10Once this feature is enabled, firmware is flashed as plaintext and then the data is encrypted
11in place on the first boot. As a result, physical readout of flash will not be sufficient to
12recover most flash contents. This is a hardware feature that can be enabled in MCUboot build process
13and is an additional security measure beyond MCUboot existent features.
14
15The following flash encryption modes are available:
16
17* Development Mode
18
19   Recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modification and
20   readout of encrypted flash contents.
21
22* Release Mode
23
24   Recommended for manufacturing and production to prevent physical readout of encrypted flash
25   contents. When release mode is selected..
26
27With flash encryption enabled, the following types of data are encrypted by default:
28
29* Bootloader area
30* Application area
31* Storage area
32
33For more details, check `ESP32 Flash Encryption`_ and `MCUBoot Readme`_.
34
35Software Requirements
36*********************
37
38The following Python modules are required when building flash encryption sample:
39
40* cryptography
41* imgtool>=1.9.0
42
43Setup
44*****
45
46This sample code isn't enough to enable flash encryption as it only consists on displaying
47encrypted/decrypted data. It requires MCUBoot bootloader previously configured to enable the
48feature. Follow the instructions provided at `MCUBoot Readme`_ prior to running this sample.
49
50.. warning::
51  When enabling the Flash Encryption, user can encrypt the content either using a device
52  generated key (remains unknown and unreadable) or a host generated key (owner is responsible
53  for keeping the key private and safe as .bin file). After the flash encryption gets enabled
54  through eFuse burning on the device, all read and write operations are decrypted/encrypted
55  in runtime.
56
57
58Supported SoCs
59**************
60
61The following SoCs are supported by this sample code so far:
62
63* ESP32
64
65Building and Running
66********************
67
68Make sure you have your board connected over USB port.
69
70.. code-block:: console
71
72   west build -b esp32_devkitc_wrover samples/boards/espressif/flash_encryption
73   west flash
74
75Sample Output
76=============
77
78To check the output of this sample, run ``west espressif monitor`` or any other serial
79console program (e.g., minicom, putty, screen, etc).
80This example uses ``west espressif monitor``, which automatically detects the serial
81port at ``/dev/ttyUSB0``:
82
83.. code-block:: console
84
85   $ west espressif monitor
86
87The sample code writes a known buffer into the storage area defined in DTS file.
88Then, it dumps 32-bytes of the same memory area in plaintext mode. The content is encrypted, meaning
89that a reading attack to the off-chip memory is safe. Last step is to perform the
90memory reading using proper spi_flash call, which decrypts the content as expected.
91
92.. code-block:: console
93
94   *** Booting Zephyr OS build v2.7.99-2729-geb08584393d6  ***
95   [00:00:00.453,000] <inf> flash_encryption: Found flash controller FLASH_CTRL.
96
97   [00:00:00.453,000] <inf> flash_encryption: BUFFER CONTENT
98                                           00 01 02 03 04 05 06 07  08 09 0a 0b 0c 0d 0e 0f |........ ........
99                                           10 11 12 13 14 15 16 17  18 19 1a 1b 1c 1d 1e 1f |........ ........
100   [00:00:00.482,000] <inf> flash_encryption: FLASH RAW DATA (Encrypted)
101                                           9a 06 93 76 12 cb 0f 7e  ec c5 12 6f 64 db d1 ff |...v...~ ...od...
102                                           08 e6 be 0c cd 06 6d ad  7d 55 3d 57 bf b7 be 0a |......m. }U=W....
103   [00:00:00.482,000] <inf> flash_encryption: FLASH DECRYPTED DATA
104                                           00 01 02 03 04 05 06 07  08 09 0a 0b 0c 0d 0e 0f |........ ........
105                                           10 11 12 13 14 15 16 17  18 19 1a 1b 1c 1d 1e 1f |........ ........
106
107
108.. _ESP32 Flash Encryption:
109   https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html
110
111.. _MCUBoot Readme:
112   https://docs.mcuboot.com/readme-espressif
113