当前位置：首页 > news >正文

OpenHarmony应用签名实操指南：从文件结构到IDE配置

news 2026/5/13 19:30:04

OpenHarmony应用签名实操指南：从文件结构到IDE配置

作者：文字与文明
平台：OpenHarmony 3.2+
适合读者：需要为应用签上系统签名（hos_system_app）的开发者

一、签名文件体系概览

在 OpenHarmony 源码中，签名相关文件分散在两个位置：

文件类型	位置	说明
Platform P12	`applications/standard/launcher/signature/OpenHarmony.p12`	平台密钥库，含所有平台密钥
应用证书（含证书链）	`applications/standard/launcher/signature/OpenHarmonyApplication.cer`	Root CA → Sub CA → App Release 三层链
Profile 证书	`developtools/hapsigner/dist/OpenHarmonyProfileDebug.pem` / `OpenHarmonyProfileRelease.pem`	用于对 Profile 签名
签名工具	`developtools/hapsigner/dist/hap-sign-tool.jar`	Java 签名工具

二、OpenHarmony.p12 包含的密钥别名

用 keytool -list -keystore OpenHarmony.p12 -storetype PKCS12 -storepass 123456 可以看到：

别名	用途
`openharmony application release`	Platform App 签名密钥（签系统应用 HAP）
`openharmony application profile release`	Platform Profile 签名密钥（签 release p7b）
`openharmony application profile debug`	Platform Profile 签名密钥（签 debug p7b）
`openharmony software signature`	软件级签名（用于其他场景）
`openharmony application root ca`	根 CA 密钥
`openharmony application ca`	中间 CA 密钥

所有密码默认都是 123456。

三、签名配置文件结构

签名配置以 JSON 形式存在，模板位于 developtools/hapsigner/dist/UnsgnedDebugProfileTemplate.json：

{"version-name": "2.0.0","version-code": 2,"type": "release",                          // release 或 debug"bundle-info": {"developer-id": "OpenHarmony","distribution-certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----","bundle-name": "com.example.fileshare",  // 必须唯一"apl": "system_basic",                  // normal / system_basic / system_core"app-feature": "hos_system_app"         // hos_normal_app / hos_system_app},"acls": {"allowed-acls": ["ohos.permission.FILE_ACCESS_MANAGER","ohos.permission.FILE_ACCESS_PERSIST","ohos.permission.GET_BUNDLE_INFO_PRIVILEGED","ohos.permission.VIBRATE"]},"permissions": {"restricted-permissions": ["ohos.permission.READ_CONTACTS"]},"issuer": "pki_internal"
}

关键字段说明

bundle-name：应用唯一标识，需要在签名之前填入实际包名
app-feature：普通应用填 hos_normal_app，系统应用填 hos_system_app
apl：普通应用 normal，系统基础应用 system_basic，系统核心应用 system_core
acls.allowed-acls：只填 system_grant 权限（无 reason/usedScene 字段的权限）
- 不需要填 user_grant 权限（那些由用户在运行时授权）
permissions.restricted-permissions：受限敏感权限，需要应用市场额外审核

四、从源码生成系统应用签名（.p7b）

步骤1：准备平台密钥

从源码复制平台密钥到你的工作目录：

cp applications/standard/launcher/signature/OpenHarmony.p12 ./
cp applications/standard/launcher/signature/OpenHarmonyApplication.cer ./
cp developtools/hapsigner/dist/OpenHarmonyProfileRelease.pem ./

步骤2：修改 UnsgnedReleasedProfileTemplate.json

把 bundle-name 改为你自己的应用包名，app-feature 改为 hos_system_app，apl 改为 system_basic。

步骤3：签名生成 .p7b

java -jar hap-sign-tool.jar sign-profile \-mode "localSign" \-keyAlias "openharmony application release" \-keyPwd "123456" \-inFile "UnsgnedReleasedProfileTemplate.json" \-outFile "your_app.p7b" \-keystoreFile "OpenHarmony.p12" \-keystorePwd "123456" \-signAlg "SHA256withECDSA" \-profileCertFile "OpenHarmonyProfileRelease.pem"

五、DevEco Studio IDE 签名配置

在 build-profile.json5 中配置：

{"signingConfigs": [{"name": "default","material": {"storeFile": "你的路径/OpenHarmony.p12","storePassword": "123456","keyAlias": "OpenHarmony Application Release","keyPassword": "123456","signAlg": "SHA256withECDSA","profile": "你的路径/your_app.p7b","certpath": "你的路径/OpenHarmonyApplication.cer"}}]
}

注意：Platform 密钥的密码是 123456，不是 hex 编码字符串。hex 编码的密码（如 00000016CE94F...）是 launcher 等预置系统应用在编译配置中使用的混淆方式。

六、常见错误：安装失败 9568322

Install Failed: error: failed to install bundle.
code:9568322
error: signature verification failed due to not trusted app source.

原因：设备不信任该应用的签名来源。

常见情况：

可能原因	解决方案
证书链不完整（只有叶子证书）	使用 `OpenHarmonyApplication.cer`（含完整 Root→Sub→App 链）
使用普通调试证书签了系统应用	系统应用必须用 Platform 签名
p7b 的 bundle-name 与实际应用不匹配	确保 p7b 是对你的应用重新生成的
Debug 签名在正式设备被拒绝	正式设备测试使用 release 签名
设备 UDID 不在 debug-info.device-ids 中	使用 release 签名绕过 UDID 限制

七、源码中平台签名文件位置汇总

applications/standard/launcher/signature/
├── OpenHarmony.p12              ← 平台 P12（含所有平台密钥）
├── OpenHarmonyApplication.cer   ← 完整证书链
└── launcher.p7b                 ← launcher 的预置 Profileprebuilts/ohos-sdk/linux/26/toolchains/lib/
├── OpenHarmony.p12              ← 从 hapsigner 编译产物复制
├── OpenHarmonyProfileDebug.pem
├── OpenHarmonyProfileRelease.pem
├── openharmony_sx.p7b           ← 示例：已签名的系统应用 Profile
└── system_UnsgnedReleasedProfileTemplate.json  ← 模板

八、ACL 权限与 system_grant / user_grant 的区别

在 allowed-acls 中只需要填 system_grant 权限。区分方式：

类型	特征	示例
system_grant	配置文件中直接授予，权限定义无 `reason` 和 `usedScene` 字段	`FILE_ACCESS_MANAGER`, `GET_BUNDLE_INFO_PRIVILEGED`
user_grant	权限定义中有 `reason` 和 `usedScene` 字段，需用户授权	`WRITE_IMAGEVIDEO`, `READ_CONTACTS`