OpenHarmony系统应用签名实操指南

> 作者：文字与文明
> 平台：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",
    "bundle-info": {
        "developer-id": "OpenHarmony",
        "distribution-certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
        "bundle-name": "com.example.fileshare",
        "apl": "system_basic",
        "app-feature": "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": []
    },
    "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 字段的权限）
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 编码的密码是 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 签名

七、签名文件在线获取（GitCode）

除从源码目录复制外，也可直接在线访问 developtools_hapsigner 仓库的 dist 分支获取签名文件，点击文件名后进入详情页点击"下载"即可。

GitCode 在线文件列表

文件名	在线地址	说明
`OpenHarmony.p12`	gitcode.com/.../OpenHarmony.p12	平台 P12 密钥库（含所有平台密钥）
`OpenHarmonyApplication.pem`	gitcode.com/.../OpenHarmonyApplication.pem	应用根证书（含 Root CA → Sub CA → App Release 三层链）
`OpenHarmonyProfileDebug.pem`	gitcode.com/.../OpenHarmonyProfileDebug.pem	Debug Profile 签名证书
`OpenHarmonyProfileRelease.pem`	gitcode.com/.../OpenHarmonyProfileRelease.pem	Release Profile 签名证书
`UnsgnedReleasedProfileTemplate.json`	gitcode.com/.../UnsgnedReleasedProfileTemplate.json	Release Profile 签名模板
`UnsgnedDebugProfileTemplate.json`	gitcode.com/.../UnsgnedDebugProfileTemplate.json	Debug Profile 签名模板
`hap-sign-tool.jar`	gitcode.com/.../hap-sign-tool.jar	签名工具

在线地址格式：https://gitcode.com/openharmony/developtools_hapsigner/blob/master/dist/<filename>

源码中的平台签名文件位置（仅 launcher 等预置系统应用有）

applications/standard/launcher/signature/
├── OpenHarmony.p12              ← 平台 P12（含所有平台密钥）
├── OpenHarmonyApplication.cer   ← 完整证书链
└── launcher.p7b                 ← launcher 的预置 Profile

prebuilts 目录中的 SDK 签名文件

prebuilts/ohos-sdk/linux/26/toolchains/lib/
├── OpenHarmony.p12
├── 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`

文件分享类应用需要的 FILE_ACCESS_MANAGER 和 FILE_ACCESS_PERSIST 属于 system_grant 权限。

> 本文基于 OpenHarmony 源码 3.2+ 版本整理，签名工具位于 developtools/hapsigner。

posted @ 2026-05-13 19:22 getmoon 阅读(134) 评论(0) 收藏举报

刷新页面返回顶部

get_moon