1# Hap包签名工具指导 2 3## 编译构建 4 5 1. 该工具基于Gradle 7.1编译构建，请确认环境已安装配置Gradle环境，并且版本高于或等于7.1。 6 7 ```shell 8 gradle -v 9 ``` 10 11 2. 下载代码，命令行打开文件目录至developtools_hapsigner/hapsigntool，执行命令进行编译打包。 12 13 ```shell 14 gradle build 15 ``` 16 或 17 ```shell 18 gradle jar 19 ``` 20 21 3. 编译后得到二进制文件，目录为: ./hap_sign_tool/build/libs/hap-sign-tool.jar。 22 23## 开发指导 24 25### 场景介绍 26 27OpenHarmony系统内置密钥库文件，文件名称为OpenHarmony.p12，内含根CA证书、中间CA证书、最终实体证书等信息，工具基于该密钥库文件对OpenHarmony应用进行签名。 28 29按照有无应用签名证书可分为以下两种场景： 30 311. 无应用签名证书场景： 32 开发者使用该工具对Hap包签名时，需按照签名步骤从第一步生成应用签名证书密钥对依次完成应用签名证书生成、profile文件签名、应用签名流程。 332. 有应用签名证书场景： 34 开发者可直接从签名步骤第三步对profile文件进行签名开始开发，使用应用签名证书和包含对应密钥的本地密钥库文件对应用进行签名。 35 36### 命令说明 37 381. 输出命令帮助信息。 39 40 ``` 41 -help # 输出命令帮助信息（不输入参数默认输出命令帮助信息） 42 ``` 43 442. 输出版本信息。 45 46 ``` 47 -version # 输出版本信息 48 ``` 49 503. 生成密钥对。 51 52 ``` 53 generate-keypair : 生成密钥对 54 ├── -keyAlias # 密钥别名，必填项 55 ├── -keyPwd # 密钥口令，可选项 56 ├── -keyAlg # 密钥算法，必填项，包括RSA/ECC 57 ├── -keySize # 密钥长度，必填项，RSA算法的长度为2048/3072/4096，ECC算法的长度NIST-P-256/NIST-P-384 58 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 59 ├── -keystorePwd # 密钥库口令，可选项 60 ``` 61 624. 生成证书签名请求。 63 ``` 64 generate-csr : 生成证书签名请求 65 ├── -keyAlias # 密钥别名，必填项 66 ├── -keyPwd # 密钥口令，可选项 67 ├── -subject # 证书主题，必填项 68 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA 69 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 70 ├── -keystorePwd # 密钥库口令，可选项 71 ├── -outFile # 输出文件，可选项，如果不填，则直接输出到控制台 72 ``` 73 745. 生成根CA/中间CA证书。 75 76 ``` 77 generate-ca : 生成根CA/中间CA证书，如果密钥不存在，一起生成密钥 78 ├── -keyAlias # 密钥别名，必填项 79 ├── -keyPwd # 密钥口令，可选项 80 ├── -keyAlg # 密钥算法，必填项，包括RSA/ECC 81 ├── -keySize # 密钥长度，必填项，RSA算法的长度为2048/3072/4096，ECC算法的长度NIST-P-256/NIST-P-384 82 ├── -issuer # 颁发者的主题，可选项，如果不填，表示根CA 83 ├── -issuerKeyAlias # 颁发者的密钥别名，可选项，如果不填，表示根CA 84 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 85 ├── -subject # 证书主题，必填项 86 ├── -validity # 证书有效期，可选项，默认为3650天 87 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA 88 ├── -basicConstraintsPathLen # 路径长度，可选项，默认为0 89 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 90 ├── -keystorePwd # 密钥库口令，可选项 91 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 92 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 93 ├── -outFile # 输出文件，可选项，如果不填，则直接输出到控制台 94 ``` 95 966. 生成应用调试/发布证书。 97 98 ``` 99 generate-app-cert : 生成应用调试/发布证书 100 ├── -keyAlias # 密钥别名，必填项 101 ├── -keyPwd # 密钥口令，可选项 102 ├── -issuer # 颁发者的主题，必填项 103 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 104 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 105 ├── -subject # 证书主题，必填项 106 ├── -validity # 证书有效期，可选项，默认为3650天 107 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA； 108 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 109 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 110 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 111 ├── -keystorePwd # 密钥库口令，可选项 112 ├── -outForm # 输出证书文件的格式，包括 cert / certChain，可选项，默认为certChain 113 ├── -rootCaCertFile # outForm为certChain时必填，根CA证书文件 114 ├── -subCaCertFile # outForm为certChain时必填，中间CA证书文件 115 ├── -outFile # 输出证书文件(证书或证书链)，可选项，如果不填，则直接输出到控制台 116 ``` 117 1187. 生成profile调试/发布证书。 119 120 ``` 121 generate-profile-cert : 生成profile调试/发布证书 122 ├── -keyAlias # 密钥别名，必填项 123 ├── -keyPwd # 密钥口令，可选项 124 ├── -issuer # 颁发者的主题，必填项 125 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 126 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 127 ├── -subject # 证书主题，必填项 128 ├── -validity # 证书有效期，可选项，默认为3650天 129 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA； 130 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 131 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 132 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 133 ├── -keystorePwd # 密钥库口令，可选项 134 ├── -outForm # 输出证书文件的格式，包括 cert / certChain，可选项，默认为certChain 135 ├── -rootCaCertFile # outForm为certChain时必填，根CA证书文件 136 ├── -subCaCertFile # outForm为certChain时必填，中间CA证书文件 137 ├── -outFile # 输出证书文件(证书或证书链)，可选项，如果不填，则直接输出到控制台 138 ``` 139 1408. 通用证书生成，可以生成自定义证书。 141 142 ``` 143 generate-cert : 通用证书生成，可以生成自定义证书 144 ├── -keyAlias # 密钥别名，必填项 145 ├── -keyPwd # 密钥口令，可选项 146 ├── -issuer # 颁发者的主题，必填项 147 ├── -issuerKeyAlias # 颁发者的密钥别名，必填项 148 ├── -issuerKeyPwd # 颁发者的密钥口令，可选项 149 ├── -subject # 证书主题，必填项 150 ├── -validity # 证书有效期，可选项，默认为1095天 151 ├── -keyUsage # 密钥用法，必选项，包括digitalSignature, nonRepudiation, keyEncipherment, 152 ├ dataEncipherment, keyAgreement, certificateSignature, crlSignature， 153 ├ encipherOnly和decipherOnly，如果证书包括多个密钥用法，用逗号分隔 154 ├── -keyUsageCritical # keyUsage是否为关键项，可选项，默认为是 155 ├── -extKeyUsage # 扩展密钥用法，可选项，包括clientAuthentication，serverAuthentication， 156 ├ codeSignature，emailProtection，smartCardLogin，timestamp，ocspSignature 157 ├── -extKeyUsageCritical # extKeyUsage是否为关键项，可选项，默认为否 158 ├── -signAlg # 签名算法，必填项，包括SHA256withRSA/SHA384withRSA/SHA256withECDSA/SHA384withECDSA 159 ├── -basicConstraints # 是否包含basicConstraints，可选项，默认为否 160 ├── -basicConstraintsCritical # basicConstraints是否包含为关键项，可选项，默认为否 161 ├── -basicConstraintsCa # 是否为CA，可选项，默认为否 162 ├── -basicConstraintsPathLen # 路径长度，可选项，默认为0 163 ├── -issuerKeystoreFile # 签发者密钥库文件，可选项，JKS或P12格式 164 ├── -issuerKeystorePwd # 签发者密钥库口令，可选项 165 ├── -keystoreFile # 密钥库文件，必填项，JKS或P12格式 166 ├── -keystorePwd # 密钥库口令，可选项 167 ├── -outFile # 输出证书文件，可选项，如果不填，则直接输出到控制台 168 ``` 169 1709. profile文件签名。 171 172 ``` 173 sign-profile : profile文件签名 174 ├── -mode # 签名模式，必填项，包括localSign，remoteSign 175 ├── -keyAlias # 密钥别名，必填项 176 ├── -keyPwd # 密钥口令，可选项 177 ├── -profileCertFile # Profile签名证书（证书链，顺序为最终实体证书-中间CA证书-根证书），必填项 178 ├── -inFile # 输入原始的模板Profile文件，文件为json格式，所在目录为developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json，必填项 179 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 180 ├── -keystoreFile # 密钥库文件，localSign模式时为必填项，JKS或P12格式 181 ├── -keystorePwd # 密钥库口令，可选项 182 ├── -outFile # 输出签名后的profile文件，p7b格式，必填项 183 ``` 184 18510. profile文件验签。 186 187 ``` 188 verify-profile : profile文件验签 189 ├── -inFile # 已签名的profile文件，p7b格式，必填项 190 ├── -outFil # 验证结果文件（包含验证结果和profile内容），json格式，可选项；如果不填，则直接输出到控制台 191 ``` 192 19311. hap应用包签名。 194 195 ``` 196 sign-app : hap应用包签名 197 ├── -mode # 签名模式，必填项，包括localSign，remoteSign，remoteResign 198 ├── -keyAlias # 密钥别名，必填项 199 ├──-keyPwd # 密钥口令，可选项 200 ├── -appCertFile # 应用签名证书文件（证书链，顺序为最终实体证书-中间CA证书-根证书），必填项 201 ├── -profileFile # 签名后的profile文件名，p7b格式，必填项 202 ├── -profileSigned # 指示profile文件是否带有签名，1表示有签名，0表示没有签名，默认为1。可选项 203 ├── -inForm # 输入的原始文件的格式，zip格式或bin格式，默认zip格式，可选项 204 ├── -inFile # 输入的原始APP包文件，hap格式或bin格式，必填项 205 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 206 ├── -keystoreFile # 密钥库文件，localSign模式时为必填项，JKS或P12格式 207 ├── -keystorePwd # 密钥库口令，可选项 208 ├── -outFile # 输出签名后的包文件，必填项 209 ``` 210 21112. hap应用包文件验签。 212 213 ``` 214 verify-app : hap应用包文件验签 215 ├── -inFile # 已签名的应用包文件，hap格式或bin格式，必填项 216 ├── -outCertchain # 签名的证书链文件，必填项 217 ├── -outProfile # 应用包中的profile文件，必填项 218 ``` 219 220### 签名步骤 221对hap包签名的完整步骤为： 222 223- 生成应用签名证书密钥对 224- 生成应用签名证书 225- 对profile文件进行签名 226- 对Hap包进行签名 227 228 229> **注意事项：** <br/> 230> 231> 1. 步骤一中的密钥对算法推荐使用ECC，出于安全性考虑，应用签名暂不使用RSA算法。 232> 2. 建议将待签名hap包、profile文件、密钥库文件OpenHarmony.p12、根CA证书、中间CA证书、签名工具放在同一个目录下，方便操作。在[**developtools_hapsigner/autosign/result**](https://gitee.com/openharmony/developtools_hapsigner/tree/master/autosign/result)路径下，有如下文件：<br/>- OpenHarmony密钥库文件**OpenHarmony.p12**<br/>- 根CA证书**rootCA.cer**<br/>- 中间CA证书**subCA.cer**<br/>- profile签名证书**OpenHarmonyProfileRelease.pem** 233 2341. **生成应用签名证书密钥对** 235 236 调用密钥对生成接口，生成签名密钥并保存到密钥库。 237 238 命令实例： 239 240 ```shell 241 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" 242 ``` 243 244 > **说明：** 请记录下**keyAlias、keyStorePwd**和**keyPwd**的值，在后续生成应用 签名证书和对Hap包进行签名操作会使用到。 245 246 该命令的参数说明： 247 248 ``` 249 generate-keypair : 生成应用签名证书密钥对 250 ├── -keyAlias #用于生成应用签名证书的密钥别名，存于OpenHarmony.p12密钥库文件中，该参数必填 251 ├── -keyAlg #密钥算法，推荐使用ECC，该参数必填 252 ├── -keySize #密钥长度，ECC算法的长度NIST-P-256/NIST-P-384，该参数必填 253 ├── -keyStoreFile #密钥库文件，推荐使用提供的OpenHarmony.p12密钥库文件，该参数必填 254 ├── -keyStorePwd #密钥库口令，OpenHarmony.p12口令默认为“123456”，必填项 255 ├── -keyPwd #密钥口令，可选项，该参数不填默认生成的密钥对无口令 256 ``` 257 2582. **生成应用签名证书** 259 260 调用应用签名证书生成接口，使用本地中间CA证书签发应用签名证书。 261 262 命令实例： 263 264 ```shell 265 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" 266 ``` 267 268 该命令的参数说明： 269 270 ``` 271 generate-app-cert：生成应用签名证书 272 ├── -keyAlias # 用于生成应用签名证书的密钥别名，请与第一步生成密钥对的密钥别名-keyAlias保持一致 273 ├── -signAlg # 签名算法，必填项，包括 SHA256withECDSA / SHA384withECDSA 274 ├── -issuer # 颁发者主题，填写已提供的中间CA证书主题，该参数必填且不能修改 275 ├── -issuerKeyAlias # 颁发者密钥别名，填写中间CA证书密钥别名，该参数必填且不能修改 276 ├── -subject # 证书主题，请参照命令实例中内容保证顺序不变，该参数必填 277 ├── -issuerKeyPwd # 颁发者密钥口令，填写中间CA证书密钥口令，该参数必填，指定“123456”，不可修改 278 ├── -keystoreFile # 密钥库文件，指定使用提供的OpenHarmony.p12密钥库文件，该参数必填且不可修改 279 ├── -rootCaCertFile # 根CA证书文件，指定为已提供的根CA证书，该参数必填且不可修改 280 ├── -subCaCertFile # 中间CA证书文件，指定为已提供的中间CA证书，该参数必填且不可修改 281 ├── -outForm # 输出证书文件格式，推荐使用certChain 282 ├── -outFile # 可选项，建议填写，不填则默认输出到控制台 283 ├── -keyPwd # 密钥口令，可选项，为第一步生成的密钥对口令 284 ├── -keystorePwd # 密钥库口令，默认为“123456” 285 ├── -validity # 证书有效期，可选项，默认为3650天 286 ``` 287 2883. **对profile文件进行签名** 289 290 调用profile文件签名接口，使用Profile签名密钥对profile文件进行签名。 291 292 命令实例： 293 294 ```shell 295 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" 296 ``` 297 298 该命令的参数说明： 299 300 ``` 301 sign-profile：签名profile文件 302 ├── -keyAlias # 生成profile证书的密钥别名，该参数必填且不能修改 303 ├── -signAlg # 签名算法，包括 SHA256withECDSA / SHA384withECDSA，该参数必填 304 ├── -mode # 签名模式，目前仅支持localSign，该参数必填 305 ├── -profileCertFile # Profile签名证书，指定已提供的profile证书文件，该参数必填且不可修改 306 ├── -inFile # 输入原始的模板Profile文件，文件为json格式，所在目录为developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json，该参数必填 307 ├── -keystoreFile # 密钥库文件，指定使用提供的OpenHarmony.p12密钥库文件，该参数必填且不可修改 308 ├── -outFile # 输出签名后的profile文件，p7b格式，该参数必填 309 ├── -keyPwd # 密钥口令，OpenHarmony.p12中的口令默认“123456” 310 ├── -keystorePwd # 密钥库口令，OpenHarmony.p12口令默认为“123456” 311 ``` 312 3134. **对Hap包进行签名** 314 315 调用Hap包签名接口，使用应用签名密钥为Hap包签名。 316 317 命令实例： 318 319 ```shell 320 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" 321 ``` 322 > **说明**：以下参数说明默认为无应用签名证书场景，当开发场景为有应用签名证书场景时，下列参数需要修改： 323 > -keyAlias：密钥别名，填写已有应用签名证书对应的密钥别名，参数必填。 324 > -appCertFile：应用签名证书，填写已有的应用签名证书，参数必填。 325 > -keystoreFile：密钥库文件，填写已有应用签名证书对应的密钥库文件，参数必填。 326 > -keyPwd：密钥口令，填写密钥库文件中对应密钥的口令。 327 > -keystorePwd：密钥库口令，填写密钥库文件的密钥口令。 328 329 该命令的参数说明： 330 331 ``` 332 sign-app：签名Hap包 333 ├── -keyAlias # 密钥别名，为第一步生成的密钥信息别名，该参数必填 334 ├── -signAlg # 签名算法，包括 SHA256withECDSA / SHA384withECDSA，该参数必填 335 ├── -mode # 签名模式，目前仅支持localSign，该参数必填 336 ├── -appCertFile # 应用签名证书（证书链，顺序为最终实体证书-中间CA证书-根证书），填写第二步生成的应用签名证书，该参数必填 337 ├── -profileFile # 签名后的profile文件，p7b格式，填写第三步中生成的profile文件，必填项 338 ├── -inFile # 输入原始APP包文件，该参数必填 339 ├── -keystoreFile # 密钥库文件，请与步骤一中密钥库文件保持一致，该参数必填且不可修改 340 ├── -outFile # 输出签名后的包文件，必填项 341 ├── -keyPwd # 密钥口令，与第一步生成的密钥对口令保持一致 342 ├── -keystorePwd # 密钥库口令，与第一步的密钥库口令保持一致 343 ``` 344 345 346## 常见问题 347 3481. 执行第二步生成应用签名证书命令时，控制台打印结果，无文件输出。 349 350 - **现象描述** 351 352 生成证书时，只在控制台打印证书内容，无对应文件输出。 353 354 - **可能原因** 355 356 outFile参数中路径不正确 和 '-outFile'中的'-'非英文格式。 357 358 - **解决办法** 359 360 检查并修正outFile参数为正确路径，'-outFile'中的'-'为英文格式 361 3622. 执行第三步对profile文件进行签名时，提示签名失败。 363 364 - **现象描述** 365 366 现象分为以下几种： 367 368 （1）执行命令后提示` "SIGN_ERROR, code: 107. Details: Failed to verify signature: Wrong key usage"` 369 370 （2）执行命令后提示 `"NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'result\profile1.pem' must a cert chain"` 371 372 （3）执行命令后提示` "VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target"` 373 374 - **可能原因** 375 376 （1）profile签名证书（最终实体证书）证书链顺序不正确。 377 378 （2）profile签名证书（最终实体证书）不是证书链。 379 380 （3）证书主题顺序不正确 或者 生成应用签名证书时“-issuerKeyAlias”参数填写错误。 381 382 - **解决办法** 383 384 （1）检查并修正证书链顺序，只能正序或反序，不可乱序。 385 386 （2）检查签名时的最终实体证书是否为证书链。 387 388 （3）检查证书主题顺序是否正确，顺序须为C、O、OU、CN。 389 3903. 对Hap包进行签名时提示签名错误。 391 392 - **现象描述** 393 394 执行命令后提示：`NOT_SUPPORT_ERROR, code: 105. Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA`。 395 396 - **可能原因** 397 398 签名算法不支持，signAlg参数填写错误。 399 400 - **解决办法** 401 402 最终实体证书密钥对推荐使用ECC生成，hap签名算法修改为ECC对应的SHA256withECDSA,SHA384withECDSA。 403