Matter NXP 工厂数据生成器（NXP Factory Data Generator）实战指南：从 KLV 架构到产线烧写与安全加固

Matter NXP 工厂数据生成器（NXP Factory Data Generator）实战指南：从 KLV 架构到产线烧写与安全加固

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

本文以 Matter（connectedhomeip）仓库中 NXP 平台专用的工厂数据生成工具为核心，讲解其基于 (K, L, V) 元组的设计架构、generate.py/default.py/custom.py三文件的实现原理，并贯通 NXP 制造数据（Manufacturing Data）的完整生产流程：证书生成、数据二进制产出、烧写地址选择、应用构建启用，以及 EdgeLock 2GO 与 SSS 加密 Blob 两类 DAC 私钥安全加固方案。读完本文，你将掌握该工具的参数全貌、二进制格式细节、扩展新参数的标准方法，并能够在真实产线上落地一套可复用的 NXP 设备工厂数据写入流程。

一、工具概览：三个文件各司其职

NXP 工厂数据生成器位于 scripts/tools/nxp/factory_data_generator，整个工具仅由三个 Python 文件组成：

从源码结构看，三者的协作关系是：generate.py通过argparse解析命令行参数，凡是指定type为某个自定义类的参数，都会被解析成对应的对象实例；随后KlvGenerator.generate()从全部参数中筛选出InputArgument实例，调用其output()方法产出(K, L, V)元组；最后to_bin()把这些元组序列化写入二进制文件。并非所有参数都会被编码进输出二进制，例如spake2p_path和out就只是普通字符串参数，它们只参与工具运行逻辑，不进入工厂数据。

二、核心架构：KLV 元组与二进制格式

2.1 (K, L, V) 元组设计

工具的核心数据模型是(Key, Length, Value)三元组：

• K（Key）：1 字节标识符，唯一标志该数据项（如 Verifier=1、Salt=2、IterationCount=3……）；
• L（Length）：2 字节小端长度值，标识 V 的字节数；
• V（Value）：编码后的实际数据字节。

InputArgument（定义于 default.py）提供抽象接口key()、length()、encode()，三者通过公开方法output()组合成元组：

def output(self): out = (self.key(), self.length(), self.encode()) log.info("'%s' length: %d", type(self).__name__, self.length()) return out

其中output()是所有类共享的公共逻辑，不应被重写；子类只需实现三个抽象方法。

2.2 二进制布局

to_bin()（generate.py）将 KLV 列表写入文件时，每条记录按1 字节 Key + 2 字节小端 Length + Length 字节 Value顺序排列，并在整体前后附加如下结构（未加密场景）：

[Hash ID (4B, "CE47BA5E" 字节反转)] [数据总长度 (4B, 小端)] [SHA256 前 4 字节] [KLV 条目...]

• hash_id为全局常量"CE47BA5E"，写入前先做字节反转，用于标识工厂数据结构；
• 数据总长度以 4 字节小端写入，供设备端计算 SHA 校验；
• 完整性校验：对整个 KLV 内容计算 SHA256，取前 4 字节（8 个十六进制字符）附加在头部。

2.3 排序保证可复现

generate()方法特别强调：args本质上是字典，条目无序，因此必须按 key 排序后再产出 KLV 列表，以保证每次生成的二进制顺序一致，从而确保两份输出可以通过 SHA256 可靠对比：

data = [obj for key, obj in vars(self.args).items() if isinstance(obj, InputArgument)] return [arg.output() for arg in sorted(data, key=lambda x: x.key())]

2.4 可选 AES 加密

当传入--aes128_key或--aes256_key（to_bin优先采用 aes256）时，KLV 内容会先补齐到 16 字节对齐，再使用Crypto.Cipher.AES以ECB 模式加密整段数据（见 generate.py）。因此该加密是"全数据集加密"而非逐条加密。使用加密前务必确认目标应用/板卡具备解密机制并可访问密钥，否则设备无法读取工厂数据。

三、默认类与自定义类：扩展新参数的规范路径

3.1 default.py 中的默认类

default.py 定义的基础类及行为如下：

注意：默认类不应被直接用来实例化参数；新增参数必须从默认类派生自定义类。

3.2 custom.py 中的自定义类与 Key 分配

custom.py 为每个输出参数定义了类，并分配了唯一的 Key：

