[Bouffalo Lab] Add a script to demonstrate mfd partition generation

wy-hh · wy-hh · commit cd7ab983dbb1 · 2024-08-26T14:19:07.000+08:00
diff --git a/docs/guides/bouffalolab/matter_factory_data.md b/docs/guides/bouffalolab/matter_factory_data.md
@@ -0,0 +1,222 @@
+# Introduction to Matter factory data
+
+Each Matter device should have it own unique factory data manufactured. 
+
+This guide demonstrates what `Bouffalo Lab` provides to support factory data:
+
+- credential factory data protected by hardware security engine
+- reference tool to generate factory data
+- tool/method to program factory data
+
+# Matter factory data
+
+## How to enable
+
+One dedicate flash region allocates for factory data as below which is read-only for firmware.
+
+```toml
+name = "MFD"
+address0 = 0x3FE000
+size0 = 0x1000
+```
+
+To enable matter factory data feature, please append `-mfd` option at end of target name. Take BL616 Wi-Fi Matter Light as example.
+
+```
+./scripts/build/build_examples.py --target bouffalolab-bl616dk-light-wifi-mfd build
+```
+
+## Factory data
+
+This flash region is divided to two parts:
+
+- One is plain text data, such as Vendor ID, Product ID, Serial number and so on.
+
+  > For development/test purpose, all data can put in plain text data.
+
+- Other is cipher text data, such as private key for device attestation data. 
+
+  `Bouffalo Lab` provides hardware security engine to decrypt this part data with **only hardware access** efuse key.
+
+Current supported data
+
+-   DAC certificate and private key
+-   PAI certificate
+-   Certificate declaration
+
+-   Discriminator ID
+-   Pass Code
+-   Spake2p iteration count, salt and verifier
+-   Vendor ID and name
+-   Product ID and name
+-   Product part number and product label
+-   Manufacturing date
+-   Hardware version and version string
+-   Serial Number
+-   Unique identifier
+
+>  Note, it is available to add customer/product own information in factory data, please reference to `bl_mfd.h`/`bl_mfd.c` in SDK and reference generation script [generate_factory_data.py](../../../scripts/tools/bouffalolab/generate_factory_data.py)
+
+# Generate Matter factory data
+
+Script tool [generate_factory_data.py](../../../scripts/tools/bouffalolab/generate_factory_data.py) call `chip-cert` to generate test certificates and verify certificates. 
+
+Please run below command to compile `chip-cert` tool under `connnectedhomeip` repo.
+
+```shell
+./scripts/build/build_examples.py --target linux-x64-chip-cert build
+```
+
+## Command options
+
+- `--cd`, certificate declare
+
+  If not specified, `Chip-Test-CD-Signing-Cert.pem` and `Chip-Test-CD-Signing-Key.pem` will sign a test certificate declare for development and test purpose
+
+- `--pai_cert` and `--pai-key`, PAI certificate and PAI private key
+
+  If not specified,  `Chip-Test-PAI-FFF1-8000-Cert.pem` and `Chip-Test-PAI-FFF1-8000-Key.pem` will be used for development and test purpose.
+
+- `--dac_cert` and `--dac_key`, DAC certificate and DAC private key.
+
+  If not specified, script will use PAI certificate and key specified by`--pai_cert` and `--pai-key` to generate DAC certificate and private key for development and test prupose.
+
+- `--discriminator`, discriminator ID
+
+  If not specified, script will generate for user.
+
+- `--passcode`, passcode
+
+  If not specified, script will generate for user.
+
+- `--spake2p_it` and `--spake2p_salt`
+
+  If not specified, script will generate and calculate verifier for user. 
+
+Please reference to `--help` for more detail.
+
+## Generate with default test certificates
+
+- Run following command to generate all plain text factory data
+
+  ```shell
+  ./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert
+  ```
+
+- Run following command to generate factory data which encrypt private of device attestation data
+
+  ```shell
+  ./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --key <hex string of 16 bytes>
+  ```
+  
+  > An example of hex string of 16 bytes: 12345678123456781234567812345678
+
+After command executes successfully, the output folder will has files as below:
+
+- Test certificate declare file which file name ends with `cd.der`
+
+  If user wants to reuse CD generated before, please specify CD with option `--cd` as below.
+
+  ```shell
+  ./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --cd <cd file>
+  ```
+
+- Test DAC certificate and DAC certificate key which file names ends with `dac_cert.pem` and `dac_key.pem` separately.
+
+- QR code  picture which file name ends with `onboard.png`
+- On board information which file name ends with `onboard.txt`
+- Matter factory data which file name ends with `mfd.bin`. 
+
+## Generate with self-defined PAA/PAI certificates
+
+Self-defined PAA/PAI certificates may use in development and test scenario. But, user should know it has limit to work with real ecosystem.
+
+- Export environment variables in terminal for easy operations
+
+  ```
+  export TEST_CERT_VENDOR_ID=130D # Vendor ID hex string
+  export TEST_CERT_CN=BFLB        # Common Name
+  ```
+
+- Generate PAA certificate and key to `out/cert` folder. 
+
+  ```shell
+  mkdir out/test-cert
+  ./out/linux-x64-chip-cert/chip-cert gen-att-cert --type a --subject-cn "${TEST_CERT_CN} PAA 01" --valid-from "2020-10-15 14:23:43" --lifetime 7305 --out-key out/test-cert/Chip-PAA-Key-${TEST_CERT_VENDOR_ID}.pem --out out/test-cert/Chip-PAA-Cert-${TEST_CERT_VENDOR_ID}.pem --subject-vid ${TEST_CERT_VENDOR_ID}
+  ```
+
+- Convert PAA PEM format file to PAA DER format file
+
+  ```shell
+  ./out/linux-x64-chip-cert/chip-cert convert-cert -d out/test-cert/Chip-PAA-Cert-${TEST_CERT_VENDOR_ID}.pem out/test-cert/Chip-PAA-Cert-${TEST_CERT_VENDOR_ID}.der
+  ```
+
+  > Please save this PAA DER format file which will be used by `chip-tool` during commissioning.
+
+- Generate PAI certificate and key:
+
+  ```shell
+  ./out/linux-x64-chip-cert/chip-cert gen-att-cert --type i --subject-cn "${TEST_CERT_CN} PAI 01" --subject-vid ${TEST_CERT_VENDOR_ID} --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key out/test-cert/Chip-PAA-Key-${TEST_CERT_VENDOR_ID}.pem --ca-cert out/test-cert/Chip-PAA-Cert-${TEST_CERT_VENDOR_ID}.pem --out-key out/test-cert/Chip-PAI-Key-${TEST_CERT_VENDOR_ID}.pem --out out/test-cert/Chip-PAI-Cert-${TEST_CERT_VENDOR_ID}.pem
+  ```
+
+- Generate MFD in plain text data
+
+  ```shell
+  ./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --paa_cert out/test-cert/Chip-PAA-Cert-${TEST_CERT_VENDOR_ID}.pem --paa_key out/test-cert/Chip-PAA-Key-${TEST_CERT_VENDOR_ID}.pem --pai_cert out/test-cert/Chip-PAI-Cert-${TEST_CERT_VENDOR_ID}.pem --pai_key out/test-cert/Chip-PAI-Key-${TEST_CERT_VENDOR_ID}.pem
+  ```
+
+  > Appending `--key <hex string of 16 bytes>` option to enable encrypt private key of attestation device data.
+
+## Generate with self-defined DAC certificate and key
+
+Self-defined DAC certificates may use in development and test scenario. But, user should know it has limit to work with real ecosystem.
+
+- Export environment variables in terminal for easy operations
+
+  ```
+  export TEST_CERT_VENDOR_ID=130D  # Vendor ID hex string
+  export TEST_CERT_PRODUCT_ID=1001 # Vendor ID hex string
+  export TEST_CERT_CN=BFLB         # Common Name
+  ```
+
+- Generate DAC certificate and key
+
+  ```shell
+  out/linux-x64-chip-cert/chip-cert gen-att-cert --type d --subject-cn "${TEST_CERT_CN} PAI 01" --subject-vid ${TEST_CERT_VENDOR_ID} --subject-pid ${TEST_CERT_VENDOR_ID} --valid-from "2020-10-16 14:23:43" --lifetime 5946 --ca-key out/test-cert/Chip-PAI-Key-${TEST_CERT_VENDOR_ID}.pem --ca-cert out/test-cert/Chip-PAI-Cert-${TEST_CERT_VENDOR_ID}.pem --out-key out/test-cert/Chip-DAC-Key-${TEST_CERT_VENDOR_ID}-${TEST_CERT_PRODUCT_ID}.pem --out out/test-cert/Chip-DAC-Cert-${TEST_CERT_VENDOR_ID}-${TEST_CERT_PRODUCT_ID}.pem
+  ```
+
+  > **Note**,  `--valid-from` and `--lifetime` should be in `--valid-from`  and `--lifetime` of PAI certificate.
+
+- Generate MFD in plain text data
+
+  ```shell
+  ./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --pai_cert out/test-cert/Chip-PAI-Cert-${TEST_CERT_VENDOR_ID}.pem --dac_cert out/test-cert/Chip-DAC-Cert-${TEST_CERT_VENDOR_ID}-${TEST_CERT_PRODUCT_ID}.pem --dac_key out/test-cert/Chip-DAC-Key-${TEST_CERT_VENDOR_ID}-${TEST_CERT_PRODUCT_ID}.pem
+  ```
+
+  > Appending `--key <hex string of 16 bytes>` option to enable encrypt private key of attestation device data.
+
+
+# Program factory data
+
+After each target built successfully, a flash programming python script will be generated under out folder.
+
+Take BL616 Wi-Fi Matter Light as example, `chip-bl616-lighting-example.flash.py` is using to program firmware, and also for factory data and factory decryption key.
+
+  ```shell
+  /out/bouffalolab-bl616dk-light-wifi-mfd/chip-bl616-lighting-example.flash.py --port <serial port>  --mfd out/test-cert/<mfd bin file>
+  ```
+
+  > If mfd file has cipher text data, please append `--key <hex string of 16 bytes>` option to program to this key to efuse.
+
+- Limits on BL IOT SDK
+
+  If developer would like to program MFD with all plain text data, option `--key <hex string of 16 bytes>` needs pass to script, otherwise, flash tool will raise an error. And SoC BL602, BL702 and BL702L use BL IOT SDK for Matter Application.
+
+Please free contact to `Bouffalo Lab` for DAC provider service and higher security solution, such as SoC inside certificate requesting. 
+
+ 
+
+  
+
+  
+
diff --git a/examples/lighting-app/bouffalolab/README.md b/examples/lighting-app/bouffalolab/README.md
@@ -99,6 +99,7 @@ The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`.
 
     ```
     ./scripts/build/build_examples.py --target bouffalolab-bl602dk-light build
