HarmonyKit | 鸿蒙开发：应用签名与证书管理完全指南

引言：签名是鸿蒙应用安全的第一道防线

如果你从 Android 开发转过来，鸿蒙的签名体系会让你感到既熟悉又陌生。熟悉的是.p12、.cer、签名算法这些概念——它们背后是通用的 PKI（公钥基础设施）。陌生的是.p7b文件（Provisioning Profile）——这是鸿蒙特有的概念，它连接了应用、设备和权限，构建了一个远比 Android 签名更精细的安全模型。

这篇文章从 HarmonyKit 的实际签名配置出发，逐一解释调试证书的自动生成机制、三种证书文件的角色、签名的完整流程、生产环境签名的配置方式，以及最常见的签名相关错误与解决方案。

项目仓库：https://atomgit.com/VON-/harmony-kit

HarmonyKit 的签名配置

HarmonyKit 目前的签名配置使用 DevEco Studio 自动生成的调试证书：

{ "signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "certpath": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.cer", "keyAlias": "debugKey", "keyPassword": "0000001A9C26AE5EA7A8E394442AC6FFB81D7F7AFA35805AC58960D735B9DFA3BAE144F68AADC4287472", "profile": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.p7b", "signAlg": "SHA256withECDSA", "storeFile": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.p12", "storePassword": "0000001AA11F49C6DB4ECC2BBCBC40B96975FE70578290DE891D989C73132FC99B5DD578410FBC95B73C" } } ] }

一眼望去，六个路径/字段组成了签名配置的核心。让我们逐一解读。

三个核心证书文件的角色

.p12 文件（storeFile）：密钥的保险箱

.p12（PKCS#12）文件是一个加密容器，内部存放着开发者的私钥和证书链。它是整个签名体系中最敏感的文件——谁拥有.p12文件和密码，谁就能以你的身份签署应用。

HarmonyKit 的调试.p12文件存储在~/.ohos/config/目录下，文件名包含项目的哈希值。密码是 DevEco Studio 自动生成的 72 位十六进制字符串。

调试.p12的生成流程：

1. 首次在 DevEco Studio 中运行项目
2. IDE 检测到没有签名配置，自动触发签名向导
3. 生成一个自签名的根证书和开发密钥对
4. 私钥存储在.p12文件中，密码自动生成
5. 公钥导出为.cer证书

生产环境的.p12管理：

调试.p12由 IDE 自动管理、自动续期、自动备份。但生产环境需要你自己管理.p12文件。关键注意事项：

• 不要将.p12提交到源码仓库。即使密码很强，私钥泄露等于应用身份被盗。
• 在 CI/CD 中通过环境变量或加密的 Secret 管理。如 GitHub Actions 的 Secrets、GitLab CI 的 Variables。
• 备份.p12和密码。丢失.p12或忘记密码意味着你无法为同一应用签名——在 AppGallery 上，这等于永远无法更新该应用。
• .p12有效期：生产证书有有效期（通常 1-2 年），过期后需要重新申请。但续期证书应使用相同的密钥对，否则系统会将其视为全新应用。

.cer 文件（certpath）：应用的身份证书

.cer（Certificate）文件是 X.509 格式的数字证书，包含开发者的公钥和身份信息。在签名体系中，.cer是"公开"部分——它被嵌入到签名后的 HAP 中，供设备验证签名的真实性。

验证流程：设备拿到 HAP 后，提取其中的.cer证书，用证书中的公钥解密 HAP 的签名值，对比哈希值是否匹配。匹配则签名有效。

对于调试证书，.cer是自签名的（不受信任的 CA 签发）。设备信任它是因为调试证书通过 Provisioning Profile 被注册到了设备的信任列表中。

对于生产证书，.cer由 AppGallery 的 CA 签发，是正式的、可验证的身份证书。

.p7b 文件（profile）：Provisioning Profile

.p7b文件（PKCS#7 Binary）是鸿蒙签名体系中最特殊的部分。它类似于 iOS 的 Provisioning Profile（实际上鸿蒙借鉴了 iOS 的安全模型），描述了以下权限绑定关系：

1. 应用身份（bundleName）：哪个应用可以使用此 profile
2. 设备列表（device IDs）：哪些设备可以安装并运行此应用
3. 证书绑定（certificate）：哪个开发证书可以使用此 profile 签名
4. 权限声明（permissions）：应用获得了哪些受保护的权限
5. 能力声明（capabilities）：应用需要哪些系统能力

调试 profile 由 DevEco Studio 自动生成，通常绑定到当前连接的调试设备。生产 profile 在 AppGallery Connect 中手动配置。

Provisioning Profile 的工作原理：

当你将调试 HAP 安装到设备时：

1. 设备从 HAP 中提取 Provisioning Profile
2. 设备验证 profile 中的设备列表是否包含自己（不在列表中的设备拒绝安装）
3. 设备验证 profile 中的 bundleName 是否与 HAP 的 bundleName 一致
4. 设备验证用于签名的证书是否在 profile 允许的证书列表中
5. 所有验证通过后，应用被安装

