Matter - 配置工厂数据（2）

部分关键名词参数简介

1. PASE(Passcode-Authenticated Session Establishment): 基于密码认证的会话建立，用于在 Commissioning 的时候 Commissioner 与 Matter Deivce 之间建立安全信道，生成对称加密密钥用于 Commissioning 后续通信消息进行加、解密和完整性保护。
2. Passcode(or Pincode): 密码或口令，用于在 Commissioning 的时候会话建立过程的输入参数之一。也是 QR 码中包含的一个重要信息。
3. Discriminator: 鉴别码。Matter Device 在 Commissioning 时会进行蓝牙广播(Advertising)，广播中包含该信息。Commissioner 通过鉴别码来识别入网设备，两者鉴别码一致才开始 Commissioning 流程。
4. Spake2+: 密码认证的密钥交换算法，PASE 建立过程中使用的算法。Matter 规范里有详细的介绍。
5. Verifier: 验证器，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。
6. Iteration count: 迭代次数，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。
7. Salt: 盐值，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。

工厂数据参数

        工厂数据是在制造过程中写入非易失性存储器的一组设备参数，在设备启动初始化时读取。所有出厂数据参数均受到保护，不会被软件修改，并且固件数据参数集在设备的使用寿命期间必须保持不变，实施固件时，必须确保在设备固件更新 (DFU) 或恢复出厂设置期间不会重写或覆盖出厂数据参数。对于 nRF Connect 平台，出厂数据默认存储在芯片内部 flash 的单独分区中。这有助于通过应用硬件写保护来保证工厂数据的安全。Fprotect 是硬件闪存保护驱动程序，用它来确保内部闪存中的工厂数据分区写保护。

工厂数据成分表

Key name	Full name	Length	Format	Conformance	Description
version	出厂数据版本	2 B	uint16	强制	当前工厂数据集的版本。用户无法更改它，并且必须与设备端当前版本的 Factory Data Provider 保持一致。
sn	序列号	<1, 32> B	ASCII string	强制	序列号参数定义制造设备的唯一编号。序列号的最大长度为 32 个字符。
vendor_id	供应商ID	2 B	uint16	强制	CSA 为负责生产设备的组织分配的 ID
product_id	产品编号	2 B	uint16	强制	设备供应商分配的用于识别产品的唯一 ID。它默认为 CSA 分配的 ID，用于指定非生产或测试产品。
vendor_name	供应商名称	<1, 32> B	ASCII string	强制	可读的供应商名称，提供一个简单的字符串
product_name	产品名称	<1, 32> B	ASCII string	强制	可读的产品名称，提供一个简单的字符串
date	生产日期	10 B	ISO 8601	强制	使用的日期格式为 ISO 8601，例如 YYYY-MM-DD
hw_ver	硬件版本	2 B	uint16	强制	值的含义和版本由供应商定义
hw_ver_str	硬件版本字符串	<1, 64> B	uint16	强制	值的含义和版本由供应商定义
rd_uid	旋转设备唯一标识	<16, 32> B	byte string	强制	由随机生成的 128 位（或更长）八位字节字符串组成。在首次引入设备后，应防止该参数通过无线方式读取或写入，并在设备的使用寿命期间保持固定。使用工厂数据支持构建应用时，必须使用工厂数据分区中存储的实际长度来设置 CONFIG_CHIP_FACTORY_DATA_ROTATING_DEVICE_UID_MAX_LEN。
dac_cert	设备认证证书	<1, 602> B	byte string	强制	设备证明证书 (DAC) 和相应的私钥对于每个 Matter 设备都是唯一的。 DAC 用于设备认证过程以及对结构进行调试。 DAC 是符合 RFC 5280 中定义的 DER 编码 X.509v3 兼容证书。
dac_key	设备认证密钥	68 B	byte string	强制	与设备证明证书 (DAC) 关联的密钥。该密钥应该被加密，并且在生成并将其提供给工厂数据时应保证最大的安全性。
pai_cert	PAI 证书	<1, 602> B	byte string	强制	Product Attestation Intermediate Certificate 产品认证机构证书，PAI 证书是 X.509 兼容的，并且以 DER（Distinguished Encoding Rules）格式编码，根据 RFC 5280 的定义。
spake2_it	Spake2+ 迭代次数	4 B	uint32	强制	在 SPAKE2+ 协议中，SPAKE2+ 迭代计数器（iteration counter）指的是在 SPAKE2+ 验证器生成过程中使用的 PBKDF2（密码基密钥导出函数，Password-Based Key Derivation Function 2）的迭代次数
spake2_salt	Spake2+ salt 值	<32, 64> B	byte string	强制	SPAKE2+ 中的 salt 值是一个随机的数据片段，长度至少为 32 字节。它被用作单向函数的额外输入，该函数执行密码学操作。对于每个密码，都应随机生成一个新的盐值。
spake2_verifier	Spake2+ 验证器	97 B	byte string	强制	SPAKE2+ 验证器是使用 SPAKE2+ salt值、迭代计数器和密码生成的。
discriminator	BLE 配对识别器	2 B	uint16	强制	discriminator 在 Matter 协议中是一个用于辅助设备发现和区分的关键字段，通过提供一个唯一的识别码，它帮助确保在设备配置和连接过程中的正确性和有效性
passcode	PASE 会话密码	4 B	uint32	可选	配对密码是一个27位的无符号整数，有效的配对密码值被限制在 0x0000001 到 0x5F5E0FE，有一些特定的数值不被视为有效的配对密码，这些包括所有的重复数字（如 11111111、22222222 等）、以及 12345678 和 87654321 这两个顺序性较强的数字序列。设备的组网（commissioning）过程中，配对密码用作拥有权的证明。当一个新设备被添加到网络中时，需要输入这个密码来验证操作者有权对设备进行配对和配置。
product_appearance	产品外观	2 B	CBOR map	可选	是用来描述产品可见外观的结构。这个字段以 CBOR（Concise Binary Object Representation，简洁二进制对象表示法）映射的形式提供，并且包含两个属性：finish（表面处理，1 字节）和 primary_color（主要颜色，1 字节）。
user	用户数据	variable, max 1024 B	CBOR map	可选	用户数据（User Data）以 JSON 格式提供。这个参数是可选的，具体使用取决于设备制造商的用途。它作为一个 CBOR 映射类型从持久存储中提供，并应在用户应用程序中进行解析。需要注意的是，Matter 栈不使用这些用户数据。

