1# crypto_sym_cipher.h 2 3<!--Kit: Crypto Architecture Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @zxz--3--> 6<!--Designer: @lanming--> 7<!--Tester: @PAFT--> 8<!--Adviser: @zengyawen--> 9 10## Overview 11 12Defines APIs for encrypting and decrypting symmetric keys. 13 14**Header file**: <CryptoArchitectureKit/crypto_sym_cipher.h> 15 16**Library**: libohcrypto.so 17 18**System capability**: SystemCapability.Security.CryptoFramework 19 20**Since**: 12 21 22**Related module**: [CryptoSymCipherApi](capi-cryptosymcipherapi.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) | OH_CryptoSymCipher | Defines a symmetric encryption and decryption instance.| 31| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) | OH_CryptoSymCipherParams | Defines symmetric encryption and decryption parameters.| 32 33### Enums 34 35| Name| typedef Keyword| Description| 36| -- | -- | -- | 37| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) | CryptoSymCipher_ParamsType | Enumerates the types of symmetric encryption and decryption parameters.| 38 39### Functions 40 41| Name| Description| 42| -- | -- | 43| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params)](#oh_cryptosymcipherparams_create) | Creates a symmetric encryption/decryption parameter instance.| 44| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params,CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value)](#oh_cryptosymcipherparams_setparam) | Sets symmetric encryption/decryption parameters.| 45| [void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params)](#oh_cryptosymcipherparams_destroy) | Destroys a symmetric encryption/decryption parameter instance.| 46| [OH_Crypto_ErrCode OH_CryptoSymCipher_Create(const char *algoName, OH_CryptoSymCipher **ctx)](#oh_cryptosymcipher_create) | Creates a symmetric encryption/decryption instance based on the given algorithm name.| 47| [OH_Crypto_ErrCode OH_CryptoSymCipher_Init(OH_CryptoSymCipher *ctx, Crypto_CipherMode mod,OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params)](#oh_cryptosymcipher_init) | Initializes a symmetric encryption/decryption instance.| 48| [OH_Crypto_ErrCode OH_CryptoSymCipher_Update(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out)](#oh_cryptosymcipher_update) | Updates the data to be encrypted or decrypted.| 49| [OH_Crypto_ErrCode OH_CryptoSymCipher_Final(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out)](#oh_cryptosymcipher_final) | Outputs the remaining data (generated by the block cipher mode) and finishes the encryption or decryption operation.| 50| [const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_getalgoname) | Obtains the symmetric encryption/decryption algorithm.| 51| [void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_destroy) | Destroys a symmetric encryption/decryption instance.| 52 53## Enum Description 54 55### CryptoSymCipher_ParamsType 56 57``` 58enum CryptoSymCipher_ParamsType 59``` 60 61**Description** 62 63Enumerates the types of symmetric encryption and decryption parameters. 64 65**Since**: 12 66 67| Enum Item| Description| 68| -- | -- | 69| CRYPTO_IV_DATABLOB = 100 | Parameters such as **iv**.| 70| CRYPTO_AAD_DATABLOB = 101 | Additional authentication data in GCM mode.| 71| CRYPTO_TAG_DATABLOB = 102 | Output tag of the encryption operation, which is used for integrity check.| 72 73 74## Function Description 75 76### OH_CryptoSymCipherParams_Create() 77 78``` 79OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params) 80``` 81 82**Description** 83 84Creates a symmetric encryption/decryption parameter instance. 85 86**Since**: 12 87 88 89**Parameters** 90 91| Name| Description| 92| -- | -- | 93| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) **params | Pointer to the symmetric encryption/decryption parameter instance.| 94 95**Returns** 96 97| Type| Description| 98| -- | -- | 99| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 100 101### OH_CryptoSymCipherParams_SetParam() 102 103``` 104OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params,CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value) 105``` 106 107**Description** 108 109Sets symmetric encryption/decryption parameters. 110 111**Since**: 12 112 113 114**Parameters** 115 116| Name| Description| 117| -- | -- | 118| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the symmetric encryption/decryption parameter instance.| 119| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) paramsType | Name of the parameter to set.| 120| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *value | Pointer to the parameter value set.| 121 122**Returns** 123 124| Type| Description| 125| -- | -- | 126| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 127 128### OH_CryptoSymCipherParams_Destroy() 129 130``` 131void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params) 132``` 133 134**Description** 135 136Destroys a symmetric encryption/decryption parameter instance. 137 138**Since**: 12 139 140 141**Parameters** 142 143| Name| Description| 144| -- | -- | 145| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the symmetric encryption/decryption parameter instance.| 146 147### OH_CryptoSymCipher_Create() 148 149``` 150OH_Crypto_ErrCode OH_CryptoSymCipher_Create(const char *algoName, OH_CryptoSymCipher **ctx) 151``` 152 153**Description** 154 155Creates a symmetric encryption/decryption instance based on the given algorithm name. 156 157**Since**: 12 158 159 160**Parameters** 161 162| Name| Description| 163| -- | -- | 164| const char *algoName | Pointer to the algorithm used to generate a cipher instance.<br> For example, **'AES128\|GCM\|PKCS7'**.| | | 165| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) **ctx | Pointer to the symmetric cipher instance created.| 166 167**Returns** 168 169| Type| Description| 170| -- | -- | 171| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 172 173### OH_CryptoSymCipher_Init() 174 175``` 176OH_Crypto_ErrCode OH_CryptoSymCipher_Init(OH_CryptoSymCipher *ctx, Crypto_CipherMode mod,OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params) 177``` 178 179**Description** 180 181Initializes a symmetric encryption/decryption instance. 182 183**Since**: 12 184 185 186**Parameters** 187 188| Name| Description| 189| -- | -- | 190| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric key cipher instance.| 191| [Crypto_CipherMode](capi-crypto-common-h.md#crypto_ciphermode) mod | Operation to perform, encryption or decryption.| 192| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *key | Pointer to the symmetric key.| 193| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the parameters for encryption or decryption.| 194 195**Returns** 196 197| Type| Description| 198| -- | -- | 199| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 200 201**Reference** 202 203[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update) 204 205[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final) 206 207 208### OH_CryptoSymCipher_Update() 209 210``` 211OH_Crypto_ErrCode OH_CryptoSymCipher_Update(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out) 212``` 213 214**Description** 215 216Updates the data to be encrypted or decrypted. 217 218**Since**: 12 219 220 221**Parameters** 222 223| Name| Description| 224| -- | -- | 225| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.| 226| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the data to be encrypted or decrypted.| 227| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the data updated.| 228 229**Returns** 230 231| Type| Description| 232| -- | -- | 233| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 234 235**Reference** 236 237[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init) 238 239[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final) 240 241 242### OH_CryptoSymCipher_Final() 243 244``` 245OH_Crypto_ErrCode OH_CryptoSymCipher_Final(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out) 246``` 247 248**Description** 249 250Outputs the remaining data (generated by the block cipher mode) and finishes the encryption or decryption operation. 251 252**Since**: 12 253 254 255**Parameters** 256 257| Name| Description| 258| -- | -- | 259| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric key cipher instance.| 260| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the data to be encrypted or decrypted.| 261| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the remaining data encrypted or decrypted.| 262 263**Returns** 264 265| Type| Description| 266| -- | -- | 267| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 268 269**Reference** 270 271[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init) 272 273[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update) 274 275 276### OH_CryptoSymCipher_GetAlgoName() 277 278``` 279const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx) 280``` 281 282**Description** 283 284Obtains the symmetric encryption/decryption algorithm. 285 286**Since**: 12 287 288 289**Parameters** 290 291| Name| Description| 292| -- | -- | 293| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.| 294 295**Returns** 296 297| Type| Description| 298| -- | -- | 299| const char * | Symmetric key encryption algorithm obtained.| 300 301### OH_CryptoSymCipher_Destroy() 302 303``` 304void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx) 305``` 306 307**Description** 308 309Destroys a symmetric encryption/decryption instance. 310 311**Since**: 12 312 313 314**Parameters** 315 316| Name| Description| 317| -- | -- | 318| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.| 319