1 /*
2  * Copyright (c) 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 #ifndef ASSET_SYSTEM_TYPE_H
17 #define ASSET_SYSTEM_TYPE_H
18 
19 /**
20  * @file asset_system_type.h
21  *
22  * @brief Defines the enums, structs, and error codes used in the Asset APIs.
23  *
24  * @since 11
25  */
26 
27 #include <stdbool.h>
28 #include <stdint.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @brief Enumerates the types of the asset attribute tags.
36  */
37 typedef enum {
38     /**
39      * The asset attribute tag is a Boolean value.
40      */
41     SEC_ASSET_TYPE_BOOL = 0x1 << 28,
42     /**
43      * The asset attribute tag is a number.
44      */
45     SEC_ASSET_TYPE_NUMBER = 0x2 << 28,
46     /**
47      * The asset attribute tag is an array of bytes.
48      */
49     SEC_ASSET_TYPE_BYTES = 0x3 << 28,
50 } AssetTagType;
51 
52 /**
53  * @brief Defines the mask used to obtain the type of the asset attribute tag.
54  */
55 #define SEC_ASSET_TAG_TYPE_MASK (0xF << 28)
56 
57 /**
58  * @brief Enumerates the asset attribute tags.
59  */
60 typedef enum {
61     /**
62      * Sensitive user data in the form of bytes, such as passwords and tokens.
63      */
64     SEC_ASSET_TAG_SECRET = SEC_ASSET_TYPE_BYTES | 0x01,
65     /**
66      * Asset alias (identifier) in the form of bytes.
67      */
68     SEC_ASSET_TAG_ALIAS = SEC_ASSET_TYPE_BYTES | 0x02,
69     /**
70      * Time when the asset is accessible. The value is of the uint32 type, which is a 32-bit unsigned integer.
71      */
72     SEC_ASSET_TAG_ACCESSIBILITY = SEC_ASSET_TYPE_NUMBER | 0x03,
73     /**
74      * A Boolean value indicating whether the asset is available only with a lock screen password.
75      */
76     SEC_ASSET_TAG_REQUIRE_PASSWORD_SET = SEC_ASSET_TYPE_BOOL | 0x04,
77     /**
78      * User authentication type for the asset. The value is of the uint32 type.
79      */
80     SEC_ASSET_TAG_AUTH_TYPE = SEC_ASSET_TYPE_NUMBER | 0x05,
81     /**
82      * Validity period of the user authentication, in seconds. The value is of the uint32 type.
83      */
84     SEC_ASSET_TAG_AUTH_VALIDITY_PERIOD = SEC_ASSET_TYPE_NUMBER | 0x06,
85     /**
86      * Challenge value, in the form of bytes, used for anti-replay during the authentication.
87      */
88     SEC_ASSET_TAG_AUTH_CHALLENGE = SEC_ASSET_TYPE_BYTES | 0x07,
89     /**
90      * Authentication token, in the form of bytes, obtained after a successful user authentication.
91      */
92     SEC_ASSET_TAG_AUTH_TOKEN = SEC_ASSET_TYPE_BYTES | 0x08,
93     /**
94      * Asset synchronization type. The value is of the uint32 type.
95      */
96     SEC_ASSET_TAG_SYNC_TYPE = SEC_ASSET_TYPE_NUMBER | 0x10,
97     /**
98      * A Boolean value indicating whether the asset needs to be stored persistently.
99      * The ohos.permission.STORE_PERSISTENT_DATA permission is required if <b>OH_Asset_Add</b> is called with this tag.
100      *
101      * @permission ohos.permission.STORE_PERSISTENT_DATA
102      */
103     SEC_ASSET_TAG_IS_PERSISTENT = SEC_ASSET_TYPE_BOOL | 0x11,
104     /**
105      * An immutable custom field, in the form of bytes.
106      */
107     SEC_ASSET_TAG_DATA_LABEL_CRITICAL_1 = SEC_ASSET_TYPE_BYTES | 0x20,
108     /**
109      * An immutable custom field, in the form of bytes.
110      */
111     SEC_ASSET_TAG_DATA_LABEL_CRITICAL_2 = SEC_ASSET_TYPE_BYTES | 0x21,
112     /**
113      * An immutable custom field, in the form of bytes.
114      */
115     SEC_ASSET_TAG_DATA_LABEL_CRITICAL_3 = SEC_ASSET_TYPE_BYTES | 0x22,
116     /**
117      * An immutable custom field, in the form of bytes.
118      */
119     SEC_ASSET_TAG_DATA_LABEL_CRITICAL_4 = SEC_ASSET_TYPE_BYTES | 0x23,
120     /**
121      * A mutable custom field, in the form of bytes.
122      */
123     SEC_ASSET_TAG_DATA_LABEL_NORMAL_1 = SEC_ASSET_TYPE_BYTES | 0x30,
124     /**
125      * A mutable custom field, in the form of bytes.
126      */
127     SEC_ASSET_TAG_DATA_LABEL_NORMAL_2 = SEC_ASSET_TYPE_BYTES | 0x31,
128     /**
129      * A mutable custom field, in the form of bytes.
130      */
131     SEC_ASSET_TAG_DATA_LABEL_NORMAL_3 = SEC_ASSET_TYPE_BYTES | 0x32,
132     /**
133      * A mutable custom field, in the form of bytes.
134      */
135     SEC_ASSET_TAG_DATA_LABEL_NORMAL_4 = SEC_ASSET_TYPE_BYTES | 0x33,
136     /**
137      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
138      */
139     SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1 = SEC_ASSET_TYPE_BYTES | 0x34,
140     /**
141      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
142      */
143     SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2 = SEC_ASSET_TYPE_BYTES | 0x35,
144     /**
145      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
146      */
147     SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3 = SEC_ASSET_TYPE_BYTES | 0x36,
148     /**
149      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
150      */
151     SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4 = SEC_ASSET_TYPE_BYTES | 0x37,
152     /**
153      * Return type of the queried asset. The value is of the uint32 type.
154      */
155     SEC_ASSET_TAG_RETURN_TYPE = SEC_ASSET_TYPE_NUMBER | 0x40,
156     /**
157      * Maximum number of assets that can be returned at a time if multiple asset records match the specified conditions.
158      * The value is of the uint32 type.
159      */
160     SEC_ASSET_TAG_RETURN_LIMIT = SEC_ASSET_TYPE_NUMBER | 0x41,
161     /**
162      * Offset that indicates the start asset when multiple asset records are returned. The value is of the uint32 type.
163      */
164     SEC_ASSET_TAG_RETURN_OFFSET = SEC_ASSET_TYPE_NUMBER | 0x42,
165     /**
166      * Sorting order of the assets in the query result. The value is of the uint32 type.
167      */
168     SEC_ASSET_TAG_RETURN_ORDERED_BY = SEC_ASSET_TYPE_NUMBER | 0x43,
169     /**
170      * Policy used to resolve the conflict occurred when an asset is added. The value is of the uint32 type.
171      */
172     SEC_ASSET_TAG_CONFLICT_RESOLUTION = SEC_ASSET_TYPE_NUMBER | 0x44,
173     /**
174      * A tag whose value is a byte array indicating the update time of an Asset.
175      */
176     SEC_ASSET_TAG_UPDATE_TIME = SEC_ASSET_TYPE_BYTES | 0x45,
177     /**
178      * A tag whose value is the uint32 type indicating the additional action.
179      */
180     SEC_ASSET_TAG_OPERATION_TYPE = SEC_ASSET_TYPE_NUMBER | 0x46,
181     /**
182      * A tag whose value is a bool indicating whether the attributes of an asset are required to be encrypted.
183      */
184     SEC_ASSET_TAG_REQUIRE_ATTR_ENCRYPTED = SEC_ASSET_TYPE_BOOL | 0x47,
185     /**
186      * Tag used to store specific user id. The value is of the uint32 type.
187      */
188     SEC_ASSET_TAG_USER_ID = SEC_ASSET_TYPE_NUMBER | 0x100,
189 } AssetTag;
190 
191 /**
192  * @brief Enumerates the result codes used in the ASSET APIs.
193  */
194 typedef enum {
195     /**
196      * The operation is successful.
197      */
198     SEC_ASSET_SUCCESS = 0,
199     /**
200      * The caller does not have the required permission.
201      */
202     SEC_ASSET_PERMISSION_DENIED = 201,
203     /**
204      * The caller not system application.
205      */
206     SEC_ASSET_NOT_SYSTEM_APPLICATION = 202,
207     /**
208      * The parameter is invalid.
209      */
210     SEC_ASSET_INVALID_ARGUMENT = 401,
211     /**
212      * The asset service is unavailable.
213      */
214     SEC_ASSET_SERVICE_UNAVAILABLE = 24000001,
215     /**
216      * The asset is not found.
217      */
218     SEC_ASSET_NOT_FOUND = 24000002,
219     /**
220      * The asset already exists.
221      */
222     SEC_ASSET_DUPLICATED = 24000003,
223     /**
224      * The access to the asset is denied.
225      */
226     SEC_ASSET_ACCESS_DENIED = 24000004,
227     /**
228      * The lock screen status does not match the access control type specified.
229      */
230     SEC_ASSET_STATUS_MISMATCH = 24000005,
231     /**
232      * The system memory is insufficient.
233      */
234     SEC_ASSET_OUT_OF_MEMORY = 24000006,
235     /**
236      * The asset is corrupted.
237      */
238     SEC_ASSET_DATA_CORRUPTED = 24000007,
239     /**
240      * The database operation failed.
241      */
242     SEC_ASSET_DATABASE_ERROR = 24000008,
243     /**
244      * The cryptography operation failed.
245      */
246     SEC_ASSET_CRYPTO_ERROR = 24000009,
247     /**
248      * The inter-process communication (IPC) failed.
249      */
250     SEC_ASSET_IPC_ERROR = 24000010,
251     /**
252      * The Bundle Manager service is abnormal.
253      */
254     SEC_ASSET_BMS_ERROR = 24000011,
255     /**
256      * The Account service is abnormal.
257      */
258     SEC_ASSET_ACCOUNT_ERROR = 24000012,
259     /**
260      * The Access Token service is abnormal.
261      */
262     SEC_ASSET_ACCESS_TOKEN_ERROR = 24000013,
263     /**
264      * The file operation failed.
265      */
266     SEC_ASSET_FILE_OPERATION_ERROR = 24000014,
267     /**
268      * The operation for obtaining the system time failed.
269      */
270     SEC_ASSET_GET_SYSTEM_TIME_ERROR = 24000015,
271     /**
272      * The number of cached assets exceeds the limit.
273      */
274     SEC_ASSET_LIMIT_EXCEEDED = 24000016,
275     /**
276      * The function is not supported.
277      */
278     SEC_ASSET_UNSUPPORTED = 24000017,
279 } AssetResultCode;
280 
281 /**
282  * @brief Enumerates the types of the access control based on the lock screen status.
283  */
284 typedef enum {
285     /**
286      * The asset can be accessed after the device is powered on.
287      */
288     SEC_ASSET_ACCESSIBILITY_DEVICE_POWERED_ON = 0,
289     /**
290      * The asset can be accessed only after the device is unlocked for the first time.
291      */
292     SEC_ASSET_ACCESSIBILITY_DEVICE_FIRST_UNLOCKED = 1,
293     /**
294      * The asset can be accessed only after the device is unlocked.
295      */
296     SEC_ASSET_ACCESSIBILITY_DEVICE_UNLOCKED = 2,
297 } AssetAccessibility;
298 
299 /**
300  * @brief Enumerates the user authentication types supported for assets.
301  */
302 typedef enum {
303     /**
304      * No user authentication is required before the asset is accessed.
305      */
306     SEC_ASSET_AUTH_TYPE_NONE = 0x00,
307     /**
308      * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is
309      * successful.
310      */
311     SEC_ASSET_AUTH_TYPE_ANY = 0xFF,
312 } AssetAuthType;
313 
314 /**
315  * @brief Enumerates the asset synchronization types.
316  */
317 typedef enum {
318     /**
319      * Asset synchronization is not allowed.
320      */
321     SEC_ASSET_SYNC_TYPE_NEVER = 0,
322     /**
323      * Asset synchronization is allowed only on the local device, for example, in data restoration on the local device.
324      */
325     SEC_ASSET_SYNC_TYPE_THIS_DEVICE = 1 << 0,
326     /**
327      * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning.
328      */
329     SEC_ASSET_SYNC_TYPE_TRUSTED_DEVICE = 1 << 1,
330     /**
331      * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning.
332      */
333     SEC_ASSET_SYNC_TYPE_TRUSTED_ACCOUNT = 1 << 2,
334 } AssetSyncType;
335 
336 /**
337  * @brief Enumerates the policies for resolving the conflict (for example, duplicate alias) occurred when
338  * an asset is added.
339  */
340 typedef enum {
341     /**
342      * Overwrite the existing asset.
343      */
344     SEC_ASSET_CONFLICT_OVERWRITE = 0,
345     /**
346      * Throw an exception for the service to perform subsequent processing.
347      */
348     SEC_ASSET_CONFLICT_THROW_ERROR = 1,
349 } AssetConflictResolution;
350 
351 /**
352  * @brief Enumerates the types of the asset query result.
353  */
354 typedef enum {
355     /**
356      * The query result contains the asset in plaintext and its attributes.
357      */
358     SEC_ASSET_RETURN_ALL = 0,
359     /**
360      * The query result contains only the asset attributes.
361      */
362     SEC_ASSET_RETURN_ATTRIBUTES = 1,
363 } AssetReturnType;
364 
365 /**
366  * @brief Enumerates the types of the asset query result.
367  */
368 typedef enum {
369     /**
370      * Trigger Sync.
371      */
372     SEC_ASSET_NEED_SYNC = 0,
373     /**
374      * Logout account to clean cloud flag.
375      */
376     SEC_ASSET_NEED_LOGOUT = 1,
377     /**
378      * Delete cloud data.
379      */
380     SEC_ASSET_NEED_DELETE_CLOUD_DATA = 2,
381 } AssetOperationType;
382 
383 /**
384  * @brief Defines an asset value in the forma of a binary array, that is, a variable-length byte array.
385  */
386 typedef struct {
387     /**
388      * Size of the byte array.
389      */
390     uint32_t size;
391     /**
392      * Pointer to the byte array.
393      */
394     uint8_t *data;
395 } AssetBlob;
396 
397 /**
398  * @brief Defines the value (content) of an asset attribute.
399  */
400 typedef union {
401     /**
402      * Asset of the Boolean type.
403      */
404     bool boolean;
405     /**
406      * Asset of the uint32 type.
407      */
408     uint32_t u32;
409     /**
410      * Asset of the bytes type.
411      */
412     AssetBlob blob;
413 } AssetValue;
414 
415 /**
416  * @brief Defines an asset attribute.
417  */
418 typedef struct {
419     /**
420      * Tag of the asset attribute.
421      */
422     uint32_t tag;
423     /**
424      * Value of the asset attribute.
425      */
426     AssetValue value;
427 } AssetAttr;
428 
429 /**
430  * @brief Represents information about an asset.
431  */
432 typedef struct {
433     /**
434      * Number of asset attributes.
435      */
436     uint32_t count;
437     /**
438      * Pointer to the array of the asset attributes.
439      */
440     AssetAttr *attrs;
441 } AssetResult;
442 
443 /**
444  * @brief Represents information about a set of assets.
445  */
446 typedef struct {
447     /**
448      * Number of assets.
449      */
450     uint32_t count;
451     /**
452      * Pointer to the array of the assets.
453      */
454     AssetResult *results;
455 } AssetResultSet;
456 
457 #ifdef __cplusplus
458 }
459 #endif
460 
461 #endif // ASSET_SYSTEM_TYPE_H