其中两个特殊类值得关注：

• DacPKey：并不直接写入文件原始字节。其generate_private_key(password, use_sss_blob=False)会调用load_der_private_key解析 DER 私钥，提取大端序 32 字节私钥数值（P-256 曲线）。若use_sss_blob=True，则直接将传入文件内容（即加密 Blob）原样作为 value 写入。
• ProductFinish/ProductPrimaryColor：可接受的值有严格枚举。ProductFinish仅接受["Other", "Matte", "Satin", "Polished", "Rugged", "Fabric"]，ProductPrimaryColor仅接受["Black", "Navy", "Green", ... "Gold"]等 21 个取值，编码为枚举下标（1 字节），非法输入会直接报错退出。命令行--help中会以 metavar 展示这些取值。

3.3 如何新增一个参数（官方示例）

在 custom.py 中定义新类，必须从默认类派生，而不是直接继承InputArgument：

class FooArgument(BarArgument): def __init__(self, arg): super().__init__(arg) def key(self): return <unique key identifier> def length(self): return <actual length of data> def encode(self): return <data as encoded bytes> def custom_function(self): pass

其中BarArgument是某个默认类；开发者可根据需要附加其他方法（例如DacPKey类中的generate_private_key）。随后在generate.py中把新类挂到参数上：

parser.add_argument("--foo", required=True, type=FooArgument, help="[int | hex] Foo argument.")

argparse的type属性指向类构造器后，字符串参数会被自动解析为FooArgument实例，并参与 KLV 生成。

3.4 参数校验逻辑

KlvGenerator._validate_args()（generate.py）在生成前执行关键约束检查：

• 未提供--dac_key_password且未提供--EL2GO_bin时，仅打印警告（意味着 DAC 私钥未受保护）；
• 不能同时提供--dac_key和--EL2GO_bin两种 DAC 供给方式；
• 必须提供 DAC 供给方式：--dac_key+--dac_cert，或--EL2GO_bin，否则抛异常；
• 使用--EL2GO_bin时必须同时提供--EL2GO_DAC_KEY_ID与--EL2GO_DAC_CERT_ID；
• 所有StrArgument的长度通过assert校验不得超过max_length()，超长会中断生成。

四、完整制造流程（Manufacturing Flow）

工具的完整用法由 docs/platforms/nxp/nxp_manufacturing_flow.md 说明。默认情况下，示例应用使用内嵌在应用代码中的通用测试证书与预置数据；最终量产应用可按下述流程生成自己的制造数据。

4.1 前置条件：构建 chip-cert 与 spake2p

在 Matter 仓库根目录执行：

gn gen out ninja -C out chip-cert ninja -C out spake2p

• chip-cert用于生成各类 Matter 证书；
• spake2p用于按需生成 SPAKE2+ verifier（若传入现成 verifier 则无需调用）。

4.2 生成证书

NXP 提供 scripts/tools/nxp/generate_certs.py 生成证书。该脚本始终生成 PAI 与 DAC 证书/密钥，并根据参数决定是否额外生成 Certification Declaration 与 PAA 证书/密钥。参数一览：

可运行python scripts/tools/nxp/generate_certs.py --help查看默认值等更多细节。

生成 CD、PAA、PAI、DAC 证书及密钥（同时输出 .pem 与 .der 格式）的完整示例：

python scripts/tools/nxp/generate_certs.py --gen_cd --cd_type 1 --chip_cert_path ./out/chip-cert --vendor_id 0x1037 --product_id 0xA220 --vendor_name "NXP Semiconductors" --product_name all-clusters-app --device_type 65535 --output .

从源码看（generate_certs.py），CD 使用仓库内置的测试签名证书credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem与对应密钥签发；PAA 默认通过gen-att-cert以类型a生成，PAI 以类型i并由 PAA 签发，DAC 由 PAI 签发。未提供 PAA 路径时会自动生成新 PAA。

注意：文中的命令仅为示例，请按实际使用场景调整 VID/PID、路径与参数。

4.3 生成工厂数据二进制

明文（未加密）模式

