From 3f93c51314c2e9560c64f276ed4b8a0471c40374 Mon Sep 17 00:00:00 2001 From: annie_wangli Date: Fri, 4 Mar 2022 15:41:20 +0800 Subject: [PATCH] update docs Signed-off-by: annie_wangli --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9ef56a6a2..2593298c2 100644 --- a/README.md +++ b/README.md @@ -1 +1,74 @@ -An english translation is now being prepared. \ No newline at end of file +# Access Control + + +## Introduction + +AccessTokenManager (ATM) provides unified app permission management based on access tokens on OpenHarmony. + +The 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. + +The ATM module provides the following functions: +- Verifying app permissions based on the token ID before an app accesses sensitive data or calls an API. +- Obtaining access token information (for example, APL) based on the token ID. + +## Directory Structure + +``` +/base/security/access_token +├── frameworks # Stores code of basic functionalities. +│ ├── accesstoken # Stores code of the ATM framework. +│ ├── tokensync # Stores code of the access token synchronization framework. +│ └── common # Stores framework common code. +├── interfaces # Stores the APIs. +│ ├── innerkits # Stores internal APIs. +│ ├── accesstoken # Stores code of access token internal APIs. +│ ├── nativetoken # Stores code of native token APIs. +│ └── tokensync # Stores code of the internal APIs for access token synchronization. +└── services # Services + ├── accesstokenmanager # Stores ATM service code. + └── tokensyncmanager # Stores code of the access token synchronization service. +``` + +## Usage +### Available APIs + +| **API**| **Description**| +| --- | --- | +| AccessTokenIDEx AllocHapToken(const HapInfoParams& info, const HapPolicyParams& policy); | Allocates a token ID to an app.| +| AccessTokenID AllocLocalTokenID(const std::string& remoteDeviceID, AccessTokenID remoteTokenID); | Allocates a local token ID to the app of a remote device.| +| int UpdateHapToken(AccessTokenID tokenID, const std::string& appIDDesc, const HapPolicyParams& policy); | Updates token information.| +| int DeleteToken(AccessTokenID tokenID); | Deletes the app's token ID and information.| +| int GetTokenType(AccessTokenID tokenID); | Obtains the type of an access token.| +| int CheckNativeDCap(AccessTokenID tokenID, const std::string& dcap); | Checks whether the native process corresponding to the given token ID has the specified distributed capability.| +| AccessTokenID GetHapTokenID(int userID, const std::string& bundleName, int instIndex); | Obtains the token ID of an app.| +| int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes); | Obtains the token information about a HAP.| +| int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes); | Obtains information about a native token.| +| int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName); | Checks whether an access token has the specified permission.| +| int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult); | Obtains definition information about the specified permission.| +| int GetDefPermissions(AccessTokenID tokenID, std::vector& permList); | Obtains the permission definition set of a HAP.| +| int GetReqPermissions(AccessTokenID tokenID, std::vector& reqPermList, bool isSystemGrant); | Obtains the status set of the permission requested by a HAP.| +| int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName); | Obtains the permissions of the app with the specified token ID.| +| int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Grants the specified permission to the app with the specified token ID.| +| int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, int flag); | Revokes the specified permission from the app with the specified token ID.| +| int ClearUserGrantedPermissionState(AccessTokenID tokenID); | Clears the user_grant permission status of the app with the specified token ID.| +| uint64_t GetAccessTokenId(const char *processname, const char **dcap, int32_t dacpNum, const char *aplStr); | Obtains the token ID of a native process.| + +### Usage Guidelines +ATM 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. + +#### Native Process +- 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. +- During the running of a native process, it calls **GetNativeTokenInfo** or **CheckNativeDCap** to obtain the token information, including the distributed capability and APL. + +#### App HAP +- When an app is installed, **AllocHapToken** is called to obtain the token ID of the app. +- When an authentication is required during app running, **VerifyAccessToken** or **GetReqPermissions** is called to obtain and verify the app permissions and APL. +- When an app is uninstalled, **DeleteToken** is called to delete the related access token information. + +## Repositories Involved + +[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite/blob/master/README.md) + +[security\_deviceauth](https://gitee.com/openharmony/security_deviceauth/blob/master/README.md) + +[security\_access\_token](https://gitee.com/openharmony/security_access_token/blob/master/README.md) -- Gitee