HarmonyOS鸿蒙Next应用开发过程签名的使用和获取

一、证书申请与应用签名

DevEco Studio 签名：

DevEco Studio 提供了自动签名与手动签名两种方案，在连接手机后，进入 file->Project Structure->Project->Signing Configs，勾选“Automatically generate signature”，即可完成自动签名。详细参考自动签名。相较于手动签名，自动签名无需申请配置证书，更便于调试。

在使用 ACL 权限或通过 AGC 开通服务等必须使用手动签名的场景时，则需先在 DevEco Studio 中配置以下内容：密钥库（.p12）文件、密钥库密码、Key alias（密钥别名）、Key password（密钥密码）、Profile、数字证书（.cer）文件。其中前四项和证书请求（.csr）文件在 IDE-Build- Generate Key and CSR 中配置，然根据证书请求文件在 AppGallery Connect 上申请数字证书和 Profile 文件，实现手动签名，详细配置和申请步骤参考手动签名。

数字证书（.cer 文件）需根据生成的证书请求文件在 AGC 上申请，分为分为调试证书（debug 证书）和发布证书（release 证书）。调试证书用于应用的安装调试，发布证书用于应用的上架分发。不可相互替代使用，否则会出现上架失败或 9568322 错误码的安装失败。

Profile（.p7b）文件包含了应用包名、申请权限、允许调试设备列表等信息，如项目使用了受限开发权限未在申请 Profile 文件时配置，或者未在 Profile 中添加调试设备，则会在签名后安装调试时出现 9568289 和 9568322 安装报错。

对应不希望在应用市场上架的企业内部应用，可按照发布企业内部应用流程。在通过企业内部应用分发资格申请后，申请组织内发布证书和 Profile。详见发布企业内部应用。

签名工具签名：

除 DevEco Studio 提供的签名方式外，还有应用包签名工具，可用于对未签名安装包或是流水线签名。签名工具分为命令行签名和一键签名。命令行签名可使用以下命令对 HAP 包签名。为提高效率，也可使用签名工具目录 autosign 中提供的一键签名脚本。

java -jar hap-sign-tool.jar sign-app -keyAlias "key0" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "test.cer" -profileFile "test.p7b" -inFile "hap-unsigned.hap" -keystoreFile "test.p12" -outFile "result\hap-signed.hap" -keyPwd "123456" -keystorePwd "123456" -signCode "1"

二、签名替换

手动替换：

当项目包名、权限变化、证书过期时需要替换签名：如自动签名证书替换成调试证书，调试证书替换成发布证书等。

项目签名与包名绑定，如果直接修改包名，会出现“hvigor ERROR: BundleName in the project configuration does not match that in the SigningConfigs”。需先删除根目录 build-profile.json5 文件-signingConfigs 签名配置，重新签名才能编译安装成功。

AGC 上申请的 Profile 和证书与 IDE 中生成的密钥（.p12）、Key alias 以及密码相绑定。如果是自动签名替换为手动签名，需要全部替换（自动签名 Key alias 默认为 debugKey，需要替换成在 ide 中生成密钥时的实际值，否则应用安装时签名会校验失败）；如果是证书过期或者发布证书切换为调试证书，则是看申请证书时是否还是用的相同的证书请求（.csr）文件。如果相同，则只用替换 Profile 和证书。

动态修改：

多人合作开发时，hvigor 提供了 hook 和 overrides 关键字两种方案实现动态修改签名，两者相比 hook 方式更加灵活，功能也更全面，可以在根目录 hvigorfile.ts 文件中，通过 hvigor 对象提供的上下文直接获取和修改配置。详细使用参考：通过 hook 以及插件上下文动态配置构建配置和基于动态配置签名的多人协同开发应用签名解决方案。

三、签名信息 SignatureInfo 获取

应用包签名信息 SignatureInfo 包含 appId、fingerprint、appIdentifier 三个属性：

• appId：包名+证书公钥组成，长度不固定，与包名有关。
• fingerprint：应用包指纹信息，签名证书（.cer 文件）的 SHA-256hash 值，当签名证书变化时，该字段也会变化，字段长度 64。
• appIdentifier：应用唯一标识，由云端分配，与 AGC 上的 APP ID 相同，字段长度 19。

常用的代码或者命令行获取方式均需应用安装在手机上才能获取，某些场景，比如未上架应用接入其他应用 SDK 时，可能会需要提供包的签名信息，由于 release 证书签名的应用不能在本地安装调试，不能通过代码和命令行查询，以下也提供了 release 证书签名信息的获取方式。

debug 证书签名应用：

方案一：代码方式

• getBundleInfoForSelf。

BundleFlag 需设置 GET_BUNDLE_INFO_WITH_SIGNATURE_INFO，否则获取到的 signatureInfo 为空。

let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION | 
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO; 

bundleManager.getBundleInfoForSelf(bundleFlags).then((data) => { 
  hilog.info(0x0000, 'testTag', 'getSignatureInfo.appId successfully. Data: %{public}s', 
    data.signatureInfo.appId); 
  hilog.info(0x0000, 'testTag', 'getSignatureInfo.fingerprint. Data: %{public}s', 
    data.signatureInfo.fingerprint); 
  hilog.info(0x0000, 'testTag', 'getSignatureInfo.appIdentifier successfully. Data: %{public}s', 
    data.signatureInfo.appIdentifier); 
}).catch((err: BusinessError) => { 
  hilog.error(0x0000, 'testTag', 'getBundleInfoForSelf failed. Cause: %{public}s', err.message); 
});

