1/*
2 * Copyright (c) 2021-2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup AccessToken
18 * @{
19 *
20 * @brief Provides permission management.
21 *
22 * Provides tokenID-based application permission verification mechanism.
23 * When an application accesses sensitive data or APIs, this module can check
24 * whether the application has the corresponding permission. Allows applications
25 * to query their access token information or APL levcels based on token IDs.
26 *
27 * @since 7.0
28 * @version 7.0
29 */
30
31/**
32 * @file accesstoken_kit.h
33 *
34 * @brief Declares access token interfaces.
35 *
36 * @since 7.0
37 * @version 7.0
38 */
39
40#ifndef INTERFACES_INNER_KITS_ACCESSTOKEN_KIT_H
41#define INTERFACES_INNER_KITS_ACCESSTOKEN_KIT_H
42
43#include <string>
44#include <vector>
45
46#include "access_token.h"
47#include "atm_tools_param_info.h"
48#include "hap_token_info.h"
49#include "native_token_info.h"
50#include "permission_def.h"
51#include "permission_list_state.h"
52#include "permission_grant_info.h"
53#include "permission_state_change_info.h"
54#include "permission_state_full.h"
55#include "perm_state_change_callback_customize.h"
56#ifdef TOKEN_SYNC_ENABLE
57#include "token_sync_kit_interface.h"
58#endif // TOKEN_SYNC_ENABLE
59
60namespace OHOS {
61namespace Security {
62namespace AccessToken {
63/**
64 * @brief Declares AccessTokenKit class
65 */
66class AccessTokenKit {
67public:
68    /**
69     * @brief Get permission used type by tokenID.
70     * @param tokenID token id
71     * @param permissionName permission to be checked
72     * @return enum PermUsedTypeEnum, see access_token.h
73     */
74    static PermUsedTypeEnum GetPermissionUsedType(AccessTokenID tokenID, const std::string& permissionName);
75
76    /**
77     * @brief Grant input permission to input tokenID flag for specified time.
78     * @param tokenID token id
79     * @param permissionName permission name quote
80     * @param onceTime the time it takes to work, the unit is second.
81     * @return error code, see access_token_error.h
82     */
83    static int GrantPermissionForSpecifiedTime(
84        AccessTokenID tokenID, const std::string& permissionName, uint32_t onceTime);
85
86    /**
87     * @brief Create a unique hap token by input values.
88     * @param info struct HapInfoParams quote, see hap_token_info.h
89     * @param policy struct HapPolicyParams quote, see hap_token_info.h
90     * @return union AccessTokenIDEx, see access_token.h
91     */
92    static AccessTokenIDEx AllocHapToken(const HapInfoParams& info, const HapPolicyParams& policy);
93    /**
94     * @brief Create a unique hap token by input values and init the permission state.
95     * @param info struct HapInfoParams quote, see hap_token_info.h
96     * @param policy struct HapPolicyParams quote, see hap_token_info.h
97     * @return union AccessTokenIDEx, see access_token.h
98     */
99    static int32_t InitHapToken(const HapInfoParams& info, HapPolicyParams& policy, AccessTokenIDEx& fullTokenId);
100    /**
101     * @brief Create a unique mapping token binding remote tokenID and DeviceID.
102     * @param remoteDeviceID remote device deviceID
103     * @param remoteTokenID remote device tokenID
104     * @return local tokenID which mapped by local token
105     */
106    static AccessTokenID AllocLocalTokenID(const std::string& remoteDeviceID, AccessTokenID remoteTokenID);
107    /**
108     * @brief Update hap token info.
109     * @param tokenIdEx union AccessTokenIDEx quote, see access_token.h
110     * @param isSystemApp is system app or not
111     * @param appIDDesc app id description quote
112     * @param apiVersion app api version
113     * @param policy struct HapPolicyParams quote, see hap_token_info.h
114     * @return error code, see access_token_error.h
115     */
116    static int32_t UpdateHapToken(
117        AccessTokenIDEx& tokenIdEx, const UpdateHapInfoParams& info, const HapPolicyParams& policy);
118    /**
119     * @brief Delete token info.
120     * @param tokenID token id
121     * @return error code, see access_token_error.h
122     */
123    static int DeleteToken(AccessTokenID tokenID);
124    /**
125     * @brief Get token type by ATM service.
126     * @param tokenID token id
127     * @return token type enum, see access_token.h
128     */
129    static ATokenTypeEnum GetTokenType(AccessTokenID tokenID);
130    /**
131     * @brief Get token type from flag in tokenId, which doesn't depend on ATM service.
132     * @param tokenID token id
133     * @return token type enum, see access_token.h
134     */
135    static ATokenTypeEnum GetTokenTypeFlag(AccessTokenID tokenID);
136    /**
137     * @brief Get token type by ATM service with uint_64 parameters.
138     * @param tokenID token id
139     * @return token type enum, see access_token.h
140     */
141    static ATokenTypeEnum GetTokenType(FullTokenID tokenID);
142    /**
143     * @brief Get token type from flag in tokenId, which doesn't depend
144     *        on ATM service, with uint_64 parameters.
145     * @param tokenID token id
146     * @return token type enum, see access_token.h
147     */
148    static ATokenTypeEnum GetTokenTypeFlag(FullTokenID tokenID);
149    /**
150     * @brief Query hap tokenID by input prarms.
151     * @param userID user id
152     * @param bundleName bundle name
153     * @param instIndex inst index
154     * @return token id if exsit or 0 if not exsit
155     */
156    static AccessTokenID GetHapTokenID(int32_t userID, const std::string& bundleName, int32_t instIndex);
157    /**
158     * @brief Query hap token attribute by input prarms.
159     * @param userID user id
160     * @param bundleName bundle name
161     * @param instIndex inst index
162     * @return union AccessTokenIDEx, see access_token.h
163     */
164    static AccessTokenIDEx GetHapTokenIDEx(int32_t userID, const std::string& bundleName, int32_t instIndex);
165    /**
166     * @brief Get hap token info by token id.
167     * @param tokenID token id
168     * @param hapTokenInfoRes HapTokenInfo quote, as query result
169     * @return error code, see access_token_error.h
170     */
171    static int GetHapTokenInfo(AccessTokenID tokenID, HapTokenInfo& hapTokenInfoRes);
172    /**
173     * @brief Get native token info by token id.
174     * @param tokenID token id
175     * @param nativeTokenInfoRes NativeTokenInfo quote, as query result
176     * @return error code, see access_token_error.h
177     */
178    static int GetNativeTokenInfo(AccessTokenID tokenID, NativeTokenInfo& nativeTokenInfoRes);
179    /**
180     * @brief Check if the input tokenID has been granted the input permission.
181     * @param tokenID token id
182     * @param permissionName permission to be checked
183     * @return enum PermissionState, see access_token.h
184     */
185    static int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName);
186    /**
187     * @brief Check if the input tokenID has been granted the input permission.
188     * @param callerTokenID the tokenID of caller native process or hap process
189     * @param firstTokenID the tokenID of first caller native process or hap process
190     * @param permissionName permission to be checked
191     * @return enum PermissionState, see access_token.h
192     */
193    static int VerifyAccessToken(
194        AccessTokenID callerTokenID, AccessTokenID firstTokenID, const std::string& permissionName);
195        /**
196     * @brief Check if the input tokenID has been granted the input permission.
197     * @param tokenID token id
198     * @param permissionName permission to be checked
199     * @param crossIpc whether to cross ipc
200     * @return enum PermissionState, see access_token.h
201     */
202    static int VerifyAccessToken(AccessTokenID tokenID, const std::string& permissionName, bool crossIpc);
203    /**
204     * @brief Check if the input tokenID has been granted the input permission.
205     * @param callerTokenID the tokenID of caller native process or hap process
206     * @param firstTokenID the tokenID of first caller native process or hap process
207     * @param permissionName permission to be checked
208     * @param crossIpc whether to cross ipc
209     * @return enum PermissionState, see access_token.h
210     */
211    static int VerifyAccessToken(AccessTokenID callerTokenID,
212        AccessTokenID firstTokenID, const std::string& permissionName, bool crossIpc);
213
214    /**
215     * @brief Get permission definition by permission name.
216     * @param permissionName permission name quote
217     * @param permissionDefResult PermissionDef quote, as query result
218     * @return error code, see access_token_error.h
219     */
220    static int GetDefPermission(const std::string& permissionName, PermissionDef& permissionDefResult);
221    /**
222     * @brief Get all permission definitions by token id.
223     * @param tokenID token id
224     * @param permList PermissionDef list quote, as query result
225     * @return error code, see access_token_error.h
226     */
227    static int GetDefPermissions(AccessTokenID tokenID, std::vector<PermissionDef>& permList);
228    /**
229     * @brief Get all requested permission full state by token id and grant mode.
230     * @param tokenID token id
231     * @param reqPermList PermissionStateFull list quote, as query result
232     * @param isSystemGrant grant mode
233     * @return error code, see access_token_error.h
234     */
235    static int GetReqPermissions(
236        AccessTokenID tokenID, std::vector<PermissionStateFull>& reqPermList, bool isSystemGrant);
237    /**
238     * @brief Get permission grant flag
239     * @param tokenID token id
240     * @param permissionName permission name quote
241     * @param flag the permission grant flag, as query result
242     * @return error code, see access_token_error.h
243     */
244    static int GetPermissionFlag(AccessTokenID tokenID, const std::string& permissionName, uint32_t& flag);
245    /**
246     * @brief Set permission request toggle status
247     * @param permissionName permission name quote
248     * @param status the permission request toggle status to set
249     * @param userID the userID
250     * @return error code, see access_token_error.h
251     */
252    static int32_t SetPermissionRequestToggleStatus(const std::string& permissionName, uint32_t status, int32_t userID);
253    /**
254     * @brief Get permission request toggle status
255     * @param permissionName permission name quote
256     * @param status the permission request toggle status to get
257     * @param userID the userID
258     * @return error code, see access_token_error.h
259     */
260    static int32_t GetPermissionRequestToggleStatus(const std::string& permissionName, uint32_t& status,
261        int32_t userID);
262    /**
263     * @brief Get requsted permission grant result
264     * @param permList PermissionListState list quote, as input and query result
265     * @return enum PermissionOper, see access_token.h
266     */
267    static PermissionOper GetSelfPermissionsState(std::vector<PermissionListState>& permList,
268        PermissionGrantInfo& info);
269    /**
270     * @brief Get requsted permissions status
271     * @param permList PermissionListState list quote, as input and query result
272     * @return error code, see access_token_error.h
273     */
274    static int32_t GetPermissionsStatus(AccessTokenID tokenID, std::vector<PermissionListState>& permList);
275    /**
276     * @brief Grant input permission to input tokenID with input flag.
277     * @param tokenID token id
278     * @param permissionName permission name quote
279     * @param flag enum PermissionFlag, see access_token.h
280     * @return error code, see access_token_error.h
281     */
282    static int GrantPermission(AccessTokenID tokenID, const std::string& permissionName, uint32_t flag);
283    /**
284     * @brief Revoke input permission to input tokenID with input flag.
285     * @param tokenID token id
286     * @param permissionName permission name quote
287     * @param flag enum PermissionFlag, see access_token.h
288     * @return error code, see access_token_error.h
289     */
290    static int RevokePermission(AccessTokenID tokenID, const std::string& permissionName, uint32_t flag);
291    /**
292     * @brief Clear all user granted permissions state in input tokenID.
293     * @param tokenID token id
294     * @return error code, see access_token_error.h
295     */
296    static int ClearUserGrantedPermissionState(AccessTokenID tokenID);
297    /**
298     * @brief Register permission state change callback.
299     * @param callback smart point of class PermStateChangeCallbackCustomize quote
300     * @return error code, see access_token_error.h
301     */
302    static int32_t RegisterPermStateChangeCallback(
303        const std::shared_ptr<PermStateChangeCallbackCustomize>& callback);
304    /**
305     * @brief Unregister permission state change callback.
306     * @param callback smart point of class PermStateChangeCallbackCustomize quote
307     * @return error code, see access_token_error.h
308     */
309    static int32_t UnRegisterPermStateChangeCallback(const std::shared_ptr<PermStateChangeCallbackCustomize>& callback);
310    /**
311     * @brief Get current version.
312     * @param version access token version.
313     * @return error code, see access_token_error.h
314     */
315    static int32_t GetVersion(uint32_t& version);
316    /**
317     * @brief Get hap dlp flag by input tokenID.
318     * @param tokenID token id
319     * @return dlp flag in tokenID bitmap, or default -1
320     */
321    static int32_t GetHapDlpFlag(AccessTokenID tokenID);
322    /**
323     * @brief Reload native token info.
324     * @return error code, see access_token_error.h
325     */
326    static int32_t ReloadNativeTokenInfo();
327    /**
328     * @brief Get tokenID by native process name.
329     * @param processName native process name
330     * @return token id of native process
331     */
332    static AccessTokenID GetNativeTokenId(const std::string& processName);
333
334    /**
335     * @brief Set permission dialog capability
336     * @param hapBaseInfo base infomation of hap
337     * @param enable status of enable dialog
338     * @return error code, see access_token_error.h
339     */
340    static int32_t SetPermDialogCap(const HapBaseInfo& hapBaseInfo, bool enable);
341
342#ifdef TOKEN_SYNC_ENABLE
343    /**
344     * @brief Get remote hap token info by remote token id.
345     * @param tokenID remote token id
346     * @param hapSync HapTokenInfoForSync quote, as query result
347     * @return error code, see access_token_error.h
348     */
349    static int GetHapTokenInfoFromRemote(AccessTokenID tokenID, HapTokenInfoForSync& hapSync);
350    /**
351     * @brief Set remote hap token info with remote deviceID.
352     * @param deviceID remote deviceID
353     * @param hapSync hap token info to set
354     * @return error code, see access_token_error.h
355     */
356    static int SetRemoteHapTokenInfo(const std::string& deviceID, const HapTokenInfoForSync& hapSync);
357    /**
358     * @brief Delete remote token by remote deviceID and remote tokenID.
359     * @param deviceID remote deviceID
360     * @param tokenID remote tokenID
361     * @return error code, see access_token_error.h
362     */
363    static int DeleteRemoteToken(const std::string& deviceID, AccessTokenID tokenID);
364    /**
365     * @brief Get local mapping native tokenID by remote deviceID
366     *        and remote tokenID.
367     * @param deviceID remote deviceID
368     * @param tokenID remote tokenID
369     * @return token id of mapping native tokenID
370     */
371    static AccessTokenID GetRemoteNativeTokenID(const std::string& deviceID, AccessTokenID tokenID);
372    /**
373     * @brief Delete remote tokens by remote deviceID.
374     * @param deviceID remote deviceID
375     * @return error code, see access_token_error.h
376     */
377    static int DeleteRemoteDeviceTokens(const std::string& deviceID);
378    /**
379     * @brief Regist a token sync service callback
380     * @param syncCallback token sync class
381     * @return error code, see access_token_error.h
382     */
383    static int32_t RegisterTokenSyncCallback(const std::shared_ptr<TokenSyncKitInterface>& syncCallback);
384    /**
385     * @brief UnRegist a token sync service callback
386     * @param syncCallback token sync class
387     * @return error code, see access_token_error.h
388     */
389    static int32_t UnRegisterTokenSyncCallback();
390#endif
391    /**
392     * @brief Dump all token infos in the cache.
393     * @param tokenID token id, if tokenID is valid, only dump this token info
394     * @param dumpInfo all token info
395     */
396    static void DumpTokenInfo(const AtmToolsParamInfo& info, std::string& dumpInfo);
397    /**
398     * @brief Get application info of permission manager.
399     * @param info application info of permission manager
400     */
401    static void GetPermissionManagerInfo(PermissionGrantInfo& info);
402
403    /**
404     * @brief Set user permission policy
405     * @param userList list of user id.
406     * @param permList list of permission
407     * @return error code, see access_token_error.h
408     */
409    static int32_t InitUserPolicy(const std::vector<UserState>& userList, const std::vector<std::string>& permList);
410
411    /**
412     * @brief Update user permission policy
413     * @param userList list of user id.
414     * @return error code, see access_token_error.h
415     */
416    static int32_t UpdateUserPolicy(const std::vector<UserState>& userList);
417
418    /**
419     * @brief Clear user permission policy
420     * @return error code, see access_token_error.h
421     */
422    static int32_t ClearUserPolicy();
423};
424} // namespace AccessToken
425} // namespace Security
426} // namespace OHOS
427#endif
428