From ec408d0e1456428e80bbba6ff4bf7f681445d9e4 Mon Sep 17 00:00:00 2001 From: chenqun1 Date: Fri, 11 Feb 2022 11:10:18 +0800 Subject: [PATCH] add docs of hapsigntool Signed-off-by: chenqun1 --- .../security/hapsigntool_guidelines.md | 140 ++++++++---------- 1 file changed, 65 insertions(+), 75 deletions(-) diff --git a/zh-cn/application-dev/security/hapsigntool_guidelines.md b/zh-cn/application-dev/security/hapsigntool_guidelines.md index 0fa5efe263..ac27c93a4c 100644 --- a/zh-cn/application-dev/security/hapsigntool_guidelines.md +++ b/zh-cn/application-dev/security/hapsigntool_guidelines.md @@ -1,59 +1,60 @@ # Hap包签名工具开发指南 -- [概述](#概述) - - [功能简介](#功能简介) - - [基本概念](#基本概念) - - [约束与限制](#约束与限制) - - [编译构建](#编译构建) -- [开发指导](#开发指导) - - [场景介绍](#场景介绍) - - [说明](#说明) - - [接口说明](#接口说明) - - [命令说明](#命令说明) - - [开发步骤](#开发步骤) - - [常见问题](#常见问题) - +* 概述 + * 功能简介 + * 基本概念 + * 约束与限制 +* 编译构建 +* 开发指导 + * 场景介绍 + * 说明 + * 命令说明 + * 开发步骤 +* 常见问题 ## 概述 ### 功能简介 -   为了保证OpenHarmony应用的完整性和来源可靠，在应用构建时需要对应用进行签名。经过签名的应用才能在真机设备上安装、运行、和调试。本仓提供了签名工具的源码，包含密钥对生成、CSR文件生成、证书生成、Profile文件签名、Hap包签名等功能。 +为了保证OpenHarmony应用的完整性和来源可靠，在应用构建时需要对应用进行签名。经过签名的应用才能在真机设备上安装、运行、和调试。[本仓](https://gitee.com/openharmony/developtools_hapsigner)提供了签名工具的源码，包含密钥对生成、CSR文件生成、证书生成、Profile文件签名、Hap包签名等功能。 ### 基本概念 -   Hap包签名工具支持本地签名需求的开发，为OpenHarmony应用提供完整性保护和来源管控机制，该签名工具基于PKI公钥证书的机制实现，在进行开发前，开发者应了解以下基本概念： +Hap包签名工具支持本地签名需求的开发，为OpenHarmony应用提供完整性保护和来源管控机制，该签名工具基于PKI公钥证书的机制实现，在进行开发前，开发者应了解以下基本概念： - 非对称密钥对 -    非对称密钥算法是数据签名/验签的基础，应用签名工具实现生成标准的非对称密钥对（ECC P384/256、RSA2048/3072/4096）,用于证书的签发和验证、Profile文件的签名和验签、以及应用包的签名和验签，提供应用的完整性保护机制。 + 非对称密钥算法是数据签名/验签的基础，应用签名工具实现生成标准的非对称密钥对（ECC P384/256、RSA2048/3072/4096，用于证书的签发和验证、Profile文件的签名和验签、以及应用包的签名和验签，提供应用的完整性保护机制。 - CSR -    CSR证书签发请求是生成证书的前提，他包括证书的公钥、证书主题和私钥签名，在申请证书之前，需要先基于密钥对生成CSR，然后提交给CA签发证书。 + CSR（Certificate Signing Request）证书签发请求是生成证书的前提，他包括证书的公钥、证书主题和私钥签名，在申请证书之前，需要先基于密钥对生成CSR，然后提交给CA签发证书。 - 证书 -    OpenHarmony采用RFC5280标准构建X509证书信任体系。用于应用签名的OpenHarmony证书按层级可分为：根CA证书、子CA证书、三级实体证书，其中三级实体证书分为应用签名证书和profile签名证书。应用签名证书表示应用开发者的身份，可保证系统上安装的应用来源可追溯，profile签名证书实现对profile文件的签名进行验签，保证profile文件的完整性。 + OpenHarmony采用RFC5280标准构建X509证书信任体系。用于应用签名的OpenHarmony证书按层级可分为：根CA证书、子CA证书、三级实体证书，其中三级实体证书分为应用签名证书和profile签名证书。应用签名证书表示应用开发者的身份，可保证系统上安装的应用来源可追溯，profile签名证书实现对profile文件的签名进行验签，保证profile文件的完整性。 - HAP包 -   HAP是Ability的部署包，OpenHarmony应用代码围绕Ability组件展开，它是由一个或者多个Ability组成。 +HAP（HarmonyOS Ability Package）是Ability的部署包，OpenHarmony应用代码围绕Ability组件展开，它是由一个或者多个Ability组成。 - profile文件 -   hap包中的描述文件，该描述文件描述了已授权的证书权限和设备ID信息等信息。 +hap包中的描述文件，该描述文件描述了已授权的证书权限和设备ID信息等信息。 ### 约束与限制 - - Hap包签名工具基于Java语言开发，需要Java8以上Java环境运行 - - 一键签名等脚本文件基于Python语言开发，使用需配置环境python3.5及以上 + - Hap包签名工具基于Java语言开发，需要Java8以上Java环境运行。 + - 一键签名等脚本文件基于Python语言开发，使用需配置环境python3.5及以上。 -### 编译构建 +## 编译构建 - 1. 该工具基于Gradle 7.1编译构建，请确认环境已安装配置Gradle环境，并且版本正确 + 1. 该工具基于Gradle 7.1编译构建，请确认环境已安装配置Gradle环境，并且版本高于或等于7.1。 gradle -v - 2. 下载代码，命令行打开文件目录至developtools_hapsigner/hapsigntool，执行命令进行编译打包 + 2. 下载代码，命令行打开文件目录至developtools_hapsigner/hapsigntool，执行命令进行编译打包。 - gradle build 或者 gradle jar + gradle build + 或 + gradle jar - 3. 编译后得到二进制文件，目录为: ./hap_sign_tool/build/libs/hap-sign-tool.jar + 3. 编译后得到二进制文件，目录为: ./hap_sign_tool/build/libs/hap-sign-tool.jar。 +## 开发指导 ### 场景介绍 @@ -67,25 +68,11 @@ OpenHarmony系统内置密钥库文件，文件名称为OpenHarmony.p12，内含

