[ESP32] Documentation guides for using secure cert with ECDSA peripheral (#27456)

* [ESP32] Documentation guides for using secure cert with ECDSA peripheral

* Added efuse to .wordlist

Author: shubhamdp

.github/.wordlist.txt

@@ -478,6 +478,7 @@ EEE
 eef
 ef
 EFR
+efuse
 eg
 EjQ
 elftools

docs/guides/esp32/secure_cert_partition.md

@@ -2,29 +2,29 @@
 
 ## 1.1 ESP Secure Cert Partition
 
--   When a device is pre-provisioned, the PKI credentials are generated for the
-    device and stored in a partition named esp_secure_cert.
--   In the Matter Pre-Provisioning service, the Matter DAC certificate is
-    pre-flashed in esp_secure_cert partition.
--   The ESP32SecureCertDACProvider reads the PKI credentials from
-    esp_secure_cert_partition.
--   The DAC,PAI and private key are read from the esp_secure_cert_partition, but
-    the certificate declaration is read from the factory data partition.
-    Therefore, we need to also generate a factory partition besides
-    esp_secure_cert_partition.
--   The esp_secure_cert partition can be generated on host with help of
-    configure_esp_secure_cert.py utility.
--   The use of esp_secure_cert_partition is demonstrated in lighting-app.
+-   When a device is pre-provisioned, PKI credentials are generated for the
+    device and stored in esp_secure_cert partition.
+-   In the Matter Pre-Provisioning service, the Matter attestation information
+    is pre-flashed into the esp_secure_cert partition.
+-   The ESP32SecureCertDACProvider reads the attestation information from the
+    esp_secure_cert partition.
+-   The DAC and PAI are read from the esp_secure_cert partition, while the
+    certification declaration is read from the factory partition.
+-   The usage of the esp_secure_cert partition is demonstrated in the
+    lighting-app.
+
+-   During the development phase, the esp_secure_cert partition can be generated
+    on the host with the help of the configure_esp_secure_cert.py utility.
+-   The steps below demonstrate how to generate certificates and the respective
+    partitions to be used during the development phase.
 
 ## 1.2 Prerequisites:
 
 To generate the esp_secure_cert_partition and the factory_data_partition, we
-need the DAC and PAI certificate as well as the private key(DAC key) in .der
-format. The factory_data_provider in addition requires the certificate
-declaration in .der format. The generation of the required certificates and keys
-is mentioned in the steps given below.
+need the DER encoded DAC, PAI certificate, DAC private key, and certification
+declaration.
 
-### 1.2.1 Build certification generation tool:
+### 1.2.1 Build chip-cert:
 
 Run the commands below:
 
@@ -41,19 +41,27 @@ At /path/to/connectedhomeip/out/host run the below commands.
 ### 1.2.2 Generating Certification Declaration
 
 ```
-./chip-cert gen-cd -K ../../credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem -C ../../credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem -O esp_dac_fff1_8000.der -f 1 -V 0xfff1 -p 0x8000 -d 0x0016 -c "CSA00000SWC00000-01" -l 0 -i 0 -n 1 -t 0
+./chip-cert gen-cd -K ../../credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \
+    -C ../../credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \
+    -O esp_dac_fff1_8000.der -f 1 \
+    -V 0xfff1 -p 0x8000 -d 0x0016 -c "CSA00000SWC00000-01" -l 0 -i 0 -n 1 -t 0
 ```
 
 ### 1.2.3 Generating PAI
 
 ```
-./chip-cert gen-att-cert -t i -c "ESP TEST PAI" -V 0xfff1 -P 0x8000 -C ../../credentials/development/attestation/Chip-Development-PAA-Cert.pem -K ../../credentials/development/attestation/Chip-Development-PAA-Key.pem -o Esp-Development-PAI-Cert.pem -O Esp-Development-PAI-Key.pem -l 4294967295
+./chip-cert gen-att-cert -t i -c "ESP TEST PAI" -V 0xfff1 -P 0x8000 \
+    -C ../../credentials/development/attestation/Chip-Development-PAA-Cert.pem \
+    -K ../../credentials/development/attestation/Chip-Development-PAA-Key.pem \
+    -o Esp-Development-PAI-Cert.pem -O Esp-Development-PAI-Key.pem -l 4294967295
 ```
 
 ### 1.2.4 Generating DAC
 
 ```
-./chip-cert gen-att-cert -t d -c "ESP TEST DAC 01" -V 0xfff1 -P 0x8000 -C Esp-Development-PAI-Cert.pem -K Esp-Development-PAI-Key.pem -o Esp-Development-DAC-01.pem -O Esp-Development-DAC-Key-01.pem -l 4294967295
+./chip-cert gen-att-cert -t d -c "ESP TEST DAC 01" -V 0xfff1 -P 0x8000 \
+    -C Esp-Development-PAI-Cert.pem -K Esp-Development-PAI-Key.pem \
+    -o Esp-Development-DAC-01.pem -O Esp-Development-DAC-Key-01.pem -l 4294967295
 ```
 
 ### 1.2.5 Change format for the certificates and key (.pem to .der format)
@@ -67,30 +75,58 @@ openssl ec -in Esp-Development-DAC-Key-01.pem -out Esp-Development-DAC-Key-01.de
 -   Convert DAC and PAI cert from .pem to .der format
 
 ```
-openssl x509 -in Esp-Development-DAC-01.pem -out Esp-Development-DAC-01.der-inform pem -outform der
+openssl x509 -in Esp-Development-DAC-01.pem -out Esp-Development-DAC-01.der -inform pem -outform der
 openssl x509 -in Esp-Development-PAI-Cert.pem -out Esp-Development-PAI-Cert.der -inform pem -outform der
 ```
 
 The certificates in the steps 1.2 will be generated at
 /path/to/connectedhomeip/out/host.For steps 1.3 and 1.4 go to
-connectedhomeip/scripts/tools , set IDF_PATH.
+connectedhomeip/scripts/tools, and set IDF_PATH.
 
 ## 1.3 Generating esp_secure_cert_partition
 
 To generate the esp_secure_cert_partition install esp-secure-cert-tool using
+below command. Please use the tool with version >= 1.0.1
 
 ```
 pip install esp-secure-cert-tool
 ```
 
-Example command to generate a esp_secure_cert_partition
+Please use esp-secure-cert-tool with version >= esp-secure-cert-too
+
+Espressif have SoCs with and without ECDSA peripheral, so there is a bit
+different flow for both. Currently only ESP32H2 has the ECDSA Peripheral.
+
+### 1.3.2 For SoCs without ECDSA Peripheral (Except ESP32H2)
+
+The following command generates the secure cert partition and flashes it to the
+connected device. Additionally, it preserves the generated partition on the
+host, allowing it to be flashed later if the entire flash is erased.
 
 ```
-configure_esp_secure_cert.py --private-key path/to/dac-key \
---device-cert path/to/dac-cert \
---ca-cert path/to/pai-cert \
---target_chip esp32c3 \
---port /dev/ttyUSB0 -- skip_flash
+configure_esp_secure_cert.py --private-key Esp-Development-DAC-Key-01.der \
+    --device-cert Esp-Development-DAC-01.der \
+    --ca-cert Esp-Development-PAI-Cert.der \
+    --target_chip esp32c3 \
+    --keep_ds_data_on_host \
+    --port /dev/ttyUSB0
+```
+
+### 1.3.1 For SoCs with ECDSA Peripheral (ESP32H2)
+
+The following command generates the secure cert partition, flashes it onto the
+connected device, burns the efuse block with the private key, and preserves the
+generated partition on the host for future use in case of a complete flash
+erase.
+
+```
+configure_esp_secure_cert.py --private-key Esp-Development-DAC-Key-01.der \
+    --priv_key_algo ECDSA 256 --efuse_key_id 2 --configure_ds \
+    --device-cert Esp-Development-DAC-01.der \
+    --ca-cert Esp-Development-PAI-Cert.der \
+    --target_chip esp32h2 \
+    --keep_ds_data_on_host \
+    --port /dev/ttyUSB0
 ```
 
 Refer
@@ -103,13 +139,10 @@ Example command to generate a factory_data_partition
 
 ```
 ./generate_esp32_chip_factory_bin.py -d 3434 -p 99663300 \
-                                    --product-name ESP-lighting-app --product-id 0x8000 \
-                                    --vendor-name Test-vendor --vendor-id 0xFFF1 \
-                                    --hw-ver 1 --hw-ver-str DevKit \
-                                    --dac-cert path/to/dac-cert \
-                                    --dac-key path/to/dac-key \
-                                    --pai-cert path/to/pai-cert \
-                                    --cd path/to/certificate-declaration
+    --product-name ESP-lighting-app --product-id 0x8000 \
+    --vendor-name Test-vendor --vendor-id 0xFFF1 \
+    --hw-ver 1 --hw-ver-str DevKit \
+    --cd esp_dac_fff1_8000.der
 ```
 
 Refer
@@ -118,6 +151,8 @@ to generate a factory_data_partition.
 
 ## 1.5 Build the firmware with below configuration options
 
+-   For SoCs without ECDSA Peripheral (Except ESP32H2)
+
 ```
 # Disable the DS Peripheral support
 CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=n
@@ -129,6 +164,19 @@ CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER=y
 CONFIG_CHIP_FACTORY_NAMESPACE_PARTITION_LABEL="fctry"
 ```
 
+-   For SoCs with ECDSA Peripheral (ESP32H2)
+
+```
+# Enable the DS Peripheral support
+CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=y
+# Use DAC Provider implementation which reads attestation data from secure cert partition
+CONFIG_SEC_CERT_DAC_PROVIDER=y
+# Enable some options which reads CD and other basic info from the factory partition
+CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER=y
+CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER=y
+CONFIG_CHIP_FACTORY_NAMESPACE_PARTITION_LABEL="fctry"
+```
+
 In order to use the esp_secure_cert_partition, in addition to enabling the above
 config options, you should also have the esp_secure_cert_partition and factory
 partition in your app. For reference, refer to partitions.csv file of
@@ -158,26 +206,3 @@ esptool.py -p (PORT) write_flash 0xd000 path/to/secure_cert_partition.bin
 ```
 esptool.py -p (PORT) write_flash 0x3E0000 path/to/factory_partition.bin
 ```
-
-### Monitor
-
-```
-idf.py monitor
-```
-
-Please flash the above mentioned partitions by looking into the addresses in
-partitions.csv.The above commands are for example purpose.
-
-## 1.6 Test commissioning using chip-tool
-
-Run the following command from host to commission the device.
-
-```
-./chip-tool pairing ble-wifi 1234 my_SSID my_PASSPHRASE my_PASSCODE my_DISCRIMINATOR --paa-trust-store-path /path/to/PAA-Certificates/
-```
-
-For example:
-
-```
-./chip-tool pairing ble-wifi 0x7283 my_SSID my_PASSPHRASE 99663300 3434 --paa-trust-store-path /path/to/connectedhomeip/credentials/development/attestation/
-```

docs/guides/esp32/setup_idf_chip.md

@@ -40,11 +40,11 @@ step.
     ```
 
 -   For ESP32C6 & ESP32H2, please use commit
-    [47852846d3](https://github.com/espressif/esp-idf/tree/47852846d3).
+    [ea5e0ff](https://github.com/espressif/esp-idf/tree/ea5e0ff).
 
     ```
     $ cd esp-idf
-    $ git checkout 47852846d3
+    $ git checkout ea5e0ff
     $ git submodule update --init
     $ ./install.sh
     ```