1 /*
2  * Copyright (c) 2023 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_TYPE_H
17 #define ASSET_TYPE_H
18 
19 /**
20  * @addtogroup AssetType
21  * @{
22  *
23  * @brief Provides the enums, structs, and error codes used in the Asset APIs.
24  *
25  * @since 11
26  */
27 
28 /**
29  * @file asset_type.h
30  *
31  * @brief Defines the enums, structs, and error codes used in the Asset APIs.
32  *
33  * @library libasset_ndk.z.so
34  * @kit AssetStoreKit
35  * @syscap SystemCapability.Security.Asset
36  * @since 11
37  */
38 
39 #include <stdbool.h>
40 #include <stdint.h>
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 /**
47  * @brief Enumerates the types of the asset attribute tags.
48  *
49  * @since 11
50  */
51 typedef enum {
52     /**
53      * The asset attribute tag is a Boolean value.
54      */
55     ASSET_TYPE_BOOL = 0x1 << 28,
56     /**
57      * The asset attribute tag is a number.
58      */
59     ASSET_TYPE_NUMBER = 0x2 << 28,
60     /**
61      * The asset attribute tag is an array of bytes.
62      */
63     ASSET_TYPE_BYTES = 0x3 << 28,
64 } Asset_TagType;
65 
66 /**
67  * @brief Defines the mask used to obtain the type of the asset attribute tag.
68  *
69  * @since 11
70  */
71 #define ASSET_TAG_TYPE_MASK (0xF << 28)
72 
73 /**
74  * @brief Enumerates the asset attribute tags.
75  *
76  * @since 11
77  */
78 typedef enum {
79     /**
80      * Sensitive user data in the form of bytes, such as passwords and tokens.
81      */
82     ASSET_TAG_SECRET = ASSET_TYPE_BYTES | 0x01,
83     /**
84      * Asset alias (identifier) in the form of bytes.
85      */
86     ASSET_TAG_ALIAS = ASSET_TYPE_BYTES | 0x02,
87     /**
88      * Time when the asset is accessible. The value is of the uint32 type, which is a 32-bit unsigned integer.
89      */
90     ASSET_TAG_ACCESSIBILITY = ASSET_TYPE_NUMBER | 0x03,
91     /**
92      * A Boolean value indicating whether the asset is available only with a lock screen password.
93      */
94     ASSET_TAG_REQUIRE_PASSWORD_SET = ASSET_TYPE_BOOL | 0x04,
95     /**
96      * User authentication type for the asset. The value is of the uint32 type.
97      */
98     ASSET_TAG_AUTH_TYPE = ASSET_TYPE_NUMBER | 0x05,
99     /**
100      * Validity period of the user authentication, in seconds. The value is of the uint32 type.
101      */
102     ASSET_TAG_AUTH_VALIDITY_PERIOD = ASSET_TYPE_NUMBER | 0x06,
103     /**
104      * Challenge value, in the form of bytes, used for anti-replay during the authentication.
105      */
106     ASSET_TAG_AUTH_CHALLENGE = ASSET_TYPE_BYTES | 0x07,
107     /**
108      * Authentication token, in the form of bytes, obtained after a successful user authentication.
109      */
110     ASSET_TAG_AUTH_TOKEN = ASSET_TYPE_BYTES | 0x08,
111     /**
112      * Asset synchronization type. The value is of the uint32 type.
113      */
114     ASSET_TAG_SYNC_TYPE = ASSET_TYPE_NUMBER | 0x10,
115     /**
116      * A Boolean value indicating whether the asset needs to be stored persistently.
117      * The ohos.permission.STORE_PERSISTENT_DATA permission is required if <b>OH_Asset_Add</b> is called with this tag.
118      *
119      * @permission ohos.permission.STORE_PERSISTENT_DATA
120      */
121     ASSET_TAG_IS_PERSISTENT = ASSET_TYPE_BOOL | 0x11,
122     /**
123      * An immutable custom field, in the form of bytes.
124      */
125     ASSET_TAG_DATA_LABEL_CRITICAL_1 = ASSET_TYPE_BYTES | 0x20,
126     /**
127      * An immutable custom field, in the form of bytes.
128      */
129     ASSET_TAG_DATA_LABEL_CRITICAL_2 = ASSET_TYPE_BYTES | 0x21,
130     /**
131      * An immutable custom field, in the form of bytes.
132      */
133     ASSET_TAG_DATA_LABEL_CRITICAL_3 = ASSET_TYPE_BYTES | 0x22,
134     /**
135      * An immutable custom field, in the form of bytes.
136      */
137     ASSET_TAG_DATA_LABEL_CRITICAL_4 = ASSET_TYPE_BYTES | 0x23,
138     /**
139      * A mutable custom field, in the form of bytes.
140      */
141     ASSET_TAG_DATA_LABEL_NORMAL_1 = ASSET_TYPE_BYTES | 0x30,
142     /**
143      * A mutable custom field, in the form of bytes.
144      */
145     ASSET_TAG_DATA_LABEL_NORMAL_2 = ASSET_TYPE_BYTES | 0x31,
146     /**
147      * A mutable custom field, in the form of bytes.
148      */
149     ASSET_TAG_DATA_LABEL_NORMAL_3 = ASSET_TYPE_BYTES | 0x32,
150     /**
151      * A mutable custom field, in the form of bytes.
152      */
153     ASSET_TAG_DATA_LABEL_NORMAL_4 = ASSET_TYPE_BYTES | 0x33,
154     /**
155      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
156      *
157      * @since 12
158      */
159     ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1 = ASSET_TYPE_BYTES | 0x34,
160     /**
161      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
162      *
163      * @since 12
164      */
165     ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2 = ASSET_TYPE_BYTES | 0x35,
166     /**
167      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
168      *
169      * @since 12
170      */
171     ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3 = ASSET_TYPE_BYTES | 0x36,
172     /**
173      * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized.
174      *
175      * @since 12
176      */
177     ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4 = ASSET_TYPE_BYTES | 0x37,
178     /**
179      * Return type of the queried asset. The value is of the uint32 type.
180      */
181     ASSET_TAG_RETURN_TYPE = ASSET_TYPE_NUMBER | 0x40,
182     /**
183      * Maximum number of assets that can be returned at a time if multiple asset records match the specified conditions.
184      * The value is of the uint32 type.
185      */
186     ASSET_TAG_RETURN_LIMIT = ASSET_TYPE_NUMBER | 0x41,
187     /**
188      * Offset that indicates the start asset when multiple asset records are returned. The value is of the uint32 type.
189      */
190     ASSET_TAG_RETURN_OFFSET = ASSET_TYPE_NUMBER | 0x42,
191     /**
192      * Sorting order of the assets in the query result. The value is of the uint32 type.
193      */
194     ASSET_TAG_RETURN_ORDERED_BY = ASSET_TYPE_NUMBER | 0x43,
195     /**
196      * Policy used to resolve the conflict occurred when an asset is added. The value is of the uint32 type.
197      */
198     ASSET_TAG_CONFLICT_RESOLUTION = ASSET_TYPE_NUMBER | 0x44,
199     /**
200      * A tag whose value is a byte array indicating the update time of an Asset.
201      *
202      * @since 12
203      */
204     ASSET_TAG_UPDATE_TIME = ASSET_TYPE_BYTES | 0x45,
205     /**
206      * A tag whose value is the uint32 type indicating the additional action.
207      *
208      * @since 12
209      */
210     ASSET_TAG_OPERATION_TYPE = ASSET_TYPE_NUMBER | 0x46,
211     /**
212      * A tag whose value is a bool indicating whether the attributes of an asset are required to be encrypted.
213      *
214      * @since 13
215      */
216     ASSET_TAG_REQUIRE_ATTR_ENCRYPTED = ASSET_TYPE_BOOL | 0x47,
217 } Asset_Tag;
218 
219 /**
220  * @brief Enumerates the result codes used in the ASSET APIs.
221  *
222  * @since 11
223  */
224 typedef enum {
225     /** @error The operation is successful. */
226     ASSET_SUCCESS = 0,
227     /** @error The caller doesn't have the permission. */
228     ASSET_PERMISSION_DENIED = 201,
229     /** @error The parameter is invalid. */
230     ASSET_INVALID_ARGUMENT = 401,
231     /** @error The ASSET service is unavailable. */
232     ASSET_SERVICE_UNAVAILABLE = 24000001,
233     /** @error The asset is not found. */
234     ASSET_NOT_FOUND = 24000002,
235     /** @error The asset already exists. */
236     ASSET_DUPLICATED = 24000003,
237     /** @error Access to the asset is denied. */
238     ASSET_ACCESS_DENIED = 24000004,
239     /** @error The screen lock status does not match. */
240     ASSET_STATUS_MISMATCH = 24000005,
241     /** @error Insufficient memory. */
242     ASSET_OUT_OF_MEMORY = 24000006,
243     /** @error The asset is corrupted. */
244     ASSET_DATA_CORRUPTED = 24000007,
245     /** @error The database operation failed. */
246     ASSET_DATABASE_ERROR = 24000008,
247     /** @error The cryptography operation failed. */
248     ASSET_CRYPTO_ERROR = 24000009,
249     /** @error IPC failed. */
250     ASSET_IPC_ERROR = 24000010,
251     /** @error Calling the Bundle Manager service failed. */
252     ASSET_BMS_ERROR = 24000011,
253     /** @error Calling the OS Account service failed. */
254     ASSET_ACCOUNT_ERROR = 24000012,
255     /** @error Calling the Access Token service failed. */
256     ASSET_ACCESS_TOKEN_ERROR = 24000013,
257     /** @error The file operation failed. */
258     ASSET_FILE_OPERATION_ERROR = 24000014,
259     /** @error Getting the system time failed. */
260     ASSET_GET_SYSTEM_TIME_ERROR = 24000015,
261     /** @error The cache exceeds the limit. */
262     ASSET_LIMIT_EXCEEDED = 24000016,
263     /** @error The capability is not supported. */
264     ASSET_UNSUPPORTED = 24000017,
265 } Asset_ResultCode;
266 
267 /**
268  * @brief Enumerates the types of the access control based on the lock screen status.
269  *
270  * @since 11
271  */
272 typedef enum {
273     /**
274      * The asset can be accessed after the device is powered on.
275      */
276     ASSET_ACCESSIBILITY_DEVICE_POWERED_ON = 0,
277     /**
278      * The asset can be accessed only after the device is unlocked for the first time.
279      */
280     ASSET_ACCESSIBILITY_DEVICE_FIRST_UNLOCKED = 1,
281     /**
282      * The asset can be accessed only after the device is unlocked.
283      */
284     ASSET_ACCESSIBILITY_DEVICE_UNLOCKED = 2,
285 } Asset_Accessibility;
286 
287 /**
288  * @brief Enumerates the user authentication types supported for assets.
289  *
290  * @since 11
291  */
292 typedef enum {
293     /**
294      * No user authentication is required before the asset is accessed.
295      */
296     ASSET_AUTH_TYPE_NONE = 0x00,
297     /**
298      * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is
299      * successful.
300      */
301     ASSET_AUTH_TYPE_ANY = 0xFF,
302 } Asset_AuthType;
303 
304 /**
305  * @brief Enumerates the asset synchronization types.
306  *
307  * @since 11
308  */
309 typedef enum {
310     /**
311      * Asset synchronization is not allowed.
312      */
313     ASSET_SYNC_TYPE_NEVER = 0,
314     /**
315      * Asset synchronization is allowed only on the local device, for example, in data restoration on the local device.
316      */
317     ASSET_SYNC_TYPE_THIS_DEVICE = 1 << 0,
318     /**
319      * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning.
320      */
321     ASSET_SYNC_TYPE_TRUSTED_DEVICE = 1 << 1,
322     /**
323      * Asset synchronization is allowed only between devices with trusted accounts.
324      *
325      * @since 12
326      */
327     ASSET_SYNC_TYPE_TRUSTED_ACCOUNT = 1 << 2,
328 } Asset_SyncType;
329 
330 /**
331  * @brief Enumerates the policies for resolving the conflict (for example, duplicate alias) occurred when
332  * an asset is added.
333  *
334  * @since 11
335  */
336 typedef enum {
337     /**
338      * Overwrite the existing asset.
339      */
340     ASSET_CONFLICT_OVERWRITE = 0,
341     /**
342      * Throw an exception for the service to perform subsequent processing.
343      */
344     ASSET_CONFLICT_THROW_ERROR = 1,
345 } Asset_ConflictResolution;
346 
347 /**
348  * @brief Enumerates the types of the asset query result.
349  *
350  * @since 11
351  */
352 typedef enum {
353     /**
354      * The query result contains the asset in plaintext and its attributes.
355      */
356     ASSET_RETURN_ALL = 0,
357     /**
358      * The query result contains only the asset attributes.
359      */
360     ASSET_RETURN_ATTRIBUTES = 1,
361 } Asset_ReturnType;
362 
363 /**
364  * @brief Enumerates the types of the additional action.
365  *
366  * @since 12
367  */
368 typedef enum {
369     /**
370      * Synchronization is required during operation.
371      */
372     ASSET_NEED_SYNC = 0,
373     /**
374      * Logout is required during operation.
375      */
376     ASSET_NEED_LOGOUT = 1,
377 } Asset_OperationType;
378 
379 /**
380  * @brief Defines an asset value in the forma of a binary array, that is, a variable-length byte array.
381  *
382  * @since 11
383  */
384 typedef struct {
385     /**
386      * Size of the byte array.
387      */
388     uint32_t size;
389     /**
390      * Pointer to the byte array.
391      */
392     uint8_t *data;
393 } Asset_Blob;
394 
395 /**
396  * @brief Defines the value (content) of an asset attribute.
397  *
398  * @since 11
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     Asset_Blob blob;
413 } Asset_Value;
414 
415 /**
416  * @brief Defines an asset attribute.
417  *
418  * @since 11
419  */
420 typedef struct {
421     /**
422      * Tag of the asset attribute.
423      */
424     uint32_t tag;
425     /**
426      * Value of the asset attribute.
427      */
428     Asset_Value value;
429 } Asset_Attr;
430 
431 /**
432  * @brief Represents information about an asset.
433  *
434  * @since 11
435  */
436 typedef struct {
437     /**
438      * Number of asset attributes.
439      */
440     uint32_t count;
441     /**
442      * Pointer to the array of the asset attributes.
443      */
444     Asset_Attr *attrs;
445 } Asset_Result;
446 
447 /**
448  * @brief Represents information about a set of assets.
449  *
450  * @since 11
451  */
452 typedef struct {
453     /**
454      * Number of assets.
455      */
456     uint32_t count;
457     /**
458      * Pointer to the array of the assets.
459      */
460     Asset_Result *results;
461 } Asset_ResultSet;
462 
463 #ifdef __cplusplus
464 }
465 #endif
466 
467 /** @} */
468 #endif // ASSET_TYPE_H