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_API_H 17 #define ASSET_API_H 18 19 #include <stdint.h> 20 #include <stdlib.h> 21 22 #include "asset_type.h" 23 24 /** 25 * @addtogroup AssetApi 26 * @{ 27 * 28 * @brief Provides APIs for storing and managing short sensitive data of users, including adding, deleting, updating, 29 * and querying the data. 30 * The short sensitive data refers to sensitive data shorter than 1024 bytes, including the user passwords 31 * (accounts/passwords), token data (application credentials), and critical data in plaintext (bank card numbers). 32 * 33 * @since 11 34 */ 35 36 /** 37 * @file asset_api.h 38 * 39 * @brief Declares the APIs for accessing assets. 40 * 41 * @library libasset_ndk.z.so 42 * @kit Asset Store Kit 43 * @syscap SystemCapability.Security.Asset 44 * @since 11 45 */ 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 /** 51 * @brief Adds an asset. 52 * 53 * @param attributes Pointer to the attributes of the asset to add. 54 * @param attributes Number of the attributes of the asset to add. 55 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 56 * @since 11 57 */ 58 int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt); 59 60 /** 61 * @brief Removes one or more assets. 62 * 63 * @param query Pointer to the conditions for removing the assets. 64 * @param queryCnt Number of conditions for removing the assets. 65 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 66 * @since 11 67 */ 68 int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt); 69 70 /** 71 * @brief Updates an asset. 72 * 73 * @param query Pointer to the conditions for updating the asset. 74 * @param queryCnt Number of conditions for updating the asset. 75 * @param attributes Pointer to the attributes of the asset to update. 76 * @param attributes Number of the attributes of the asset to update. 77 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 78 * @since 11 79 */ 80 int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt, 81 const Asset_Attr *attributesToUpdate, uint32_t updateCnt); 82 83 /** 84 * @brief Preprocesses data before querying the asset that can be accessed only after a successful user authentication. 85 * 86 * @param query Pointer to the search criteria of the asset. 87 * @param queryCnt Number of the search criteria. 88 * @param challenge Pointer to the challenge value to be used when <b>OH_Asset_Query</b> is called. 89 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 90 * @since 11 91 */ 92 int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge); 93 94 /** 95 * @brief Queries assets. 96 * 97 * @param query Pointer to the search criteria. 98 * @param queryCnt Number of the search criteria. 99 * @param resultSet Pointer to the query result obtained. 100 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 101 * @since 11 102 */ 103 int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet); 104 105 /** 106 * @brief Processes data after the query of the asset that requires user authentication. 107 * 108 * @param handle Pointer to the handle of the data to process, which includes the challenge value returned by 109 * <b>OH_Asset_PreQuery</b>. 110 * @param handleCnt Number of the elements in the handle attribute set. 111 * @return Returns <b>ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 112 * @since 11 113 */ 114 int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt); 115 116 /** 117 * @brief Parses the query result to obtain the specified attribute value. 118 * 119 * @param result Pointer to the query result to parse, which is obtained by <b>OH_Asset_Query</b>. 120 * @param tag Tag of the attribute to obtain. 121 * @return Returns <b>Asset_Attr</b> obtained if the operation is successful; returns <b>NULL</b> otherwise. 122 * The attribute does not need to be released by the service. 123 * @since 11 124 */ 125 Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag); 126 127 /** 128 * @brief Releases the memory occupied by the challenge value. 129 * 130 * @param blob Pointer to the challenge value (obtained by <b>OH_Asset_PreQuery</b>) to release. 131 * @since 11 132 */ 133 void OH_Asset_FreeBlob(Asset_Blob *blob); 134 135 /** 136 * @brief Releases the memory occupied by the query result. 137 * 138 * @param resultSet Pointer to the query result (obtained by <b>OH_Asset_Query</b>) to release. 139 * @since 11 140 */ 141 void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet); 142 143 #ifdef __cplusplus 144 } 145 #endif 146 147 /** @} */ 148 #endif // ASSET_API_H 149