OpenHarmony应用签名 - 厂商私有签名 原创 精华
概述
文档环境
开发环境:Windows 11
DevEco Studio 版本:DevEco Studio 3.1 Release(3.1.0.500)
SDK 版本:3.2.12.5(Full SDK)
开发板型号:DAYU 200
系统版本:OpenHarmony 3.2 Release
涉及仓库:Hap包签名工具[developtools_hapsigner]
功能简介
为了保证OpenHarmony应用的完整性和来源可靠,在应用构建时需要对应用进行签名。经过签名的应用才能在真机设备上安装、运行、和调试。developtools_hapsigner仓提供了签名工具的源码,包含密钥对生成、CSR文件生成、证书生成、Profile文件签名、Hap包签名等功能。
OpenHarmony系统中有一套默认签名信息,用于应用的开发和调试。当系统厂商正式发布系统时,需要新增或替换私有签名信息,本篇文档将介绍如何生成私有签名并在系统中进行配置。本文档需准备Java和Gradle编译环境。
基本概念
- 非对称密钥对:数据签名/验签的基础,应用签名工具实现了标准的非对称密钥对生成功能(支持的密钥对类型包括ECC P384/256、RSA2048/3072/4096)
- CSR:Certificate Signing Request 证书签发请求是生成证书的前提,他包括证书的公钥、证书主题和私钥签名,在申请证书之前,需要先基于密钥对生成CSR,然后提交给CA签发证书。
- 证书:OpenHarmony采用RFC5280标准构建X509证书信任体系。用于应用签名的OpenHarmony证书共有三级,分为:根CA证书、中间CA证书、最终实体证书,其中最终实体证书分为应用签名证书和profile签名证书。应用签名证书表示应用开发者的身份,可保证系统上安装的应用来源可追溯,profile签名证书实现对profile文件的签名进行验签,保证profile文件的完整性。
- HAP:OpenHarmony Ability Package 是Ability的部署包,OpenHarmony应用代码围绕Ability组件展开,它是由一个或者多个Ability组成。
- Profile文件:HarmonyAppProvision 配置文件,hap包中的描述文件,该描述文件描述了已授权的证书权限和设备ID信息等信息。
Profile签名场景:
应用签名场景:
如何生成私有签名
准备签名工具
- 克隆developtools_hapsigner仓库
git clone https://gitee.com/openharmony/developtools_hapsigner.git
- 命令行打开文件目录至developtools_hapsigner/hapsigntool,执行命令进行编译打包
gradle build 或者 gradle jar
- 编译后得到二进制文件,目录为:
developtools_hapsigner/hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar
签名工具说明
- 生成密钥对
- 生成证书签名请求
- 生成根CA/中间CA证书,如果密钥不存在,一起生成密钥
- 生成应用调试/发布证书
- 生成profile调试/发布证书
- 通用证书生成,可以生成自定义证书
- ProvisionProfile文件签名
- ProvisionProfile文件验签
- hap应用包签名
- hap应用包文件验签
生成签名文件
- 生成密钥对,keystorePwd为密钥库口令。
java -jar hap-sign-tool.jar generate-keypair -keyAlias "OpenHarmony-Tizi" -keyAlg "ECC" -keySize "NIST-P-256" -keystoreFile "OpenHarmony-Tizi.p12" -keyPwd "Pwd-Tizi-1" -keystorePwd "Pwd-Tizi-2"
- 生成RootCA证书,subject为RootCA的证书主题,用于配置trusted_root_ca.json。
java -jar hap-sign-tool.jar generate-ca -keyAlias "OpenHarmony-Tizi-rootCA" -signAlg "SHA256withECDSA" -keyAlg "ECC" -keySize "NIST-P-256" -subject "C=CN, O=OpenHarmony-Tizi-rootCA, OU=OpenHarmony-Tizi-rootCA Community, CN=OpenHarmony Application Root CA" -keystoreFile "OpenHarmony-Tizi.p12" -outFile "OpenHarmony-Tizi-rootCA.cer" -keyPwd "Pwd-Tizi-3" -keystorePwd "Pwd-Tizi-2" -validity "365"
- 生成SubCA证书。
java -jar hap-sign-tool.jar generate-ca -keyAlias "OpenHarmony-Tizi-subCA" -signAlg "SHA256withECDSA" -keyAlg "ECC" -keySize "NIST-P-256" -subject "C=CN, O=OpenHarmony-Tizi-subCA, OU=OpenHarmony-Tizi-subCA Community, CN=OpenHarmony Application Sub CA" -keystoreFile "OpenHarmony-Tizi.p12" -outFile "OpenHarmony-Tizi-subCA.cer" -keyPwd "Pwd-Tizi-4" -keystorePwd "Pwd-Tizi-2" -issuer "C=CN, O=OpenHarmony-Tizi-rootCA, OU=OpenHarmony-Tizi-rootCA Community, CN=OpenHarmony Application Root CA" -issuerKeyAlias "OpenHarmony-Tizi-rootCA" -issuerKeyPwd "Pwd-Tizi-3" -validity "365"
- 生成应用调试/发布证书,subject用于配置trusted_apps_sources.json中的app-signing-cert项。
java -jar hap-sign-tool.jar generate-app-cert -keyAlias "OpenHarmony-Tizi-subCA" -signAlg "SHA256withECDSA" -subject "C=CN, O=OpenHarmony-Tizi-app-cert, OU=OpenHarmony-Tizi-app-cert Community, CN=OpenHarmony Application Release" -keystoreFile "OpenHarmony-Tizi.p12" -subCaCertFile "OpenHarmony-Tizi-subCA.cer" -rootCaCertFile "OpenHarmony-Tizi-rootCA.cer" -outForm "certChain" -outFile "OpenHarmony-Tizi-app-cert.pem" -keyPwd "Pwd-Tizi-4" -keystorePwd "Pwd-Tizi-2" -issuer "C=CN, O=OpenHarmony-Tizi-subCA, OU=OpenHarmony-Tizi-subCA Community, CN=OpenHarmony Application Sub CA" -issuerKeyAlias "OpenHarmony-Tizi-subCA" -issuerKeyPwd "Pwd-Tizi-4" -validity "365"
- 生成ProfileCA证书,subject用于配置trusted_apps_sources.json中的issuer-ca项。
java -jar hap-sign-tool.jar generate-ca -keyAlias "OpenHarmony-Tizi-profileCA" -signAlg "SHA256withECDSA" -keyAlg "ECC" -keySize "NIST-P-256" -subject "C=CN, O=OpenHarmony-Tizi-subCA, OU=OpenHarmony-Tizi-subCA Community, CN=OpenHarmony Application CA" -keystoreFile "OpenHarmony-Tizi.p12" -outFile "OpenHarmony-Tizi-profileCA.cer" -keyPwd "Pwd-Tizi-5" -keystorePwd "Pwd-Tizi-2" -issuer "C=CN, O=OpenHarmony-Tizi-rootCA, OU=OpenHarmony-Tizi-rootCA Community, CN=OpenHarmony Application Root CA" -issuerKeyAlias "OpenHarmony-Tizi-rootCA" -issuerKeyPwd "Pwd-Tizi-3" -validity "365"
- 生成应用Release版profile调试/发布证书,subject用于配置trusted_apps_sources.json中的profile-signing-certificate项。
java -jar hap-sign-tool.jar generate-profile-cert -keyAlias "OpenHarmony-Tizi-profileCA" -signAlg "SHA256withECDSA" -subject "C=CN, O=OpenHarmony-Tizi-profile-cert, OU=OpenHarmony-Tizi-profile-cert Community, CN=OpenHarmony Application Profile Release" -keystoreFile "OpenHarmony-Tizi.p12" -subCaCertFile "OpenHarmony-Tizi-profileCA.cer" -rootCaCertFile "OpenHarmony-Tizi-rootCA.cer" -outForm "certChain" -outFile "OpenHarmony-Tizi-profile-cert-release.pem" -keyPwd "Pwd-Tizi-5" -keystorePwd "Pwd-Tizi-2" -issuer "C=CN, O=OpenHarmony-Tizi-subCA, OU=OpenHarmony-Tizi-subCA Community, CN=OpenHarmony Application CA" -issuerKeyAlias "OpenHarmony-Tizi-profileCA" -issuerKeyPwd "Pwd-Tizi-5" -validity "365"
- 生成应用Debug版profile调试/发布证书,subject用于配置trusted_apps_sources.json中的profile-debug-signing-certificate项。
java -jar hap-sign-tool.jar generate-profile-cert -keyAlias "OpenHarmony-Tizi-profileCA" -signAlg "SHA256withECDSA" -subject "C=CN, O=OpenHarmony-Tizi-profile-cert, OU=OpenHarmony-Tizi-profile-cert Community, CN=OpenHarmony Application Profile Debug" -keystoreFile "OpenHarmony-Tizi.p12" -subCaCertFile "OpenHarmony-Tizi-profileCA.cer" -rootCaCertFile "OpenHarmony-Tizi-rootCA.cer" -outForm "certChain" -outFile "OpenHarmony-Tizi-profile-cert-debug.pem" -keyPwd "Pwd-Tizi-5" -keystorePwd "Pwd-Tizi-2" -issuer "C=CN, O=OpenHarmony-Tizi-subCA, OU=OpenHarmony-Tizi-subCA Community, CN=OpenHarmony Application CA" -issuerKeyAlias "OpenHarmony-Tizi-profileCA" -issuerKeyPwd "Pwd-Tizi-5" -validity "365"
- 将OpenHarmony-Tizi-app-cert.pem中第一部分的密钥,把回车转换为\n字符,放入UnsgnedReleasedProfileTemplate.json的distribution-certificate中。例如:
转换前:
转换后:
- ProvisionProfile文件签名
java -jar hap-sign-tool.jar sign-profile -keyAlias "OpenHarmony-Tizi-profileCA" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile "OpenHarmony-Tizi-profile-cert-release.pem" -inFile "UnsgnedReleasedProfileTemplate.json" -keystoreFile "OpenHarmony-Tizi.p12" -outFile "com.openharmony.signtest.p7b" -keyPwd "Pwd-Tizi-5" -keystorePwd "Pwd-Tizi-2"
- hap应用包签名
java -jar hap-sign-tool.jar sign-app -keyAlias "OpenHarmony-Tizi-subCA" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "OpenHarmony-Tizi-app-cert.pem" -profileFile "com.openharmony.signtest.p7b" -inFile "entry-default-unsigned.hap" -keystoreFile "OpenHarmony-Tizi.p12" -outFile "entry-default-signed.hap" -keyPwd "Pwd-Tizi-4" -keystorePwd "Pwd-Tizi-2"
配置系统证书
- 系统中证书配置文件位于/etc/security/中
- 配置 trusted_apps_sources.json 文件。注意“,”符号后面需要加入空格才可正常匹配。
- 配置 trusted_root_ca.json 文件,将 OpenHarmony-Tizi-rootCA.cer 密钥信息处理后加入到文件中。
- 将文件推送回系统中并重启。
- 安装签名应用。
参考文档
OpenHarmony Gitee Docs - Hap包签名工具概述
OpenHarmony Gitee Docs - Hap包签名工具指导
OpenHarmony Gitee Docs - HarmonyAppProvision配置文件说明
很完整的实践流程
私有签名配置如何导入IDE呢,我进行IDE手动配置时Certpath file(*.cer)不知道配置哪一个,导致hap编译失败,出现诸如这类错误:
Details: Profile cert 'C:/Users/xxx/Desktop/demo/OpenHarmony-Tizi.cer' must a cert chain
Detail: Please check the message from tools.
可以参考https://ost.51cto.com/posts/21466这篇文章,CER文件实际就是PEM文件,可以直接把PEM的后缀改为CER使用。
通过java -jar hap-sign-tool.jar sign-app命令签名后的hap可以正常安装和运行。
按照上面说的直接修改PEM后缀为CER或者
运行hap-sign-tool.jar generate-app-cert命令生成时将后缀改为CER,IDE编译还是报错:
> hvigor ERROR: Failed :entry:default@SignHap...
> hvigor ERROR: Tools execution failed.
06-25 15:53:41 ERROR - hap-sign-tool: error: {errorcode:0,message:generate SignerBlock failed}
com.ohos.hapsigntool.hap.exception.SignatureException: {errorcode:0,message:generate SignerBlock failed}
at com.ohos.hapsigntool.hap.sign.SignHap.generateHapSignatureSchemeBlock(SignHap.java:304) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.SignHap.generateHapSigningBlock(SignHap.java:202) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.SignHap.getHapSigningBlock(SignHap.java:190) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.SignHap.sign(SignHap.java:350) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.provider.SignProvider.sign(SignProvider.java:302) [hap-sign-tool.jar:?]
at com.ohos.hapsigntool.api.SignToolServiceImpl.signHap(SignToolServiceImpl.java:319) [hap-sign-tool.jar:?]
at com.ohos.hapsigntool.HapSignTool.runSignApp(HapSignTool.java:285) [hap-sign-tool.jar:?]
at com.ohos.hapsigntool.HapSignTool.dispatchParams(HapSignTool.java:152) [hap-sign-tool.jar:?]
at com.ohos.hapsigntool.HapSignTool.processCmd(HapSignTool.java:109) [hap-sign-tool.jar:?]
at com.ohos.hapsigntool.HapSignTool.main(HapSignTool.java:79) [hap-sign-tool.jar:?]
Caused by: com.ohos.hapsigntool.hap.exception.SignatureException: {errorcode:0,message:Signature did not verify}
at com.ohos.hapsigntool.hap.sign.BcPkcs7Generator.verifySignatureFromServer(BcPkcs7Generator.java:252) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.BcPkcs7Generator.getSignerInfo(BcPkcs7Generator.java:164) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.BcPkcs7Generator.generateSignedData(BcPkcs7Generator.java:91) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.SignHap.generateSignerBlock(SignHap.java:331) ~[hap-sign-tool.jar:?]
at com.ohos.hapsigntool.hap.sign.SignHap.generateHapSignatureSchemeBlock(SignHap.java:302) ~[hap-sign-tool.jar:?]
... 9 more
Detail: Please check the message from tools.
> hvigor ERROR: BUILD FAILED in 4 s 838 ms
使用的PEM文件为OpenHarmony-Tizi-app-cert.pem,更改为CER。
感谢大佬指导,keyAlias和keyPassword更正后验证OK
大佬,配置系统证书这一步,我在文章最后的参考文档里没发现有提及,请问官方有指导文档么?
官方Docs中现在暂时没有文档进行说明。
大佬,本篇是演示了release版本的签名,看第7步已经生成了应用Debug版profile调试/发布证书,但是想问一下应该怎么使用呢;和使用release版的证书的区别在哪里;我通过第9步进行ProvisionProfile文件签名,生成了debug级的p7b,然后将ide里p7b文件那栏换成了生成的debug的p7b,编译成功但是install失败,报的错是"error: signature verification failed due to not trusted app source.",在这之前使用release的p7b去install应用是ok的,请问一下是什么原因导致的,是我哪里没有配置或者更改吗?
检查一下是否把第7步中的,subject配置到了trusted_apps_sources.json中的profile-debug-signing-certificate项里。
有的,配置了
在用ide编译私有签名应用的时候,正常来说只需要一个p12,一个cer,一个release或者一个debug的p7b就可以了对吧
我有试过:在处理UnsgnedReleasedProfileTemplate.json文件的时候,type字段改成debug,但直接就无法生成debug.p7b了,报错:"Require cert in bundleInfo";大佬有试过使用debug等级的p7b进行签名编译安装吗?
Debug对应的Profile文件为UnsgnedDebugProfileTemplate.json。
我也是遇到了跟您一样的轻松是一模一样的配置,但是在Openharmony4.0上是ok的,但是升级之后在Openharmony4.1上就是不行,死活都不行呢