Skip to content

Commit fe7b23e

Browse files
wy-hhwy-hh
committed
fix restyle
1 parent cd7ab98 commit fe7b23e

File tree

3 files changed

+160
-139
lines changed

3 files changed

+160
-139
lines changed

‎docs/guides/bouffalolab/matter_factory_data.md

+128-103
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,28 @@
11
# Introduction to Matter factory data
22

3-
Each Matter device should have it own unique factory data manufactured.
3+
Each Matter device should have it own unique factory data manufactured.
44

55
This guide demonstrates what `Bouffalo Lab` provides to support factory data:
66

7-
- credential factory data protected by hardware security engine
8-
- reference tool to generate factory data
9-
- tool/method to program factory data
7+
- credential factory data protected by hardware security engine
8+
- reference tool to generate factory data
9+
- tool/method to program factory data
1010

1111
# Matter factory data
1212

1313
## How to enable
1414

15-
One dedicate flash region allocates for factory data as below which is read-only for firmware.
15+
One dedicate flash region allocates for factory data as below which is read-only
16+
for firmware.
1617

1718
```toml
1819
name = "MFD"
1920
address0 = 0x3FE000
2021
size0 = 0x1000
2122
```
2223

23-
To enable matter factory data feature, please append `-mfd` option at end of target name. Take BL616 Wi-Fi Matter Light as example.
24+
To enable matter factory data feature, please append `-mfd` option at end of
25+
target name. Take BL616 Wi-Fi Matter Light as example.
2426

