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 /** 17 * @addtogroup AssetApi 18 * @{ 19 * 20 * @brief Provides APIs for storing and managing short sensitive data of users, including adding, deleting, updating, 21 * and querying the data. 22 * The short sensitive data refers to sensitive data shorter than 1024 bytes, including the user passwords 23 * (accounts/passwords), token data (application credentials), and critical data in plaintext (bank card numbers). 24 * 25 * @since 11 26 */ 27 28 /** 29 * @file asset_api.h 30 * 31 * @brief Declares the APIs for accessing assets. 32 * 33 * @library libasset_ndk.z.so 34 * @kit AssetStoreKit 35 * @syscap SystemCapability.Security.Asset 36 * @since 11 37 */ 38 39 #ifndef ASSET_API_H 40 #define ASSET_API_H 41 42 #include <stdint.h> 43 #include <stdlib.h> 44 45 #include "asset_type.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 /** 51 * @brief Adds an asset. Permission ohos.permission.STORE_PERSISTENT_DATA is required when the Asset needs to be stored 52 * persistently by setting {@link ASSET_TAG_IS_PERSISTENT} tag. 53 * 54 * @param attributes Pointer to the attributes of the asset to add. 55 * @param attributes Number of the attributes of the asset to add. 56 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 57 * {@link ASSET_PERMISSION_DENIED} 201 - The caller doesn't have the permission. 58 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 59 * 1. Mandatory parameters are left unspecified. 60 * 2. Incorrect parameter types. 61 * 3. Parameter verification failed. 62 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 63 * {@link ASSET_DUPLICATED} 24000003 - The asset already exists. 64 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 65 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 66 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 67 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 68 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 69 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 70 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 71 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 72 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 73 * {@link ASSET_FILE_OPERATION_ERROR} 24000014 - The file operation failed. 74 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 75 * @since 11 76 */ 77 int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt); 78 79 /** 80 * @brief Removes one or more assets. 81 * 82 * @param query Pointer to the conditions for removing the assets. 83 * @param queryCnt Number of conditions for removing the assets. 84 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 85 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 86 * 1. Incorrect parameter types. 87 * 2. Parameter verification failed. 88 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 89 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 90 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 91 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 92 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 93 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 94 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 95 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 96 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 97 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 98 * @since 11 99 */ 100 int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt); 101 102 /** 103 * @brief Updates an asset. 104 * 105 * @param query Pointer to the conditions for updating the asset. 106 * @param queryCnt Number of conditions for updating the asset. 107 * @param attributes Pointer to the attributes of the asset to update. 108 * @param attributes Number of the attributes of the asset to update. 109 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 110 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 111 * 1. Mandatory parameters are left unspecified. 112 * 2. Incorrect parameter types. 113 * 3. Parameter verification failed. 114 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 115 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 116 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 117 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 118 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 119 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 120 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 121 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 122 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 123 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 124 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 125 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 126 * @since 11 127 */ 128 int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt, 129 const Asset_Attr *attributesToUpdate, uint32_t updateCnt); 130 131 /** 132 * @brief Preprocesses data before querying the asset that can be accessed only after a successful user authentication. 133 * 134 * @param query Pointer to the search criteria of the asset. 135 * @param queryCnt Number of the search criteria. 136 * @param challenge Pointer to the challenge value to be used when <b>OH_Asset_Query</b> is called. 137 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 138 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 139 * 1. Incorrect parameter types. 140 * 2. Parameter verification failed. 141 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 142 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 143 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 144 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 145 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 146 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 147 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 148 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 149 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 150 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 151 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 152 * {@link ASSET_LIMIT_EXCEEDED} 24000016 - The cache exceeds the limit. 153 * {@link ASSET_UNSUPPORTED} 24000017 - The capability is not supported. 154 * @since 11 155 */ 156 int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge); 157 158 /** 159 * @brief Queries assets. 160 * 161 * @param query Pointer to the search criteria. 162 * @param queryCnt Number of the search criteria. 163 * @param resultSet Pointer to the query result obtained. 164 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 165 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 166 * 1. Incorrect parameter types. 167 * 2. Parameter verification failed. 168 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 169 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 170 * {@link ASSET_ACCESS_DENIED} 24000004 - Access to the asset is denied. 171 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 172 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 173 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 174 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 175 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 176 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 177 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 178 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 179 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 180 * {@link ASSET_UNSUPPORTED} 24000017 - The capability is not supported. 181 * @since 11 182 */ 183 int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet); 184 185 /** 186 * @brief Processes data after the query of the asset that requires user authentication. 187 * 188 * @param handle Pointer to the handle of the data to process, which includes the challenge value returned by 189 * <b>OH_Asset_PreQuery</b>. 190 * @param handleCnt Number of the elements in the handle attribute set. 191 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 192 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 193 * 1. Mandatory parameters are left unspecified. 194 * 2. Incorrect parameter types. 195 * 3. Parameter verification failed. 196 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 197 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 198 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 199 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 200 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 201 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 202 * @since 11 203 */ 204 int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt); 205 206 /** 207 * @brief Query the result of synchronization. 208 * 209 * @param query Pointer to the search criteria. 210 * @param queryCnt Number of the search criteria. 211 * @param syncResult Pointer to the synchronization result obtained. 212 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 213 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 214 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 215 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 216 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 217 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 218 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 219 * {@link ASSET_FILE_OPERATION_ERROR} 24000014 - The file operation failed. 220 * {@link ASSET_PARAM_VERIFICATION_FAILED} 24000018 - Parameter verification failed. 221 * @since 20 222 */ 223 int32_t OH_Asset_QuerySyncResult(const Asset_Attr *query, uint32_t queryCnt, Asset_SyncResult *syncResult); 224 225 /** 226 * @brief Parses the query result to obtain the specified attribute value. 227 * 228 * @param result Pointer to the query result to parse, which is obtained by <b>OH_Asset_Query</b>. 229 * @param tag Tag of the attribute to obtain. 230 * @return Returns <b>Asset_Attr</b> obtained if the operation is successful; returns <b>NULL</b> otherwise. 231 * The attribute does not need to be released by the service. 232 * @since 11 233 */ 234 Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag); 235 236 /** 237 * @brief Releases the memory occupied by the challenge value. 238 * 239 * @param blob Pointer to the challenge value (obtained by <b>OH_Asset_PreQuery</b>) to release. 240 * @since 11 241 */ 242 void OH_Asset_FreeBlob(Asset_Blob *blob); 243 244 /** 245 * @brief Releases the memory occupied by the query result. 246 * 247 * @param resultSet Pointer to the query result (obtained by <b>OH_Asset_Query</b>) to release. 248 * @since 11 249 */ 250 void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet); 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 /** @} */ 257 #endif // ASSET_API_H 258