虽然并非必需,但某些测试场景需要创建非生产环境 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 规范。
安装 Matter SDK
这些说明假定您已安装并正常运行 Matter SDK。如需了解详情,请参阅 Github 上的文档或Matter 使用入门。
如果您没有 hexdump 实用程序 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 outgn输出示例:Done. Made 5774 targets from 289 files in 658ms运行构建:
$ ninja -C outninja输出示例:ninja: Entering directory `out' [2000/2000] stamp obj/default.stamp
铸造证书
将自定义 VID/PID 导出为环境变量,以减少在修改命令实参时出现 笔误的可能性:
$ cd ../..
$ export VID=hexVendorId
$ export PID=hexProductId
生成 CD
使用
chip-cert生成 CD。目前,Commissioner 仅验证 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 信息,但省略该信息可让您在测试时拥有更大的灵活性。如果您需要其他 PID 的 DAC,则只需执行 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
您可以使用类似的过程来生成自签名 PAA,但这样做不是必需的。
相反,我们在此处使用的是现有的自签名开发 PAA,其中不包含 VID 信息。
如需查看生成 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; ```将上一步中提取的文本复制到用于在 build 中定义 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