1# HuksKeyApi
2
3
4## Overview
5
6Defines the OpenHarmony Universal KeyStore (HUKS) capabilities, including key management and cryptography operations, provided for applications. Applications can call the HUKS functions to import or generate keys.
7
8**System capability**: SystemCapability.Security.Huks
9
10**Since**: 9
11
12
13## Summary
14
15
16### File
17
18| Name| Description|
19| -------- | -------- |
20| [native_huks_api.h](native__huks__api_8h.md) | Declares the functions used to access HUKS.<br>**File to include**: <huks/native_huks_api.h><br>**Library**: libhuks_ndk.z.so |
21
22
23### Functions
24
25| Name| Description|
26| -------- | -------- |
27| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GetSdkVersion](#oh_huks_getsdkversion) (struct [OH_Huks_Blob](_o_h___huks___blob.md) \*sdkVersion) | Obtains the current HUKS SDK version. |
28| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GenerateKeyItem](#oh_huks_generatekeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetIn, struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetOut) | Generates a key. |
29| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ImportKeyItem](#oh_huks_importkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*key) | Imports a key in plaintext. |
30| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ImportWrappedKeyItem](#oh_huks_importwrappedkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*wrappingKeyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*wrappedKeyData) | Imports a key in ciphertext. |
31| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ExportPublicKeyItem](#oh_huks_exportpublickeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*key) | Exports the public key. |
32| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_DeleteKeyItem](#oh_huks_deletekeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | Deletes a key. |
33| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GetKeyItemParamSet](#oh_huks_getkeyitemparamset) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetIn, struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetOut) | Obtains the properties of a key. |
34| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_IsKeyItemExist](#oh_huks_iskeyitemexist) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | Checks whether a key exists. |
35| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AttestKeyItem](#oh_huks_attestkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_CertChain](_o_h___huks___cert_chain.md) \*certChain) | Obtains the certificate chain of a key. |
36| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AnonAttestKeyItem](#oh_huks_anonattestkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_CertChain](_o_h___huks___cert_chain.md) \*certChain) | Obtains the certificate chain of a key. |
37| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_InitSession](#oh_huks_initsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*token) | Initializes a key session. This function returns a session handle (mandatory) and a challenge value (optional). |
38| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_UpdateSession](#oh_huks_updatesession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*inData, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*outData) | Adds and processes data by segment for a key operation, and outputs the processed data. |
39| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_FinishSession](#oh_huks_finishsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*inData, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*outData) | Finishes a key session. |
40| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AbortSession](#oh_huks_abortsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | Aborts a key session. |
41| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ListAliases](#oh_huks_listaliases) (const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_KeyAliasSet](_o_h___huks___key_alias_set.md) \*\*outData) | Lists key aliases. |
42
43
44## Function Description
45
46
47### OH_Huks_AbortSession()
48
49```
50struct OH_Huks_Result OH_Huks_AbortSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet )
51```
52**Description**
53Aborts a key session.
54
55**Since**: 9
56
57**Parameters**
58
59| Name| Description|
60| -------- | -------- |
61| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). |
62| paramSet | Pointer to the parameters for aborting the key session. By default, this parameter is a null pointer. |
63
64**Returns**
65
66Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
67
68**See**
69
70[OH_Huks_InitSession](#oh_huks_initsession)
71
72[OH_Huks_UpdateSession](#oh_huks_updatesession)
73
74[OH_Huks_FinishSession](#oh_huks_finishsession)
75
76
77### OH_Huks_AnonAttestKeyItem()
78
79```
80struct OH_Huks_Result OH_Huks_AnonAttestKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_CertChain * certChain )
81```
82**Description**
83Obtains the certificate chain of a key.
84
85**Since**: 11
86
87**Parameters**
88
89| Name| Description|
90| -------- | -------- |
91| keyAlias | Pointer to the alias of the target key. |
92| paramSet | Pointer to the parameters for obtaining the certificate chain. |
93| certChain | Pointer to the certificate chain obtained. |
94
95**Returns**
96
97Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
98
99**NOTE**
100
101This function involves time-consuming network operation. The caller can obtain the certificate chain through an asynchronous thread.
102
103
104### OH_Huks_AttestKeyItem()
105
106```
107struct OH_Huks_Result OH_Huks_AttestKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_CertChain * certChain )
108```
109
110**Description**
111Obtains the certificate chain of a key.
112
113**Required permissions**
114ohos.permission.ATTEST_KEY (for system applications only)
115
116**Since**: 9
117
118**Parameters**
119
120| Name| Description|
121| -------- | -------- |
122| keyAlias | Pointer to the alias of the target key. |
123| paramSet | Pointer to the parameters for obtaining the certificate chain. |
124| certChain | Pointer to the certificate chain obtained. |
125
126**Returns**
127
128Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
129
130
131### OH_Huks_DeleteKeyItem()
132
133```
134struct OH_Huks_Result OH_Huks_DeleteKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet )
135```
136**Description**
137Deletes a key.
138
139**Since**: 9
140
141**Parameters**
142
143| Name| Description|
144| -------- | -------- |
145| keyAlias | Pointer to the alias of the key to delete. It must be the same as the alias used for generating the key. |
146| paramSet | Pointer to the parameters for deleting the key. By default, this parameter is a null pointer. |
147
148**Returns**
149
150Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
151
152
153### OH_Huks_ExportPublicKeyItem()
154
155```
156struct OH_Huks_Result OH_Huks_ExportPublicKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * key )
157```
158**Description**
159Exports a public key.
160
161**Since**: 9
162
163**Parameters**
164
165| Name| Description|
166| -------- | -------- |
167| keyAlias | Pointer to the alias of the public key to export. It must be the same as the alias used for generating the key. |
168| paramSet | Pointer to the parameters for exporting the public key. |
169| key | Pointer to the public key exported. |
170
171**Returns**
172
173Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
174
175
176### OH_Huks_FinishSession()
177
178```
179struct OH_Huks_Result OH_Huks_FinishSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * inData, struct OH_Huks_Blob * outData )
180```
181**Description**
182Finishes a key session.
183
184**Since**: 9
185
186**Parameters**
187
188| Name| Description|
189| -------- | -------- |
190| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). |
191| paramSet | Pointer to the parameters required for the key operation. |
192| inData | Pointer to the data to be passed in. |
193| outData | Pointer to the output data. |
194
195**Returns**
196
197Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
198
199**See**
200
201[OH_Huks_InitSession](#oh_huks_initsession)
202
203[OH_Huks_UpdateSession](#oh_huks_updatesession)
204
205[OH_Huks_AbortSession](#oh_huks_abortsession)
206
207
208### OH_Huks_GenerateKeyItem()
209
210```
211struct OH_Huks_Result OH_Huks_GenerateKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut )
212```
213**Description**
214Generates a key.
215
216**Since**: 9
217
218**Parameters**
219
220| Name| Description|
221| -------- | -------- |
222| keyAlias | Pointer to the alias of the key to generate. The alias must be unique in the process of the service. |
223| paramSetIn | Pointer to the parameters for generating the key. |
224| paramSetOut | Pointer to a temporary key generated. If the generated key is not a temporary key, this parameter is a null pointer. |
225
226**Returns**
227
228Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
229
230
231### OH_Huks_GetKeyItemParamSet()
232
233```
234struct OH_Huks_Result OH_Huks_GetKeyItemParamSet (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut )
235```
236**Description**
237Obtains the properties of a key.
238
239**Since**: 9
240
241**Parameters**
242
243| Name| Description|
244| -------- | -------- |
245| keyAlias | Pointer to the alias of the target key. |
246| paramSetIn | Pointer to the tag required for obtaining the properties. By default, this parameter is a null pointer. |
247| paramSetOut | Pointer to the key properties obtained. |
248
249**Returns**
250
251Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
252
253
254### OH_Huks_GetSdkVersion()
255
256```
257struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion)
258```
259**Description**
260Obtains the current HUKS SDK version.
261
262**Since**: 9
263
264**Parameters**
265
266| Name| Description|
267| -------- | -------- |
268| sdkVersion | Pointer to the SDK version (string) obtained. |
269
270**Returns**
271
272Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
273
274
275### OH_Huks_ImportKeyItem()
276
277```
278struct OH_Huks_Result OH_Huks_ImportKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * key )
279```
280**Description**
281Imports a key in plaintext.
282
283**Since**: 9
284
285**Parameters**
286
287| Name| Description|
288| -------- | -------- |
289| keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service. |
290| paramSet | Pointer to the properties of the key to import. |
291| key | Pointer to the key to import. The key data must be of the [HuksTypeApi](_huks_type_api.md) type. |
292
293**Returns**
294
295Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
296
297
298### OH_Huks_ImportWrappedKeyItem()
299
300```
301struct OH_Huks_Result OH_Huks_ImportWrappedKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_Blob * wrappingKeyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * wrappedKeyData )
302```
303**Description**
304Imports a key in ciphertext.
305
306**Since**: 9
307
308**Parameters**
309
310| Name| Description|
311| -------- | -------- |
312| keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service. |
313| wrappingKeyAlias | Pointer to the alias of the key used for key agreement, which generates a shared secret to decrypt the key to import. |
314| paramSet | Pointer to the parameters for importing the key in ciphertext. |
315| wrappedKeyData | Pointer to the encrypted key to import. The data must be of the [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite) type.|
316
317**Returns**
318
319Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
320
321
322### OH_Huks_InitSession()
323
324```
325struct OH_Huks_Result OH_Huks_InitSession (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * handle, struct OH_Huks_Blob * token )
326```
327**Description**
328Initializes a key session. This function returns a handle (mandatory) and a challenge value (optional).
329
330**Since**: 9
331
332**Parameters**
333
334| Name| Description|
335| -------- | -------- |
336| keyAlias | Pointer to the alias of the target key. |
337| paramSet | Pointer to the parameters for the initialization operation. |
338| handle | Pointer to the handle of the key session. This handle is required for subsequent operations of the same key, including [OH_Huks_UpdateSession](#oh_huks_updatesession), [OH_Huks_FinishSession](#oh_huks_finishsession), and [OH_Huks_AbortSession](#oh_huks_abortsession). |
339| token | Pointer to the token used for key access control. |
340
341**Returns**
342
343Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
344
345**See**
346
347[OH_Huks_UpdateSession](#oh_huks_updatesession)
348
349[OH_Huks_FinishSession](#oh_huks_finishsession)
350
351[OH_Huks_AbortSession](#oh_huks_abortsession)
352
353
354### OH_Huks_IsKeyItemExist()
355
356```
357struct OH_Huks_Result OH_Huks_IsKeyItemExist (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet )
358```
359**Description**
360Checks whether a key exists.
361
362**Since**: 9
363
364**Parameters**
365
366| Name| Description|
367| -------- | -------- |
368| keyAlias | Pointer to the alias of the key to check. |
369| paramSet | Pointer to the parameters for checking the key. By default, this parameter is a null pointer. |
370
371**Returns**
372
373Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the key exists.
374
375Returns [OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md#oh_huks_errcode) if the key does not exist. 
376
377Returns other errors in other cases.
378
379
380### OH_Huks_ListAliases()
381
382```
383struct OH_Huks_Result OH_Huks_ListAliases (const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_KeyAliasSet ** outData )
384```
385**Description**
386Lists key aliases.
387
388**Since**: 12
389
390**Parameters**
391
392| Name| Description|
393| -------- | -------- |
394| paramSet | Pointer to the parameters for listing the key aliases. By default, this parameter is a null pointer. |
395| outData | pointer to the key aliases obtained. |
396
397**Returns**
398
399Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
400
401
402### OH_Huks_UpdateSession()
403
404```
405struct OH_Huks_Result OH_Huks_UpdateSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * inData, struct OH_Huks_Blob * outData )
406```
407**Description**
408Adds and processes data by segment for a key operation, and outputs the processed data.
409
410**Since**: 9
411
412**Parameters**
413
414| Name| Description|
415| -------- | -------- |
416| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). |
417| paramSet | Pointer to the parameters required for the key operation. |
418| inData | Pointer to the data to be processed. If there is a large amount of data to be processed, you can call this function multiple times to process data by segment. |
419| outData | Pointer to the output data. |
420
421**Returns**
422
423Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise.
424
425**See**
426
427[OH_Huks_InitSession](#oh_huks_initsession)
428
429[OH_Huks_FinishSession](#oh_huks_finishsession)
430
431[OH_Huks_AbortSession](#oh_huks_abortsession)
432