| 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.
## 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).