python3 ./scripts/tools/nxp/factory_data_generator/generate.py -i 10000 -s UXKLzwHdN3DZZLBaL2iVGhQi/OoQwIwJRQV4rpEalbA= -p 14014 -d 1000 --vid 0x1037 --pid 0xA220 --vendor_name "NXP Semiconductors" --product_name "Lighting app" --serial_num "12345678" --date "2023-01-01" --hw_version 1 --hw_version_str "1.0" --cert_declaration ./Chip-Test-CD-1037-A220.der --dac_cert ./Chip-DAC-NXP-1037-A220-Cert.der --dac_key ./Chip-DAC-NXP-1037-A220-Key.der --pai_cert ./Chip-PAI-NXP-1037-A220-Cert.der --spake2p_path ./out/spake2p --unique_id "00112233445566778899aabbccddeeff" --out ./factory_data.bin

传入现成 verifier（跳过 spake2p 调用）

python3 ./scripts/tools/nxp/factory_data_generator/generate.py -i 10000 -s UXKLzwHdN3DZZLBaL2iVGhQi/OoQwIwJRQV4rpEalbA= -p 14014 -d 1000 --vid "0x1037" --pid "0xA220" --vendor_name "NXP Semiconductors" --product_name "Lighting app" --serial_num "12345678" --date "2023-01-01" --hw_version 1 --hw_version_str "1.0" --cert_declaration ./Chip-Test-CD-1037-A220.der --dac_cert ./Chip-DAC-NXP-1037-A220-Cert.der --dac_key ./Chip-DAC-NXP-1037-A220-Key.der --pai_cert ./Chip-PAI-NXP-1037-A220-Cert.der --spake2p_path ./out/spake2p --spake2p_verifier ivD5n3L2t5+zeFt6SjW7BhHRF30gFXWZVvvXgDxgCNcE+BGuTA5AUaVm3qDZBcMMKn1a6CakI4SxyPUnJr0CpJ4pwpr0DvpTlkQKqaRvkOQfAQ1XDyf55DuavM5KVGdDrg== --unique_id "00112233445566778899aabbccddeeff" --out ./factory_data.bin

AES 加密模式

在以上任一命令中追加：

--aes128_key 2B7E151628AED2A6ABF7158809CF4F3C

必填参数释义

-i -> SPAKE2+ iteration -s -> SPAKE2+ salt（base64 字符串） -p -> SPAKE2+ passcode -d -> discriminator --vid -> Vendor ID --pid -> Product ID --vendor_name -> Vendor Name --product_name -> Product Name --hw_version -> Hardware Version（数值） --hw_version_str -> Hardware Version（字符串） --cert_declaration -> Certification Declaration 路径（der 格式） --pai_cert -> PAI 路径（der 格式） --spake2p_path -> spake2p 工具路径 --out -> 输出二进制文件名

可选参数释义

--dac_cert -> DAC 证书路径（der 格式） --dac_key -> DAC 密钥路径（der 格式） --EL2GO_bin -> EdgeLock 2Go 二进制路径（bin 格式） --EL2GO_DAC_KEY_ID -> EdgeLock 2Go 中配置的 DAC key ID（hex） --EL2GO_DAC_CERT_ID -> EdgeLock 2Go 中配置的 DAC 证书 ID（hex） --dac_key_password -> 解密 DAC key 的密码 --dac_key_use_sss_blob -> 当 --dac_key 指向加密 blob 而非真实私钥时使用；blob 元数据为 24 字节， 总长度 = 私钥长度 32 + 24 = 56。默认 False --spake2p_verifier -> 现成 SPAKE2+ verifier（base64）。设置后全部 SPAKE2+ 输入直接编码进二进制， 不再调用 spake2p 工具现场生成 --aes128_key -> 128 位 AES 密钥，加密整个数据集。需确保目标应用/板卡支持解密 --date -> 生产日期（YYYY-MM-DD 格式） --part_number -> 料号（字符串） --product_url -> 产品 URL（字符串） --product_label -> 产品标签（字符串） --serial_num -> 序列号 --unique_id -> 用于旋转设备 ID 生成的唯一标识 --product_finish -> 产品可见表面处理 --product_primary_color -> 产品可见部分代表色 --hw_params -> 使用 Hardware Parameters 组件的应用工厂数据

4.4 SPAKE2+ verifier 的现场生成机制

若未提供--spake2p_verifier，Spake2p.generate()（generate.py）会调用spake2p gen-verifier，将迭代次数、salt、PIN code 传入，并把输出的 Verifier、Salt、Iteration Count 写回参数对象。因此无论哪种方式，verifier/salt/迭代次数最终都会进入输出二进制。

