多模块签名与证书管理

一、签名在 HarmonyOS 中的重要性

应用签名是 HarmonyOS 安全体系的核心组成部分。每个应用在发布前都必须经过签名，签名的目的是：

1. 身份验证：确认应用的开发者身份，防止应用被篡改
2. 完整性保护：确保应用包在签名后没有被修改
3. 权限授权：某些系统级权限要求应用必须经过特定签名才能使用
4. 应用升级：同包名的应用必须使用相同签名才能覆盖安装

在我们的 11 模块架构中，签名配置在根级别的 build-profile.json5 中统一管理，所有子模块共享同一个签名配置。

二、build-profile.json5 中的 signingConfigs 配置

根目录的 build-profile.json5 中定义了签名配置：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "certpath": "C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.cer",
          "keyAlias": "debugKey",
          "keyPassword": "0000001B...",
          "profile": "C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.p12",
          "storePassword": "0000001B..."
        }
      }
    ]
  }
}

配置字段解析：

• name：签名配置的名称，用于在 product 中引用
• type：签名类型，HarmonyOS 应用固定为 “HarmonyOS”
• material：签名材料

签名材料中的文件类型：

文件	格式	用途
certpath	.cer	数字证书，包含公钥和开发者信息
storeFile	.p12	PKCS#12 密钥库，包含私钥
profile	.p7b	应用签名配置文件，包含权限声明

三、p7b 证书与 profile 文件

.cer 证书（数字证书）

.cer 文件是开发者的数字证书，由华为开发者联盟颁发。它包含了：

• 开发者的公钥
• 开发者身份信息（名称、组织等）
• 证书有效期
• 颁发机构（华为 CA）的签名

.p7b（PKCS#7）签名配置文件

.p7b 文件不是传统的"证书"，而是包含应用签名配置信息的 PKCS#7 容器。它涉及：

• 应用的包名（bundleName）
• 应用的权限声明
• 应用的调试/发布模式
• 授权的设备列表（调试模式下）

p7b 文件的作用是告诉系统该应用可以做什么（权限）、由谁签名、可以在什么设备上运行。

.p12（PKCS#12）密钥库

.p12 文件是私钥的加密容器。它受密码保护（storePassword），包含了：

• 开发者的私钥（用于签名）
• 对应的数字证书

安全性警告：签名的私钥和密码是应用安全的核心。.p12 文件和密码不应该提交到版本控制系统中。在我们的项目中，这些文件存储在用户目录 .ohos/config/ 下，而不是项目目录中。

四、调试签名 vs 发布签名

调试签名（Debug）

• 用于开发阶段，在模拟器或调试设备上运行
• 证书由 DevEco Studio 自动生成，有效期通常较长（如 3650 天）
• 限制较少，可以在所有调试设备上运行
• 配置在 buildModeSet 中的 debug 模式

发布签名（Release）

• 用于发布到应用市场
• 证书需要在华为开发者联盟正式申请
• 有更严格的权限和安装限制
• 配置在 buildModeSet 中的 release 模式

"buildModeSet": [
  { "name": "debug" },
  { "name": "release" }
]

在构建时，通过 --mode 参数指定使用 debug 还是 release 配置。Hvigor 会根据配置选择对应的签名材料。

五、多模块签名策略

在 11 模块架构中，签名策略是"统一签名"：

1. 统一签名配置：所有模块使用根目录 build-profile.json5 中定义的同一套签名配置
2. 模块不单独签名：HAR 模块（如 commonLib）在开发阶段不需要签名，只有在最终打包为 HAP 时才签名
3. entry 模块继承签名：entry 作为应用入口模块，在构建 HAP 包时应用签名

这种策略的好处是：

• 签名配置集中管理，一处修改所有模块生效
• 避免多个模块使用不同签名导致的安装冲突
• 简化 CI/CD 配置，只需维护一套签名

六、签名相关的常见问题

1. 签名过期

数字证书有有效期限制。证书过期后，安装已签名的应用会失败。

解决方案：在华为开发者联盟重新申请证书，更新 signingConfigs 中的文件路径。

2. 包名不匹配

如果打包时 app.json5 中的 bundleName 与申请证书时使用的包名不同，签名会失败。

3. 密码错误

.p12 文件的 storePassword 和 keyPassword 必须正确。如果密码错误，构建过程中的签名步骤会失败。

4. 多开发者协作

不同开发者有不同的签名证书和密码。在团队协作中，建议：

• 每个开发者使用自己的调试证书
• 发布证书由项目管理员保管
• CI/CD 系统使用专用的发布证书

七、总结

签名是多模块 HarmonyOS 应用发布前的必要环节。在 11 模块架构中，签名配置通过根 build-profile.json5 的 signingConfigs 统一管理，所有模块共享同一套签名材料。.cer 证书、.p7b profile 文件和 .p12 密钥库构成了完整的签名体系。调试和发布模式使用不同的签名配置，确保了开发和生产的隔离。妥善管理签名文件和密码，是应用安全的重要防线。