diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 7969832d408944..750009aabbeb45 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -478,6 +478,7 @@ EEE eef ef EFR +efuse eg EjQ elftools diff --git a/docs/guides/esp32/secure_cert_partition.md b/docs/guides/esp32/secure_cert_partition.md index a001fb0f030cf2..40d40d92d4432a 100644 --- a/docs/guides/esp32/secure_cert_partition.md +++ b/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/ -``` diff --git a/docs/guides/esp32/setup_idf_chip.md b/docs/guides/esp32/setup_idf_chip.md index 7ee72089194645..ff5ee40c60aed8 100644 --- a/docs/guides/esp32/setup_idf_chip.md +++ b/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 ```