MeshTalos-Client/managed_components/espressif__esp_secure_cert_mgr/tools

esp_secure_cert Configuration Tool

WARNING: This tool is to be used only for development purpose. It does not enable any kind security feature for the protection of the sensitive data in the esp_secure_cert partition.

The script configure_esp_secure_cert.py is used for configuring the ESP platform with PKI credentials into the esp_secure_cert partition which shall reside on its flash storage. It also configures the DS peripheral on the ESP32-S2/ESP32-S3/ESP32-C3 SoC. The steps in the script are based on technical details of certain operations in the Digital Signature calculation, which can be found in the Digital Signature Section of ESP32-S2 TRM.

The script generates a partition named esp_secure_cert on host machine, that contains the parameters required by the DS peripheral. The configure_esp_secure_cert.py utility automatically flashes the partition to the ESP platform which has been connected.

Installation

pip install esp-secure-cert-tool

Configuration

1. Generate root ca and key pair:

openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -x509 -days 3650 -out cacert.pem -subj "/CN=Test CA"

2. Generate client private key:

openssl genrsa -out client.key

3. Generate device cert:

openssl req -out client.csr -key client.key -new
openssl x509 -req -days 365 -in client.csr -CA cacert.pem -CAkey prvtkey.pem  -sha256 -CAcreateserial -out client.crt

Generate esp_secure_cert partition

1. Generating esp_secure_cert partition using CSV file

You can create an esp_secure_cert partition using a CSV file that lists all certificates, keys, and custom data you want to include. The CSV format makes it easy to specify what goes into the partition, including support for advanced features like DS/ECDSA peripherals and custom TLV entries.

For details on the CSV format and examples, see docs/esp_secure_cert_tools/configure_esp_secure_cert_csv.md.

NOTE: Before creating the esp_secure_cert partition on actual hardware, it is recommended to first test your configuration and process using QEMU (the ESP32 emulator). This allows you to validate your CSV, partition generation, and flashing workflow in a safe environment before applying changes to real hardware.

2. Creating esp_secure_cert partition without using CSV:

Following commands can be used to configure the DS peripheral and generate the esp_secure_cert partition. The script can generate cust_flash as well as nvs type of esp_secure_cert partition. Please refer upper level README for more details about type of partitions.

• When configuring the DS peripheral, by default the configuration script does not enable the read protection for the efuse key block in which the DS key is programmed. This is done for allowing flexibility while using the script for development purpose.

• Please remove the --configure_ds argument from these commands if use of the DS peripheral is disabled in the menu config.

WARNING: This is not recommended for production purpose as the private key shall be stored as plaintext.

Generate esp_secure_cert partition of type cust_flash_tlv:

This command shall generate a binary partition containing the PKI credentials stored in the TLV format and flash it at the default offset of 0xD000.

configure_esp_secure_cert.py -p /* Serial port */ --keep_ds_data_on_host --efuse_key_id 1 --ca-cert cacert.pem --device-cert client.crt --private-key client.key --target_chip /* target chip */ --secure_cert_type cust_flash_tlv --configure_ds

• When Flash Encryption is enabled for the device, the option --skip_flash (explained below) can be used to prevent the flashing opereation and only save the esp_secure_cert.bin on the host machine. It can then be flashed on the target using below command:

  esptool.py -p /* Serial Port*/ write_flash 0xD000 esp_secure_cert.bin --encrypt

  More details regarding esptool.py utility can be found here.

  Note: This is only applicable for Development mode of Flash Encryption.

Legacy partition formats:

1. Generate esp_secure_cert partition of type cust_flash:

configure_esp_secure_cert.py -p /* Serial port */ --keep_ds_data_on_host --efuse_key_id 1 --ca-cert cacert.pem --device-cert client.crt --private-key client.key --target_chip /* target chip */ --secure_cert_type cust_flash --configure_ds

2. Generate esp_secure_cert partition of type nvs:

configure_esp_secure_cert.py -p /* Serial port */ --keep_ds_data_on_host --efuse_key_id 1 --ca-cert cacert.pem --device-cert client.crt --private-key client.key --target_chip /* target chip */ --secure_cert_type nvs --configure_ds

Test esp_secure_cert partition using QEMU

QEMU is a free, open-source emulator that lets you run and test software for different hardware platforms on your computer, without needing the actual device. Currently, QEMU supports ESP32, ESP32C3, and ESP32S3. For more information, refer to https://github.com/espressif/esp-toolchain-docs/blob/main/README.md

1. Set the target:

cd examples/esp_secure_cert_app
idf.py set-target <target>

2. Modify the sdkconfig file according to requirement and build the application:

idf.py build

3. Create the qemu_flash.bin and qemu_efuse.bin, which emulate the application and efuse:

cd build
esptool.py --chip esp32c3 merge_bin --fill-flash-size 4MB -o flash_image.bin @flash_args

• For efuse, create efuse, create efuse.hex and copy the following data into it:

000000000000000000000000000000000000000000000000000000000000
00000000000000000c000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000
00000000

• Convert this .hex into .bin using xxd -p

xxd -r -p efuse.hex qemu_efuse.bin

4. Start the qemu as server (Download mode), which listen on TCP port socket://localhost:5555:

qemu-system-riscv32 -nographic \
    -machine esp32c3 \
    -drive file=flash_image.bin,if=mtd,format=raw \
    -global driver=esp32c3.gpio,property=strap_mode,value=0x02 \
    -drive file=qemu_efuse.bin,if=none,format=raw,id=efuse \
    -global driver=nvram.esp32c3.efuse,property=drive,value=efuse \
    -serial tcp::5555,server,nowait

5. Create the esp_secure_cert.bin file:

../../tools/configure_esp_secure_cert.py --esp_secure_cert_csv esp_secure_cert_config_examples.csv --port socket://localhost:5555 --target_chip esp32c3 --skip_flash

• If required then BURN the efuse.

6. Flash the esp_secure_cert.bin on device with TCP port socket://localhost:5555

esptool.py --before no_reset --no-stub --after no_reset --chip esp32c3 -p socket://localhost:5555 write_flash 0xD000 esp_secure_cert_data/esp_secure_cert.bin

7. Exit from the Download Mode and start with Boot Mode:

qemu-system-riscv32 -nographic \
    -machine esp32c3 \
    -drive file=flash_image.bin,if=mtd,format=raw \
    -global driver=esp32c3.gpio,property=strap_mode,value=0x08 \
    -drive file=qemu_efuse.bin,if=none,format=raw,id=efuse \
    -global driver=nvram.esp32c3.efuse,property=drive,value=efuse \

Additional options for the utility

The following options can be provided additional to the main arguments given above.

Set the esp_secure_cert partition offset

By default the esp_secure_cert partition shall be flashed at an offset of 0xD000 by the utility. In order to flash the esp_secure_cert partition at a different offset, the following argument can be provided additionally to the configure_esp_secure_cert.py script.

configure_esp_secure_cert.py  --sec_cert_part_offset /* offset value in hex e.g. 0xD000 */

Skip automatic flashing of esp_secure_cert partition

By default the esp_secure_cert partition shall be flashed automatically at the offset value provided to sec_cert_part_offset argument. In order to stop the flashing process the following argument can be provided additionally to the configure_esp_secure_cert.py script

configure_esp_secure_cert.py --skip_flash

Help section

The additional options supported by the utility can be found at configure_esp_secure_cert.py --help.