2527
```
2628
./scripts/build/build_examples.py --target bouffalolab-bl616dk-light-wifi-mfd build
@@ -30,13 +32,15 @@ To enable matter factory data feature, please append `-mfd` option at end of tar
3032

3133
This flash region is divided to two parts:
3234

33-
- One is plain text data, such as Vendor ID, Product ID, Serial number and so on.
35+
- One is plain text data, such as Vendor ID, Product ID, Serial number and so
36+
on.
3437

35-
> For development/test purpose, all data can put in plain text data.
38+
> For development/test purpose, all data can put in plain text data.
3639
37-
- Other is cipher text data, such as private key for device attestation data.
40+
- Other is cipher text data, such as private key for device attestation data.
3841

39-
`Bouffalo Lab` provides hardware security engine to decrypt this part data with **only hardware access** efuse key.
42+
`Bouffalo Lab` provides hardware security engine to decrypt this part data
43+
with **only hardware access** efuse key.
4044

4145
Current supported data
4246

@@ -55,168 +59,189 @@ Current supported data
5559
- Serial Number
5660
- Unique identifier
5761

58-
> 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)
62+
> Note, it is available to add customer/product own information in factory data,
63+
> please reference to `bl_mfd.h`/`bl_mfd.c` in SDK and reference generation
64+
> script
65+
> [generate_factory_data.py](../../../scripts/tools/bouffalolab/generate_factory_data.py)
5966
6067
# Generate Matter factory data
6168

62-
Script tool [generate_factory_data.py](../../../scripts/tools/bouffalolab/generate_factory_data.py) call `chip-cert` to generate test certificates and verify certificates.
69+
Script tool
70+
[generate_factory_data.py](../../../scripts/tools/bouffalolab/generate_factory_data.py)
71+
call `chip-cert` to generate test certificates and verify certificates.
6372

64-
Please run below command to compile `chip-cert` tool under `connnectedhomeip` repo.
73+
Please run below command to compile `chip-cert` tool under `connnectedhomeip`
74+
repo.
6575

6676
```shell
6777
./scripts/build/build_examples.py --target linux-x64-chip-cert build
6878
```
6979

7080
## Command options
7181

72-
- `--cd`, certificate declare
82+
- `--cd`, certificate declare
7383

74-
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
84+
If not specified, `Chip-Test-CD-Signing-Cert.pem` and
85+
`Chip-Test-CD-Signing-Key.pem` will sign a test certificate declare for
86+
development and test purpose
7587

76-
- `--pai_cert` and `--pai-key`, PAI certificate and PAI private key
88+
- `--pai_cert` and `--pai-key`, PAI certificate and PAI private key
7789

78-
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.
90+
If not specified, `Chip-Test-PAI-FFF1-8000-Cert.pem` and
91+
`Chip-Test-PAI-FFF1-8000-Key.pem` will be used for development and test
92+
purpose.
7993

80-
- `--dac_cert` and `--dac_key`, DAC certificate and DAC private key.
94+
- `--dac_cert` and `--dac_key`, DAC certificate and DAC private key.
8195

82-
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.
96+
If not specified, script will use PAI certificate and key specified
97+
by`--pai_cert` and `--pai-key` to generate DAC certificate and private key
98+
for development and test prupose.
8399

84-
- `--discriminator`, discriminator ID
100+
- `--discriminator`, discriminator ID
85101

86-
If not specified, script will generate for user.
102+
If not specified, script will generate for user.
87103

88-
- `--passcode`, passcode
104+
- `--passcode`, passcode
89105

90-
If not specified, script will generate for user.
106+
If not specified, script will generate for user.
91107

92-
- `--spake2p_it` and `--spake2p_salt`
108+
- `--spake2p_it` and `--spake2p_salt`
93109

94-
If not specified, script will generate and calculate verifier for user.
110+
If not specified, script will generate and calculate verifier for user.
95111

96112
Please reference to `--help` for more detail.
97113

98114
## Generate with default test certificates
99115

100-
- Run following command to generate all plain text factory data
116+
- Run following command to generate all plain text factory data
101117

102-
```shell
103-
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert
104-
```
118+
```shell
119+
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert
120+
```
105121

106-
- Run following command to generate factory data which encrypt private of device attestation data
122+
- Run following command to generate factory data which encrypt private of
123+
device attestation data
107124

108-
```shell
109-
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --key <hex string of 16 bytes>
110-
```
111-
112-
> An example of hex string of 16 bytes: 12345678123456781234567812345678
125+
```shell
126+
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --key <hex string of 16 bytes>
127+
```
128+
129+
> An example of hex string of 16 bytes: 12345678123456781234567812345678
113130

114131
After command executes successfully, the output folder will has files as below:
115132

116-
- Test certificate declare file which file name ends with `cd.der`
133+
- Test certificate declare file which file name ends with `cd.der`
117134

118-
If user wants to reuse CD generated before, please specify CD with option `--cd` as below.
135+
If user wants to reuse CD generated before, please specify CD with option
136+
`--cd` as below.
119137

120-
```shell
121-
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --cd <cd file>
122-
```
138+
```shell
139+
./scripts/tools/bouffalolab/generate_factory_data.py --output out/test-cert --cd <cd file>
140+
```
123141

124-
- Test DAC certificate and DAC certificate key which file names ends with `dac_cert.pem` and `dac_key.pem` separately.
142+
- Test DAC certificate and DAC certificate key which file names ends with
143+
`dac_cert.pem` and `dac_key.pem` separately.
125144

126-
- QR code picture which file name ends with `onboard.png`
127-
- On board information which file name ends with `onboard.txt`
128-
- Matter factory data which file name ends with `mfd.bin`.
145+
- QR code picture which file name ends with `onboard.png`
146+
- On board information which file name ends with `onboard.txt`
147+
- Matter factory data which file name ends with `mfd.bin`.
129148

130149
## Generate with self-defined PAA/PAI certificates
131150

132-
Self-defined PAA/PAI certificates may use in development and test scenario. But, user should know it has limit to work with real ecosystem.
151+
Self-defined PAA/PAI certificates may use in development and test scenario. But,
152+
user should know it has limit to work with real ecosystem.
133153

134-
- Export environment variables in terminal for easy operations
154+
- Export environment variables in terminal for easy operations
135155

136-
```
137-
export TEST_CERT_VENDOR_ID=130D # Vendor ID hex string
138-
export TEST_CERT_CN=BFLB # Common Name
139-
```
156+
```
157+
export TEST_CERT_VENDOR_ID=130D # Vendor ID hex string
158+
export TEST_CERT_CN=BFLB # Common Name
159+
```
140160

141-
- Generate PAA certificate and key to `out/cert` folder.
161+
- Generate PAA certificate and key to `out/cert` folder.
142162

143-
```shell
144-
mkdir out/test-cert
145-
./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}
146-
```
163+
```shell
164+
mkdir out/test-cert
165+
./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}
166+
```
147167

148-
- Convert PAA PEM format file to PAA DER format file
168+
- Convert PAA PEM format file to PAA DER format file
149169

150-
```shell
151-
./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
152-
```
170+
```shell
171+
./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
172+
```
153173

154-
> Please save this PAA DER format file which will be used by `chip-tool` during commissioning.
174+
> Please save this PAA DER format file which will be used by `chip-tool`
175+
> during commissioning.
155176

156-
- Generate PAI certificate and key:
177+
- Generate PAI certificate and key:
157178

158-
```shell
159-
./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
160-
```
179+
```shell
180+
./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
181+
```
161182

162-
- Generate MFD in plain text data
183+
- Generate MFD in plain text data
163184

164-
```shell
165-
./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
166-
```
185+
```shell
186+
./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
187+
```
167188

168-
> Appending `--key <hex string of 16 bytes>` option to enable encrypt private key of attestation device data.
189+
> Appending `--key <hex string of 16 bytes>` option to enable encrypt
190+
> private key of attestation device data.
169191

170192
## Generate with self-defined DAC certificate and key
171193

172-
Self-defined DAC certificates may use in development and test scenario. But, user should know it has limit to work with real ecosystem.
173-
174-
- Export environment variables in terminal for easy operations
194+
Self-defined DAC certificates may use in development and test scenario. But,
195+
user should know it has limit to work with real ecosystem.
175196

176-
```
177-
export TEST_CERT_VENDOR_ID=130D # Vendor ID hex string
178-
export TEST_CERT_PRODUCT_ID=1001 # Vendor ID hex string
179-
export TEST_CERT_CN=BFLB # Common Name
180-
```
197+
- Export environment variables in terminal for easy operations
181198

182-
- Generate DAC certificate and key
199+
```
200+
export TEST_CERT_VENDOR_ID=130D # Vendor ID hex string
201+
export TEST_CERT_PRODUCT_ID=1001 # Vendor ID hex string
202+
export TEST_CERT_CN=BFLB # Common Name
203+
```
183204

184-
```shell
185-
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
186-
```
205+
- Generate DAC certificate and key
187206

188-
> **Note**, `--valid-from` and `--lifetime` should be in `--valid-from` and `--lifetime` of PAI certificate.
207+
```shell
208+
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
209+
```
189210

190-
- Generate MFD in plain text data
211+
> **Note**, `--valid-from` and `--lifetime` should be in `--valid-from` and
212+
> `--lifetime` of PAI certificate.
191213

192-
```shell
193-
./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
194-
```
214+
- Generate MFD in plain text data
195215

196-
> Appending `--key <hex string of 16 bytes>` option to enable encrypt private key of attestation device data.
216+
```shell
217+
./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
218+
```
197219

220+
> Appending `--key <hex string of 16 bytes>` option to enable encrypt
221+
> private key of attestation device data.
198222

199223
# Program factory data
200224

201-
After each target built successfully, a flash programming python script will be generated under out folder.
202-
203-
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.
204-
205-
```shell
206-
/out/bouffalolab-bl616dk-light-wifi-mfd/chip-bl616-lighting-example.flash.py --port <serial port> --mfd out/test-cert/<mfd bin file>
207-
```
225+
After each target built successfully, a flash programming python script will be
226+
generated under out folder.
208227

209-
> If mfd file has cipher text data, please append `--key <hex string of 16 bytes>` option to program to this key to efuse.
228+
Take BL616 Wi-Fi Matter Light as example, `chip-bl616-lighting-example.flash.py`
229+
is using to program firmware, and also for factory data and factory decryption
230+
key.
210231

211-
- Limits on BL IOT SDK
212-
213-
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.
214-
215-
Please free contact to `Bouffalo Lab` for DAC provider service and higher security solution, such as SoC inside certificate requesting.
232+
```shell
233+
/out/bouffalolab-bl616dk-light-wifi-mfd/chip-bl616-lighting-example.flash.py --port <serial port> --mfd out/test-cert/<mfd bin file>
234+
```
216235

217-
236+
> If mfd file has cipher text data, please append
237+
> `--key <hex string of 16 bytes>` option to program to this key to efuse.
218238

219-
239+
- Limits on BL IOT SDK
220240

221-
241+
If developer would like to program MFD with all plain text data, option
242+
`--key <hex string of 16 bytes>` needs pass to script, otherwise, flash tool
243+
will raise an error. And SoC BL602, BL702 and BL702L use BL IOT SDK for
244+
Matter Application.
222245

246+
Please free contact to `Bouffalo Lab` for DAC provider service and higher
247+
security solution, such as SoC inside certificate requesting.

‎examples/lighting-app/bouffalolab/README.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ Legacy supported boards:
1717
- `BL602-NIGHT-LIGHT`
1818
- `XT-ZB6-DevKit`
1919
- `BL706-NIGHT-LIGHT`
20-
- `BL706DK`
21-
- `BL704LDK`
2220

2321
> Warning: Changing the VID/PID may cause compilation problems, we recommend
2422
> leaving it as the default while using this example.
@@ -119,8 +117,7 @@ The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`.
119117
- BL602 uses Wi-Fi by defualt. `-wifi` could be elided.
120118
- BL702 needs it to specify to use BL706 + BL602 for Wi-Fi.
121119
122-
- `-thread`, specifies to use Thread for Matter
123-
application.
120+
- `-thread`, specifies to use Thread for Matter application.
124121
125122
- BL70X uses Thread by defualt. `-thread` could be elided.
126123
@@ -130,9 +127,11 @@ The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`.
130127
131128
- `-littlefs`, specifies to use littlefs for flash access.
132129
- `-easyflash`, specifies to use `easyflash` for flash access.
133-
- for platform BL602/BL70X, it is necessary to specify one of `-easyflash` and `-littlefs`.
130+
- for platform BL602/BL70X, it is necessary to specify one of `-easyflash`
131+
and `-littlefs`.
134132
- `-mfd`, enable Matter factory data feature, which load factory data from
135133
`MFD` partition
134+
- Please refer to [Bouffalo Lab Matter factory data guide](../../../docs/guides/bouffalolab/matter_factory_data.md) or contact to `Bouffalo Lab` for support.
136135
- `-shell`, enable command line
137136
- `-rpc`, enable Pigweed RPC feature
138137
- `-115200`, set UART baudrate to 115200 for log and command line

0 commit comments

Comments
 (0)