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 AssetStoreKit 43 * @syscap SystemCapability.Security.Asset 44 * @since 11 45 */ 46 47#ifdef __cplusplus 48extern "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 {@link ASSET_SUCCESS} 0 - The operation is successful. 56 * {@link ASSET_PERMISSION_DENIED} 201 - The caller doesn't have the permission. 57 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 58 * 1. Mandatory parameters are left unspecified. 59 * 2. Incorrect parameter types. 60 * 3. Parameter verification failed. 61 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 62 * {@link ASSET_DUPLICATED} 24000003 - The asset already exists. 63 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 64 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 65 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 66 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 67 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 68 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 69 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 70 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 71 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 72 * {@link ASSET_FILE_OPERATION_ERROR} 24000014 - The file operation failed. 73 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 74 * @since 11 75 */ 76int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt); 77 78/** 79 * @brief Removes one or more assets. 80 * 81 * @param query Pointer to the conditions for removing the assets. 82 * @param queryCnt Number of conditions for removing the assets. 83 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 84 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 85 * 1. Incorrect parameter types. 86 * 2. Parameter verification failed. 87 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 88 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 89 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 90 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 91 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 92 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 93 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 94 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 95 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 96 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 97 * @since 11 98 */ 99int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt); 100 101/** 102 * @brief Updates an asset. 103 * 104 * @param query Pointer to the conditions for updating the asset. 105 * @param queryCnt Number of conditions for updating the asset. 106 * @param attributes Pointer to the attributes of the asset to update. 107 * @param attributes Number of the attributes of the asset to update. 108 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 109 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 110 * 1. Mandatory parameters are left unspecified. 111 * 2. Incorrect parameter types. 112 * 3. Parameter verification failed. 113 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 114 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 115 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 116 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 117 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 118 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 119 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 120 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 121 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 122 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 123 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 124 * {@link ASSET_GET_SYSTEM_TIME_ERROR} 24000015 - Getting the system time failed. 125 * @since 11 126 */ 127int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt, 128 const Asset_Attr *attributesToUpdate, uint32_t updateCnt); 129 130/** 131 * @brief Preprocesses data before querying the asset that can be accessed only after a successful user authentication. 132 * 133 * @param query Pointer to the search criteria of the asset. 134 * @param queryCnt Number of the search criteria. 135 * @param challenge Pointer to the challenge value to be used when <b>OH_Asset_Query</b> is called. 136 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 137 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 138 * 1. Incorrect parameter types. 139 * 2. Parameter verification failed. 140 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 141 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 142 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 143 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 144 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 145 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 146 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 147 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 148 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 149 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 150 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 151 * {@link ASSET_LIMIT_EXCEEDED} 24000016 - The cache exceeds the limit. 152 * {@link ASSET_UNSUPPORTED} 24000017 - The capability is not supported. 153 * @since 11 154 */ 155int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge); 156 157/** 158 * @brief Queries assets. 159 * 160 * @param query Pointer to the search criteria. 161 * @param queryCnt Number of the search criteria. 162 * @param resultSet Pointer to the query result obtained. 163 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 164 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 165 * 1. Incorrect parameter types. 166 * 2. Parameter verification failed. 167 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 168 * {@link ASSET_NOT_FOUND} 24000002 - The asset is not found. 169 * {@link ASSET_ACCESS_DENIED} 24000004 - Access to the asset is denied. 170 * {@link ASSET_STATUS_MISMATCH} 24000005 - The screen lock status does not match. 171 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 172 * {@link ASSET_DATA_CORRUPTED} 24000007 - The asset is corrupted. 173 * {@link ASSET_DATABASE_ERROR} 24000008 - The database operation failed. 174 * {@link ASSET_CRYPTO_ERROR} 24000009 - The cryptography operation failed. 175 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 176 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 177 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 178 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 179 * {@link ASSET_UNSUPPORTED} 24000017 - The capability is not supported. 180 * @since 11 181 */ 182int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet); 183 184/** 185 * @brief Processes data after the query of the asset that requires user authentication. 186 * 187 * @param handle Pointer to the handle of the data to process, which includes the challenge value returned by 188 * <b>OH_Asset_PreQuery</b>. 189 * @param handleCnt Number of the elements in the handle attribute set. 190 * @return {@link ASSET_SUCCESS} 0 - The operation is successful. 191 * {@link ASSET_INVALID_ARGUMENT} 401 - Parameter error. Possible causes: 192 * 1. Mandatory parameters are left unspecified. 193 * 2. Incorrect parameter types. 194 * 3. Parameter verification failed. 195 * {@link ASSET_SERVICE_UNAVAILABLE} 24000001 - The ASSET service is unavailable. 196 * {@link ASSET_OUT_OF_MEMORY} 24000006 - Insufficient memory. 197 * {@link ASSET_IPC_ERROR} 24000010 - IPC failed. 198 * {@link ASSET_BMS_ERROR} 24000011 - Calling the Bundle Manager service failed. 199 * {@link ASSET_ACCOUNT_ERROR} 24000012 - Calling the OS Account service failed. 200 * {@link ASSET_ACCESS_TOKEN_ERROR} 24000013 - Calling the Access Token service failed. 201 * @since 11 202 */ 203int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt); 204 205/** 206 * @brief Parses the query result to obtain the specified attribute value. 207 * 208 * @param result Pointer to the query result to parse, which is obtained by <b>OH_Asset_Query</b>. 209 * @param tag Tag of the attribute to obtain. 210 * @return Returns <b>Asset_Attr</b> obtained if the operation is successful; returns <b>NULL</b> otherwise. 211 * The attribute does not need to be released by the service. 212 * @since 11 213 */ 214Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag); 215 216/** 217 * @brief Releases the memory occupied by the challenge value. 218 * 219 * @param blob Pointer to the challenge value (obtained by <b>OH_Asset_PreQuery</b>) to release. 220 * @since 11 221 */ 222void OH_Asset_FreeBlob(Asset_Blob *blob); 223 224/** 225 * @brief Releases the memory occupied by the query result. 226 * 227 * @param resultSet Pointer to the query result (obtained by <b>OH_Asset_Query</b>) to release. 228 * @since 11 229 */ 230void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet); 231 232#ifdef __cplusplus 233} 234#endif 235 236/** @} */ 237#endif // ASSET_API_H 238