README.md
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
README_zh.md
1# 访问控制部件<a name="ZH-CN_TOPIC_0000001101239136"></a>
2
3 - [简介<a name="section11660541593"></a>](#简介)
4 - [目录<a name="section161941989596"></a>](#目录)
5 - [使用<a name="section137768191623"></a>](#使用)
6 - [接口说明<a name="section1551164914237"></a>](#接口说明)
7 - [使用说明<a name="section129654513264"></a>](#使用说明)
8 - [native进程](#native进程)
9 - [应用hap](#应用hap)
10 - [相关仓<a name="section1371113476307"></a>](#相关仓)
11
12## 简介<a name="section11660541593"></a>
13
14ATM(AccessTokenManager)是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。
15
16应用的Accesstoken信息主要包括应用身份标识APPID、用户ID，应用分身索引、应用APL(Ability Privilege Level)等级、应用权限信息等。每个应用的Accesstoken信息由一个32bits的设备内唯一标识符TokenID(Token identity)来标识。
17
18ATM模块主要提供如下功能：
19- 提供基于TokenID的应用权限校验机制，应用访问敏感数据或者API时可以检查是否有对应的权限。
20- 提供基于TokenID的Accesstoken信息查询，应用可以根据TokenID查询自身的APL等级等信息。
21
22ATM部件的架构图如下所示：
23
24
25## 目录<a name="section161941989596"></a>
26
27```
28/base/security/access_token
29├── frameworks # 框架层，基础功能代码存放目录
30│ ├── accesstoken # Accesstoken管理框架代码存放目录
31│ ├── common # 框架公共代码存放目录
32│ ├── privacy # privacy管理框架代码存放目录
33│ └── tokensync # Accesstoken信息同步框架代码存放目录
34├── interfaces # 接口层
35│ └── innerkits # 内部接口层
36│ │ ├── accesstoken # Accesstoken内部接口代码存放目录
37│ │ ├── nativetoken # nativetoken内部接口代码存放目录
38│ │ ├── privacy # privacy内部接口代码存放目录
39│ │ ├── token_callback # 回调内部接口代码存放目录
40│ │ ├── token_setproc # tokenid内核交互内部接口代码存放目录
41│ │ └── tokensync # Accesstoken信息同步内部接口代码存放目录
42│ └── kits # 外部接口层
43│ │ ├── accesstoken # Accesstoken外部接口代码存放目录
44│ │ ├── common # 外部接口公共代码存放目录
45│ │ └── privacy # privacy信息外部接口代码存放目录
46└── services # 服务层
47 ├── accesstokenmanager # Accesstoken管理服务代码存放目录
48 ├── privacymanager # privacy管理服务代码存放目录
49 └── tokensyncmanager # Accesstoken信息同步服务代码存放目录
50
51```
52
53## 使用<a name="section137768191623"></a>
54### 接口说明<a name="section1551164914237"></a>
55
56| **接口申明** | **接口描述** |
57| --- | --- |
58| AccessTokenIDEx AllocHapToken(const HapInfoParams& info, const HapPolicyParams& policy); | 为应用进程分配一个tokenID |
59| AccessTokenID AllocLocalTokenID(const std::string& remoteDeviceID, AccessTokenID remoteTokenID); | 为远端设备的应用进程分配一个本地tokenID |
60| int UpdateHapToken(AccessTokenID tokenID, const std::string& appIDDesc, int32_t apiVersion, const HapPolicyParams& policy); | 更新tokenId对应的tokenInfo信息 |
61| int DeleteToken(AccessTokenID tokenID); | 删除应用tokenID及其对应的tokenInfo信息 |
62| int GetTokenType(AccessTokenID tokenID); | 查询指定tokenID的类型 |
63| int CheckNativeDCap(AccessTokenID tokenID, const std::string& dcap); | 检测指定tokenID对应的native进程是否具有指定的分布式能力 |
64| AccessTokenID GetHapTokenID(int userID, const std::string& bundleName, int instIndex); | 查询指定应用的tokenId |
65| int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes); | 查询指定tokenID对应的hap包的tokenInfo信息 |
66| int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes); | 查询指定tokenID对应的native的tokenInfo信息 |
67| int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName); | 检查指定tokenID是否具有指定权限 |
68| int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult); | 查询指定权限的权限定义信息 |
69| int GetDefPermissions(AccessTokenID tokenID, std::vector<PermissionDef>& permList); | 查询指定tokenID对应的hap包的权限定义集合 |
70| int GetReqPermissions(AccessTokenID tokenID, std::vector<PermissionStateFull>& reqPermList, bool isSystemGrant); | 查询指定tokenID对应的hap包申请的权限状态集合 |
71| int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName); | 查询指定tokenID的应用的指定权限 |
72| int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | 授予指定tokenID的应用的指定权限 |
73| int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | 撤销指定tokenID的应用的指定权限 |
74| int ClearUserGrantedPermissionState(AccessTokenID tokenID); | 清空指定tokenID的应用的user_grant权限状态 |
75| uint64_t GetAccessTokenId(const char *processname, const char **dcap, int32_t dacpNum, const char *aplStr); | 创建获取native进程的tokenId |
76
77### 使用说明<a name="section129654513264"></a>
78ATM提供了统一的应用权限访问控制功能，支持应用程序或者SA查询校验应用权限、APL等信息。从使用者角度，可以分为基于native进程启动的SA和应用Hap两类使用者。
79
80#### native进程
81- 在native进程拉起前，需要调用GetAccessTokenId函数，获取该native进程的TokenID；再调用SetSelfTokenID将进程TokenID设置到内核中。
82- 在native进程运行过程中，可以通过调用GetNativeTokenInfo、CheckNativeDCap来查验对应进程所具备的token信息，包括分布式能力、APL等级等信息。
83
84#### 应用hap
85- 在应用安装时，需要调用AllocHapToken创建获取该应用的TokenID。
86- 在应用运行过程中，需要进行鉴权等操作时，可调用VerifyAccessToken、GetReqPermissions等函数查询校验应用权限、APL等信息。
87- 在应用卸载时，需要调用DeleteToken函数删除系统中管理的对应Accesstoken信息。
88
89## 相关仓<a name="section1371113476307"></a>
90
91[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite/blob/master/README_zh.md)
92
93[security\_device\_auth](https://gitee.com/openharmony/security_device_auth/blob/master/README_zh.md)
94
95**[security\_access\_token](https://gitee.com/openharmony/security_access_token/blob/master/README_zh.md)**
96
