1# hapsigner Guide 2 3## Build 4 5 1. Check that Gradle 7.1 has been installed. 6 7 ```shell 8 gradle -v 9 ``` 10 11 2. Download the code, open the file directory **developtools_hapsigner/hapsigntool**, and run the following command to build the code: 12 13 ```shell 14 gradle build 15 ``` 16 Or 17 ```shell 18 gradle jar 19 ``` 20 21 3. Check that **hap-sign-tool.jar** (binary files) is generated in the **./hap_sign_tool/build/libs** directory. 22 23## Usage Guidelines 24 25### When to Use 26 27The OpenHarmony system has a built-in KeyStore (KS) file named **OpenHarmony.p12**. This file contains the root CA certificate, intermediate CA certificate, and end-entity certificate information. The hapsigner tool signs the OpenHarmony applications based on this KS file. 28 29The usage of hapsigner varies depending on whether an application signing certificate is available. 30 31- If no application signing certificate is available:<br/> 32 You need to generate a key pair, generate an application signing certificate, sign the profile, and sign the application. 33- If an application signing certification is available:<br/> 34 You need to sign the profile, and use the application signing certificate and the local KS file (containing the corresponding key) to sign the application. 35 36### Description 37 381. Display command help information. 39 40 ``` 41 -help # If no parameter is specified, the command help information is displayed by default. 42 ``` 43 442. Display version information 45 46 ``` 47 -version # Display the tool version information. 48 ``` 49 503. Generate a key pair. 51 52 ``` 53 generate-keypair: Generate a key pair. 54 ├── -keyAlias # Key alias. It is mandatory. 55 ├── -keyPwd # Key password. It is optional. 56 ├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory. 57 ├── -keySize # Key length. It is mandatory. The key length is 2048, 3072, or 4096 bits if RSA is used and is NIST-P-256 or NIST-P-384 if ECC is used. 58 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 59 ├── -keystorePwd # KS password. It is optional. 60 ``` 61 624. Generate a CSR. 63 ``` 64 generate-csr: Generate a CSR. 65 ├── -keyAlias # Key alias. It is mandatory. 66 ├── -keyPwd # Key password. It is optional. 67 ├── -subject # Certificate subject. It is mandatory. 68 ├── -signAlg # Signing algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory. 69 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 70 ├── -keystorePwd # KS password. It is optional. 71 ├── -outFile # CSR to generate. It is optional. If you do not specify this parameter, the CSR is output to the console. 72 ``` 73 745. Generate a root CA or intermediate CA certificate. 75 76 ``` 77 generate-ca: Generate a root CA or intermediate CA certificate. If the key does not exist, generate a key together with the certificate. 78 ├── -keyAlias # Key alias. It is mandatory. 79 ├── -keyPwd # Key password. It is optional. 80 ├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory. 81 ├── -keySize # Key length. It is mandatory. The key length is 2048, 3072, or 4096 bits if RSA is used and is NIST-P-256 or NIST-P-384 if ECC is used. 82 ├── -issuer # Issuer of the certificate. It is optional. It indicates a root CA certificate if not specified. 83 ├── -issuerKeyAlias # Key alias of the issuer. It is optional. It indicates a root CA certificate if not specified. 84 ├── -issuerKeyPwd # Key password of the issuer. It is optional. 85 ├── -subject # Certificate subject. It is mandatory. 86 ├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days. 87 ├── -signAlg # Signing algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory. 88 ├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0. 89 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 90 ├── -keystorePwd # KS password. It is optional. 91 ├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional. 92 ├── -issuerKeystorePwd # KS password of the issuer. It is optional. 93 ├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified. 94 ``` 95 966. Generate an application debug or release certificate. 97 98 ``` 99 generate-app-cert: Generate an application debug or release certificate. 100 ├── -keyAlias # Key alias. It is mandatory. 101 ├── -keyPwd # Key password. It is optional. 102 ├── -issuer # Issuer of the certificate. It is mandatory. 103 ├── -issuerKeyAlias # Key alias of the issuer. It is mandatory. 104 ├── -issuerKeyPwd # Key password of the issuer. It is optional. 105 ├── -subject # Certificate subject. It is mandatory. 106 ├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days. 107 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. 108 ├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional. 109 ├── -issuerKeystorePwd # KS password of the issuer. It is optional. 110 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 111 ├── -keystorePwd # KS password. It is optional. 112 ├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain. 113 ├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain. 114 ├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain. 115 ├── -outFile # Certificate file (certificate or certificate chain) to generate. It is optional. The file is output to the console if this parameter is not specified. 116 ``` 117 1187. Generate a profile debug or release certificate. 119 120 ``` 121 generate-profile-cert: Generate a profile debug or release certificate. 122 ├── -keyAlias # Key alias. It is mandatory. 123 ├── -keyPwd # Key password. It is optional. 124 ├── -issuer # Issuer of the certificate. It is mandatory. 125 ├── -issuerKeyAlias # Key alias of the issuer. It is mandatory. 126 ├── -issuerKeyPwd # Key password of the issuer. It is optional. 127 ├── -subject # Certificate subject. It is mandatory. 128 ├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days. 129 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. 130 ├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional. 131 ├── -issuerKeystorePwd # KS password of the issuer. It is optional. 132 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 133 ├── -keystorePwd # KS password. It is optional. 134 ├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain. 135 ├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain. 136 ├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain. 137 ├── -outFile # Certificate file (certificate or certificate chain) to generate. It is optional. The file is output to the console if this parameter is not specified. 138 ``` 139 1408. Generate a common certificate, which can be used to generate a custom certificate. 141 142 ``` 143 generate-cert: Generate a common certificate, which can be used to generate a custom certificate. 144 ├── -keyAlias # Key alias. It is mandatory. 145 ├── -keyPwd # Key password. It is optional. 146 ├── -issuer # Issuer of the certificate. It is mandatory. 147 ├── -issuerKeyAlias # Key alias of the issuer. It is mandatory. 148 ├── -issuerKeyPwd # Key password of the issuer. It is optional. 149 ├── -subject # Certificate subject. It is mandatory. 150 ├── -validity # Validity period of the certificate. It is optional. The default value is 1095 days. 151 ├── -keyUsage # Usages of the key. It is mandatory. The key usages include digitalSignature, nonRepudiation, keyEncipherment, 152 ├ dataEncipherment, keyAgreement, certificateSignature, crlSignature, 153 ├ encipherOnly, and decipherOnly. Use a comma (,) to separate multiple values. 154 ├── -keyUsageCritical # Whether keyUsage is a critical option. It is optional. The default value is true. 155 ├── -extKeyUsage # Extended key usages. It is optional. The extended key usages include clientAuthentication, serverAuthentication, 156 ├ codeSignature, emailProtection, smartCardLogin, timestamp, and ocspSignature. 157 ├── -extKeyUsageCritical # Whether extKeyUsage is a critical option. It is optional. The default value is false. 158 ├── -signAlg # Signing algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory. 159 ├── -basicConstraints # Whether basicConstraints is contained. It is optional. The default value is false. 160 ├── -basicConstraintsCritical # Whether basicConstraints is a critical option. It is optional. The default value is false. 161 ├── -basicConstraintsCa # Whether it is CA. It is optional. The default value is false. 162 ├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0. 163 ├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional. 164 ├── -issuerKeystorePwd # KS password of the issuer. It is optional. 165 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory. 166 ├── -keystorePwd # KS password. It is optional. 167 ├── -outFile # Certificate file to generate. It is optional. The file is output to the console if this parameter is not specified. 168 ``` 169 1709. Sign a profile. 171 172 ``` 173 sign-profile: Sign a profile. 174 ├── -mode # Signing mode, which can be localSign or remoteSign. It is mandatory. 175 ├── -keyAlias # Key alias. It is mandatory. 176 ├── -keyPwd # Key password. It is optional. 177 ├── -profileCertFile # Profile signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory. 178 ├── -inFile # Raw profile template in JSON format (developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json). It is mandatory. 179 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory. 180 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign. 181 ├── -keystorePwd # KS password. It is optional. 182 ├── -outFile # Signed profile to generate, in p7b format. This parameter is mandatory. 183 ``` 184 18510. Verify the signature of the profile. 186 187 ``` 188 verify-profile: Verify the profile signature. 189 ├── -inFile # Signed profile in p7b format. This parameter is mandatory. 190 ├── -outFile # Verification result file (including the verification result and profile content), in json format. It is optional. The file is output to the console if this parameter is not specified. 191 ``` 192 19311. Sign a HAP. 194 195 ``` 196 sign-app: Sign a HAP. 197 ├── -mode # Signing mode, which can be localSign, remoteSign, or remoteResign. It is mandatory. 198 ├── -keyAlias # Key alias. It is mandatory. 199 ├── -keyPwd # Key password. It is optional. 200 ├── -appCertFile # Application signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory. 201 ├── -profileFile # Name of the signed profile in p7b format. This parameter is mandatory. 202 ├── -profileSigned # Whether the profile is signed. The value 1 means signed, and value 0 means unsigned. The default value is 1. This parameter is optional. 203 ├── -inForm # Raw file, in .zip (default) or .bin format. It is optional. 204 ├── -inFile # Raw application package, in HAP or .bin format. It is mandatory. 205 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory. 206 ├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign. 207 ├── -keystorePwd # KS password. It is optional. 208 ├── -outFile # Signed HAP file to generate. It is mandatory. 209 ``` 210 21112. Verify the HAP signature. 212 213 ``` 214 verify-app: Verify the HAP signature. 215 ├── -inFile # Signed application file, in HAP or bin format. It is mandatory. 216 ├── -outCertchain # Signed certificate chain file. It is mandatory. 217 ├── -outProfile # Profile of the application. It is mandatory. 218 ``` 219 220### Signing Procedure 221The process of signing a HAP is as follows: 222 2231. Generate a key pair for an application signing certificate. 2242. Generate an application signing certificate. 2253. Sign the profile. 2264. Sign the HAP. 227 228 229> **Precautions** <br> 230> 231> For security purposes, use ECC to generate the key pair in step 1. Do not use RSA. 232> 233> You are advised to place the HAP to be signed, profile, **OpenHarmony.p12**, root CA certificate, intermediate CA certificate, and hapsigner in the same directory for easy operation. The [**developtools_hapsigner/autosign/result**](https://gitee.com/openharmony/developtools_hapsigner/tree/master/autosign/result) directory has the following files: 234> 235> - OpenHarmony KS file: **OpenHarmony.p12** 236> - Root CA certificate: **rootCA.cer** 237> - Intermediate CA certificate: **subCA.cer** 238> - Profile signing certificate: **OpenHarmonyProfileRelease.pem** 239 2401. **Generate a key pair for the application signing certificate.** 241 242 Generate a signing key pair and save it to the KS. 243 244 Example: 245 246 ```shell 247 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" 248 ``` 249 250 > **NOTE** 251 > 252 > Record the values of **keyAlias**, **keyStorePwd**, and **keyPwd**. These values will be used when the application signing certificate is generated and the HAP is signed. 253 254 The command parameters are described as follows: 255 256 ``` 257 generate-keypair: Generate a key pair for the application signing certificate. 258 ├── -keyAlias # Alias of the key used to generate the application signing certificate. It is stored in the OpenHarmony.p12 file. This parameter is mandatory. 259 ├── -keyAlg # Key algorithm. It is mandatory. ECC is recommended. 260 ├── -keySize # Key length. It is NIST-P-256/NIST-P-384 if ECC is used. This parameter is mandatory. 261 ├── -keyStoreFile # KS file. OpenHarmony.p12 is recommended. This parameter is mandatory. 262 ├── -keyStorePwd # KS password. It is mandatory. The default password 123456 for OpenHarmony.p12. 263 ├── -keyPwd # Key password. It is optional. If this parameter is not specified, the generated key pair has no password. 264 ``` 265 2662. **Generate an application signing certificate.** 267 268 Use the local intermediate CA certificate to issue an application signing certificate. 269 270 Example: 271 272 ```shell 273 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" 274 ``` 275 276 The command parameters are described as follows: 277 278 ``` 279 generate-app-cert: Generate an application signing certificate. 280 ├── -keyAlias # Key alias, which must be the same as that in the previous step. 281 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory. 282 ├── -issuer # Issuer of the certificate. Enter the issuer of the intermediate CA certificate. It is mandatory and cannot be changed. 283 ├── -issuerKeyAlias # Key alias of the issuer. Enter the key alias of the intermediate CA certificate. This parameter is mandatory and cannot be changed. 284 ├── -subject # Subject of the certificate. Enter the subject in the same sequence specified in the command. This parameter is mandatory. 285 ├── -issuerKeyPwd # Key password of the issuer. Enter the key password of the intermediate CA certificate. It is mandatory and cannot be changed. In this example, it is 123456. 286 ├── -keystoreFile # KS file. Use OpenHarmony.p12. It is mandatory and cannot be changed. 287 ├── -rootCaCertFile # Root certificate. It is mandatory and cannot be changed. 288 ├── -subCaCertFile # Intermediate CA certificate. This parameter is mandatory and cannot be changed. 289 ├── -outForm # Format of the certificate file to generate. certChain is recommended. 290 ├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified. 291 ├── -keyPwd # Key password. It is optional. It is the key password set when the key pair is generated. 292 ├── -keystorePwd # KS password. The default value is 123456. 293 ├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days. 294 ``` 295 2963. **Sign the profile.** 297 298 Call the profile signing API to sign the profile using the profile signing key. 299 300 Example: 301 302 ```shell 303 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" 304 ``` 305 306 The command parameters are described as follows: 307 308 ``` 309 sign-profile: Sign a profile. 310 ├── -keyAlias # Alias of the key for generating the profile certificate. It is mandatory and cannot be changed. 311 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory. 312 ├── -mode # Signing mode, which must be localSign. It is mandatory. 313 ├── -profileCertFile # Profile signing certificate. Use the certificate provided. It is mandatory and cannot be changed. 314 ├── -inFile # Raw profile template in JSON format (developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json). It is mandatory. 315 ├── -keystoreFile # KS file. Use OpenHarmony.p12. It is mandatory and cannot be changed. 316 ├── -outFile # Signed profile to generate, in p7b format. This parameter is mandatory. 317 ├── -keyPwd # Key password. The default key password in OpenHarmony.p12 is 123456. 318 ├── -keystorePwd # KS password. The default key password in OpenHarmony.p12 is 123456. 319 ``` 320 3214. **Sign the HAP.** 322 323 Call the HAP signing API to sign the HAP using the application signing key. 324 325 Example: 326 327 ```shell 328 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" 329 ``` 330 > **NOTE** 331 > 332 > The following parameters are used when there is no application signing certificate available. If the application signing certificate is available, the following parameters must be modified. 333 > 334 > - **keyAlias**: Enter the key alias of the application signing certificate. This parameter is mandatory. 335 > - **appCertFile**: Enter the application signing certificate. This parameter is mandatory. 336 > - **keystoreFile**: Enter the KS file of the application signing certificate. This parameter is mandatory. 337> - **keyPwd**: Enter the key password in the KS file. 338 > - **keystorePwd**: Enter the KS password in the KS file. 339 340 The command parameters are described as follows: 341 342 ``` 343 sign-app: Sign a HAP. 344 ├──-keyAlias # Key alias, which must be the same as the alias of the key pair generated. This parameter is mandatory. 345 ├── -signAlg # Signing algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory. 346 ├── -mode # Signing mode, which must be localSign. It is mandatory. 347 ├── -appCertFile # Application signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). Enter the application signing certificate generated in step 2. This parameter is mandatory. 348 ├── -profileFile # Signed profile in p7b format. Enter the profile generated. This parameter is mandatory. 349 ├── -inFile # Raw application package. It is mandatory. 350 ├── -keystoreFile # KS file, which must be the same as the KS file generated. It is mandatory and cannot be changed. 351 ├── -outFile # Signed file to generate. It is mandatory. 352 ├── -keyPwd # Key password, which must be the actual key password. 353 ├── -keystorePwd # KS password, which must be the actual KS password. 354 ``` 355 356 357## FAQs 358 3591. When the application signing certificate is generated, the console displays the result but no file is output. 360 361 - **Symptom** 362 363 When the tool is used to generate an application signing certificate, the certificate content is displayed on the console and no certificate is generated. 364 365 - **Possible Causes** 366 367 The path in the **outFile** parameter is incorrect, or the hyphen (-) in **-outFile** is not an English character. 368 369 - **Solution** 370 371 Check and correct the value of **outFile**, and ensure the hyphen (-) in **-outFile** is an English character. 372 3732. Failed to sign the profile. 374 375 - **Symptom** 376 377 When the tool is used to sign a profile, any of the following information is displayed: 378 379 (1) ` "SIGN_ERROR, code: 107. Details: Failed to verify signature: Wrong key usage"` 380 381 (2) `"NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'result\profile1.pem' must a cert chain"` 382 383 (3) ` "VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target"` 384 385 - **Possible Causes** 386 387 (1) The certificate chain of the profile signing certificate is in incorrect order. 388 389 (2) The profile signing certificate is not a certificate chain. 390 391 (3) The certificate subject is in incorrect sequence, or the **-issuerKeyAlias** parameter set to generate the application signing certificate is incorrect. 392 393 - **Solution** 394 395 (1) Check that the certificate chain is in ascending or descending order of seniority. 396 397 (2) Check that the certificate is a certificate chain. 398 399 (3) Check that the certificate subject is in the C, O, OU, and CN order. 400 4013. An error message is displayed when the tool is used to sign a HAP. 402 403 - **Symptom** 404 405 The following information is displayed after the command is executed:<br>`NOT_SUPPORT_ERROR, code: 105. Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA` 406 407 - **Possible Causes** 408 409 The signing algorithm is not supported. Check the value of **signAlg**. 410 411 - **Solution** 412 413 Use ECC to generate the key pair for the application or profile signing certificate. Use SHA256withECDSA or SHA384withECDSA as the HAP signing algorithm. 414