+    ./scripts/build/build_examples.py --target bouffalolab-bl616dk-light-wifi build
     ./scripts/build/build_examples.py --target bouffalolab-bl704ldk-light build
     ./scripts/build/build_examples.py --target bouffalolab-bl706dk-light build
     ```
@@ -113,23 +114,23 @@ The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`.
 
 ### Build options with build_examples.py
 
--   `-wifi`, to specify that connectivity Wi-Fi is enabled for Matter
-    application.
+-   `-wifi`, specifies to use Wi-Fi for Matter application.
 
-    -   BL602 uses `-wifi` by default
-    -   BL702 needs specify to use BL706 + BL602 for Wi-Fi connectivity.
+    -   BL602 uses Wi-Fi by defualt. `-wifi` could be elided.
+    -   BL702 needs it to specify to use BL706 + BL602 for Wi-Fi.
 
--   `-thread`, to specify that connectivity Thread is enabled for Matter
+-   `-thread`, specifies to use Thread for Matter
     application.
 
-    -   BL70X uses `-thread` by default.
+    -   BL70X uses Thread by defualt. `-thread` could be elided.
 
--   `-ethernet`, to specify that connectivity Ethernet is enabled for Matte
-    application.
+-   `-ethernet`, specifies to use Ethernet for Matter application.
 