2.有应用签名证书场景：

-- 开发者可直接从开发步骤[第三步](#对profile文件进行签名)开始开发 ,使用应用签名证书和包含对应密钥的本地密钥库文件对应用进行签名 +- 开发者可直接从开发步骤[第三步](#对profile文件进行签名)开始开发 ,使用应用签名证书和包含对应密钥的本地密钥库文件对应用进行签名。 ### 说明 -#### 接口说明 - -| 接口名 | 描述 | -| -------- | -------- | -| boolean generateKeyStore(Options options) | 生成密钥对，并保存至对应秘钥库 | -| boolean generateCsr(Options options) | 生成证书请求 csr | -| boolean generateCert(Options options) | 通用证书生成方法| -| boolean generateCA(Options options) | 生成根CA证书或子CA证书 | -| boolean generateAppCert(Options options) | 生成应用签名证书（三级证书） | -| boolean generateProfileCert(Options options) | 生成Profile签名证书（三级证书） | -| boolean signProfile(Options options) | 对Profile文件进行签名 | -| boolean verifyProfile(Options options) | 对已签名profile(.p7b)文件进行验签| -| boolean signHap(Options options) | 对未签名鸿蒙应用进行签名 | -| boolean verifyHap(Options options) | 对已签名应用包文件进行验签 | #### 命令说明 1.输出命令帮助信息 @@ -96,7 +83,7 @@ OpenHarmony系统内置密钥库文件，文件名称为OpenHarmony.p12，内含 -version # 输出版本信息 -以下命令可参考README文件 + 3.生成密钥对 generate-keypair : 生成密钥对 @@ -248,25 +235,25 @@ OpenHarmony系统内置密钥库文件，文件名称为OpenHarmony.p12，内含 - [对profile文件进行签名](#对profile文件进行签名) - [对Hap包进行签名](#对Hap包进行签名) -> ![icon-note.gif](../public_sys-resources/icon-note.gif)**注意事项：** +> **注意事项：** 1.步骤一中的密钥对算法推荐使用ECC，出于安全性考虑，应用签名暂不使用RSA算法 2.建议将待签名hap包、profile文件、密钥库文件OpenHarmony.p12、根CA证书、子CA证书、签名工具放在同一个目录下，方便操作。 3. OpenHarmony密钥库文件所在路径：developtools_hapsigner/autosign/result/OpenHarmony.p12； -  根CA证书所在路径：developtools_hapsigner/autosign/result/rootCA.cer； -  子CA证书所在路径：developtools_hapsigner/autosign/result/subCA.cer； -  pfofile签名证书路径：developtools_hapsigner/autosign/result/OpenHarmonyProfileRelease.pem。 + 根CA证书所在路径：developtools_hapsigner/autosign/result/rootCA.cer； + 子CA证书所在路径：developtools_hapsigner/autosign/result/subCA.cer； + pfofile签名证书路径：developtools_hapsigner/autosign/result/OpenHarmonyProfileRelease.pem。 **

1.生成应用签名证书密钥对

** -    调用密钥对生成接口，生成签名密钥并保存到密钥库。 -    命令实例： +调用密钥对生成接口，生成签名密钥并保存到密钥库。 +命令实例： ```shell java -jar hap-sign-tool.jar generate-keypair -keyAlias "oh-app1-key-v1" -keyAlg "ECC" -keySize "NIST-P-256" -keystoreFile "OpenHarmony.p12" -keyPwd "123456" -keystorePwd "123456" ``` > ![icon-note.gif](../public_sys-resources/icon-note.gif) **说明：**请记录下**keyAlias、keyStorePwd**和**keyPwd**的值，在后续[生成应用签名证书](#生成应用签名证书)和[对Hap包进行签名](#对Hap包进行签名)操作会使用到。 -    该命令的参数说明： +该命令的参数说明： generate-keypair : 生成应用签名证书密钥对 ├── -keyAlias #用于生成应用签名证书的密钥别名，存于OpenHarmony.p12密钥库文件中，该参数必填 @@ -280,13 +267,13 @@ java -jar hap-sign-tool.jar generate-keypair -keyAlias "oh-app1-key-v1" -keyAlg **

2.生成应用签名证书

** -    调用应用签名证书生成接口，使用本地二级CA证书签发应用签名证书。 -    命令实例： +调用应用签名证书生成接口，使用本地二级CA证书签发应用签名证书。 + 命令实例： ```shell java -jar hap-sign-tool.jar generate-app-cert -keyAlias "oh-app1-key-v1" -signAlg "SHA256withECDSA" -issuer "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN= OpenHarmony Application CA" -issuerKeyAlias "openharmony application ca" -subject "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN=OpenHarmony Application Release" -keystoreFile "OpenHarmony.p12" -subCaCertFile "subCA.cer" -rootCaCertFile "rootCA.cer" -outForm "certChain" -outFile "app1.pem" -keyPwd "123456" -keystorePwd "123456" -issuerKeyPwd "123456" -validity "365" ``` -   该命令的参数说明： +该命令的参数说明： generate-app-cert：生成应用签名证书 ├── -keyAlias # 用于生成应用签名证书的密钥别名，请与第一步生成密钥对的密钥别名-keyAlias保持一致 @@ -307,13 +294,13 @@ java -jar hap-sign-tool.jar generate-app-cert -keyAlias "oh-app1-key-v1" -signAl **

3.对profile文件进行签名

** -   调用Profile文件签名接口，使用Profile签名密钥对Profile文件进行签名 -   命令实例： +调用Profile文件签名接口，使用Profile签名密钥对Profile文件进行签名 +命令实例： ```shell java -jar hap-sign-tool.jar sign-profile -keyAlias "openharmony application profile release" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile "OpenHarmonyProfileRelease.pem" -inFile "UnsgnedReleasedProfileTemplate.json" -keystoreFile "OpenHarmony.p12" -outFile "app1-profile.p7b" -keyPwd "123456" -keystorePwd "123456" ``` -   该命令的参数说明： +该命令的参数说明： sign-profile：签名profile文件 ├── -keyAlias # 生成profile证书的密钥别名，该参数必填且不能修改 @@ -329,20 +316,20 @@ java -jar hap-sign-tool.jar sign-profile -keyAlias "openharmony application pro **

4.对Hap包进行签名

** -   调用Hap包签名接口，使用应用签名密钥为Hap包签名。 -   命令实例： +调用Hap包签名接口，使用应用签名密钥为Hap包签名。 +命令实例： ```shell java -jar hap-sign-tool.jar sign-app -keyAlias "oh-app1-key-v1" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "app1.pem" -profileFile "app1-profile.p7b" -inFile "app1-unsigned.zip" -keystoreFile "OpenHarmony.p12" -outFile "app1-signed.hap" -keyPwd "123456" -keystorePwd "123456" ``` - > ![icon-note.gif](../public_sys-resources/icon-note.gif) **说明**：以下参数说明默认开发场景为场景一，当开发场景为场景二时，下列参数需要修改： -    -keyAlias：密钥别名，填写已有应用签名证书对应的密钥别名，参数必填 -    -appCertFile：应用签名证书，填写已有的应用签名证书，参数必填 -    -keystoreFile：密钥库文件，填写已有应用签名证书对应的密钥库文件，参数必填 -    -keyPwd：密钥口令，填写密钥库文件中对应密钥的口令 -    -keystorePwd：密钥库口令，填写密钥库文件的密钥口令 + > ![icon-note.gif](../public_sys-resources/icon-note.gif) **说明**：以下参数说明默认为[无应用签名证书场景](#无应用签名证书场景)，当开发场景为[有应用签名证书场景](#有应用签名证书场景)时，下列参数需要修改： +-keyAlias：密钥别名，填写已有应用签名证书对应的密钥别名，参数必填 +-appCertFile：应用签名证书，填写已有的应用签名证书，参数必填 +-keystoreFile：密钥库文件，填写已有应用签名证书对应的密钥库文件，参数必填 +-keyPwd：密钥口令，填写密钥库文件中对应密钥的口令 +-keystorePwd：密钥库口令，填写密钥库文件的密钥口令 -   该命令的参数说明： +该命令的参数说明： sign-app：签名Hap包 ├──-keyAlias # 密钥别名，为第一步生成的密钥信息别名，该参数必填 @@ -371,32 +358,35 @@ java -jar hap-sign-tool.jar sign-app -keyAlias "oh-app1-key-v1" -signAlg "SHA256 - **解决办法** 检查并修正outFile参数为正确路径，'-outFile'中的'-'为英文格式 -**2.执行第三步对profile文件进行签名时，提示签名失败** +**2.执行第三步[对profile文件进行签名](#对profile文件进行签名)时，提示签名失败** -- **现象描述** +**现象描述** 现象分为以下几种： 1.执行命令后提示 "SIGN_ERROR, code: 107. Details: Failed to verify signature: Wrong key usage". 2.执行命令后提示 "NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'result\profile1.pem' must a cert chain". 3.执行命令后提示 "VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target" -- **可能原因** + **可能原因** - 对应现象描述的可能原因： 1.profile签名证书（三级证书）证书链顺序不正确。 2.profile签名证书（三级证书）不是证书链。 - 3.证书主题顺序不正确 + 3.证书主题顺序不正确或者 生成应用签名证书时“-issuerKeyAlias”参数填写错误 -- **解决办法** +**解决办法** 1.检查并修正证书链顺序，只能正序或反序，不可乱序。 2.检查签名时的三级证书是否为证书链。 3.检查证书主题顺序是否正确，顺序须为C、O、OU、CN。 -**3.签名hap包时提示签名错误** +**3.[对Hap包进行签名](#对Hap包进行签名)时提示签名错误** -- **现象描述** + **现象描述** 执行命令后提示：NOT_SUPPORT_ERROR, code: 105. Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA -- **可能原因** + **可能原因** 签名算法不支持，signAlg参数填写错误 -- **解决办法** - 三级证书密钥对推荐使用ECC生成，hap签名算法修改为ECC对应的SHA256withECDSA,SHA384withECDSA \ No newline at end of file + **解决办法** + 三级证书密钥对推荐使用ECC生成，hap签名算法修改为ECC对应的SHA256withECDSA,SHA384withECDSA + + + [1]: www.baidu.com \ No newline at end of file -- GitLab