某些开发场景(如 OTA 测试)需要创建非生产 Matter 证书。
Google 生态系统的某些功能(包括设备 OTA 软件更新)无法使用测试 VID/PID 执行。
本指南介绍如何创建和验证非生产 Matter 证书以用于测试。证书类型如下:
- 认证声明 (CD)
- 产品认证中间证书 (PAI)
- 设备认证证书 (DAC)
在调试过程中,经过 Matter 认证的设备需要对自身进行证明,即证明其是经过 Matter 认证的正品。Matter 设备用于认证的凭据包括:
- 认证密钥对
- 证书链
设备认证证书 (DAC) 是证书链的第一个链接,由产品认证中间证书 (PAI) 进行验证,PAI 继而由产品认证机构 (PAA) 验证。
证书会在生成认证密钥对的同时签名,并使用证书授权机构的私钥进行签名,从而形成信任链。因此,DAC 证书由 PAI 密钥签名,PAI 证书由 PAA 密钥签名。位于链顶端的 PAA 证书是自签名证书。此信任链构成了联合 PAA 结构,该结构由分布式合规性分类账 (DCL) 同步。
如需详细了解认证流程和认证声明 (CD),请参阅其他证明文档和消息以及诉讼或调查规范。
安装 Matter SDK
以下说明假定您已安装 Matter SDK 的有效安装。请参阅相关 GitHub 文档,或者参阅 Matter 使用入门了解详情。
如果没有十六进制转储实用程序 xxd
,请进行安装。此工具对于以 C 样式的格式输出凭据非常有用:
sudo apt-get install xxd
构建作业 chip-cert
请确保您使用的是最新版本的 SDK。我们在 GitHub SHA
0b17bce8
的v1.0-branch
分支上对这些步骤进行了测试:$ cd connectedhomeip $ git checkout v1.0-branch $ git pull
构建
chip-cert
,该工具用于对 Matter 设备的凭据执行多项操作:配置构建:
$ cd src/credentials $ source ../../scripts/activate.sh $ gn gen out
gn
输出示例:Done. Made 5774 targets from 289 files in 658ms
运行 build:
$ ninja -C out
ninja
输出示例:ninja: Entering directory `out' [2000/2000] stamp obj/default.stamp
创建证书
将自定义 VID/PID 导出为环境变量,以降低修改命令参数时出现语法错误的可能性:
$ cd ../..
$ export VID=hexVendorId
$ export PID=hexProductId
生成 CD
使用
chip-cert
生成 CD。目前,调试器仅验证 VID 和 PID 是否与设备其他位置公开的数据匹配:基本信息集群、DAC 和 DAC 源(如果具有)。其他字段可以保持不变:$ src/credentials/out/chip-cert gen-cd \ --key credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \ --cert credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \ --out credentials/test/certification-declaration/Chip-Test-CD-${VID}-${PID}.der \ --format-version "1" \ --vendor-id "${VID}" \ --product-id "${PID}" \ --device-type-id "0x1234" \ --certificate-id "ZIG20141ZB330001-24" \ --security-level "0" \ --security-info "0" \ --version-number "9876" \ --certification-type "0"
验证 CD。确保其中包含您的 VID/PID(采用十进制格式):
$ src/credentials/out/chip-cert print-cd credentials/test/certification-declaration/Chip-Test-CD-${VID}-${PID}.der
输出示例:
SignerKeyId value: hex:62FA823359ACFAA9963E1CFA140ADDF504F37160 0x01, tag[Anonymous]: 0xffffffff, type: Structure (0x15), container: 0x04, tag[Context Specific]: 0x0, type: Unsigned Fixed Point (0x04), value: 1 0x08, tag[Context Specific]: 0x1, type: Unsigned Fixed Point (0x04), value: XXXXX // <- VID 0x0A, tag[Context Specific]: 0x2, type: Array (0x16), container: 0x0D, tag[Anonymous]: 0xffffffff, type: Unsigned Fixed Point (0x04), value: XXXXX // <- PID 0x12, tag[Context Specific]: 0x3, type: Unsigned Fixed Point (0x04), value: 4660 0x15, tag[Context Specific]: 0x4, type: UTF-8 String (0x0c), length: 19, value: "ZIG20141ZB330001-24" 0x2B, tag[Context Specific]: 0x5, type: Unsigned Fixed Point (0x04), value: 0 0x2E, tag[Context Specific]: 0x6,type: Unsigned Fixed Point (0x04), value: 0 0x32, tag[Context Specific]: 0x7, type: Unsigned Fixed Point (0x04), value: 39030 0x35, tag[Context Specific]: 0x8, type: Unsigned Fixed Point (0x04), value: 0
生成 PAI 和 DAC
在此示例中,我们将使用 Matter 自己的测试产品认证机构 (PAA) 证书和签名密钥 Chip-Test-PAA-NoVID
作为根证书。我们将将其用作根 CA 以生成我们自己的 PAI 和 DAC。
使用 PAA 生成 PAI。您可以选择在 PAI 中包含 PID 信息,但省略此信息可提高测试的灵活性。如果您需要 DAC 用于额外的 PID,则可以只执行 DAC 生成步骤:
$ src/credentials/out/chip-cert gen-att-cert --type i \ --subject-cn "Matter Test PAI" \ --subject-vid "${VID}" \ --valid-from "2021-06-28 14:23:43" \ --lifetime "4294967295" \ --ca-key credentials/test/attestation/Chip-Test-PAA-NoVID-Key.pem \ --ca-cert credentials/test/attestation/Chip-Test-PAA-NoVID-Cert.pem \ --out-key credentials/test/attestation/"test-PAI-${VID}-key".pem \ --out credentials/test/attestation/"test-PAI-${VID}-cert".pem
使用 PAI 生成 DAC:
$ src/credentials/out/chip-cert gen-att-cert --type d \ --subject-cn "Matter Test DAC 0" \ --subject-vid "${VID}" \ --subject-pid "${PID}" \ --valid-from "2021-06-28 14:23:43" \ --lifetime "4294967295" \ --ca-key credentials/test/attestation/"test-PAI-${VID}-key".pem \ --ca-cert credentials/test/attestation/"test-PAI-${VID}-cert".pem \ --out-key credentials/test/attestation/"test-DAC-${VID}-${PID}-key".pem \ --out credentials/test/attestation/"test-DAC-${VID}-${PID}-cert".pem
验证 DAC、PAI 和 PAA 链。如果输出中未显示任何错误,则表示证书证明链已成功通过验证:
$ src/credentials/out/chip-cert validate-att-cert \ --dac credentials/test/attestation/"test-DAC-${VID}-${PID}-cert".pem \ --pai credentials/test/attestation/"test-PAI-${VID}-cert".pem \ --paa credentials/test/attestation/Chip-Test-PAA-NoVID-Cert.pem
您可以使用
openssl
检查密钥:$ openssl ec -noout -text -in \ credentials/test/attestation/test-DAC-${VID}-${PID}-key.pem
输出示例:
read EC key Private-Key: (256 bit) priv: c9:f2:b3:04:b2:db:0d:6f:cd:c6:be:f3:7b:76:8d: 8c:01:4e:0b:9e:ce:3e:72:49:3c:0e:35:63:7c:6c: 6c:d6 pub: 04:4f:93:ba:3b:bf:63:90:73:98:76:1e:af:87:79: 11:e6:77:e8:e2:df:a7:49:f1:7c:ac:a8:a6:91:76: 08:5b:39:ce:6c:72:db:6d:9a:92:b3:ba:05:b0:e8: 31:a0:bf:36:50:2b:5c:72:55:7f:11:c8:01:ff:3a: 46:b9:19:60:28 ASN1 OID: prime256v1 NIST CURVE: P-256
您还可以使用
openssl
检查生成的证书:$ openssl x509 -noout -text -in \ credentials/test/attestation/test-DAC-${VID}-${PID}-cert.pem
输出示例:
Certificate: Data: Version: 3 (0x2) Serial Number: 2875998130766646679 (0x27e9990fef088d97) Signature Algorithm: ecdsa-with-SHA256 Issuer: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = hexVendorId Validity Not Before: Jun 28 14:23:43 2021 GMT Not After : Dec 31 23:59:59 9999 GMT Subject: CN = Matter Test DAC 0, 1.3.6.1.4.1.37244.2.1 = hexVendorId, 1.3.6.1.4.1.37244.2.2 = hexProductId Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit) pub: 04:4f:93:ba:3b:bf:63:90:73:98:76:1e:af:87:79: 11:e6:77:e8:e2:df:a7:49:f1:7c:ac:a8:a6:91:76: 08:5b:39:ce:6c:72:db:6d:9a:92:b3:ba:05:b0:e8: 31:a0:bf:36:50:2b:5c:72:55:7f:11:c8:01:ff:3a: 46:b9:19:60:28 ASN1 OID: prime256v1 NIST CURVE: P-256 X509v3 extensions: X509v3 Basic Constraints: critical CA:FALSE X509v3 Key Usage: critical Digital Signature X509v3 Subject Key Identifier: 21:0A:CA:B1:B6:5F:17:65:D8:61:19:73:84:1A:9D:52:81:19:C5:39 X509v3 Authority Key Identifier: 37:7F:24:9A:73:41:4B:16:6E:6A:42:6E:F5:E8:89:FB:75:F8:77:BB Signature Algorithm: ecdsa-with-SHA256 Signature Value: 30:45:02:20:38:8f:c5:0d:3e:90:95:dd:7d:7c:e9:5a:05:19: 1f:2d:14:08:a3:d7:0e:b5:15:6d:d3:b0:0b:f7:b8:28:4d:bf: 02:21:00:d4:05:30:43:a6:05:00:0e:b9:99:0d:34:3d:75:fe: d3:c1:4e:73:ff:e7:05:64:7a:62:8d:2d:38:8f:fd:4d:ad
私下竞价
类似的过程可用于生成自签名 PAA,但这不是必需的。
在这里,我们所做的是使用不包含 VID 信息的现有自签名开发 PAA。
如需查看生成 CD 的更多示例,请参阅 credentials/test/gen-test-cds.sh
。如需查看生成 PAA、PAI 和 DAC 的更多示例,请参阅 credentials/test/gen-test-attestation-certs.sh
替换证书
替换 PAA 和 PAI
- 运行以下帮助程序脚本,该脚本使用 CHIP 证书工具 (
chip-cert
) 生成 C 样式的证书数组。
#!/bin/bash # # generate-embeddable-certs.sh script # —---------------------------------- # # This script generates self-minted DAC and PAI. # The output may easily be included in your C++ source code. # # Edit this information with your paths and certificates folder="credentials/test/attestation" chip_cert_tool="src/credentials/out/chip-cert" cert_file_der="${folder}/test-PAI-${VID}-cert.der" cert_file_pem="${folder}/test-PAI-${VID}-cert.pem" key_file_pem="${folder}/test-PAI-${VID}-key.pem" type="Pai" printf "namespace chip {\n" printf "namespace DevelopmentCerts {\n\n" printf "#if CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID == ${PID}\n\n" printcert() { # convert cert to DER if [ -f "${cert_file_der}" ]; then rm "${cert_file_der}" fi "${chip_cert_tool}" convert-cert "${cert_file_pem}" "${cert_file_der}" --x509-der printf "// ------------------------------------------------------------ \n" printf "// ${type} CERTIFICATE ${cert_file_der} \n\n" printf "constexpr uint8_t ${type}_Cert_Array[] = {\n" less -f "${cert_file_der}" | od -t x1 -An | sed 's/\0x/g' | sed 's/\>/,/g' | sed 's/^/ /g' printf "};\n\n" printf "ByteSpan k${type}Cert = ByteSpan(${type}_Cert_Array);\n\n" printf "// ${type} PUBLIC KEY FROM ${key_file_pem} \n\n" printf "constexpr uint8_t ${type}_PublicKey_Array[] = {\n" openssl ec -text -noout -in "${key_file_pem}" 2>/dev/null | sed '/ASN1 OID/d' | sed '/NIST CURVE/d' | sed -n '/pub:/,$p' | sed '/pub:/d' | sed 's/\([0-9a-fA-F][0-9a-fA-F]\)/0x\1/g' | sed 's/:/, /g' printf "};\n\n" printf "ByteSpan k${type}PublicKey = ByteSpan(${type}_PublicKey_Array);\n\n" printf "// ${type} PRIVATE KEY FROM ${key_file_pem} \n\n" printf "constexpr uint8_t ${type}_PrivateKey_Array[] = {\n" openssl ec -text -noout -in "${key_file_pem}" 2>/dev/null | sed '/read EC key/d' | sed '/Private-Key/d' | sed '/priv:/d' | sed '/pub:/,$d' | sed 's/\([0-9a-fA-F][0-9a-fA-F]\)/0x\1/g' | sed 's/:/, /g' printf "};\n\n" printf "ByteSpan k${type}PrivateKey = ByteSpan(${type}_PrivateKey_Array);\n\n" } # generates PAI printcert type="Dac" cert_file_der="${folder}/test-DAC-${VID}-${PID}-cert.der" cert_file_pem="${folder}/test-DAC-${VID}-${PID}-cert.pem" key_file_pem="${folder}/test-DAC-${VID}-${PID}-key.pem" # generates DAC printcert printf "#endif // CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID\n" printf "} // namespace DevelopmentCerts\n" printf "} // namespace chip\n"
将 PAI 和 DAC 输出的内容复制到
DeviceAttestationCredentialsProvider::GetProductAttestationIntermediateCert
实现。在生产设备上,PAI 和 DAC 位于出厂数据中,而 CD 则嵌入到固件本身中。
如果您尚未使用工厂数据,则可能需要将 PAI 放在
src/credentials/examples/ExampleDACs.cpp
中。在这种情况下,请将生成的代码附加到ExampleDACs.cpp
文件中:ByteSpan kDacCert = ByteSpan(kDevelopmentDAC_Cert_FFF1_801F); ByteSpan kDacPrivateKey = ByteSpan(kDevelopmentDAC_PrivateKey_FFF1_801F); ByteSpan kDacPublicKey = ByteSpan(kDevelopmentDAC_PublicKey_FFF1_801F); #endif } // namespace DevelopmentCerts } // namespace chip /* ------------------------------------------ */ /* current end-of-file */ /* ------------------------------------------ */ /* ------------------------------------------ */ /* output of creds-codelab.sh script */ /* ------------------------------------------ */ namespace chip { namespace DevelopmentCerts { #if CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID == hexProductId ... ByteSpan kDacPrivateKey = ByteSpan(Dac_PrivateKey_Array); #endif // CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID } // namespace DevelopmentCerts } // namespace chip
如果您使用的是出厂数据或自定义凭据提供程序,请务必在适当的位置插入凭据。您可能需要与您的 SoC 提供商联系,以了解您平台的具体情况。
更换 CD
使用
xxd
提取 CD 文件内容的文本表示形式:$ xxd -i credentials/test/certification-declaration/Chip-Test-CD-${VID}-${PID}.der
输出示例:
unsigned char credentials_test_certification_declaration_Chip_Test_CD_hexVendorId_hexProductId_der[] = { 0x30, 0x81, 0xe9, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x07, 0x02, 0xa0, 0x81, 0xdb, 0x30, 0x81, 0xd8, 0x02, 0x01, 0x03, 0x31, 0x0d, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x30, 0x45, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x07, 0x01, 0xa0, 0x38, 0x04, 0x36, 0x15, 0x24, 0x00, 0x01, 0x25, 0x01, 0xfe, 0xca, 0x36, 0x02, 0x05, 0xce, 0xfa, 0x18, 0x25, 0x03, 0x34, 0x12, 0x2c, 0x04, 0x13, 0x5a, 0x49, 0x47, 0x32, 0x30, 0x31, 0x34, 0x31, 0x5a, 0x42, 0x33, 0x33, 0x30, 0x30, 0x30, 0x31, 0x2d, 0x32, 0x34, 0x24, 0x05, 0x00, 0x24, 0x06, 0x00, 0x25, 0x07, 0x76, 0x98, 0x24, 0x08, 0x00, 0x18, 0x31, 0x7d, 0x30, 0x7b, 0x02, 0x01, 0x03, 0x80, 0x14, 0x62, 0xfa, 0x82, 0x33, 0x59, 0xac, 0xfa, 0xa9, 0x96, 0x3e, 0x1c, 0xfa, 0x14, 0x0a, 0xdd, 0xf5, 0x04, 0xf3, 0x71, 0x60, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x30, 0x0a, 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x04, 0x03, 0x02, 0x04, 0x47, 0x30, 0x45, 0x02, 0x20, 0x53, 0x25, 0x03, 0x2c, 0x96, 0x50, 0xb6, 0x64, 0xf4, 0x18, 0xbf, 0x99, 0x47, 0xf8, 0x9d, 0xe6, 0xeb, 0x43, 0x94, 0xf1, 0xce, 0xb2, 0x61, 0x00, 0xe0, 0xf9, 0x89, 0xa8, 0x71, 0x82, 0x02, 0x0a, 0x02, 0x21, 0x00, 0xea, 0x0a, 0x40, 0xab, 0x87, 0xad, 0x7e, 0x25, 0xe1, 0xa1, 0x6c, 0xb1, 0x12, 0xfa, 0x86, 0xfe, 0xea, 0x8a, 0xaf, 0x4b, 0xc1, 0xf3, 0x6f, 0x09, 0x85, 0x46, 0x50, 0xb6, 0xd0, 0x55, 0x40, 0xe2 }; unsigned int credentials_test_certification_declaration_Chip_Test_CD_hexVendorId_hexProductId_der_len = 236; ```
将您在上一步中提取的文本复制到用于定义 CD 的文件中。与 PAI 和 DAC 一样,具体方法取决于您在哪个平台上进行开发。
如果您使用的是凭据示例,则可能需要替换 src/credentials/examples/DeviceAttestationCredsExample.cpp
中 ExampleDACProvider::GetCertificationDeclaration
中 kCdForAllExamples
的内容:
const uint8_t kCdForAllExamples[] = {
0x30, 0x81, 0xe9, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01,
0x07, 0x02, 0xa0, 0x81, 0xdb, 0x30, 0x81, 0xd8, 0x02, 0x01, 0x03, 0x31,
0x0d, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04,
0x02, 0x01, 0x30, 0x45, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d,
0x01, 0x07, 0x01, 0xa0, 0x38, 0x04, 0x36, 0x15, 0x24, 0x00, 0x01, 0x25,
0x01, 0xfe, 0xca, 0x36, 0x02, 0x05, 0xce, 0xfa, 0x18, 0x25, 0x03, 0x34,
0x12, 0x2c, 0x04, 0x13, 0x5a, 0x49, 0x47, 0x32, 0x30, 0x31, 0x34, 0x31,
0x5a, 0x42, 0x33, 0x33, 0x30, 0x30, 0x30, 0x31, 0x2d, 0x32, 0x34, 0x24,
0x05, 0x00, 0x24, 0x06, 0x00, 0x25, 0x07, 0x76, 0x98, 0x24, 0x08, 0x00,
0x18, 0x31, 0x7d, 0x30, 0x7b, 0x02, 0x01, 0x03, 0x80, 0x14, 0x62, 0xfa,
0x82, 0x33, 0x59, 0xac, 0xfa, 0xa9, 0x96, 0x3e, 0x1c, 0xfa, 0x14, 0x0a,
0xdd, 0xf5, 0x04, 0xf3, 0x71, 0x60, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86,
0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x30, 0x0a, 0x06, 0x08, 0x2a,
0x86, 0x48, 0xce, 0x3d, 0x04, 0x03, 0x02, 0x04, 0x47, 0x30, 0x45, 0x02,
0x20, 0x53, 0x25, 0x03, 0x2c, 0x96, 0x50, 0xb6, 0x64, 0xf4, 0x18, 0xbf,
0x99, 0x47, 0xf8, 0x9d, 0xe6, 0xeb, 0x43, 0x94, 0xf1, 0xce, 0xb2, 0x61,
0x00, 0xe0, 0xf9, 0x89, 0xa8, 0x71, 0x82, 0x02, 0x0a, 0x02, 0x21, 0x00,
0xea, 0x0a, 0x40, 0xab, 0x87, 0xad, 0x7e, 0x25, 0xe1, 0xa1, 0x6c, 0xb1,
0x12, 0xfa, 0x86, 0xfe, 0xea, 0x8a, 0xaf, 0x4b, 0xc1, 0xf3, 0x6f, 0x09,
0x85, 0x46, 0x50, 0xb6, 0xd0, 0x55, 0x40, 0xe2
};
构建目标
使用新创建的凭据构建并刷写目标。此部分视平台而定。如需了解详情,请参阅您的 SoC 文档或支持的设备。
调试设备
您现在可以按照配对 Matter 设备中所述的步骤,在 Google Home platform 上调试您的 Matter 设备。
使用 chip-tool
调试问题
chip-tool
是一款很实用的工具,可用于检查您的设备是否发送了正确的证书。要进行构建,请按以下步骤操作:
$ cd examples/chip-tool
$ gn gen out/debug
Done. Made 114 targets from 112 files in 157ms
$ ninja -C out/debug
ninja: Entering directory `out/debug'
$ cd ../..
如需启用额外的日志,每当运行 chip-tool
时,都请务必传递 --trace_decode 1
标志。此外,最好使用 --paa-trust-store-path
标志传递 PAA 文件的路径。
因此,要使用 BLE 调试 Thread 设备,您可以运行:
```
$ examples/chip-tool/out/debug/chip-tool pairing ble-thread 1 \
hex:Thread_credentials \
pairing_code \
discriminator \
--paa-trust-store-path <path to PAA folder> \
--trace_decode 1
```
对于测试设备,<PAIRING CODE>
为 20202021
,<DISCRIMINATOR>
为 3840
。
如需从 Google Nest Hub (2nd gen) 获取 Thread 凭据,您可以运行以下命令:
$ adb connect border_router_ip_address
$ adb -e shell ot-ctl dataset active -x
$ adb disconnect
如需调试 Wi-Fi 设备,您可以使用 ble-wifi
选项:
$ examples/chip-tool/out/debug/chip-tool pairing ble-wifi 1 "SSID" SSID_password pairing_code discriminator