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