这套机制确保了：

• 未经你授权的设备无法安装你的调试版本（防止测试包泄露）
• 未经授权的开发者无法用他们的证书给你的应用签名
• 未声明的权限不会在运行时生效

签名算法的选择

HarmonyKit 使用SHA256withECDSA签名算法。这让它由两个部分组成：

ECDSA（Elliptic Curve Digital Signature Algorithm）：基于椭圆曲线的数字签名算法。与 RSA 相比，ECDSA 提供同等级别的安全性但使用更短的密钥——256 位的 ECDSA 安全性相当于 3072 位的 RSA。更短的密钥意味着更小的签名值，更少的计算开销。

SHA-256：签名过程中用于计算哈希值的哈希算法。应用的原始数据先经过 SHA-256 哈希（产生一个固定长度的摘要），然后对该摘要使用 ECDSA 私钥进行签名。

鸿蒙支持的签名算法包括：

• SHA256withECDSA（最常用，推荐）
• SHA256withRSA
• SHA384withECDSA
• SHA384withRSA

一般选择SHA256withECDSA即可。更高的 SHA 位数（384）提供更强的安全性但带来更大的签名开销，对应用签名来说没有实际必要。

调试签名的自动管理机制

DevEco Studio 的调试签名自动管理是它最方便的特性之一。但理解它的内部机制能在遇到问题时快速定位：

1. 首次运行触发：项目第一次在 DevEco Studio 中运行时，IDE 检测build-profile.json5中没有有效签名配置，弹出"自动生成签名"对话框。

2. 证书存储位置：自动生成的证书文件存放在~/.ohos/config/目录下。文件命名格式为{projectType}_{projectName}_{hash}。换一台电脑或删除该目录，证书就丢失了。

3. 设备注册：连接调试设备后，DevEco Studio 会自动将设备的 UDID 注册到 Provisioning Profile 中。换一台新设备需要重新注册——IDE 通常会弹窗提示"是否为此设备注册调试配置"。

4. 证书过期：调试证书的有效期通常是 1 年。到期前 DevEco Studio 会提示更新。更新操作会生成新的密钥对和证书，旧的已安装应用不受影响。

5. 多设备调试：如果你同时连接了手机和平板，DevEco Studio 会将两个设备的 UDID 都写入 Provisioning Profile。每个设备有自己唯一的 UDID，确保只有你指定的设备可以运行调试版本。

生产签名与 AppGallery 上架

当 HarmonyKit 准备上架 AppGallery 时，需要一套全新的签名流程：

Step 1: 在 AppGallery Connect 创建应用

在 AppGallery Connect 网站创建应用，填写 bundleName（必须与app.json5中的bundleName完全一致）、应用名称、类别等信息。

Step 2: 生成/上传签名证书

AppGallery Connect 提供两种选择：

方案 A：让 AppGallery 生成证书

• 优点：不需要手动管理密钥，AppGallery 托管私钥安全存储
• 缺点：你必须使用 AppGallery 生成的证书，无法自行控制密钥生命周期

方案 B：上传你自己的证书

• 优点：完全控制密钥，支持企业已有的证书体系
• 缺点：需要自己保管.p12私钥和密码，丢失即无法更新应用

对于个人开发者，AppGallery 代管证书是最简单的选择。对于企业，可能已有 PKI 体系，更倾向于上传自己的证书。

Step 3: 配置 Provisioning Profile

生产环境需要手动配置 Provisioning Profile，包含：

1. 选择证书：绑定 Step 2 中的签名证书
2. 声明权限：列出应用需要使用的敏感权限（如位置、相机、通讯录等）
3. 声明能力：列出应用需要的系统能力（如推送、分析、支付等）
4. 设备范围：调试 profile 绑定特定设备，生产 profile 通常不限制设备范围（所有设备可安装）

Step 4: 更新 build-profile.json5

将生产签名配置添加到signingConfigs数组：