connectedhomeip 目录下执行 python3 scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h，查看生成工厂数据需要提供的相关参数：

必需参数

• --sn SN: 设备的序列号，用于在 Matter 证书结构中识别序列号字段。序列号的最大长度为 20 字节。
• --vendor_id VENDOR_ID: 提供供应商识别号（整数或十六进制）。
• --product_id PRODUCT_ID: 提供产品识别号（整数或十六进制）。
• --vendor_name VENDOR_NAME: 提供人类可读的供应商名称。
• --product_name PRODUCT_NAME: 提供人类可读的产品名称。
• --date DATE: 提供制造日期，使用 ISO 8601 格式，例如 YYYY-MM-DD。
• --hw_ver HW_VER: 提供硬件版本（整数或十六进制格式）。
• --hw_ver_str HW_VER_STR: 提供硬件版本的字符串表示形式。
• --spake2_it SPAKE2_IT: 提供 Spake2+ 迭代次数（整数或十六进制）。
• --spake2_salt SPAKE2_SALT: 提供 Spake2+ 盐值（Base64 字符串）。
• --discriminator DISCRIMINATOR: 提供 BLE 配对鉴别码，一个与设置代码中同名字段相匹配的 12 位值。

可选参数

• --product_url PRODUCT_URL: 提供指向产品特定网页的链接。
• --product_label PRODUCT_LABEL: 提供人类可读的产品标签。
• --part_number PART_NUMBER: 提供人类可读的产品编号。
• --chip_cert_path CHIP_CERT_PATH: 生成 DAC 和 PAI 证书的路径。
• --dac_cert DAC_CERT: 提供包含 DAC 证书的 .der 文件路径。
• --dac_key DAC_KEY: 提供包含 DAC 密钥的 .der 文件路径。
• --generate_rd_uid: 生成新的旋转设备唯一 ID。
• --pai_cert PAI_CERT: 提供包含 PAI 证书的 .der 文件路径。
• --passcode PASSCODE: 默认的 PASE 会话密码。
• --spake2_verifier SPAKE2_VERIFIER: 提供 Spake2+ 验证器，而不是生成它。
• --enable_key ENABLE_KEY: 启用键，用于触发制造商特定动作。
• --gen_cd: 生成证书声明。
• --cd_type CD_TYPE: 生成的认证声明类型：0 - 开发，1 - 临时，2 - 正式。
• --paa_cert PAA_CERT: 提供用于生成 PAI 证书的产品认证机构证书路径。
• --paa_key PAA_KEY: 提供用于生成 PAI 证书的产品认证机构密钥路径。
• --generate_onboarding: 生成手册代码和 QR 码。
• --product_finish: 提供产品的表面处理。
• --product_color: 提供产品的颜色。

工厂数据配置

1、命令行： 

