一、证书申请与应用签名

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值。

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

      

      

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

      

      

   2. 使用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. lt may be the current system time is inaccurate, pleasecalibrate 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.

   问题根因：通常是设备UDID未添加或者使用了release证书签名的应用导致

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

   

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

   问题根因：可能是签名信息中的包名与应用包名不一致导致。

   解决方案：

   1. 打开签名使用的Profile（.p7b）文件，搜索bundle-name，确认与app.json5下的bundleName是否一致。

      

      

   2. 确认是否有依赖三方HSP包，应用安装时会校验项目中所有hap和hsp的bundleName，如果有依赖其他非同包名工程打出的HSP包，也不是集成态HSP，会出现该错误码。该场景建议HSP提供方提供集成态HSP包使用，或者使用方使用打包工具打包归一指令修改依赖的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”，则需切换调试证书。