README.md
1# ATM
2
3
4## Introduction
5
6AccessTokenManager (ATM) implements unified app permission management based on access tokens on OpenHarmony.
7
8The 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.
9
10The ATM module provides the following functions:
11- Verifying app permissions based on the token ID before an app accesses sensitive data or calls an API.
12- Obtaining access token information (for example, APL) based on the token ID.
13
14The following figure shows the ATM architecture.
15
16
17## Directory Structure
18
19```
20/base/security/access_token
21├── frameworks # Code of basic functionalities.
22│ ├── accesstoken # Code of the ATM framework.
23│ ├── common # Common code.
24│ ├── privacy # Code of the privacy framework.
25│ └── tokensync # Code of the access token synchronization framework.
26├── interfaces # Interfaces
27│ ├── innerkits # Internal interfaces.
28│ │ ├── accesstoken # Code of the internal access token interfaces.
29│ │ ├── nativetoken # Code of the internal native token interfaces.
30│ │ ├── privacy # Code of the internal privacy interfaces.
31│ │ ├── token_callback # Code of the internal callbacks.
32│ │ ├── token_setproc # Code of internal interfaces for exchanging token IDs.
33│ │ └── tokensync # Code of the internal access token synchronization interfaces.
34│ └── kits # External interfaces.
35│ │ ├── accesstoken # Code of the external access token interfaces.
36│ │ ├── common # Common code of external interfaces.
37│ │ └── privacy # Code of the external privacy interfaces.
38└── services # Services
39 ├── accesstokenmanager # ATM service code.
40 ├── privacymanager # Privacy manager service code.
41 └── tokensyncmanager # Code of the access token synchronization service.
42
43```
44
45## Usage
46### Available APIs
47
48| **API**| **Description**|
49| --- | --- |
50| AccessTokenIDEx AllocHapToken(const HapInfoParams& info, const HapPolicyParams& policy); | Allocates a token ID to an app.|
51| AccessTokenID AllocLocalTokenID(const std::string& remoteDeviceID, AccessTokenID remoteTokenID); | Allocates a local token ID to the app of a remote device.|
52| int UpdateHapToken(AccessTokenIDEx& tokenIdEx, bool isSystemApp, const std::string& appIDDesc, int32_t apiVersion, const HapPolicyParams& policy); | Updates token information.|
53| int DeleteToken(AccessTokenID tokenID); | Deletes the app's token ID and information.|
54| int GetTokenType(AccessTokenID tokenID); | Obtains the type of an access token.|
55| int GetTokenTypeFlag(AccessTokenID tokenID); | Obtains the type of a trusted token ID.|
56| int GetTokenType(FullTokenID tokenID); | Obtains the type of an access token.|
57| int GetTokenTypeFlag(FullTokenID tokenID); | Obtains the type of a trusted token ID.|
58| int CheckNativeDCap(AccessTokenID tokenID, const std::string& dcap); | Checks whether the native process corresponding to the given token ID has the specified distributed capability.|
59| AccessTokenID GetHapTokenID(int32_t userID, const std::string& bundleName, int32_t instIndex); | Obtains the token ID of an app.|
60| AccessTokenIDEx GetHapTokenIDEx(int32_t userID, const std::string& bundleName, int32_t instIndex); | Obtains the token ID of an app.|
61| int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes); | Obtains the token information about an OpenHarmony Ability Package (HAP).|
62| int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes); | Obtains the native token information.|
63| int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName); | Checks whether an access token has the specified permission.|
64| int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult); | Obtains definition information about the specified permission.|
65| int GetDefPermissions(AccessTokenID tokenID, std::vector<PermissionDef>& permList); | Obtains the permission definition set of a HAP.|
66| int GetReqPermissions(AccessTokenID tokenID, std::vector<PermissionStateFull>& reqPermList, bool isSystemGrant); | Obtains the status set of the permission requested by a HAP.|
67| int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName); | Obtains the permissions of the app with the specified token ID.|
68| int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Grants a permission to the app with the specified token ID.|
69| int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Revokes a permission from the app with the specified token ID.|
70| int ClearUserGrantedPermissionState(AccessTokenID tokenID); | Clears the user_grant permission status of the app with the specified token ID.|
71| uint64_t GetAccessTokenId(const char *processname, const char **dcap, int32_t dacpNum, const char *aplStr); | Obtains the token ID of a native process.|
72
73### How to Use
74ATM 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.
75
76#### Native Process
77- 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.
78- During the running of a native process, it calls **GetNativeTokenInfo** or **CheckNativeDCap** to obtain the token information, including the distributed capability and APL.
79
80#### App HAP
81- When an app is installed, **AllocHapToken** is called to obtain the token ID of the app.
82- When an authentication is required during app running, **VerifyAccessToken** or **GetReqPermissions** is called to obtain and verify the app permissions and APL.
83- When an app is uninstalled, **DeleteToken** is called to delete the related access token information.
84
85## Repositories Involved
86
87[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite)
88
89[security\_device\_auth](https://gitee.com/openharmony/security_device_auth)
90
91**[security\_access\_token](https://gitee.com/openharmony/security_access_token)**
92
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(AccessTokenIDEx& tokenIdEx, bool isSystemApp, 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 GetTokenTypeFlag(AccessTokenID tokenID); | 查询指定可信tokenID的类型 |
64| int GetTokenType(FullTokenID tokenID); | 查询指定tokenID的类型 |
65| int GetTokenTypeFlag(FullTokenID tokenID); | 查询指定可信tokenID的类型 |
66| int CheckNativeDCap(AccessTokenID tokenID, const std::string& dcap); | 检测指定tokenID对应的native进程是否具有指定的分布式能力 |
67| AccessTokenID GetHapTokenID(int32_t userID, const std::string& bundleName, int32_t instIndex); | 查询指定应用的tokenId |
68| AccessTokenIDEx GetHapTokenIDEx(int32_t userID, const std::string& bundleName, int32_t instIndex); | 查询指定应用的tokenIDEx |
69| int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes); | 查询指定tokenID对应的hap包的tokenInfo信息 |
70| int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes); | 查询指定tokenID对应的native的tokenInfo信息 |
71| int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName); | 检查指定tokenID是否具有指定权限 |
72| int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult); | 查询指定权限的权限定义信息 |
73| int GetDefPermissions(AccessTokenID tokenID, std::vector<PermissionDef>& permList); | 查询指定tokenID对应的hap包的权限定义集合 |
74| int GetReqPermissions(AccessTokenID tokenID, std::vector<PermissionStateFull>& reqPermList, bool isSystemGrant); | 查询指定tokenID对应的hap包申请的权限状态集合 |
75| int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName); | 查询指定tokenID的应用的指定权限 |
76| int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | 授予指定tokenID的应用的指定权限 |
77| int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | 撤销指定tokenID的应用的指定权限 |
78| int ClearUserGrantedPermissionState(AccessTokenID tokenID); | 清空指定tokenID的应用的user_grant权限状态 |
79| uint64_t GetAccessTokenId(const char *processname, const char **dcap, int32_t dacpNum, const char *aplStr); | 创建获取native进程的tokenId |
80
81### 使用说明<a name="section129654513264"></a>
82ATM提供了统一的应用权限访问控制功能，支持应用程序或者SA查询校验应用权限、APL等信息。从使用者角度，可以分为基于native进程启动的SA和应用Hap两类使用者。
83
84#### native进程
85- 在native进程拉起前，需要调用GetAccessTokenId函数，获取该native进程的TokenID；再调用SetSelfTokenID将进程TokenID设置到内核中。
86- 在native进程运行过程中，可以通过调用GetNativeTokenInfo、CheckNativeDCap来查验对应进程所具备的token信息，包括分布式能力、APL等级等信息。
87
88#### 应用hap
89- 在应用安装时，需要调用AllocHapToken创建获取该应用的TokenID。
90- 在应用运行过程中，需要进行鉴权等操作时，可调用VerifyAccessToken、GetReqPermissions等函数查询校验应用权限、APL等信息。
91- 在应用卸载时，需要调用DeleteToken函数删除系统中管理的对应Accesstoken信息。
92
93## 相关仓<a name="section1371113476307"></a>
94
95[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite/blob/master/README_zh.md)
96
97[security\_device\_auth](https://gitee.com/openharmony/security_device_auth/blob/master/README_zh.md)
98
99**[security\_access\_token](https://gitee.com/openharmony/security_access_token/blob/master/README_zh.md)**
100
