1# CryptoSymKeyApi
2
3
4## Overview
5
6Provides APIs for symmetric key operations.
7
8**Since**: 12
9
10
11## Summary
12
13
14### Files
15
16| Name | Description |
17| -------- | -------- |
18| [crypto_sym_key.h](crypto__sym__key_8h.md) | Defines APIs for symmetric key operations. |
19
20
21### Types
22
23| Name | Description |
24| -------- | -------- |
25| typedef struct [OH_CryptoSymKey](#oh_cryptosymkey) [OH_CryptoSymKey](#oh_cryptosymkey) | Defines a struct for a symmetric key. |
26| typedef struct [OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) [OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) | Defines a struct for a symmetric key generator. |
27
28
29### Functions
30
31| Name | Description |
32| -------- | -------- |
33| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymKeyGenerator_Create](#oh_cryptosymkeygenerator_create) (const char \*algoName, [OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) \*\*ctx) | Creates a symmetric key generator instance based on the given algorithm name. |
34| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymKeyGenerator_Generate](#oh_cryptosymkeygenerator_generate) ([OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) \*ctx, [OH_CryptoSymKey](#oh_cryptosymkey) \*\*keyCtx) | Randomly generates a symmetric key. |
35| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymKeyGenerator_Convert](#oh_cryptosymkeygenerator_convert) ([OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) \*ctx, const [Crypto_DataBlob](_crypto___data_blob.md) \*keyData, [OH_CryptoSymKey](#oh_cryptosymkey) \*\*keyCtx) | Converts binary data into a symmetric key. |
36| const char \* [OH_CryptoSymKeyGenerator_GetAlgoName](#oh_cryptosymkeygenerator_getalgoname) ([OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) \*ctx) | Obtains the algorithm of a symmetric key generator instance. |
37| void [OH_CryptoSymKeyGenerator_Destroy](#oh_cryptosymkeygenerator_destroy) ([OH_CryptoSymKeyGenerator](#oh_cryptosymkeygenerator) \*ctx) | Destroys a symmetric key generator instance. |
38| const char \* [OH_CryptoSymKey_GetAlgoName](#oh_cryptosymkey_getalgoname) ([OH_CryptoSymKey](#oh_cryptosymkey) \*keyCtx) | Obtains the algorithm of a symmetric key. |
39| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymKey_GetKeyData](#oh_cryptosymkey_getkeydata) ([OH_CryptoSymKey](#oh_cryptosymkey) \*keyCtx, [Crypto_DataBlob](_crypto___data_blob.md) \*out) | Obtains symmetric key data from a key instance. |
40| void [OH_CryptoSymKey_Destroy](#oh_cryptosymkey_destroy) ([OH_CryptoSymKey](#oh_cryptosymkey) \*keyCtx) | Destroys a symmetric key instance. |
41
42
43## Type Description
44
45
46### OH_CryptoSymKey
47
48```
49typedef struct OH_CryptoSymKeyOH_CryptoSymKey
50```
51
52**Description**
53
54Defines a struct for a symmetric key.
55
56**Since**: 12
57
58
59### OH_CryptoSymKeyGenerator
60
61```
62typedef struct OH_CryptoSymKeyGeneratorOH_CryptoSymKeyGenerator
63```
64
65**Description**
66
67Defines a struct for a symmetric key generator.
68
69**Since**: 12
70
71
72## Function Description
73
74
75### OH_CryptoSymKey_Destroy()
76
77```
78void OH_CryptoSymKey_Destroy (OH_CryptoSymKey *keyCtx)
79```
80
81**Description**
82
83Destroys a symmetric key instance.
84
85**Since**: 12
86
87**Parameters**
88
89| Name | Description |
90| -------- | -------- |
91| keyCtx | Pointer to the symmetric key instance to destroy. |
92
93
94### OH_CryptoSymKey_GetAlgoName()
95
96```
97const char* OH_CryptoSymKey_GetAlgoName (OH_CryptoSymKey *keyCtx)
98```
99
100**Description**
101
102Obtains the algorithm of a symmetric key.
103
104**Since**: 12
105
106**Parameters**
107
108| Name | Description |
109| -------- | -------- |
110| keyCtx | Pointer to the symmetric key instance. |
111
112**Returns**
113
114Symmetric key algorithm obtained.
115
116
117### OH_CryptoSymKey_GetKeyData()
118
119```
120OH_Crypto_ErrCode OH_CryptoSymKey_GetKeyData (OH_CryptoSymKey *keyCtx, Crypto_DataBlob *out )
121```
122
123**Description**
124
125Obtains symmetric key data from a key instance.
126
127**Since**: 12
128
129**Parameters**
130
131| Name | Description |
132| -------- | -------- |
133| keyCtx | Pointer to the symmetric key instance. |
134| out | Pointer to the data obtained. |
135
136**Returns**
137
138[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
139
140**0**: The operation is successful.
141
142**401**: Invalid parameters are detected.
143
144**801**: The operation is not supported.
145
146**17620001**: A memory error occurred.
147
148**17630001**: Failed to call an API of a third-party algorithm library.
149
150
151### OH_CryptoSymKeyGenerator_Convert()
152
153```
154OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Convert (OH_CryptoSymKeyGenerator *ctx, const Crypto_DataBlob *keyData, OH_CryptoSymKey **keyCtx )
155```
156
157**Description**
158
159Converts binary data into a symmetric key.
160
161**Since**: 12
162
163**Parameters**
164
165| Name | Description |
166| -------- | -------- |
167| ctx | Pointer to the symmetric key generator instance. |
168| keyData | Pointer to the data to convert. |
169| keyCtx | Pointer to the symmetric key obtained. |
170
171**Returns**
172
173[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
174
175**0**: The operation is successful.
176
177**401**: Invalid parameters are detected.
178
179**801**: The operation is not supported.
180
181**17620001**: A memory error occurred.
182
183**17630001**: Failed to call an API of a third-party algorithm library.
184
185
186### OH_CryptoSymKeyGenerator_Create()
187
188```
189OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Create (const char *algoName, OH_CryptoSymKeyGenerator **ctx )
190```
191
192**Description**
193
194Creates a symmetric key generator instance based on the given algorithm name.
195
196**Since**: 12
197
198**Parameters**
199
200| Name | Description |
201| -------- | -------- |
202| algoName | Pointer to the algorithm used to generate the symmetric key. For example, **'AES256'**. |
203| ctx | Double pointer to the symmetric key generator instance created. |
204
205**Returns**
206
207[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
208
209**0**: The operation is successful.
210
211**401**: Invalid parameters are detected.
212
213**801**: The operation is not supported.
214
215**17620001**: A memory error occurred.
216
217**17630001**: Failed to call an API of a third-party algorithm library.
218
219
220### OH_CryptoSymKeyGenerator_Destroy()
221
222```
223void OH_CryptoSymKeyGenerator_Destroy (OH_CryptoSymKeyGenerator *ctx)
224```
225
226**Description**
227
228Destroys a symmetric key generator instance.
229
230**Since**: 12
231
232**Parameters**
233
234| Name | Description |
235| -------- | -------- |
236| ctx | Pointer to the symmetric key generator instance to destroy. |
237
238
239### OH_CryptoSymKeyGenerator_Generate()
240
241```
242OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Generate (OH_CryptoSymKeyGenerator *ctx, OH_CryptoSymKey **keyCtx )
243```
244
245**Description**
246
247Randomly generates a symmetric key.
248
249**Since**: 12
250
251**Parameters**
252
253| Name | Description |
254| -------- | -------- |
255| ctx | Pointer to the symmetric key generator instance. |
256| keyCtx | Pointer to the symmetric key created. |
257
258**Returns**
259
260[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
261
262**0**: The operation is successful.
263
264**401**: Invalid parameters are detected.
265
266**801**: The operation is not supported.
267
268**17620001**: A memory error occurred.
269
270**17630001**: Failed to call an API of a third-party algorithm library.
271
272
273### OH_CryptoSymKeyGenerator_GetAlgoName()
274
275```
276const char* OH_CryptoSymKeyGenerator_GetAlgoName (OH_CryptoSymKeyGenerator *ctx)
277```
278
279**Description**
280
281Obtains the algorithm of a symmetric key generator instance.
282
283**Since**: 12
284
285**Parameters**
286
287| Name | Description |
288| -------- | -------- |
289| ctx | Pointer to the symmetric key generator instance. |
290
291**Returns**
292
293Symmetric key algorithm obtained.
294