4.5 烧写工厂数据到目标平台

不同 NXP 平台使用不同的烧写工具与地址：

4.6 在应用中启用工厂数据并验证

启用方式：

• GN 构建：在gn gen命令中加入nxp_use_factory_data=true；
• CMake 构建：在构建命令中加入-DCONFIG_CHIP_FACTORY_DATA=y，或使用支持工厂数据的prj_<flavour>.conf（完整配置列表见 docs/platforms/nxp/nxp_examples_freertos_platforms.md）。

使用 chip-tool 携带新 PAA 进行配对验证：

./chip-tool pairing ble-thread 2 hex: $hex_value 14014 1000 --paa-trust-store-path /home/ubuntu/certs/paa

--paa-trust-store-path -> 生成的 PAA 路径（der 格式）

注意事项：

• paa-trust-store-path目录中只能放置 PAA 证书，混入其他证书会干扰 chip-tool；
• PAA 证书可用 SCP 等工具拷贝到 chip-tool 所在机器；
• 该步骤用于验证自生成的 DAC；若使用正式 PAI 签发的 DAC（真实量产场景），通常无需此步骤。

五、DAC 私钥安全加固方案

5.1 方案一：SSS + EdgeLock 2GO

EdgeLock 2GO 服务可在制造阶段安全地预置 DAC 密钥/证书。支持平台：rw61x。

生成工厂数据二进制前，需先按 EL2GO 流程生成 EL2GO 数据（含加密的 DAC 私钥与证书），随后在工厂数据生成命令中添加：

• --EL2GO_bin ~/secure_objects.bin：包含 EL2GO 信息（加密 DAC 私钥与证书）；
• --EL2GO_DAC_KEY_ID 0x40000：与 EL2GO 密钥生成时选择的 DAC key ID 对应；
• --EL2GO_DAC_CERT_ID 0x40001：与 EL2GO 密钥生成时选择的 DAC 证书 ID 对应。

参考命令：

python3 ./scripts/tools/nxp/factory_data_generator/generate.py -i 10000 -s UXKLzwHdN3DZZLBaL2iVGhQi/OoQwIwJRQV4rpEalbA= -p ${passcode} -d ${discriminator} --vid "0x$VID" --pid "0x$PID" --vendor_name "NXP Semiconductors" --product_name "Thermostat" --serial_num "12345678" --date "$DATE" --hw_version 1 --hw_version_str "1.0" --cert_declaration $FACTORY_DATA_DEST/Chip-Test-CD-$VID-$PID.der --EL2GO_bin ~/secure_objects.bin --EL2GO_DAC_KEY_ID 0x40000 --EL2GO_DAC_CERT_ID 0x40001 --pai_cert $FACTORY_DATA_DEST/Chip-PAI-NXP-$VID-$PID-Cert.der --spake2p_path ./out/spake2p --unique_id "00112233445566778899aabbccddeeff" --out $FACTORY_DATA_DEST/factory_data.bin

构建启用方式：

• GN 构建：在nxp_use_factory_data=true基础上追加nxp_enable_secure_EL2GO_factory_data=true；
• CMake 构建：启用CONFIG_CHIP_ENABLE_EL2GO_FACTORY_DATAKconfig，可通过支持工厂数据的prj_<flavour>.conf配置，或构建命令行加-DCONFIG_CHIP_ENABLE_EL2GO_FACTORY_DATA=y。

此模式下 EdgeLock 2GO 密钥始终加密，仅SSS（Secure Subsystem）可使用；所有需要 DAC 私钥的操作都会被转移到 SSS 执行。

5.2 方案二：SSS 加密 Blob（无 EdgeLock 2GO）

支持平台：mcxw71、rw61x。

对于带安全子系统（SSS）的平台，可将 DAC 私钥转换为加密 Blob，该 Blob 会替换工厂数据中的 DAC 私钥，并由工厂数据 provider 实例导入 SSS。制造流程之外，DAC 私钥始终仅 SSS 可用，所有需要 DAC 私钥的操作都转移到 SSS。应用会在初始化时检查 DAC 私钥是否已转换，必要时自行转换；但出于安全考虑，转换应在制造阶段完成。

参考生成命令（注意--hw_params的使用）：

