| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | Verifies whether an app has the specified permission. This API uses a promise to return the result.|
| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | Verifies whether an app has the specified permission. This API uses a promise to return the result.|
## Declaring Permissions
### config.json
Declare the permissions required by the app one by one in the **config.json** file. The app cannot obtain a permission if it is not declared in the **config.json** file.
Declare the permissions required by the app one by one in the **config.json** file. The app can obtain permissions that have been declared in the **config.json** file.
| reason | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
| abilities | Abilities that use the permission. The value is an array.|
| when | Time when the permission is used. The value can be **inuse** (the permission can be used only in the foreground) or **always** (the permission can be used in foreground and background).|
| reason | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
| abilities | Abilities that use the permission. The value is an array.|
| when | Time when the permission is used. The value can be **inuse** (the permission can be used only in the foreground) or **always** (the permission can be used in foreground and background).|
**Example**
```json
{
"module":{
"requesetPermissions":[
"requestPermissions":[
{
"name":"ohos.permission.PERMISSION1",
"reason":"$string:reason",
...
...
@@ -107,7 +107,7 @@ In addition to declaring all the permissions in the **config.json** file, you mu
After the permissions are declared, the system grants the system_grant permission during the installation of the app. The user_grant permission must be authorized by the user.
Therefore, before invoking the API protected by the **ohos.permission.PERMISSION2 permission**, the app needs to verify whether it has the permission.
Therefore, before allowing the app to call the API protected by the **ohos.permission.PERMISSION2** permission, the system needs to verify whether the app has the permission to do so.
If the verification result indicates that the app has the permission, the app can access the target API. Otherwise, the app needs to request user authorization and then proceeds based on the authorization result. For details, see [Access Control Overview](accesstoken-overview.md).
...
...
@@ -119,34 +119,26 @@ If the verification result indicates that the app has the permission, the app ca
The procedure is as follows:
1. Obtain the caller's identity tokenId.
2. Determine the permission to be verified. In this example, the permission is **permissionNameUser**.
3. Call **verifyAccessToken** to verify the permissions of the caller.
4. Proceed based on the permission verification result.
1. Obtain the ability context.
2. Call **requestPermissionsFromUser** to verify whether the app has required permissions.
3. Proceed based on the permission verification result.
@@ -74,7 +74,10 @@ The table below describes the APLs.
| system_basic| The apps of this level provide basic system services. |
| Normal | The apps of this level are normal apps. |
By default, apps are of the normal APL. For the app of the system_basic or system_core APL, declare the app APL level in the **apl** field in the app's profile, and use the profile signing tool to generate a certificate when developing the app installation package. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
By default, apps are of the normal APL.
For the app of the system_basic or system_core APL, declare the app APL level in the **apl** field in the app's profile, and use the profile signing tool to generate a certificate when developing the app installation package. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
### Permission Levels
The permissions open to apps vary with the permission level. The permission levels include the following in ascending order of seniority.
...
...
@@ -105,9 +108,24 @@ The Access Control List (ACL) makes low-level apps have high-level permissions.
**Example**
The APL of app A is normal. App A needs to have permission B (system_basic level) and permission C (normal level). In this case, you can use the ACL to grant permission B to app A.
The APL of app A is normal. App A needs to have permission B (system_basic level) and permission C (normal level).
In this case, you can use the ACL to grant permission B to app A.
For details, see [Using the ACL](#using-the-acl).
For details about whether the ACL is enabled for a permission, see [Permission List](permission-list.md).
### Using the ACL
If the permission required by an app has higher level than the app's APL, you can use the ACL to grant the permissions required.
In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL.
In other words, in addition to declaring the required permissions in the **config.json** file, you must declare the high-level permissions in the app's [profile](accesstoken-guidelines.md#declaring-the-acl). The subsequent steps of authorization are the same.
**NOTE**
Declare the target ACL in the **acl** field of the app's profile in the app installation package, and generate a certificate using the profile signing tool. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
## Permission Authorization Modes
...
...
@@ -129,7 +147,7 @@ Permissions can be classified into the following types based on the authorizatio
The user_grant permission list must also be presented on the details page of the app in the app store.
## Authorization Processes
### Authorization Processes
The process for an app obtaining the required permissions varies depending on the permission authorization mode.
...
...
@@ -153,18 +171,6 @@ The procedure is as follows:
- Check the app's permission each time before the operation requiring the permission is performed.
- To check whether a user has granted specific permissions to your app, use the [verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md#verifyaccesstoken) method. This method returns [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md#grantstatus) or [PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md#grantstatus). For details about the sample code, see [Access Control Development](accesstoken-guidelines.md).
- To check whether a user has granted specific permissions to your app, use the [verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md) method. This method returns [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md) or [PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md). For details about the sample code, see [Access Control Development](accesstoken-guidelines.md).
- Users must be able to understand and control the authorization of user_grant permissions. During the running process, the app requiring user authorization must proactively call the API to dynamically request the authorization. Then, the system displays a dialog box asking the user to grant the requested permission. The user will determine whether to grant the permission based on the running context of the app.
- The permission authorized is not permanent, because the user may revoke the authorization at any time. Therefore, even if the user has granted the requested permission to the app, the app must check for the permission before calling the API controlled by this permission.
### Using the ACL
If the permission required by an app has higher level than the app's APL, you can use the ACL to grant the permissions required.
In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL.
In other words, in addition to declaring the required permissions in the **config.json** file, you must declare the high-level permissions in the app's [profile](accesstoken-guidelines.md). The subsequent steps of authorization are the same.
**NOTE**
Declare the target ACL in the **acl** field of the app's profile in the app installation package, and generate a certificate using the profile signing tool. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
To ensure the integrity and secure source of OpenHarmony applications, the applications must be signed during the build process. Only signed applications can be installed, run, and debugged on real devices. [developtools_hapsigner](https://gitee.com/openharmony/developtools_hapsigner) provides the source code of the OpenHarmony Ability Package (HAP) signing tool - hapsigner. This tool can be used to generate key pairs, certificate signing requests (CSRs), certificates, profile signatures, and HAP signatures.
### Key Concepts
The hapsigner tool is implemented based on the Public Key Infrastructure (PKI). Before using this tool, you should understand the following concepts:
- Asymmetric key pair
The asymmetric key algorithm is the basis of data signature and signature verification. The hapsigner tool can generate standard asymmetric key pairs, including ECC P384/256 and RSA 2048/3072/4096.
- CSR
The CSR contains the public key, subject, and private key signature of a certificate. Before applying for a certificate, you must generate a CSR based on the key pair and submit the CSR to the Certificate Authority (CA).
- Certificate
OpenHarmony uses the RFC5280 standard to build the X.509 certificate trust system. The OpenHarmony certificates used for application signatures are classified into the root CA certificate, intermediate CA certificate, and end-entity certificate (application or profile signing certificate). The application signing certificate indicates the identity of the application developer, which ensures the traceability of the source of the applications. The profile signing certificate is used to verify the signature of the profile, which ensures the integrity of the profile.
- HAP
HAP is a package used to deploy an ability, which is the basic unit for OpenHarmony application development. An OpenHarmony application consists of one or more abilities.
- Profile
The profile in a HAP contains information such as the authorized certificate permission and device ID.
### Constraints
- hapsigner is developed in Java and must run in JRE 8.0 or later.
- The scripts, such as the one-click signature script, are developed in Python, and must run on Python 3.5 or later.
## Build
1. Check that Gradle 7.1 has been installed.
```shell
gradle -v
gradle -v
```
2. Download the code, open the file directory **developtools_hapsigner/hapsigntool**, and run the following command to build the code:
```shell
gradle build
gradle build
```
Or
```shell
gradle jar
gradle jar
```
3. Check that **hap-sign-tool.jar** (binary files) is generated in the **./hap_sign_tool/build/libs** directory.
...
...
@@ -70,169 +33,191 @@ The usage of hapsigner varies depending on whether an application signing certif
- If an application signing certification is available:<br/>
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.
### Usage
### Description
#### Description
1. Display help information.
1. Display command help information.
-help # If no parameter is specified, the command help information is displayed by default.
```
-help # If no parameter is specified, the command help information is displayed by default.
```
2. Display the version information.
2. Display version information
-version # Display the tool version information.
```
-version # Display the tool version information.
```
3. Generate a key pair.
3. Generate a key pair.
generate-keypair: Generate a key pair.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory.
├── -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.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
```
generate-keypair: Generate a key pair.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory.
├── -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.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
```
4. Generate a CSR.
generate-csr: Generate a CSR.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outFile # CSR to generate. It is optional. If you do not specify this parameter, the CSR is output to the console.
```
generate-csr: Generate a CSR.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outFile # CSR to generate. It is optional. If you do not specify this parameter, the CSR is output to the console.
```
5. Generate a root CA or intermediate CA certificate.
generate-ca: Generate a root CA or intermediate CA certificate. If the key does not exist, generate a key together with the certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory.
├── -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.
├── -issuer # Issuer of the certificate. It is optional. It indicates a root CA certificate if not specified.
├── -issuerKeyAlias # Key alias of the issuer. It is optional. It indicates a root CA certificate if not specified.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified.
```
generate-ca: Generate a root CA or intermediate CA certificate. If the key does not exist, generate a key together with the certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -keyAlg # Key algorithm, which can be RSA or ECC. It is mandatory.
├── -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.
├── -issuer # Issuer of the certificate. It is optional. It indicates a root CA certificate if not specified.
├── -issuerKeyAlias # Key alias of the issuer. It is optional. It indicates a root CA certificate if not specified.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified.
```
6. Generate an application debug or release certificate.
generate-app-cert: Generate an application debug or release certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algoritym, which can be SHA256withECDSA or SHA384withECDSA.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain.
├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain.
├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain.
├── -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.
```
generate-app-cert: Generate an application debug or release certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algoritym, which can be SHA256withECDSA or SHA384withECDSA.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain.
├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain.
├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain.
├── -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.
```
7. Generate a profile debug or release certificate.
generate-profile-cert: Generate a profile debug or release certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algoritym, which can be SHA256withECDSA or SHA384withECDSA.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain.
├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain.
├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain.
├── -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.
```
generate-profile-cert: Generate a profile debug or release certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
├── -signAlg # Signature algoritym, which can be SHA256withECDSA or SHA384withECDSA.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outForm # Format of the certificate to generate. It is optional. The value can be cert or certChain. The default value is certChain.
├── -rootCaCertFile # Root CA certificate, which is mandatory when outForm is certChain.
├── -subCaCertFile # Intermediate CA certificate, which is mandatory when outForm is certChain.
├── -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.
```
8. Generate a common certificate, which can be used to generate a custom certificate.
generate-cert: Generate a common certificate, which can be used to generate a custom certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 1095 days.
├── -keyUsage # Usages of the key. It is mandatory. The key usages include digitalSignature, nonRepudiation,
├ encipherOnly, and decipherOnly. Use a comma (,) to separate multiple values.
├── -keyUsageCritical # Whether keyUsage is a critical option. It is optional. The default value is true.
├── -extKeyUsage # Extended key usages. It is optional. The extended key usages include clientAuthentication,
├ serverAuthentication, codeSignature, emailProtection, smartCardLogin, timestamp, and ocspSignature.
├── -extKeyUsageCritical # Whether extKeyUsage is a critical option. It is optional. The default value is false.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -basicConstraints # Whether basicConstraints is contained. It is optional. The default value is false.
├── -basicConstraintsCritical # Whether basicConstraints is a critical option. It is optional. The default value is false.
├── -basicConstraintsCa # Whether it is CA. It is optional. The default value is false.
├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Certificate file to generate. It is optional. The file is output to the console if this parameter is not specified.
9. Sign a provisioning profile.
sign-profile: Sign a provisioning profile.
├── -mode # Signing mode, which can be localSign or remoteSign. It is mandatory.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -profileCertFile # Profile signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory.
├── -inFile # Raw profile template in JSON format (developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json). It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Signed provisioning profile to generate, in p7b format. It is mandatory.
10. Verify the provisioning profile signature.
verify-profile: Verify the provisioning profile signature.
├── -inFile # Signed provisioning profile, in p7b format. It is mandatory.
├── -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.
```
generate-cert: Generate a common certificate, which can be used to generate a custom certificate.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -issuer # Issuer of the certificate. It is mandatory.
├── -issuerKeyAlias # Key alias of the issuer. It is mandatory.
├── -issuerKeyPwd # Key password of the issuer. It is optional.
├── -subject # Certificate subject. It is mandatory.
├── -validity # Validity period of the certificate. It is optional. The default value is 1095 days.
├── -keyUsage # Usages of the key. It is mandatory. The key usages include digitalSignature, nonRepudiation, keyEncipherment,
├ encipherOnly, and decipherOnly. Use a comma (,) to separate multiple values.
├── -keyUsageCritical # Whether keyUsage is a critical option. It is optional. The default value is true.
├── -extKeyUsage # Extended key usages. It is optional. The extended key usages include clientAuthentication, serverAuthentication,
├ codeSignature, emailProtection, smartCardLogin, timestamp, and ocspSignature.
├── -extKeyUsageCritical # Whether extKeyUsage is a critical option. It is optional. The default value is false.
├── -signAlg # Signature algorithm, which can be SHA256withRSA, SHA384withRSA, SHA256withECDSA, or SHA384withECDSA. It is mandatory.
├── -basicConstraints # Whether basicConstraints is contained. It is optional. The default value is false.
├── -basicConstraintsCritical # Whether basicConstraints is a critical option. It is optional. The default value is false.
├── -basicConstraintsCa # Whether it is CA. It is optional. The default value is false.
├── -basicConstraintsPathLen # Path length. It is optional. The default value is 0.
├── -issuerKeystoreFile # KS file of the issuer, in JKS or P12 format. It is optional.
├── -issuerKeystorePwd # KS password of the issuer. It is optional.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Certificate file to generate. It is optional. The file is output to the console if this parameter is not specified.
```
9. Sign a profile.
```
sign-profile: Sign a profile.
├── -mode # Signing mode, which can be localSign or remoteSign. It is mandatory.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -profileCertFile # Profile signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory.
├── -inFile # Raw profile template in JSON format (developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json). It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Signed profile to generate, in p7b format. This parameter is mandatory.
```
10. Verify the signature of the profile.
```
verify-profile: Verify the profile signature.
├── -inFile # Signed profile in p7b format. This parameter is mandatory.
├── -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.
```
11. Sign a HAP.
sign-app: Sign a HAP.
├── -mode # Signing mode, which can be localSign, remoteSign, or remoteResign. It is mandatory.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -appCertFile # Application signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory.
├── -profileFile # Signed provisioning profile, in p7b format. It is mandatory.
├── -profileSigned # Whether the profile is signed. The value 1 means signed, and value 0 means unsigned. The default value is 1. It is optional.
├── -inForm # Raw file, in .zip (default) or .bin format. It is optional.
├── -inFile # Raw application package, in HAP or .bin format. It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Signed HAP file to generate. It is mandatory.
```
sign-app: Sign a HAP.
├── -mode # Signing mode, which can be localSign, remoteSign, or remoteResign. It is mandatory.
├── -keyAlias # Key alias. It is mandatory.
├── -keyPwd # Key password. It is optional.
├── -appCertFile # Application signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). It is mandatory.
├── -profileFile # Name of the signed profile in p7b format. This parameter is mandatory.
├── -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.
├── -inForm # Raw file, in .zip (default) or .bin format. It is optional.
├── -inFile # Raw application package, in HAP or .bin format. It is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -keystoreFile # KS file, in JKS or P12 format. It is mandatory if the signing mode is localSign.
├── -keystorePwd # KS password. It is optional.
├── -outFile # Signed HAP file to generate. It is mandatory.
```
12. Verify the HAP signature.
verify-app: Verify the HAP signature.
├── -inFile # Signed application file, in HAP or bin format. It is mandatory.
├── -outCertchain # Signed certificate chain file. It is mandatory.
├── -outProfile # Profile of the application. It is mandatory.
```
verify-app: Verify the HAP signature.
├── -inFile # Signed application file, in HAP or bin format. It is mandatory.
├── -outCertchain # Signed certificate chain file. It is mandatory.
├── -outProfile # Profile of the application. It is mandatory.
```
### Signing Procedure
The process of signing a HAP is as follows:
...
...
@@ -242,174 +227,184 @@ The process of signing a HAP is as follows:
4. Sign the HAP.
> **Precautions** <br/>
> **Precautions** <br>
>
> For security purposes, the ECC algorithm is recommended for generating key pairs for application signing signatures. The RSA algorithm is not recommended.<br/>
> You are advised to place the HAP, profile, KS file **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:<br/>- OpenHarmony KS file **OpenHarmony.p12** <br/>- Root CA certificate **rootCA.cer**<br/>- Intermediate CA certificate **subCA.cer**<br/>- Profile signing certificate **OpenHarmonyProfileRelease.pem**
**1. Generate a key pair for the application signing certificate.**
Generate a signature key pair and save it to the KS.
>  **NOTE**<br/>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.
The command parameters are described as follows:
generate-keypair: Generate a key pair for the application signing certificate.
├── -keyAlias # Alias of the key used to generate the application signing certificate. It is stored in the OpenHarmony.p12 file. This parameter is mandatory.
├── -keyAlg # Key algorithm. It is mandatory. ECC is recommended.
├── -keySize # Key length. It is NIST-P-256/NIST-P-384 if ECC is used. This parameter is mandatory.
├── -keyStoreFile # KS file. OpenHarmony.p12 is recommended. This parameter is mandatory.
├── -keyStorePwd # KS password. It is mandatory. The default password 123456 for OpenHarmony.p12.
├── -keyPwd # Key password. It is optional. If this parameter is not specified, the generated key pair has no password.
**2. Generate an application signing certificate.**
Use the local intermediate CA certificate to issue an application signing certificate.
generate-app-cert: Generate an application signing certificate.
├── -keyAlias # Key alias, which must be the same as that in the previous step.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -issuer # Issuer of the certificate. Enter the issuer of the intermediate CA certificate. It is mandatory and cannot be changed.
├── -issuerKeyAlias # Key alias of the issuer. Enter the key alias of the intermediate CA certificate. It is mandatory and cannot be changed.
├── -subject # Subject of the certificate. Enter the subject in the same sequence specified in the command. This parameter is mandatory.
├── -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.
├── -keystoreFile # KS file. Use OpenHarmony.p12. It is mandatory and cannot be changed.
├── -rootCaCertFile # Root certificate. It is mandatory and cannot be changed.
├── -subCaCertFile # Intermediate CA certificate. It is mandatory and cannot be changed.
├── -outForm # Format of the certificate file to generate. certChain is recommended.
├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified.
├── -keyPwd # Key password. It is optional. It is the key password set when the key pair is generated.
├── -keystorePwd # KS password. The default value is 123456.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
<br/>
**3. Sign the profile.**
Use the profile signature key to sign the profile.
>  **NOTE**:<br/>The following parameters used are for the scenario where there is no application signing certificate available. If the application signing certificate is available, the following parameters need to be modified:<br/>
-**keyAlias**: Enter the key alias of the application signing certificate. This parameter is mandatory. <br/>
-**appCertFile**: Enter the application signing certificate. This parameter is mandatory.<br/>
-**keystoreFile**: Enter the KS file of the application signing certificate. This parameter is mandatory. <br/>
-**keyPwd**: Enter the key password in the KS file. <br/>
-**keystorePwd**: Enter the KS password in the KS file.<br/>
> For security purposes, use ECC to generate the key pair in step 1. Do not use RSA.
>
> 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:
> Note:<br>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.
The command parameters are described as follows:
```
generate-keypair: Generate a key pair for the application signing certificate.
├── -keyAlias # Alias of the key used to generate the application signing certificate. It is stored in the OpenHarmony.p12 file. This parameter is mandatory.
├── -keyAlg # Key algorithm. It is mandatory. ECC is recommended.
├── -keySize # Key length. It is NIST-P-256/NIST-P-384 if ECC is used. This parameter is mandatory.
├── -keyStoreFile # KS file. OpenHarmony.p12 is recommended. This parameter is mandatory.
├── -keyStorePwd # KS password. It is mandatory. The default password 123456 for OpenHarmony.p12.
├── -keyPwd # Key password. It is optional. If this parameter is not specified, the generated key pair has no password.
```
2.**Generate an application signing certificate.**
Use the local intermediate CA certificate to issue an application signing certificate.
generate-app-cert: Generate an application signing certificate.
├── -keyAlias # Key alias, which must be the same as that in the previous step.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -issuer # Issuer of the certificate. Enter the issuer of the intermediate CA certificate. It is mandatory and cannot be changed.
├── -issuerKeyAlias # Key alias of the issuer. Enter the key alias of the intermediate CA certificate. This parameter is mandatory and cannot be changed.
├── -subject # Subject of the certificate. Enter the subject in the same sequence specified in the command. This parameter is mandatory.
├── -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.
├── -keystoreFile # KS file. Use OpenHarmony.p12. It is mandatory and cannot be changed.
├── -rootCaCertFile # Root certificate. It is mandatory and cannot be changed.
├── -subCaCertFile # Intermediate CA certificate. This parameter is mandatory and cannot be changed.
├── -outForm # Format of the certificate file to generate. certChain is recommended.
├── -outFile # File to generate. It is optional. The file is output to the console if this parameter is not specified.
├── -keyPwd # Key password. It is optional. It is the key password set when the key pair is generated.
├── -keystorePwd # KS password. The default value is 123456.
├── -validity # Validity period of the certificate. It is optional. The default value is 3650 days.
```
3.**Sign the profile.**
Call the profile signing API to sign the profile using the profile signing key.
> Note:<br>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.
>
> - **keyAlias**: Enter the key alias of the application signing certificate. This parameter is mandatory.
> - **appCertFile**: Enter the application signing certificate. This parameter is mandatory.
> - **keystoreFile**: Enter the KS file of the application signing certificate. This parameter is mandatory.
> - **keyPwd**: Enter the key password in the KS file.
> - **keystorePwd**: Enter the KS password in the KS file.
The command parameters are described as follows:
sign-app: Sign a HAP.
├──-keyAlias # Key alias, which must be the same as the alias of the key pair generated. This parameter is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -mode # Signing mode, which must be localSign. It is mandatory.
├── -appCertFile # Application signing certificate (certificate chain, in the end-entity certificate, intermediate CA certificate, and root certificate order). Enter the application signing certificate generated. This parameter is mandatory.
├── -profileFile # Signed provisioning profile in p7b format. Enter the profile generated. This parameter is mandatory.
├── -inFile # Raw application package. It is mandatory.
├── -keystoreFile # KS file, which must be the same as the KS file generated. It is mandatory and cannot be changed.
├── -outFile # Signed file to generate. It is mandatory.
├── -keyPwd # Key password, which must be the actual key password.
├── -keystorePwd # KS password, which must be the actual KS password.
```
sign-app: Sign a HAP.
├──-keyAlias # Key alias, which must be the same as the alias of the key pair generated. This parameter is mandatory.
├── -signAlg # Signature algorithm, which can be SHA256withECDSA or SHA384withECDSA. It is mandatory.
├── -mode # Signing mode, which must be localSign. It is mandatory.
├── -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.
├── -profileFile # Signed profile in p7b format. Enter the profile generated. This parameter is mandatory.
├── -inFile # Raw application package. It is mandatory.
├── -keystoreFile # KS file, which must be the same as the KS file generated. It is mandatory and cannot be changed.
├── -outFile # Signed file to generate. It is mandatory.
├── -keyPwd # Key password, which must be the actual key password.
├── -keystorePwd # KS password, which must be the actual KS password.
```
## FAQs
**1. When the application signing certificate is generated, the console displays the result but no file is output.**
-**Symptom**
When the tool is used to to generate an application signing certificate, the certificate content is displayed on the console and no certificate is generated.
-**Possible Causes**
The path in the **outFile** parameter is incorrect, or the hyphen (-) in **-outFile** is not an English character.
-**Solution**
1. When the application signing certificate is generated, the console displays the result but no file is output.
Check and correct the value of **outFile**, and ensure the hyphen (-) in **-outFile** is an English character.
-**Symptom**
**2. Failed to sign the profile.**
When the tool is used to generate an application signing certificate, the certificate content is displayed on the console and no certificate is generated.
-**Symptom**
-**Possible Causes**
The path in the **outFile** parameter is incorrect, or the hyphen (-) in **-outFile** is not an English character.
-**Solution**
Check and correct the value of **outFile**, and ensure the hyphen (-) in **-outFile** is an English character.
When the tool is used to sign a profile, any of the following information is displayed:
(2) `"NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'result\profile1.pem' must a cert chain"`
-**Possible Causes**
(3) ` "VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target"`
The possible causes for the error messages are as follows:
-**Possible Causes**
(1) The certificate chain of the profile signing certificate is in incorrect order.
(1) The certificate chain of the profile signing certificate is in incorrect order.
(2) The profile signing certificate is not a certificate chain.
(2) The profile signing certificate is not a certificate chain.
(3) The certificate subject is in incorrect sequence, or the **-issuerKeyAlias** parameter set to generate the application signing certificate is incorrect.
(3) The certificate subject is in incorrect sequence, or the **-issuerKeyAlias** parameter set to generate the application signing certificate is incorrect.
-**Solution**
-**Solution**
(1) Check that the certificate chain is in ascending or descending order of seniority.
(1) Check that the certificate chain is in ascending or descending order of seniority.
(2) Check that the certificate is a certificate chain.
(2) Check that the certificate is a certificate chain.
(3) Check that the certificate subject is in the C, O, OU, and CN order.
(3) Check that the certificate subject is in the C, O, OU, and CN order.
**3. An error message is displayed when the tool is used to sign a HAP.**
3. An error message is displayed when the tool is used to sign a HAP.
-**Symptom**
-**Symptom**
The following error message is displayed: "NOT_SUPPORT_ERROR, code: 105.Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA
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`
-**Possible Causes**
-**Possible Causes**
The signature algorithm is not supported. Check the value of **signAlg**.
The signature algorithm is not supported. Check the value of **signAlg**.
-**Solution**
-**Solution**
Use ECC to generate the key pair for an application or profile signing certificate. Use **SHA256withECDSA** or **SHA384withECDSA** as the HAP signature algorithm.
Use ECC to generate the key pair for the application or profile signing certificate. Use SHA256withECDSA or SHA384withECDSA as the HAP signature algorithm.
To ensure the integrity and secure source of OpenHarmony applications, the applications must be signed during the build process. Only signed applications can be installed, run, and debugged on real devices. [developtools_hapsigner](https://gitee.com/openharmony/developtools_hapsigner) provides the source code of the OpenHarmony Ability Package (HAP) signing tool - hapsigner. This tool can be used to generate key pairs, certificate signing requests (CSRs), certificates, profile signatures, and HAP signatures.
## Basic Concepts
The hapsigner tool is implemented based on the Public Key Infrastructure (PKI). Before using this tool, you should understand the following concepts:
- Asymmetric key pair
The asymmetric key algorithm is the basis of data signature and signature verification. The hapsigner tool can generate standard asymmetric key pairs, including ECC P384/256 and RSA 2048/3072/4096.
- CSR
The CSR contains the public key, subject, and private key signature of a certificate. Before applying for a certificate, you must generate a CSR based on the key pair and submit the CSR to the Certificate Authority (CA).
- Certificate
OpenHarmony uses the RFC5280 standard to build the X.509 certificate trust system. The OpenHarmony certificates used for application signatures are classified into the root CA certificate, intermediate CA certificate, and end-entity certificate (application or profile signing certificate). The application signing certificate indicates the identity of the application developer, which ensures the traceability of the source of the applications. The profile signing certificate is used to verify the signature of the profile, which ensures the integrity of the profile.
- HAP
HAP is a package used to deploy an ability, which is the basic unit for OpenHarmony application development. An OpenHarmony application consists of one or more abilities.
- Profile
HarmonyAppProvision configuration file in a HAP contains information such as the authorized application permissions and device ID.
## Constraints
- hapsigner is developed in Java and must run in JRE 8.0 or later.
- The scripts, such as the one-click signature script, are developed in Python, and must run on Python 3.5 or later.
The following lists the permissions defined by the system.
On the basis of the [principles for app permission management](accesstoken-overview.md#basic-principles), apply for permissions for an app by following the procedure illustrated in the figure below.
For details about the permission levels, permission authorization modes, and use of the ACL, see [Access Control Overview](accesstoken-overview.md). For details about permission usage examples, see [Access Control Development](accesstoken-guidelines.md).
1. For details about the mapping between the app's ability privilege level (APL) and permission level, see [Permission Levels](accesstoken-overview.md#permission-levels).
2. Permissions can be authorized by the user (user_grant) or the system (system_grant). For details, see [Permission Authorization Modes](accesstoken-overview.md#permission-authorization-modes).
3. In principle, an app with a lower APL cannot apply for higher permissions by default. The Access Control List (ACL) makes low-level apps have high-level permissions. For details, see [ACL](accesstoken-overview.md#acl).
The following lists the permissions defined by the system. For details about permission usage examples, see [Access Control Development](accesstoken-guidelines.md).