native 侧获取参考：OH_NativeBundle_GetAppId()。

方案二：命令行方式

• bm 工具。

获取 appId 命令：bm dump -n com.example.mysignatureinfo | grep appId； 获取 fingerprint 命令：bm dump -n com.example.mysignatureinfo | grep fingerprint； 获取 appIdentifier 命令：bm dump -n com.example.mysignatureinfo | grep appIdentifier。

release 证书签名应用：

1、获取 appid：

appid 的生成与密钥（.p12）文件有关，只要密钥（.p12）文件不变，debug 证书与 release 证书签名的应用 appid 的值相同，可用 debug 证书签名的应用通过接口或命令行查询。

2、获取 fingerprint：

指纹信息 fingerprint 是 Profile 文件（.p7b 文件）的 SHA256 值。

• 找到 .p7b 文件，打开后搜索 certificate，将对应字段拷贝至新文本文件，并改名为 xxx.cer。

如果有签名后的 hap 包，也可以以文本格式打开 hap 包，同样方式搜索 certificate，拷贝对应字段（下图为 debug 证书示例，为 development-certificate 对应内容，如果是 release 证书，则为 distribution-certificate）。

使用 keytool 工具（在 DevEco Studio 安装目录下的 jbr/bin 文件夹内）打印对应的证书的指纹 keytool -printcert -file xxx.cer。

keytool 工具是 JDK 提供的一个命令行工具，用于管理密钥库，可执行多种操作，包括生成密钥对、导入导出证书、查看密钥库内容等，参考keytool 使用手册。可使用 -printcert 查看导出的证书信息，去掉冒号后即可得到指纹信息 fingerprint。

3、获取 appIdentifier：

appIdentifier 与 AGC 上的 APP ID 相同，可在 AppGallery Connect 上查询，我的应用->应用信息->APP ID

四、签名相关典型问题及解决方案

1、自动签名失败

• Q：The signature does not take effect or has expired. It may be the current system time is inaccurate, please calibrate the system time and sign again.

• A：本地系统时间与北京时间不一致导致，日期和时间设置里点击“立即同步”。

• Q：Failed to download the certificate file. Check the following configurations: Network connection, HTTP Proxy etc. HTTP Proxy settings

• A：网络问题导致，确认当前设备是否连接网络。

• Q：Failed to read the .csr file, please try again later

• A：可通过清理临时文件、重启 IDE、清理工程等流程重新尝试自动签名。

• Q：Unable to create the profile due to a lack of a device. Connect a device via IP or USB first.

• A：确认设备是否连接，设置->开发者选项-USB 调试是否打开。

• Q：元服务签名，提示 Invalid AppId in the bundle name.

• A：详见元服务签名时，提示 “Invalid AppId in the bundle name.”。

2、编译安装失败

问题描述：9568289 Error: install failed due to grant request permissions failed.

• 问题根因：通常是由于应用配置了受限权限导致。
• 解决方案：如不能判断哪个权限导致的，在 hilog 日志中搜关键字：need acl，确定具体哪个权限导致的问题，然后查询受限开放权限列表，确认是否该权限是否可申请，如在开放列表内，参考使用 ACL 的签名配置指导配置重新签名打包安装，如不在列表内则为系统权限，不支持三方应用使用。

问题描述：9568322 Error: signature verification failed due to not trusted app source.

• 问题根因：通常是设备 UDIM 未添加或者使用了 release 证书签名的应用导致。
• 解决方案：确认是否使用的是 debug 证书，然后在 hilog 日志中搜索 HapVerify，current device is type 返回 0 表示当前设备非研发设备，会校验 udid 是否添加，返回 1 则表示是研发设备，不会校验 udid, 以下日志可看出，非研发设备且未添加 udid，解决方案请参考手动签名，在 UnsgnedDebugProfileTemplate.json 文件中添加该调试设备的 UDIM。

问题描述：9568329 Error: verify signature failed.

• 问题根因：可能是签名信息中的包名与应用包名不一致导致。
• 解决方案：
  • 打开签名使用的 Profile（.p7b）文件，搜索 bundle-name，确认与 app.json5 下的 bundleName 是否一致。
  • 确认是否有依赖三方 HSP 包，应用安装时会校验项目中所有 hap 和 hsp 的 bundleName，如果有依赖其他非同包名工程打出的 HSP 包，也不是集成态 HSP，会出现该错误码。该场景建议 HSP 提供方提供集成态 HSP 包使用，或者使用方使用打包工具打包归一指令 packagenormalize修改依赖的 HSP 包名。

问题描述：9568332 Error: install sign info inconsistent.

• 问题根因：待安装的应用与设备上已安装的应用不一致导致，通常是开发者使用了新的签名文件导致。
• 解决方案：卸载已安装的应用后，重新安装该应用。

问题描述：9568393 Error: verify code signature failed

• 问题根因：代码签名失败。
• 解决方案：使用签名工具校验签名，下载签名工具，执行命令：java -jar hap-sign-tool.jar verify-app -outCertChain out.cer -outProfile out.p7b -inFile XXX.hap。

如果出现“can not find codesign block”，则说明没有代码签名，需使用签名工具重新对应用签名，如果返回“verify codesign success”，则表示签名正常。

如果红框处出现“ide_demo_app”，则在 ide 签名的时候，需要勾选 SupportHarmonyOS，再重新签名。

如果出现“OpenHarmony Application Release”，则需切换调试证书。