python3 ./scripts/tools/nxp/factory_data_generator/generate.py -i 10000 -s UXKLzwHdN3DZZLBaL2iVGhQi/OoQwIwJRQV4rpEalbA= -p 14014 -d 1000 --vid "0x1037" --pid "0xA221" --vendor_name "NXP Semiconductors" --product_name "Lighting app" --serial_num "12345678" --date "2023-01-01" --hw_version 1 --hw_version_str "1.0" --cert_declaration ./Chip-Test-CD-1037-A221.der --dac_cert ./Chip-DAC-NXP-1037-A221-Cert.der --dac_key ./Chip-DAC-NXP-1037-A221-Key.der --pai_cert ./Chip-PAI-NXP-1037-A221-Cert.der --spake2p_path ./out/spake2p --unique_id "00112233445566778899aabbccddeeff" --hw_params --out ./factory_data.bin

此场景无需额外二进制，流程为：烧写工厂数据二进制 → 以nxp_use_factory_data=true（GN）或-DCONFIG_CHIP_FACTORY_DATA=y/ 支持工厂数据的prj_<flavour>.conf（CMake）构建应用 → 正常烧写运行。完成后工厂数据中应包含对应的加密 Blob 而非 DAC 私钥明文。

如果加密 Blob 已通过其他方式预先获得，可跳过转换过程，改用--dac_key_use_sss_blob：

python3 ./scripts/tools/nxp/factory_data_generator/generate.py -i 10000 -s UXKLzwHdN3DZZLBaL2iVGhQi/OoQwIwJRQV4rpEalbA= -p 14014 -d 1000 --vid "0x1037" --pid "0xA221" --vendor_name "NXP Semiconductors" --product_name "Lighting app" --serial_num "12345678" --date "2023-01-01" --hw_version 1 --hw_version_str "1.0" --cert_declaration ./Chip-Test-CD-1037-A221.der --dac_cert ./Chip-DAC-NXP-1037-A221-Cert.der --dac_key ./Chip-DAC-NXP-1037-A221-Key-encrypted-blob.bin --pai_cert ./Chip-PAI-NXP-1037-A221-Cert.der --spake2p_path ./out/spake2p --unique_id "00112233445566778899aabbccddeeff" --dac_key_use_sss_blob --out ./factory_data_with_blob.bin

注意此时--dac_key指向的是包含加密 Blob 的二进制文件。另外，若想绕开 SSS 直接使用明文 DAC 私钥，可加 GN 参数chip_use_plain_dac_key=true（rw61x 不支持）。

六、补充信息与已知注意事项

• 制造数据预置实现已使用OpenSSL 1.1.1l生成的测试证书验证通过；
• 启用工厂数据所需的演示用 DAC、PAI、PAA 证书位于 scripts/tools/nxp/demo_generated_certs，包含dac/dut1、dac/dut2、paa、pai各目录的 .pem/.der 文件，可用于本地快速验证流程；
• --hw_params选项会将工厂数据按 Hardware Parameters 组件的 APP 段格式组织。从 generate.py 的to_bin()实现看，启用后会追加APP_FACT_DATA:魔数头部、4 字节小端大小、数据本体以及 2 字节 CRC16（XMODEM）校验尾；
• 生成过程中to_bin()会在日志中输出 4 字节段哈希、最终二进制大小与整体 SHA256，可用于产线校验（两份二进制可通过 SHA256 直接对比）；
• NXP 相关构建配置（如 config/nxp/chip-module/Kconfig.defaults、config/nxp/chip-module/generate_factory_data.cmake）中可见工厂数据的构建期生成与 Kconfig 开关逻辑，可在 CMake 构建体系内联动。

七、小结

NXP 工厂数据生成器以极简的三文件结构，完成了从命令行参数到 KLV 序列化、再到可烧写二进制（含可选 AES 加密与完整性校验）的完整链路。其核心设计——抽象基类 + 默认类 + 自定义类的三层派生体系——保证了新增产线字段的成本极低且可复现。配合generate_certs.py的证书体系、按平台区分的烧写地址表，以及 EL2GO / SSS Blob 两类 DAC 私钥安全方案，开发者可以在 Matter 认证设备量产时，建立一套从"证书签发"到"数据写入"再到"安全存储"的完整工厂数据流水线。

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip