README.md
1| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
2| ----------------- | ----- | -------- | -------- | -------- |
3
4# Secure Boot
5
6The example checks if the secure boot feature is enabled/disabled and if enabled prints the secure boot version (Version 1 / Version 2) and FLASH_CRYPT_CNT eFuse value.
7
8## How to use example
9
10### Hardware Required
11
12Any of the following ESP module:
13* ESP32 (supports Secure Boot V1)
14* ESP32-ECO3 (supports Secure Boot V2 & Secure Boot V1)
15* ESP32S2 (supports Secure Boot V2)
16* ESP32C3-ECO3 (supports Secure Boot V2)
17* ESP32S3 (supports Secure Boot V2)
18
19It is recommended to use Secure Boot V2 from ESP32-ECO3 onwards.
20
21### Configure the project
22
23```
24idf.py menuconfig
25```
26
27* Set serial port under Serial Flasher Options.
28
29* Enable the `Enable hardware Secure Boot` under Security Features. Default version for ESP32 is Secure Boot V1. The chip revision should be changed to revision 3(ESP32- ECO3) to view the Secure Boot V2 option.
30
31* To change the chip revision, set "Component Config" -> "ESP32- Specific"->"Minimum Supported ESP32 Revision" to Rev 3. Now, set Secure Boot V2 option can now be enabled under "Enable hardware Secure Boot in bootloader" -> "Secure Boot Version".
32
33* Specify the apt secure boot signing key path. If not present generate one using `python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_signing_key --version {VERSION} secure_boot_signing_key.pem`
34
35* Ensure Bootloader log verbosity is Info under Bootloader config.
36
37* Select Single factory app, no OTA under Partition Table options. Change the partition table offset to 0xb000 from 0x8000 since after enabling secure boot the size of bootloader is increased.
38
39### Build and Flash
40
41- The below steps can be used in any application to enable secure boot.
42
43- Secure Boot is an irreversible operation, please read the Secure Boot section in ESP-IDF Programming Manual.
44
45- Secure boot will be enabled on building the project after enabling hardware secure boot feature in _Security features_ in menuconfig and flashing it to the board FOR THE FIRST TIME.
46
47- The bootloader will not be automatically flashed when secure boot is enabled. Running `idf.py bootloader` will print a command to flash the bootloader on the ESP32. Run this command manually to flash the bootloader.
48
49Run following command to program the partition table and application on the ESP32 and monitor the output:
50```
51idf.py -p PORT flash monitor
52```
53
54(To exit the serial monitor, type ``Ctrl-]``.)
55
56See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
57
58- On subsequent boots, the secure boot hardware will verify the software bootloader has not changed and the software bootloader will verify the signed app image (using the validated public key portion of its appended signature block).
59
60## Example Output
61
62## Troubleshooting
63
64---
65
66# Secure Boot tests (For internal use only)
67
68Purpose of the example test cases (`example_test.py`) is to test the secure boot implementation and detect if it is broken. It consists of positive and negative test cases.
69
70### Hardware required
71
72* FPGA setup with ESP32C3/ESP32S3 image
73
74* COM port for programming and export it as ESPPORT
75 e.g `export ESPPORT=/dev/ttyUSB0`
76
77* Use another COM port for resetting efuses and connect its DTR pin to efuse reset pin on the FPGA board. Export it as EFUSEPORT
78 e.g `export EFUSEPORT=/dev/ttyUSB1`
79
80### Configure the project
81
82```
83export IDF_ENV_FPGA=1
84
85idf.py set-target esp32c3 #(or esp32s3)
86
87idf.py menuconfig
88```
89
90Under `Security features`
91
92- Enable the `Enable hardware Secure Boot`
93
94- Set the secure boot signing key ("test_rsa_3072_key.pem")
95
96- Set UART ROM download mode to ENABLED (Required for the script to read the EFUSE)
97
98- Install and export TTFW requirements
99```
100python -m pip install -r $IDF_PATH/tools/ci/python_packages/ttfw_idf/requirements.txt
101
102export PYTHONPATH="$IDF_PATH/tools:$IDF_PATH/tools/ci/python_packages"
103```
104
105### Build and test
106
107- Build the example
108```
109idf.py build
110```
111
112- Run the example test
113```
114python example_test.py
115```
116
