1 /* 2 * Copyright (c) 2022-2025 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 HuksKeyApi 18 * @{ 19 * 20 * @brief Describes the OpenHarmony Universal KeyStore (HUKS) capabilities, including key management and 21 * cryptography operations, provided for applications. 22 * The keys managed by HUKS can be imported by applications or generated by calling the HUKS APIs. 23 * 24 * @since 9 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_huks_api.h 30 * 31 * @brief Defines the Universal Keystore Kit APIs. 32 * 33 * @library libhuks_ndk.z.so 34 * @syscap SystemCapability.Security.Huks.Core 35 * 36 * include "huks/include/native_huks_type.h" 37 * @kit UniversalKeystoreKit 38 * @since 9 39 * @version 1.0 40 */ 41 42 #ifndef NATIVE_HUKS_API_H 43 #define NATIVE_HUKS_API_H 44 45 #include "native_huks_type.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Obtains the current HUKS SDK version. 53 * 54 * @param sdkVersion Indicates the pointer to the SDK version (in string format) obtained. 55 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 56 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If sdkVersion or 57 * sdkVersion->data is null, or if sdkVersion->size is too small. 58 * @since 9 59 * @version 1.0 60 */ 61 struct OH_Huks_Result OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion); 62 63 /** 64 * @brief Generates a key. 65 * 66 * @param keyAlias Indicates the pointer to the alias of the key to generate. 67 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 68 * @param paramSetIn Indicates the pointer to the parameter set for generating the key. 69 * @param paramSetOut Indicates the pointer to a temporary key generated. If the generated key is 70 * not of a temporary type, this parameter is a null pointer. 71 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 72 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSetIn or 73 * paramSetOut is invalid. 74 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 75 * input parameter abnormal.. 76 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL} 12000004 - If failed to remove file, 77 * or if failed to write file. 78 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 79 * is invalid. 80 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the base key file is not exit. 81 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 82 * get key argument. 83 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 84 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 85 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 86 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED} 12000015 - If Failed to obtain 87 * the security information via UserIAM. 88 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET} 12000016 - If device password is required 89 * but not set. 90 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 91 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST} 12000017 - If the key with same alias is 92 * already exist, add since api 20. 93 * @since 9 94 * @version 1.0 95 */ 96 struct OH_Huks_Result OH_Huks_GenerateKeyItem(const struct OH_Huks_Blob *keyAlias, 97 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 98 99 /** 100 * @brief Imports a key in plaintext. 101 * 102 * @param keyAlias Indicates the pointer to the alias of the key to import. 103 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 104 * @param paramSet Indicates the pointer to the parameters of the key to import. 105 * @param key Indicates the pointer to the key to import. The key must be in the format required by the HUKS. 106 * For details, see {@link HuksTypeApi}. 107 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 108 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSet or key is invalid. 109 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 110 * input parameter abnormal.. 111 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL} 12000004 - If failed to remove file, 112 * or if failed to write file. 113 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 114 * is invalid. 115 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 116 * get key argument. 117 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 118 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 119 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED} 12000015 - If Failed to obtain 120 * the security information via UserIAM. 121 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 122 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST} 12000017 - If the key with same alias is 123 * already exist, add since api 20. 124 * @since 9 125 * @version 1.0 126 */ 127 struct OH_Huks_Result OH_Huks_ImportKeyItem(const struct OH_Huks_Blob *keyAlias, 128 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key); 129 130 /** 131 * @brief Imports a wrapped key. 132 * 133 * @param keyAlias Indicates the pointer to the alias of the key to import. 134 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 135 * @param wrappingKeyAlias Indicates the pointer to the alias of the wrapping key, 136 * which is obtained through key agreement and used to decrypt the key to import. 137 * @param paramSet Indicates the pointer to the parameters of the wrapped key to import. 138 * @param wrappedKeyData Indicates the pointer to the wrapped key to import. 139 * The key must be in the format required by the HUKS. For details, see {@link OH_Huks_AlgSuite}. 140 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 141 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or wrappingKeyAlias or 142 * paramSet or wrappedKeyData is invalid. 143 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 144 * input parameter abnormal.. 145 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL} 12000004 - If failed to remove file, 146 * or if failed to write file. 147 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 148 * is invalid. 149 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 150 * get key argument. 151 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 152 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 153 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 154 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED} 12000015 - If Failed to obtain 155 * the security information via UserIAM. 156 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 157 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST} 12000017 - If the key with same alias is 158 * already exist, add since api 20. 159 * @since 9 160 * @version 1.0 161 */ 162 struct OH_Huks_Result OH_Huks_ImportWrappedKeyItem(const struct OH_Huks_Blob *keyAlias, 163 const struct OH_Huks_Blob *wrappingKeyAlias, const struct OH_Huks_ParamSet *paramSet, 164 const struct OH_Huks_Blob *wrappedKeyData); 165 166 /** 167 * @brief Exports a public key. 168 * 169 * @param keyAlias Indicates the pointer to the alias of the public key to export. 170 * The alias must be the same as the alias for the key generated. 171 * @param paramSet Indicates the pointer to the parameters required for exporting the public key. 172 * @param key Indicates the pointer to the public key exported. 173 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 174 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSet or key is invalid. 175 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 176 * input parameter abnormal.. 177 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 178 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 179 * is invalid. 180 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 181 * get key argument. 182 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 183 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 184 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 185 * @since 9 186 * @version 1.0 187 */ 188 struct OH_Huks_Result OH_Huks_ExportPublicKeyItem(const struct OH_Huks_Blob *keyAlias, 189 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key); 190 191 /** 192 * @brief Deletes a key. 193 * 194 * @param keyAlias Indicates the pointer to the alias of the key to delete. 195 * The alias must be the same as the alias for the key generated. 196 * @param paramSet Indicates the pointer to the parameters required for deleting the key. 197 * By default, this parameter is a null pointer. 198 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 199 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSet is invalid. 200 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 201 * input parameter abnormal.. 202 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 203 * is invalid. 204 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 205 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 206 * get key argument. 207 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 208 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 209 * @since 9 210 * @version 1.0 211 */ 212 struct OH_Huks_Result OH_Huks_DeleteKeyItem(const struct OH_Huks_Blob *keyAlias, 213 const struct OH_Huks_ParamSet *paramSet); 214 215 /** 216 * @brief Obtains the attributes of a key. 217 * 218 * @param keyAlias Indicates the pointer to the alias of the target key. 219 * @param paramSetIn Indicates the pointer to the attribute tag required for 220 * obtaining the attributes. By default, this parameter is a null pointer. 221 * @param paramSetOut Indicates the pointer to the attributes obtained. 222 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 223 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSetIn or 224 * paramSetOut is invalid. 225 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 226 * input parameter abnormal.. 227 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 228 * is invalid. 229 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 230 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 231 * get key argument. 232 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 233 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 234 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 235 * @since 9 236 * @version 1.0 237 */ 238 struct OH_Huks_Result OH_Huks_GetKeyItemParamSet(const struct OH_Huks_Blob *keyAlias, 239 const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut); 240 241 /** 242 * @brief Checks whether a key exists. 243 * 244 * @param keyAlias Indicates the pointer to the alias of the target key. 245 * @param paramSet Indicates the pointer to the attribute tag required for checking the key. 246 * By default, this parameter is a null pointer. 247 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 248 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSet is invalid. 249 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 250 * input parameter abnormal.. 251 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 252 * is invalid. 253 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 254 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 255 * get key argument. 256 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 257 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 258 * @since 9 259 * @version 1.0 260 */ 261 struct OH_Huks_Result OH_Huks_IsKeyItemExist(const struct OH_Huks_Blob *keyAlias, 262 const struct OH_Huks_ParamSet *paramSet); 263 264 /** 265 * @brief Obtain the key certificate chain. This API can be called only by system applications. 266 * 267 * @permission ohos.permission.ATTEST_KEY 268 * @param keyAlias Indicates the pointer to the alias of the target key. 269 * @param paramSet Indicates the pointer to the parameters required for obtaining the key certificate. 270 * @param certChain Indicates the pointer to the key certificate chain obtained. 271 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 272 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or 273 * paramSet or certChain is invalid. 274 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 275 * input parameter abnormal.. 276 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 277 * is invalid. 278 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 279 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 280 * get key argument. 281 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 282 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 283 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 284 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 285 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_PERMISSION_FAIL} 201 - If the permission check failed, 286 * please apply for the required permissions first. 287 * @since 9 288 * @version 1.0 289 */ 290 struct OH_Huks_Result OH_Huks_AttestKeyItem(const struct OH_Huks_Blob *keyAlias, 291 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain); 292 293 /** 294 * @brief Obtain the key certificate chain. 295 * 296 * @param keyAlias Indicates the pointer to the alias of the target key. 297 * @param paramSet Indicates the pointer to the parameters required for obtaining the key certificate. 298 * @param certChain Indicates the pointer to the key certificate chain obtained. 299 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 300 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or 301 * paramSet or certChain is invalid. 302 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 303 * input parameter abnormal.. 304 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 305 * is invalid. 306 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 307 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 308 * get key argument. 309 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 310 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 311 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 312 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 313 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_PERMISSION_FAIL} 201 - If the permission check failed, 314 * please apply for the required permissions first. 315 * @since 11 316 * @version 1.0 317 * @note this is a networking duration interface caller need to get the certChain in asynchronous thread 318 */ 319 struct OH_Huks_Result OH_Huks_AnonAttestKeyItem(const struct OH_Huks_Blob *keyAlias, 320 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain); 321 322 /** 323 * @brief Initializes the key session interface and obtains a handle (mandatory) and challenge value (optional). 324 * 325 * @param keyAlias Indicates the pointer to the alias of the target key. 326 * @param paramSet Indicates the pointer to the parameters for the initialization operation. 327 * @param handle Indicates the pointer to the handle of the key session obtained. 328 * This handle is required for subsequent operations, including {@link OH_Huks_UpdateSession}, 329 * {@link OH_Huks_FinishSession}, and {@link OH_Huks_AbortSession}. 330 * @param token Indicates the pointer to the token used for key access control. 331 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 332 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If keyAlias or paramSet or handle or 333 * token is invalid. 334 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 335 * input parameter abnormal.. 336 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 337 * is invalid. 338 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 339 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 340 * get key argument. 341 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 342 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_SESSION_LIMIT} 12000010 - If reached max session limit. 343 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 344 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 345 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 346 * @since 9 347 * @version 1.0 348 * @see OH_Huks_UpdateSession 349 * @see OH_Huks_FinishSession 350 * @see OH_Huks_AbortSession 351 */ 352 struct OH_Huks_Result OH_Huks_InitSession(const struct OH_Huks_Blob *keyAlias, 353 const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *handle, struct OH_Huks_Blob *token); 354 355 /** 356 * @brief Adds data by segment for the key operation, performs the related key operation, 357 * and outputs the processed data. 358 * 359 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 360 * @param paramSet Indicates the pointer to the parameters required for the key operation. 361 * @param inData Indicates the pointer to the data to be processed. 362 * This API can be called multiples time to process large data by segment. 363 * @param outData Indicates the pointer to the output data. 364 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 365 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If handle or paramSet or inData or 366 * outData is invalid. 367 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 368 * input parameter abnormal.. 369 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 370 * is invalid. 371 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit, 372 * or if the handle is not exist. 373 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 374 * get key argument. 375 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 376 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST} 12000013 - If credemtial is not exist. 377 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 378 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED} 12000008 - If auth token verify failed. 379 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED} 12000007 - If auth token info 380 * verify failed. 381 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT} 12000009 - If authentication token timed out. 382 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 383 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET} 12000016 - If device password is required 384 * but not set. 385 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 386 * @since 9 387 * @version 1.0 388 * @see OH_Huks_InitSession 389 * @see OH_Huks_FinishSession 390 * @see OH_Huks_AbortSession 391 */ 392 struct OH_Huks_Result OH_Huks_UpdateSession(const struct OH_Huks_Blob *handle, 393 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData); 394 395 /** 396 * @brief Ends the key session. 397 * 398 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 399 * @param paramSet Indicates the pointer to the parameters required for the key operation. 400 * @param inData Indicates the pointer to the data to be processed. 401 * @param outData Indicates the pointer to the output data. 402 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 403 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If handle or paramSet or inData or 404 * outData is invalid. 405 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 406 * input parameter abnormal.. 407 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 408 * is invalid. 409 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit, 410 * or if the handle is not exist. 411 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 412 * get key argument. 413 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 414 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST} 12000013 - If credemtial is not exist. 415 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CRYPTO_FAIL} 12000006 - If crypto engine failed. 416 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED} 12000008 - If auth token verify failed. 417 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED} 12000007 - If auth token info 418 * verify failed. 419 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT} 12000009 - If authentication token timed out. 420 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 421 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET} 12000016 - If device password is required 422 * but not set. 423 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED} 12000001 - If the feature is not support. 424 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST} 12000017 - If the key with same alias is 425 * already exist, add since api 20. 426 * @since 9 427 * @version 1.0 428 * @see OH_Huks_InitSession 429 * @see OH_Huks_UpdateSession 430 * @see OH_Huks_AbortSession 431 */ 432 struct OH_Huks_Result OH_Huks_FinishSession(const struct OH_Huks_Blob *handle, 433 const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData); 434 435 /** 436 * @brief Aborts a key session. 437 * 438 * @param handle Indicates the pointer to the key session handle, which is generated by {@link OH_Huks_InitSession}. 439 * @param paramSet Indicates the pointer to the parameters required for aborting the key session. 440 * By default, this parameter is a null pointer. 441 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 442 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If handle or paramSet or inData or 443 * outData is invalid. 444 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 445 * input parameter abnormal.. 446 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT} 12000003 - If the key argument 447 * is invalid. 448 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - or if the handle is not exist. 449 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT} 12000002 - If failed to 450 * get key argument. 451 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 452 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST} 12000013 - If credemtial is not exist. 453 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 454 * @since 9 455 * @version 1.0 456 * @see OH_Huks_InitSession 457 * @see OH_Huks_UpdateSession 458 * @see OH_Huks_FinishSession 459 */ 460 struct OH_Huks_Result OH_Huks_AbortSession(const struct OH_Huks_Blob *handle, 461 const struct OH_Huks_ParamSet *paramSet); 462 463 /** 464 * @brief Get key alias list. 465 * 466 * @param paramSet Indicates the pointer to the parameters required for getting key alias list. 467 * By default, this parameter is a null pointer. 468 * @param outData Indicates the pointer to the output data. 469 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 470 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT} 401 - If paramSet or outData is invalid. 471 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If Device environment or 472 * input parameter abnormal.. 473 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 474 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 475 * @since 20 476 * @version 1.0 477 */ 478 struct OH_Huks_Result OH_Huks_ListAliases(const struct OH_Huks_ParamSet *paramSet, 479 struct OH_Huks_KeyAliasSet **outData); 480 481 /** 482 * @brief Export the wrapped key encrypted by a specific key. 483 * 484 * @param keyAlias Indicates the pointer to the alias of the key to export. 485 * @param paramSet Indicates the pointer to the export parameters. 486 * @param wrappedKey Indicates the - indicates the wrapped key to export. 487 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 488 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_NOT_SUPPORTED_API} 801 - api is not supported 489 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL} 12000004 - If failed to remove file, 490 * or if failed to write file. 491 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 492 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST} 12000011 - If the key file is not exit. 493 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If system error ocurred. 494 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 495 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_ARGUMENT} 12000018 - If the input parameter is invalid. 496 * @since 20 497 */ 498 struct OH_Huks_Result OH_Huks_WrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet, 499 struct OH_Huks_Blob *wrappedKey); 500 501 /** 502 * @brief Import the wrapped key encrypted by a specific key. 503 * 504 * @param keyAlias Indicates the pointer to the alias of the key to import. 505 * The alias must be unique in the process of the service. Otherwise, the key will be overwritten. 506 * @param paramSet Indicates the pointer to the import parameters. 507 * @param wrappedKey Indicates the - indicates the wrapped key to import. 508 * @return {@link OH_Huks_ErrCode#OH_HUKS_SUCCESS} 0 - If the operation is successful. 509 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_NOT_SUPPORTED_API} 801 - api is not supported 510 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL} 12000004 - If failed to remove file, 511 * or if failed to write file. 512 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_COMMUNICATION_FAIL} 12000005 - If Ipc commuication failed. 513 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INTERNAL_ERROR} 12000012 - If system error ocurred. 514 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY} 12000014 - If the memory is insufficient. 515 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED} 12000015 - If connect userIam failed. 516 * {@link OH_Huks_ErrCode#OH_HUKS_ERR_CODE_INVALID_ARGUMENT} 12000018 - If the input parameter is invalid. 517 * @since 20 518 */ 519 struct OH_Huks_Result OH_Huks_UnwrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet, 520 struct OH_Huks_Blob *wrappedKey); 521 522 #ifdef __cplusplus 523 } 524 #endif 525 526 /** @} */ 527 #endif /* NATIVE_HUKS_API_H */ 528