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格式、elf格式或bin格式，默认zip格式，可选项 204 ├── -inFile # 输入的原始APP包文件，hap格式或bin格式，必填项 205 ├── -signAlg # 签名算法，必填项，包括SHA256withECDSA / SHA384withECDSA 206 ├── -keystoreFile # 密钥库文件，localSign模式时为必填项，JKS或P12格式 207 ├── -keystorePwd # 密钥库口令，可选项 208 ├── -outFile # 输出签名后的包文件，必填项 209 ├── -signCode # 是否启用代码签名，1表示开启代码签名，0表示关闭代码签名，默认为1。可选项 210 ``` 211 21212. hap应用包和调试工具文件验签。 213 214 ``` 215 verify-app : hap应用包和调试工具文件验签 216 ├── -inFile # 已签名的应用包文件，hap格式或bin格式，必填项 217 ├── -outCertchain # 签名的证书链文件，必填项 218 ├── -outProfile # 应用包中的profile文件，必填项 219 ├── -inForm # 输入的原始文件的格式，zip格式、elf格式或bin格式，默认zip格式，可选项 220 ``` 221 222### 签名步骤 223对hap包签名的完整步骤为： 224 225- 生成应用签名证书密钥对 226- 生成应用签名证书 227- 对profile文件进行签名 228- 对Hap包进行签名 229 230 231> **注意事项：** <br/> 232> 233> 1. 步骤一中的密钥对算法推荐使用ECC，出于安全性考虑，应用签名暂不使用RSA算法。 234> 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** 235 2361. **生成应用签名证书密钥对** 237 238 调用密钥对生成接口，生成签名密钥并保存到密钥库。 239 240 命令实例： 241 242 ```shell 243 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" 244 ``` 245 246 > **说明：** 247 > 248 > 请记录下**keyAlias、keyStorePwd**和**keyPwd**的值，在后续生成应用 签名证书和对Hap包进行签名操作会使用到。 249 250 该命令的参数说明： 251 252 ``` 253 generate-keypair : 生成应用签名证书密钥对 254 ├── -keyAlias #用于生成应用签名证书的密钥别名，存于OpenHarmony.p12密钥库文件中，该参数必填 255 ├── -keyAlg #密钥算法，推荐使用ECC，该参数必填 256 ├── -keySize #密钥长度，ECC算法的长度NIST-P-256/NIST-P-384，该参数必填 257 ├── -keyStoreFile #密钥库文件，推荐使用提供的OpenHarmony.p12密钥库文件，该参数必填 258 ├── -keyStorePwd #密钥库口令，OpenHarmony.p12口令默认为“123456”，必填项 259 ├── -keyPwd #密钥口令，可选项，该参数不填默认生成的密钥对无口令 260 ``` 261 2622. **生成应用签名证书** 263 264 调用应用签名证书生成接口，使用本地中间CA证书签发应用签名证书。 265 266 命令实例： 267 268 ```shell 269 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" 270 ``` 271 272 该命令的参数说明： 273 274 ``` 275 generate-app-cert：生成应用签名证书 276 ├── -keyAlias # 用于生成应用签名证书的密钥别名，请与第一步生成密钥对的密钥别名-keyAlias保持一致 277 ├── -signAlg # 签名算法，必填项，包括 SHA256withECDSA / SHA384withECDSA 278 ├── -issuer # 颁发者主题，填写已提供的中间CA证书主题，该参数必填且不能修改 279 ├── -issuerKeyAlias # 颁发者密钥别名，填写中间CA证书密钥别名，该参数必填且不能修改 280 ├── -subject # 证书主题，请参照命令实例中内容保证顺序不变，该参数必填 281 ├── -issuerKeyPwd # 颁发者密钥口令，填写中间CA证书密钥口令，该参数必填，指定“123456”，不可修改 282 ├── -keystoreFile # 密钥库文件，指定使用提供的OpenHarmony.p12密钥库文件，该参数必填且不可修改 283 ├── -rootCaCertFile # 根CA证书文件，指定为已提供的根CA证书，该参数必填且不可修改 284 ├── -subCaCertFile # 中间CA证书文件，指定为已提供的中间CA证书，该参数必填且不可修改 285 ├── -outForm # 输出证书文件格式，推荐使用certChain 286 ├── -outFile # 可选项，建议填写，不填则默认输出到控制台 287 ├── -keyPwd # 密钥口令，可选项，为第一步生成的密钥对口令 288 ├── -keystorePwd # 密钥库口令，默认为“123456” 289 ├── -validity # 证书有效期，可选项，默认为3650天 290 ``` 291 2923. **对profile文件进行签名** 293 294 调用profile文件签名接口，使用Profile签名密钥对profile文件进行签名。 295 296 命令实例： 297 298 ```shell 299 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" 300 ``` 301 302 该命令的参数说明： 303 304 ``` 305 sign-profile：签名profile文件 306 ├── -keyAlias # 生成profile证书的密钥别名，该参数必填且不能修改 307 ├── -signAlg # 签名算法，包括 SHA256withECDSA / SHA384withECDSA，该参数必填 308 ├── -mode # 签名模式，目前仅支持localSign，该参数必填 309 ├── -profileCertFile # Profile签名证书，指定已提供的profile证书文件，该参数必填且不可修改 310 ├── -inFile # 输入原始的模板Profile文件，文件为json格式，所在目录为developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json，该参数必填 311 ├── -keystoreFile # 密钥库文件，指定使用提供的OpenHarmony.p12密钥库文件，该参数必填且不可修改 312 ├── -outFile # 输出签名后的profile文件，p7b格式，该参数必填 313 ├── -keyPwd # 密钥口令，OpenHarmony.p12中的口令默认“123456” 314 ├── -keystorePwd # 密钥库口令，OpenHarmony.p12口令默认为“123456” 315 ``` 316 3174. **对Hap包进行签名** 318 319 调用Hap包签名接口，使用应用签名密钥为Hap包签名。 320 321 命令实例： 322 323 ```shell 324 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" 325 ``` 326 > **说明**： 327 > 328 > 以下参数说明默认为无应用签名证书场景，当开发场景为有应用签名证书场景时，下列参数需要修改： 329 > -keyAlias：密钥别名，填写已有应用签名证书对应的密钥别名，参数必填。 330 > -appCertFile：应用签名证书，填写已有的应用签名证书，参数必填。 331 > -keystoreFile：密钥库文件，填写已有应用签名证书对应的密钥库文件，参数必填。 332 > -keyPwd：密钥口令，填写密钥库文件中对应密钥的口令。 333 > -keystorePwd：密钥库口令，填写密钥库文件的密钥口令。 334 335 该命令的参数说明： 336 337 ``` 338 sign-app：签名Hap包 339 ├── -keyAlias # 密钥别名，为第一步生成的密钥信息别名，该参数必填 340 ├── -signAlg # 签名算法，包括 SHA256withECDSA / SHA384withECDSA，该参数必填 341 ├── -mode # 签名模式，目前仅支持localSign，该参数必填 342 ├── -appCertFile # 应用签名证书（证书链，顺序为最终实体证书-中间CA证书-根证书），填写第二步生成的应用签名证书，该参数必填 343 ├── -profileFile # 签名后的profile文件，p7b格式，填写第三步中生成的profile文件，必填项 344 ├── -inFile # 输入原始APP包文件，该参数必填 345 ├── -keystoreFile # 密钥库文件，请与步骤一中密钥库文件保持一致，该参数必填且不可修改 346 ├── -outFile # 输出签名后的包文件，必填项 347 ├── -keyPwd # 密钥口令，与第一步生成的密钥对口令保持一致 348 ├── -keystorePwd # 密钥库口令，与第一步的密钥库口令保持一致 349 ``` 350 351 352## 常见问题 353 3541. 执行第二步生成应用签名证书命令时，控制台打印结果，无文件输出。 355 356 - **现象描述** 357 358 生成证书时，只在控制台打印证书内容，无对应文件输出。 359 360 - **可能原因** 361 362 outFile参数中路径不正确 和 '-outFile'中的'-'非英文格式。 363 364 - **解决办法** 365 366 检查并修正outFile参数为正确路径，'-outFile'中的'-'为英文格式 367 3682. 执行第三步对profile文件进行签名时，提示签名失败。 369 370 - **现象描述** 371 372 现象分为以下几种： 373 374 （1）执行命令后提示` "SIGN_ERROR, code: 107. Details: Failed to verify signature: Wrong key usage"` 375 376 （2）执行命令后提示 `"NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'result\profile1.pem' must a cert chain"` 377 378 （3）执行命令后提示` "VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target"` 379 380 - **可能原因** 381 382 （1）profile签名证书（最终实体证书）证书链顺序不正确。 383 384 （2）profile签名证书（最终实体证书）不是证书链。 385 386 （3）证书主题顺序不正确 或者 生成应用签名证书时“-issuerKeyAlias”参数填写错误。 387 388 - **解决办法** 389 390 （1）检查并修正证书链顺序，只能正序或反序，不可乱序。 391 392 （2）检查签名时的最终实体证书是否为证书链。 393 394 （3）检查证书主题顺序是否正确，顺序须为C、O、OU、CN。 395 3963. 对Hap包进行签名时提示签名错误。 397 398 - **现象描述** 399 400 执行命令后提示：`NOT_SUPPORT_ERROR, code: 105. Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA`。 401 402 - **可能原因** 403 404 签名算法不支持，signAlg参数填写错误。 405 406 - **解决办法** 407 408 最终实体证书密钥对推荐使用ECC生成，hap签名算法修改为ECC对应的SHA256withECDSA,SHA384withECDSA。 409 4104. 签名hap包失败，提示证书CN字段为空。 411 412 - **现象描述** 413 414 执行命令后提示：`error: Common name of certificate is empty! `。 415 416 - **可能原因** 417 418 当前使用的hap包签名证书，不包含CN字段，导致签名失败。 419 420 - **解决办法** 421 422 根据业界证书规范，hap包签名证书的CN字段必须不为空，请重新生成格式正确的证书。 423