1# CryptoSymCipherApi
2
3
4## Overview
5
6Provides APIs for symmetric key encryption and decryption.
7
8**Since**: 12
9
10
11## Summary
12
13
14### Files
15
16| Name | Description |
17| -------- | -------- |
18| [crypto_sym_cipher.h](crypto__sym__cipher_8h.md) | Defines APIs for symmetric encryption and decryption. |
19
20
21### Types
22
23| Name | Description |
24| -------- | -------- |
25| typedef struct [OH_CryptoSymCipher](#oh_cryptosymcipher) [OH_CryptoSymCipher](#oh_cryptosymcipher) | Defines a symmetric encryption and decryption instance. |
26| typedef struct [OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) [OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) | Defines symmetric encryption and decryption parameters. |
27
28
29### Enums
30
31| Name | Description |
32| -------- | -------- |
33| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) {<br>CRYPTO_IV_DATABLOB = 100,<br>CRYPTO_AAD_DATABLOB = 101,<br>CRYPTO_TAG_DATABLOB = 102<br>} | Enumerates the types of symmetric encryption and decryption parameters. |
34
35
36### Functions
37
38| Name | Description |
39| -------- | -------- |
40| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipherParams_Create](#oh_cryptosymcipherparams_create) ([OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) \*\*params) | Creates a symmetric encryption/decryption parameter instance. |
41| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipherParams_SetParam](#oh_cryptosymcipherparams_setparam) ([OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) \*params, [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) paramsType, [Crypto_DataBlob](_crypto___data_blob.md) \*value) | Sets a symmetric encryption/decryption parameter. |
42| void [OH_CryptoSymCipherParams_Destroy](#oh_cryptosymcipherparams_destroy) ([OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) \*params) | Destroys a symmetric encryption/decryption parameter instance. |
43| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipher_Create](#oh_cryptosymcipher_create) (const char \*algoName, [OH_CryptoSymCipher](#oh_cryptosymcipher) \*\*ctx) | Creates a symmetric cipher instance based on the given algorithm name. |
44| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx, [Crypto_CipherMode](_crypto_common_api.md#crypto_ciphermode) mod, [OH_CryptoSymKey](_crypto_sym_key_api.md#oh_cryptosymkey) \*key, [OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) \*params) | Initializes a symmetric cipher instance. |
45| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx, [Crypto_DataBlob](_crypto___data_blob.md) \*in, [Crypto_DataBlob](_crypto___data_blob.md) \*out) | Updates the data to be encrypted or decrypted. |
46| [OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode) [OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx, [Crypto_DataBlob](_crypto___data_blob.md) \*in, [Crypto_DataBlob](_crypto___data_blob.md) \*out) | Outputs the remaining data (generated by the block cipher mode) and finishes the encryption or decryption operation. |
47| const char \* [OH_CryptoSymCipher_GetAlgoName](#oh_cryptosymcipher_getalgoname) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx) | Obtains the symmetric encryption/decryption algorithm. |
48| void [OH_CryptoSymCipher_Destroy](#oh_cryptosymcipher_destroy) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx) | Destroys a symmetric cipher instance. |
49
50
51## Type Description
52
53
54### OH_CryptoSymCipher
55
56```
57typedef struct OH_CryptoSymCipherOH_CryptoSymCipher
58```
59
60**Description**
61
62Defines a symmetric encryption and decryption instance.
63
64**Since**: 12
65
66
67### OH_CryptoSymCipherParams
68
69```
70typedef struct OH_CryptoSymCipherParamsOH_CryptoSymCipherParams
71```
72
73**Description**
74
75Defines symmetric encryption and decryption parameters.
76
77**Since**: 12
78
79
80## Enum Description
81
82
83### CryptoSymCipher_ParamsType
84
85```
86enum CryptoSymCipher_ParamsType
87```
88
89**Description**
90
91Enumerates the types of symmetric encryption and decryption parameters.
92
93**Since**: 12
94
95| Enum | Description |
96| -------- | -------- |
97| CRYPTO_IV_DATABLOB | Initialization vector (IV). |
98| CRYPTO_AAD_DATABLOB | Additional authentication data (AAD). |
99| CRYPTO_TAG_DATABLOB | authTag. |
100
101
102## Function Description
103
104
105### OH_CryptoSymCipher_Create()
106
107```
108OH_Crypto_ErrCode OH_CryptoSymCipher_Create (const char *algoName, OH_CryptoSymCipher **ctx )
109```
110
111**Description**
112
113Creates a symmetric cipher instance based on the given algorithm name.
114
115**Since**: 12
116
117**Parameters**
118
119| Name | Description |
120| -------- | -------- |
121| algoName | Pointer to the algorithm used to create a symmetric cipher instance. For example, **'AES128\|GCM\|PKCS7'**.| |  |
122| ctx | Pointer to the symmetric cipher instance created. |
123
124**Returns**
125
126[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
127
128**0**: The operation is successful.
129
130**401**: Invalid parameters are detected.
131
132**801**: The operation is not supported.
133
134**17620001**: A memory error occurred.
135
136**17630001**: Failed to call an API of a third-party algorithm library.
137
138
139### OH_CryptoSymCipher_Destroy()
140
141```
142void OH_CryptoSymCipher_Destroy (OH_CryptoSymCipher *ctx)
143```
144
145**Description**
146
147Destroys a symmetric cipher instance.
148
149**Since**: 12
150
151**Parameters**
152
153| Name | Description |
154| -------- | -------- |
155| ctx | Pointer to the symmetric cipher instance to destroy. |
156
157
158### OH_CryptoSymCipher_Final()
159
160```
161OH_Crypto_ErrCode OH_CryptoSymCipher_Final (OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out )
162```
163
164**Description**
165
166Outputs the remaining data (generated by the block cipher mode) and finishes the encryption or decryption operation.
167
168**Since**: 12
169
170**Parameters**
171
172| Name | Description |
173| -------- | -------- |
174| ctx | Pointer to the symmetric cipher instance. |
175| in | Pointer to the data to be encrypted or decrypted. |
176| out | Pointer to the remaining data encrypted or decrypted. |
177
178**Returns**
179
180[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
181
182**0**: The operation is successful.
183
184**401**: Invalid parameters are detected.
185
186**801**: The operation is not supported.
187
188**17620001**: A memory error occurred.
189
190**17630001**: Failed to call an API of a third-party algorithm library.
191
192**See**
193
194[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init)
195
196[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update)
197
198
199### OH_CryptoSymCipher_GetAlgoName()
200
201```
202const char* OH_CryptoSymCipher_GetAlgoName (OH_CryptoSymCipher *ctx)
203```
204
205**Description**
206
207Obtains the symmetric encryption/decryption algorithm.
208
209**Since**: 12
210
211**Parameters**
212
213| Name | Description |
214| -------- | -------- |
215| ctx | Pointer to the symmetric cipher instance. |
216
217**Returns**
218
219Symmetric encryption/decryption algorithm obtained.
220
221
222### OH_CryptoSymCipher_Init()
223
224```
225OH_Crypto_ErrCode OH_CryptoSymCipher_Init (OH_CryptoSymCipher *ctx, Crypto_CipherMode mod, OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params )
226```
227
228**Description**
229
230Initializes a symmetric cipher instance.
231
232**Since**: 12
233
234**Parameters**
235
236| Name | Description |
237| -------- | -------- |
238| ctx | Pointer to the symmetric cipher instance. |
239| mod | Operation to perform, encryption or decryption. |
240| key | Pointer to the symmetric key. |
241| params | Pointer to the parameters for encryption or decryption. |
242
243**Returns**
244
245[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
246
247**0**: The operation is successful.
248
249**401**: Invalid parameters are detected.
250
251**801**: The operation is not supported.
252
253**17620001**: A memory error occurred.
254
255**17630001**: Failed to call an API of a third-party algorithm library.
256
257
258### OH_CryptoSymCipher_Update()
259
260```
261OH_Crypto_ErrCode OH_CryptoSymCipher_Update (OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out )
262```
263
264**Description**
265
266Updates the data to be encrypted or decrypted.
267
268**Since**: 12
269
270**Parameters**
271
272| Name | Description |
273| -------- | -------- |
274| ctx | Pointer to the symmetric cipher instance. |
275| in | Data to be encrypted or decrypted. |
276| out | Pointer to the data updated. |
277
278**Returns**
279
280[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
281
282**0**: The operation is successful.
283
284**401**: Invalid parameters are detected.
285
286**801**: The operation is not supported.
287
288**17620001**: A memory error occurred.
289
290**17630001**: Failed to call an API of a third-party algorithm library.
291
292
293### OH_CryptoSymCipherParams_Create()
294
295```
296OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create (OH_CryptoSymCipherParams **params)
297```
298
299**Description**
300
301Creates a symmetric encryption/decryption parameter instance.
302
303**Since**: 12
304
305**Parameters**
306
307| Name | Description |
308| -------- | -------- |
309| params | Pointer to the symmetric encryption/decryption parameter instance. |
310
311**Returns**
312
313[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
314
315**0**: The operation is successful.
316
317**401**: Invalid parameters are detected.
318
319**801**: The operation is not supported.
320
321**17620001**: A memory error occurred.
322
323**17630001**: Failed to call an API of a third-party algorithm library.
324
325
326### OH_CryptoSymCipherParams_Destroy()
327
328```
329void OH_CryptoSymCipherParams_Destroy (OH_CryptoSymCipherParams *params)
330```
331
332**Description**
333
334Destroys a symmetric encryption/decryption parameter instance.
335
336**Since**: 12
337
338**Parameters**
339
340| Name | Description |
341| -------- | -------- |
342| params | Pointer to the symmetric encryption/decryption parameter instance. |
343
344
345### OH_CryptoSymCipherParams_SetParam()
346
347```
348OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam (OH_CryptoSymCipherParams *params, CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value )
349```
350
351**Description**
352
353Sets a symmetric encryption/decryption parameter.
354
355**Since**: 12
356
357**Parameters**
358
359| Name | Description |
360| -------- | -------- |
361| params | Pointer to the symmetric encryption/decryption parameter instance. |
362| paramsType | Name of the parameter to set. |
363| value | Pointer to the parameter value set. |
364
365**Returns**
366
367[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):
368
369**0**: The operation is successful.
370
371**401**: Invalid parameters are detected.
372
373**801**: The operation is not supported.
374
375**17620001**: A memory error occurred.
376
377**17630001**: Failed to call an API of a third-party algorithm library.
378