-    -   BL706 needs specify to use Ethernet connectivity.
+    -   BL706 needs it to specify to use Ethernet.
 
--   `-easyflash`, to specify that `easyflash` is used for flash storage access.
+-   `-littlefs`, specifies to use littlefs for flash access.
+-   `-easyflash`, specifies to use `easyflash` for flash access.
+    -   for platform BL602/BL70X, it is necessary to specify one of `-easyflash` and `-littlefs`.
 -   `-mfd`, enable Matter factory data feature, which load factory data from
     `MFD` partition
 -   `-shell`, enable command line
@@ -175,9 +176,10 @@ The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`.
 
 
             ```shell
-            ./out/bouffalolab-bl602dk-light/chip-bl602-lighting-example.flash.py --port /dev/ttyACM0
-            ./out/bouffalolab-bl704ldk-light/chip-bl702l-lighting-example.flash.py --port /dev/ttyACM0
-            ./out/bouffalolab-bl706dk-light/chip-bl702-lighting-example.flash.py --port /dev/ttyACM0
+          ./out/bouffalolab-bl602dk-light-littlefs/chip-bl602-lighting-example.flash.py --port /dev/ttyACM0
+          ./out/bouffalolab-bl616dk-light-wifi/chip-bl616dk-lighting-example.flash.py --port /dev/ttyACM0
+          ./out/bouffalolab-bl704ldk-light-littlefs/chip-bl702l-lighting-example.flash.py --port /dev/ttyACM0
+          ./out/bouffalolab-bl706dk-light-littlefs/chip-bl702-lighting-example.flash.py --port /dev/ttyACM0
             ```
 
         -   To wipe out flash and download image, please append `--erase`
diff --git a/scripts/tools/bouffalolab/generate_factory_data.py b/scripts/tools/bouffalolab/generate_factory_data.py