"signingConfigs": [ { "name": "debug", // 保留调试配置 "type": "HarmonyOS", "material": { /* 自动生成的调试证书 */ } }, { "name": "release", // 新增生产配置 "type": "HarmonyOS", "material": { "certpath": "./keystore/release.cer", "keyAlias": "releaseKey", "keyPassword": "你的密钥密码", "profile": "./keystore/release.p7b", "signAlg": "SHA256withECDSA", "storeFile": "./keystore/release.p12", "storePassword": "你的密钥库密码" } } ]

同时更新 products 配置，为不同构建模式使用不同签名：

"products": [ { "name": "default", "signingConfig": "debug", // 日常开发用 debug 签名 // ... }, { "name": "release", "signingConfig": "release", // 发布用 release 签名 // ... } ]

构建时选择 release product：

hvigorw assembleHap-pproduct=release-pbuildMode=release

签名相关常见错误及修复

错误一：设备不在 Provisioning Profile 允许列表中

现象：

ERROR: Failed to install HAP. The device is not authorized. ERROR: Provisioning profile does not contain this device.

原因：连接了新的调试设备，但该设备的 UDID 还没有被注册到调试 Provisioning Profile 中。

修复：

1. 在 DevEco Studio 中连接设备
2. IDE 会弹出"允许此设备进行调试?"对话框
3. 点击"允许"，IDE 自动将设备 UDID 添加到 profile 中
4. 重新运行项目

错误二：证书已过期

现象：

ERROR: The certificate has expired.

原因：调试证书有效期通常为 1 年，到期后需要更新。

修复：

1. DevEco Studio > Build > Generate Key and CSR
2. 或：删除~/.ohos/config/目录下对应项目的证书文件
3. 重新运行项目让 IDE 自动生成新证书

错误三：签名密码不匹配

现象：

ERROR: Keystore was tampered with, or password was incorrect.

原因：.p12文件的密码与配置不一致。可能发生在更换了证书文件但没有更新密码配置的情况下。

修复：

1. 确认storePassword和keyPassword是否正确
2. 如果密码确实丢失，只能重新生成证书
3. 删除旧的.p12、.cer、.p7b文件，让 IDE 重新生成

错误四：跨电脑协作的签名问题

现象：从 Git 拉取项目后，构建失败，报签名相关错误。

原因：证书文件的绝对路径（~/.ohos/config/...）指向了另一台电脑的文件系统，当前电脑上不存在这些文件。

修复（三人团队推荐方案）：

1. 将证书文件放在项目内部（不提交到 Git）：

# 创建本地 keystore 目录（已在 .gitignore 中）mkdir-pkeystore# 在 build-profile.json5 中使用相对路径"certpath":"./keystore/debug.cer","storeFile":"./keystore/debug.p12","profile":"./keystore/debug.p7b"

2. 通过安全渠道共享证书（如加密邮件、密码管理器），每个开发者将证书放到本地keystore/目录。

3. 确保.gitignore包含 keystore 目录：

/keystore/

对于较大的团队，建议每个开发者使用自己的调试证书（让 IDE 自动生成），只在 CI/CD 流程中使用共享的生产签名配置。

错误五：bundleName 与 Provisioning Profile 不匹配

现象：

ERROR: The bundleName in the HAP does not match the profile.

原因：修改了AppScope/app.json5中的bundleName，但签名用的 Provisioning Profile 仍然是基于旧 bundleName 生成的。

修复：重新生成签名配置。bundleName 变更是一个"重大变更"——系统将新 bundleName 的应用视为一个全新应用。

签名安全的最佳实践

1. 密钥分级管理

• 调试密钥：允许每个开发者生成自己的，不集中管理
• 测试密钥：CI/CD 环境使用专用的测试密钥（与个人开发者的调试密钥分离）
• 生产密钥：仅限极少数人持有，通过加密的 Secret 管理

2. .gitignore 必须包含签名相关路径

HarmonyKit 的.gitignore虽然没有显式列出证书文件，但已经通过忽略整个/entry/build/排除了构建产物。建议显式添加：

/keystore/ *.p12 *.cer *.p7b

3. CI/CD 中的签名处理

在 CI/CD 流水线中，签名配置不应该以明文形式存在。推荐做法：

# GitHub Actions 示例- name: Setup Signing Configuration run:|echo"${{ secrets.KEYSTORE_BASE64 }}"|base64-d>keystore/release.p12echo"${{ secrets.CERTIFICATE }}">keystore/release.cerecho"${{ secrets.PROFILE }}">keystore/release.p7b

值通过 CI/CD 平台的 Secret 管理，流水线运行时动态解密和注入。

4. Proton 文件的更新管理

Provisioning Profile 有独立于证书的有效期。当你添加新权限或新设备时，需要更新 profile。AppGallery Connect 提供了 profile 的管理界面，可以随时修改设备列表和权限声明。

修改 profile 后，需要重新下载并替换项目中的.p7b文件，然后重新签名 HAP。

签名与 AppGallery 审核的关系

AppGallery 的审核流程中，签名检查是第一关：

1. 证书验证：检查签名证书是否由受信任的 CA 签发（或由 AppGallery 代管）
2. Profile 校验：检查 Provisioning Profile 是否有效、是否过期
3. 权限匹配：检查 HAP 中声明的权限是否在 profile 的权限范围内
4. 签名完整性：检查 HAP 是否被篡改（签名值与内容哈希是否匹配）

任何一项不合格都会导致审核直接拒绝。因此，在上架之前务必在真机环境（非模拟器）上完整测试 release 签名的安装和运行流程。

结语

签名系统是鸿蒙安全模型的基石。它看起来复杂——三个证书文件、哈希算法、椭圆曲线、权限绑定——但本质上只解决一个问题：确认这个应用确实是你发布的，且没有被篡改过。

对 HarmonyKit 这样的开源工具应用来说，签名更多是一个工程实践而非安全壁垒。我们的代码完全公开，没有需要保护的知识产权。但正确的签名实践是发布到 AppGallery 的前提，也是专业鸿蒙开发者必须掌握的技能。

项目仓库：https://atomgit.com/VON-/harmony-kit