• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Access Control<a name="EN-US_TOPIC_0000001101239136"></a>
2
3 - [Introduction<a name="section11660541593"></a>](#introduction)
4 - [Directory Structure<a name="section161941989596"></a>](#directory-structure)
5 - [Usage<a name="section137768191623"></a>](#usage)
6  - [Available APIs<a name="section1551164914237"></a>](#available-apis)
7  - [Usage Guidelines<a name="section129654513264"></a>](#usage-guidelines)
8   - [Native Process](#native-process)
9   - [App HAP](#app-hap)
10 - [Repositories Involved<a name="section1371113476307"></a>](#repositories-involved)
11
12## Introduction<a name="section11660541593"></a>
13
14AccessTokenManager (ATM) provides unified app permission management based on access tokens on OpenHarmony.
15
16The access token information of an app includes the app identifier (**APPID**), user ID, app twin index, app Ability Privilege Level (APL), and permission information. The access token of each app is identified by a 32-bit token identity (**TokenID**) in the device.
17
18The ATM module provides the following functions:
19-   Verifying app permissions based on the token ID before an app accesses sensitive data or calls an API.
20-   Obtaining access token information (for example, APL) based on the token ID.
21
22## Directory Structure<a name="section161941989596"></a>
23
24```
25/base/security/access_token
26├── frameworks                  # Stores code of basic functionalities.
27│   ├── accesstoken             # Stores code of the ATM framework.
28│   ├── tokensync               # Stores code of the access token synchronization framework.
29│   └── common                  # Stores framework common code.
30├── interfaces                  # Stores the APIs.
31│   ├── innerkits               # Stores internal APIs.
32│       ├── accesstoken         # Stores code of access token internal APIs.
33│       ├── nativetoken         # Stores code of native token APIs.
34│       └── tokensync           # Stores code of the internal APIs for access token synchronization.
35└── services                    # Services
36    ├── accesstokenmanager      # Stores ATM service code.
37    └── tokensyncmanager        # Stores code of the access token synchronization service.
38```
39
40## Usage<a name="section137768191623"></a>
41### Available APIs<a name="section1551164914237"></a>
42
43| **API**| **Description**|
44| --- | --- |
45| AccessTokenIDEx AllocHapToken(const HapInfoParams& info, const HapPolicyParams& policy); | Allocates a token ID to an app.|
46| AccessTokenID AllocLocalTokenID(const std::string& remoteDeviceID, AccessTokenID remoteTokenID); | Allocates a local token ID to the app of a remote device.|
47| int UpdateHapToken(AccessTokenID tokenID, const std::string& appIDDesc, int32_t apiVersion, const HapPolicyParams& policy); | Updates token information.|
48| int DeleteToken(AccessTokenID tokenID); | Deletes the app's token ID and information.|
49| int GetTokenType(AccessTokenID tokenID); | Obtains the type of an access token.|
50| int CheckNativeDCap(AccessTokenID tokenID, const std::string& dcap); | Checks whether the native process corresponding to the given token ID has the specified distributed capability.|
51| AccessTokenID GetHapTokenID(int userID, const std::string& bundleName, int instIndex); | Obtains the token ID of an app.|
52| int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes); | Obtains the token information about a HAP.|
53| int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes); | Obtains information about a native token.|
54| int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName); | Checks whether an access token has the specified permission.|
55| int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult); | Obtains definition information about the specified permission.|
56| int GetDefPermissions(AccessTokenID tokenID, std::vector<PermissionDef>& permList); | Obtains the permission definition set of a HAP.|
57| int GetReqPermissions(AccessTokenID tokenID, std::vector<PermissionStateFull>& reqPermList, bool isSystemGrant); | Obtains the status set of the permission requested by a HAP.|
58| int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName); | Obtains the permissions of the app with the specified token ID.|
59| int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Grants the specified permission to the app with the specified token ID.|
60| int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Revokes the specified permission from the app with the specified token ID.|
61| int ClearUserGrantedPermissionState(AccessTokenID tokenID); | Clears the user_grant permission status of the app with the specified token ID.|
62| uint64_t GetAccessTokenId(const char *processname, const char **dcap, int32_t dacpNum, const char *aplStr); | Obtains the token ID of a native process.|
63
64### Usage Guidelines<a name="section129654513264"></a>
65ATM provides unified access control for apps and allows apps or service abilities to obtain and verify app permissions and APL. The ATM APIs can be called by a service ability started by a native process or an app HAP.
66
67#### Native Process
68-  Before a native process starts, it calls **GetAccessTokenId** to obtain a token ID, and then calls **SetSelfTokenID** to set the token ID to the kernel.
69-  During the running of a native process, it calls **GetNativeTokenInfo** or **CheckNativeDCap** to obtain the token information, including the distributed capability and APL.
70
71#### App HAP
72-  When an app is installed, **AllocHapToken** is called to obtain the token ID of the app.
73-  When an authentication is required during app running, **VerifyAccessToken** or **GetReqPermissions** is called to obtain and verify the app permissions and APL.
74-  When an app is uninstalled, **DeleteToken** is called to delete the related access token information.
75
76## Repositories Involved<a name="section1371113476307"></a>
77
78[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite/blob/master/README.md)
79
80[security\_device\_auth](https://gitee.com/openharmony/security_device_auth/blob/master/README.md)
81
82[security\_access\_token](https://gitee.com/openharmony/security_access_token/blob/master/README.md)
83