例如，Python 脚本的最终调用可能类似于以下内容：

python3 scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py \
--sn "11223344556677889900" \
--vendor_id 65521 \
--product_id 32774 \
--vendor_name "Nordic Semiconductor ASA" \
--product_name "not-specified" \
--date "2022-02-02" \
--hw_ver 1 \
--hw_ver_str "prerelase" \
--dac_cert "credentials/development/attestation/Matter-Development-DAC-FFF1-8006-Cert.der" \
--dac_key "credentials/development/attestation/Matter-Development-DAC-FFF1-8006-Key.der" \
--pai_cert "credentials/development/attestation/Matter-Development-PAI-FFF1-noPID-Cert.der" \
--spake2_it 1000 \
--spake2_salt "U1BBS0UyUCBLZXkgU2FsdA==" \
--discriminator 0xF00 \
--generate_rd_uid \
--passcode 20202021 \
--product_finish "matte" \
--product_color "black" \
--out "build.json" \
--schema "scripts/tools/nrfconnect/nrfconnect_factory_data.schema"

• --sn "11223344556677889900"：设备的序列号。

• --vendor_id 65521：供应商标识号。

• --product_id 32774：产品标识号。

• --vendor_name "Nordic Semiconductor ASA"：供应商名称。

• --product_name "not-specified"：产品名称。

• --date "2022-02-02"：制造日期。

• --hw_ver 1：硬件版本。

• --hw_ver_str "prerelase"：硬件版本的字符串表示。

• --dac_cert 和 --dac_key：DAC（Device Attestation Certificate）的证书和密钥文件的路径。

• --pai_cert：PAI（Product Attestation Identity）的证书文件路径。

• --spake2_it 1000：SPAKE2+ 迭代次数。

• --spake2_salt "U1BBS0UyUCBLZXkgU2FsdA=="：SPAKE2+ salt 的 base64 编码值。

• --discriminator 0xF00：BLE 配对鉴别码。

• --generate_rd_uid：生成旋转设备唯一标识符（RD UID）。

• --passcode 20202021：配对密码。

• --product_finish "matte"：产品的表面处理类型，这里是哑光（matte）。

• --product_color "black"：产品的颜色，这里是黑色。

• --out "build.json"：生成的工厂数据的输出路径。

• --schema "scripts/tools/nrfconnect/nrfconnect_factory_data.schema"：JSON 模式文件的路径，用于验证生成的工厂数据。

生成手动配对代码和 QR 码，首先需要安装 Matter 网络相关的 Python 依赖。通过以下命令来安装：

python -m pip install -r ./scripts/setup/requirements.nrfconnect.txt

在脚本的最终调用中添加 --generate_onboarding 参数，执行后在 --out 指定目录下生成：

• 最新工厂数据集的 JSON 文件。
• 包含生成的手动代码和QR码文本版本的测试文件。
• PNG 格式的 QR 码图像。

使用目标 .json 文件生成 factory.hex、factory.bin 文件，移动至 matter libraries 根目录：

python3 scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i build/zephyr/factory_data.json -o build/zephyr/factory_data --offset 0xfb000 --size 0x1000

python3 scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i <path_to_JSON_file> -o <path_to_output> --offset <partition_address_in_memory> --size <partition_size>

• <path_to_JSON_file>：提供 .json 文件路径。
• <path_to_output>：提供输出路径。
• <partition_address_in_memory>：提供烧录到内部 flash 中的分区偏移地址。
• <partition_size>：提供分区大小。

使用 nrfjprog 工具烧录至芯片的工厂数据分区中：

nrfjprog --program factory_data.hex

使用 west 编译应用程序时，使能 CONFIG_CHIP_FACTORY_DATA、DCONFIG_CHIP_FACTORY_DATA_BUILD、DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE，生成应用程序固件时同时生成工厂数据的 .hex、.bin 文件和 QR 码相关文件在 build/zephyr 路径（默认）中，同时合并固件，如：

west build -b nrf5340dk_nrf5340_cpuapp -- \
-DCONFIG_CHIP_FACTORY_DATA=y \
-DCONFIG_CHIP_FACTORY_DATA_BUILD=y \
-DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=y

添加禁用 DCONFIG_CHIP_FACTORY_DATA_USE_DEFAULT_CERTS=n，将自动生成新的CD、DAC、PAI 证书添加到工程数据中。

2、VS Code  

新建 matter light_bulb 工程，使用默认工程配置文件 prj.conf ，默认打开 OTA、工厂数据配置生成等，nRF Kconfig GUI 下，Modules -> connectedhomeip -> ...更改相关配置。

参考：Configuring factory data for the nRF Connect examples