1# Hap包签名工具 2 3* 简介 4* 目录 5* 约束 6* 编译构建 7* 说明 8 * 签名相关文件用法说明 9 * 使用说明 10 * 接口说明 11* 相关仓 12 13#### 简介 14 15为了保证OpenHarmony应用和二进制工具（如：lldb-server）的完整性和来源可靠，需要对应用和二进制工具进行签名。经过签名的应用和二进制工具才能在真机设备上安装、运行和调试。本仓提供了签名工具的源码，包含密钥对生成、CSR文件生成、证书生成、Profile文件签名、Hap包签名、二进制工具签名等功能。 16在支持强制代码签名机制的设备上，该机制可以为应用提供运行时的合法性校验以及完整性保护，杜绝未经审核的恶意代码在端侧任意执行，或应用代码被攻击者恶意篡改。 17签名工具默认开启代码签名，若用户确定不需要强制执行代码签名，可参考以下说明，关闭代码签名功能。签名工具当前仅支持对hap格式应用和二进制工具执行代码签名。 18 19 20#### 目录 21 22 developtools_hapsigner 23 24 ├── autosign # 一键签名脚本 25 ├── dist # SDK预置文件 26 ├── hapsigntool # 主代码 27 ├──hap_sign_tool # 主程序入口，完成输入参数的基础校验 28 ├──hap_sign_tool_lib # 签名工具库，解析命令字和参数列表，实现各模块逻辑功能 29 ├── tools # 自动化测试脚本 30 31 32 33#### 约束 34- Hap包签名工具基于Java语言开发，需要在Java8以上Java环境运行。 35- 一键签名等脚本文件基于Python语言开发，使用需配置环境python3.5及以上。 36#### 编译构建 37 38 1. 该工具基于Maven3编译构建，请确认环境已安装配置Maven3环境，并且版本正确 39 40 mvn -version 41 42 2. 下载代码，命令行打开文件目录至developtools_hapsigner/hapsigntool，执行命令进行编译打包 43 44 mvn package 45 46 3. 编译后得到二进制文件，目录为: ./hap_sign_tool/target 47 48**** 49#### 说明 50##### 签名相关文件用法说明 51 52开发者通过IDE进行应用签名时，可在SDK中会获得如下签名相关文件： 53 54``` 55签名密钥库文件：OpenHarmony.p12 56Profile签名证书：OpenHarmonyProfileRelease.pem、OpenHarmonyProfileDebug.pem 57Profile模板文件：UnsgnedReleasedProfileTemplate.json、UnsgnedDebugProfileTemplate.json 58签名工具：hap-sign-tool.jar 59``` 60上述文件的使用场景如下图所示。 61 62**Profile签名场景：** 63 64 65 66**应用签名场景：** 67 68 69##### 使用说明 70 71以下说明中使用jar包为编译构建中生成的二进制文件 72 731.命令行签名 74 命令行签名分为profile文件签名和hap包或二进制工具签名。 75 76 （1）签名profile文件的命令实例如下： 77 78 79```shell 80java -jar hap-sign-tool.jar sign-profile -keyAlias "oh-profile1-key-v1" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile "result\profile1.pem" -inFile "app1-profile-release.json" -keystoreFile "result\ohtest.jks" -outFile "result\app1-profile.p7b" -keyPwd "123456" -keystorePwd "123456" 81``` 82该命令的参数说明如下： 83 84 sign-profile : ProvisionProfile文件签名 85 ├── -mode #签名模式，必填项，包括localSign，remoteSign 86 ├── -keyAlias #密钥别名，必填项 87 ├── -keyPwd #密钥口令，可选项 88 ├── -profileCertFile #Profile签名证书（证书链，顺序为实体证书-中间CA证书-根证书），必填项 89 ├── -inFile #输入的原始Provision Profile文件，必填项 90 ├── -signAlg #签名算法，必填项，包括 SHA256withECDSA / SHA384withECDSA 91 ├── -keystoreFile #密钥库文件，localSign模式时为必填项，JKS或P12格式 92 ├── -keystorePwd #密钥库口令，可选项 93 ├── -outFile #输出签名后的Provision Profile文件，p7b格式，必填项 94 95 96 97（2）签名Hap包或二进制工具的命令实例如下： 98 99 100```shell 101java -jar hap-sign-tool.jar sign-app -keyAlias "oh-app1-key-v1" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "result\app1.pem" -profileFile "result\app1-profile.p7b" -inFile "app1-unsigned.zip" -keystoreFile "result\ohtest.jks" -outFile "result\app1-unsigned.hap" -keyPwd "123456" -keystorePwd "123456" -signCode "1" 102``` 103该命令的参数说明如下: 104 105 sign-app : hap应用包和二进制工具签名 106 ├── -mode #签名模式，必填项，包括localSign，remoteSign 107 ├── -keyAlias #密钥别名，必填项 108 ├── -keyPwd #密钥口令，可选项 109 ├── -appCertFile #应用签名证书文件（证书链，顺序为实体证书-中间CA证书-根证书），必填项 110 ├── -profileFile #签名后的Provision Profile文件名，p7b格式，hap应用包签名必填项，二进制工具签名选填 111 ├── -profileSigned #指示profile文件是否带有签名，1表示有签名，0表示没有签名，默认为1。可选项 112 ├── -inForm #输入的原始文件的格式，枚举值：zip、elf或bin；zip和elf支持代码签名，hap 应用包对应zip，二进制工具对应elf，默认zip；可选项 113 ├── -inFile #输入的原始文件，hap应用、elf或bin文件，必填项 114 ├── -signAlg #签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 115 ├── -keystoreFile #密钥库文件，localSign模式时为必填项，JKS或P12格式 116 ├── -keystorePwd #密钥库口令，可选项 117 ├── -outFile #输出签名后的包文件，必填项 118 ├── -signCode #是否启用代码签名，1表示开启代码签名，0表示关闭代码签名，默认为1。可选项 119 1202.一键签名 121 122 123为降低学习成本，提高开发效率，本项目还将基于应用签名工具提供一键签名脚本，免于输入繁杂的参数命令，脚本内容包括生成密钥对、实体证书、签名profile包、签名hap包和二进制工具的命令。 124脚本以及配置文件位于目录 autosign 下： 125 126 - create_root.sh/create_root.bat 127 - create_appcert_sign_profile.sh/create_appcert_sign_profile.bat 128 - sign_hap.sh/sign_hap.bat 129 - sign_elf.sh/sign_elf.bat 130 - createAppCertAndProfile.config 131 - createRootAndSubCert.config 132 - signHap.config 133 - signElf.config 134 135使用指导： 1361. 准备依赖环境 python3.5 以上 1372. 准备签名工具jar包：hap-sign-tool.jar（参照上文编译生成的产物） 1383. 准备待签名的应用hap包、二进制工具和 Provision profile 模板文件 1394. 使用文本编辑器编辑 createAppCertAndProfile.config、signElf.config 和 signHap.config，修改配置文件中的配置信息：common.keyPwd 和 common.issuerKeyPwd 参数值改成自己定义的口令信息 1405. Linux运行 create_appcert_sign_profile.sh、Windows运行 create_appcert_sign_profile.bat 生成签名所需文件 1416. Linux运行 sign_hap.sh、Windows运行 sign_hap.bat 对hap包进行签名；Linux运行 sign_elf.sh、Windows运行 sign_elf.bat 对二进制工具进行签名 142 143 > 说明：如需自定义生成密钥库文件，根CA，中间CA证书，profile签名证书，可执行以下步骤 144 1.使用文本编辑器编辑 createRootAndSubCert.config 修改配置文件中的配置信息：common.keyPwd 和 common.issuerKeyPwd 参数值改成自己定义的口令信息 145 2.Linux运行 create_root.sh、Windows运行 create_root.bat 生成所需密钥库文件，根CA，中间CA证书，profile签名证书 146 147 148**** 149##### 接口说明 1501.生成密钥对 151 152 generate-keypair : 生成密钥对 153 ├── -keyAlias # 密钥别名，必填项 154 ├── -keyPwd # 密钥口令，可选项 155 ├── -keyAlg # 密钥算法，必填项，包括RSA/ECC 156 ├── -keySize # 密钥长度，必填项，RSA算法的长度为2048/3072/4096，ECC算法的长度NIST-P-256/NIST-P-384 157 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 158 ├── -keystorePwd # 密钥库口令，可选项 159 1602.生成证书签名请求 161 162 generate-csr : 生成证书签名请求 163 ├── -keyAlias # 密钥别名，必填项 164 ├── -keyPwd # 密钥口令，可选项 165 ├── -subject # 证书主题，必填项 166 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA 167 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 168 ├── -keystorePwd # 密钥库口令，可选项 169 ├── -outFile # 输出文件，可选项，如果不填，则直接输出到控制台 170 1713.生成根CA/中间CA证书 172 173 generate-ca : 生成根CA/中间CA证书，如果密钥不存在，一起生成密钥 174 ├── -keyAlias # 密钥别名，必填项 175 ├── -keyPwd # 密钥口令，可选项 176 ├── -keyAlg # 密钥算法，必填项，包括RSA/ECC 177 ├── -keySize # 密钥长度，必填项，RSA算法的长度为2048/3072/4096，ECC算法的长度NIST-P-256/NIST-P-384 178 ├── -issuer # 颁发者的主题，可选项，如果不填，表示根CA 179 ├── -issuerKeyAlias # 颁发者的密钥别名，可选项，如果不填，表示根CA 180 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 181 ├── -subject # 证书主题，必填项 182 ├── -validity # 证书有效期，可选项，默认为3650天 183 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA 184 ├── -basicConstraintsPathLen # 路径长度，可选项，默认为0 185 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 186 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 187 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 188 ├── -keystorePwd # 密钥库口令，可选项 189 ├── -outFile # 输出文件，可选项，如果不填，则直接输出到控制台 190 1914.生成应用调试/发布证书 192 193 generate-app-cert : 生成应用调试/发布证书 194 ├── -keyAlias # 密钥别名，必填项 195 ├── -keyPwd # 密钥口令，可选项 196 ├── -issuer # 颁发者的主题，必填项 197 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 198 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 199 ├── -subject # 证书主题，必填项 200 ├── -validity # 证书有效期，可选项，默认为3650天 201 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA； 202 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 203 ├── -keystorePwd # 密钥库口令，可选项 204 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 205 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 206 ├── -outForm # 输出证书文件的格式，包括 cert / certChain，可选项，默认为certChain 207 ├── -rootCaCertFile # outForm为certChain时必填，根CA证书文件 208 ├── -subCaCertFile # outForm为certChain时必填，中间CA证书文件 209 ├── -outFile # 输出证书文件(证书或证书链)，可选项，如果不填，则直接输出到控制台 210 2115.生成profile调试/发布证书 212 213 generate-profile-cert : 生成profile调试/发布证书 214 ├── -keyAlias # 密钥别名，必填项 215 ├── -keyPwd # 密钥口令，可选项 216 ├── -issuer # 颁发者的主题，必填项 217 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 218 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 219 ├── -subject # 证书主题，必填项 220 ├── -validity # 证书有效期，可选项，默认为3650天 221 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA； 222 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 223 ├── -keystorePwd # 密钥库口令，可选项 224 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 225 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 226 ├── -outForm # 输出证书文件的格式，包括 cert / certChain，可选项，默认为certChain 227 ├── -rootCaCertFile # outForm为certChain时必填，根CA证书文件 228 ├── -subCaCertFile # outForm为certChain时必填，中间CA证书文件 229 ├── -outFile # 输出证书文件(证书或证书链)，可选项，如果不填，则直接输出到控制台 230 2316.通用证书生成，可以生成自定义证书 232 233 generate-cert : 通用证书生成，可以生成自定义证书 234 ├── -keyAlias # 密钥别名，必填项 235 ├── -keyPwd # 密钥口令，可选项 236 ├── -issuer # 颁发者的主题，必填项 237 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 238 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 239 ├── -subject # 证书主题，必填项 240 ├── -validity # 证书有效期，可选项，默认为1095天 241 ├── -keyUsage # 密钥用法，必选项，包括digitalSignature, nonRepudiation, keyEncipherment, 242 ├ dataEncipherment, keyAgreement, certificateSignature, crlSignature， 243 ├ encipherOnly和decipherOnly，如果证书包括多个密钥用法，用逗号分隔 244 ├── -keyUsageCritical # keyUsage是否为关键项，可选项，默认为是 245 ├── -extKeyUsage # 扩展密钥用法，可选项，包括clientAuthentication，serverAuthentication， 246 ├ codeSignature，emailProtection，smartCardLogin，timestamp，ocspSignature 247 ├── -extKeyUsageCritical # extKeyUsage是否为关键项，可选项，默认为否 248 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA/SHA384withRSA/SHA256withECDSA/SHA384withECDSA 249 ├── -basicConstraints # 是否包含basicConstraints，可选项，默认为否 250 ├── -basicConstraintsCritical # basicConstraints是否包含为关键项，可选项，默认为否 251 ├── -basicConstraintsCa # 是否为CA，可选项，默认为否 252 ├── -basicConstraintsPathLen # 路径长度，可选项，默认为0 253 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 254 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 255 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 256 ├── -keystorePwd # 密钥库口令，可选项 257 ├── -outFile # 输出证书文件，可选项，如果不填，则直接输出到控制台 258 2597.ProvisionProfile文件签名 260 261 sign-profile : ProvisionProfile文件签名 262 ├── -mode # 签名模式，必填项，包括localSign，remoteSign 263 ├── -keyAlias # 密钥别名，必填项 264 ├── -keyPwd # 密钥口令，可选项 265 ├── -profileCertFile # Profile签名证书（证书链，顺序为实体证书-中间CA证书-根证书），必填项 266 ├── -inFile # 输入的原始Provision Profile文件，必填项 267 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 268 ├── -keystoreFile # 密钥库文件，localSign模式时为必填项，JKS或P12格式 269 ├── -keystorePwd # 密钥库口令，可选项 270 ├── -outFile # 输出签名后的Provision Profile文件，p7b格式，必填项 271 2728.ProvisionProfile文件验签 273 274 verify-profile : ProvisionProfile文件验签 275 ├── -inFile # 已签名的Provision Profile文件，p7b格式，必填项 276 ├── -outFile # 验证结果文件（包含验证结果和profile内容），json格式，可选项；如果不填，则直接输出到控制台 277 2789.hap应用包和二进制工具签名 279 280 sign-app : hap应用包和二进制工具签名 281 ├── -mode # 签名模式，必填项，包括localSign，remoteSign，remoteResign 282 ├── -keyAlias # 密钥别名，必填项 283 ├── -keyPwd # 密钥口令，可选项 284 ├── -appCertFile # 应用签名证书文件（证书链，顺序为实体证书-中间CA证书-根证书），必填项 285 ├── -profileFile # 签名后的Provision Profile文件名，profileSigned为1时为p7b格式，profileSigned为0时为json格式，hap应用包签名必填项，二进制工具签名选填 286 ├── -profileSigned # 指示profile文件是否带有签名，1表示有签名，0表示没有签名，默认为1。可选项 287 ├── -inForm # 输入的原始文件的格式，枚举值：zip、elf或bin；zip和elf支持代码签名，hap 应用包对应zip，二进制工具对应elf，默认zip；可选项 288 ├── -inFile # 输入的原始文件，hap应用、elf或bin文件，必填项 289 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 290 ├── -keystoreFile # 密钥库文件，localSign模式时为必填项，JKS或P12格式 291 ├── -keystorePwd # 密钥库口令，可选项 292 ├── -outFile # 输出签名后的包文件，必填项 293 ├── -signCode # 是否启用代码签名，1表示开启代码签名，0表示关闭代码签名，默认为1。可选项 294 29510.hap应用包和二进制工具文件验签 296 297 verify-app : hap应用包和二进制工具文件验签 298 ├── -inFile # 已签名的文件，hap应用、elf或bin文件，必填项 299 ├── -outCertChain # 签名的证书链文件，必填项 300 ├── -outProfile # 应用包中的profile文件，必填项 301 ├── -inForm # 输入的原始文件的格式，枚举值：zip、elf或bin；zip和elf支持代码签名，hap 应用包对应zip，二进制工具对应elf，默认zip；可选项 302 303 304#### 相关仓 305 不涉及
