# CryptoSymCipherApi


## Overview

Provides APIs for symmetric key encryption and decryption.

**Since**: 12


## Summary


### Files

| Name | Description |
| -------- | -------- |
| [crypto_sym_cipher.h](crypto__sym__cipher_8h.md) | Defines APIs for symmetric encryption and decryption. |


### Types

| Name | Description |
| -------- | -------- |
| typedef struct [OH_CryptoSymCipher](#oh_cryptosymcipher) [OH_CryptoSymCipher](#oh_cryptosymcipher) | Defines a symmetric encryption and decryption instance. |
| typedef struct [OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) [OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) | Defines symmetric encryption and decryption parameters. |


### Enums

| Name | Description |
| -------- | -------- |
| [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. |


### Functions

| Name | Description |
| -------- | -------- |
| [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. |
| [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. |
| void [OH_CryptoSymCipherParams_Destroy](#oh_cryptosymcipherparams_destroy) ([OH_CryptoSymCipherParams](#oh_cryptosymcipherparams) \*params) | Destroys a symmetric encryption/decryption parameter instance. |
| [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. |
| [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. |
| [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. |
| [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. |
| const char \* [OH_CryptoSymCipher_GetAlgoName](#oh_cryptosymcipher_getalgoname) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx) | Obtains the symmetric encryption/decryption algorithm. |
| void [OH_CryptoSymCipher_Destroy](#oh_cryptosymcipher_destroy) ([OH_CryptoSymCipher](#oh_cryptosymcipher) \*ctx) | Destroys a symmetric cipher instance. |


## Type Description


### OH_CryptoSymCipher

```
typedef struct OH_CryptoSymCipherOH_CryptoSymCipher
```

**Description**

Defines a symmetric encryption and decryption instance.

**Since**: 12


### OH_CryptoSymCipherParams

```
typedef struct OH_CryptoSymCipherParamsOH_CryptoSymCipherParams
```

**Description**

Defines symmetric encryption and decryption parameters.

**Since**: 12


## Enum Description


### CryptoSymCipher_ParamsType

```
enum CryptoSymCipher_ParamsType
```

**Description**

Enumerates the types of symmetric encryption and decryption parameters.

**Since**: 12

| Enum | Description |
| -------- | -------- |
| CRYPTO_IV_DATABLOB | Initialization vector (IV). |
| CRYPTO_AAD_DATABLOB | Additional authentication data (AAD). |
| CRYPTO_TAG_DATABLOB | authTag. |


## Function Description


### OH_CryptoSymCipher_Create()

```
OH_Crypto_ErrCode OH_CryptoSymCipher_Create (const char *algoName, OH_CryptoSymCipher **ctx )
```

**Description**

Creates a symmetric cipher instance based on the given algorithm name.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| algoName | Pointer to the algorithm used to create a symmetric cipher instance. For example, **'AES128\|GCM\|PKCS7'**.| |  |
| ctx | Pointer to the symmetric cipher instance created. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.


### OH_CryptoSymCipher_Destroy()

```
void OH_CryptoSymCipher_Destroy (OH_CryptoSymCipher *ctx)
```

**Description**

Destroys a symmetric cipher instance.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| ctx | Pointer to the symmetric cipher instance to destroy. |


### OH_CryptoSymCipher_Final()

```
OH_Crypto_ErrCode OH_CryptoSymCipher_Final (OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out )
```

**Description**

Outputs the remaining data (generated by the block cipher mode) and finishes the encryption or decryption operation.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| ctx | Pointer to the symmetric cipher instance. |
| in | Pointer to the data to be encrypted or decrypted. |
| out | Pointer to the remaining data encrypted or decrypted. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.

**See**

[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init)

[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update)


### OH_CryptoSymCipher_GetAlgoName()

```
const char* OH_CryptoSymCipher_GetAlgoName (OH_CryptoSymCipher *ctx)
```

**Description**

Obtains the symmetric encryption/decryption algorithm.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| ctx | Pointer to the symmetric cipher instance. |

**Returns**

Symmetric encryption/decryption algorithm obtained.


### OH_CryptoSymCipher_Init()

```
OH_Crypto_ErrCode OH_CryptoSymCipher_Init (OH_CryptoSymCipher *ctx, Crypto_CipherMode mod, OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params )
```

**Description**

Initializes a symmetric cipher instance.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| ctx | Pointer to the symmetric cipher instance. |
| mod | Operation to perform, encryption or decryption. |
| key | Pointer to the symmetric key. |
| params | Pointer to the parameters for encryption or decryption. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.


### OH_CryptoSymCipher_Update()

```
OH_Crypto_ErrCode OH_CryptoSymCipher_Update (OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out )
```

**Description**

Updates the data to be encrypted or decrypted.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| ctx | Pointer to the symmetric cipher instance. |
| in | Data to be encrypted or decrypted. |
| out | Pointer to the data updated. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.


### OH_CryptoSymCipherParams_Create()

```
OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create (OH_CryptoSymCipherParams **params)
```

**Description**

Creates a symmetric encryption/decryption parameter instance.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| params | Pointer to the symmetric encryption/decryption parameter instance. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.


### OH_CryptoSymCipherParams_Destroy()

```
void OH_CryptoSymCipherParams_Destroy (OH_CryptoSymCipherParams *params)
```

**Description**

Destroys a symmetric encryption/decryption parameter instance.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| params | Pointer to the symmetric encryption/decryption parameter instance. |


### OH_CryptoSymCipherParams_SetParam()

```
OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam (OH_CryptoSymCipherParams *params, CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value )
```

**Description**

Sets a symmetric encryption/decryption parameter.

**Since**: 12

**Parameters**

| Name | Description |
| -------- | -------- |
| params | Pointer to the symmetric encryption/decryption parameter instance. |
| paramsType | Name of the parameter to set. |
| value | Pointer to the parameter value set. |

**Returns**

[OH_Crypto_ErrCode](_crypto_common_api.md#oh_crypto_errcode):

**0**: The operation is successful.

**401**: Invalid parameters are detected.

**801**: The operation is not supported.

**17620001**: A memory error occurred.

**17630001**: Failed to call an API of a third-party algorithm library.