# crypto_sym_cipher.h

<!--Kit: Crypto Architecture Kit-->
<!--Subsystem: Security-->
<!--Owner: @zxz--3-->
<!--Designer: @lanming-->
<!--Tester: @PAFT-->
<!--Adviser: @zengyawen-->

## Overview

Defines APIs for encrypting and decrypting symmetric keys.

**Header file**: <CryptoArchitectureKit/crypto_sym_cipher.h>

**Library**: libohcrypto.so

**System capability**: SystemCapability.Security.CryptoFramework

**Since**: 12

**Related module**: [CryptoSymCipherApi](capi-cryptosymcipherapi.md)

## Summary

### Structs

| Name| typedef Keyword| Description|
| -- | -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) | OH_CryptoSymCipher | Defines a symmetric encryption and decryption instance.|
| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) | OH_CryptoSymCipherParams | Defines symmetric encryption and decryption parameters.|

### Enums

| Name| typedef Keyword| Description|
| -- | -- | -- |
| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) | CryptoSymCipher_ParamsType | Enumerates the types of symmetric encryption and decryption parameters.|

### Functions

| Name| Description|
| -- | -- |
| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params)](#oh_cryptosymcipherparams_create) | Creates a symmetric encryption/decryption parameter instance.|
| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params,CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value)](#oh_cryptosymcipherparams_setparam) | Sets symmetric encryption/decryption parameters.|
| [void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params)](#oh_cryptosymcipherparams_destroy) | Destroys a symmetric encryption/decryption parameter instance.|
| [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.|
| [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.|
| [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.|
| [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.|
| [const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_getalgoname) | Obtains the symmetric encryption/decryption algorithm.|
| [void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_destroy) | Destroys a symmetric encryption/decryption instance.|

## Enum Description

### CryptoSymCipher_ParamsType

```
enum CryptoSymCipher_ParamsType
```

**Description**

Enumerates the types of symmetric encryption and decryption parameters.

**Since**: 12

| Enum Item| Description|
| -- | -- |
| CRYPTO_IV_DATABLOB = 100 | Parameters such as **iv**.|
| CRYPTO_AAD_DATABLOB = 101 | Additional authentication data in GCM mode.|
| CRYPTO_TAG_DATABLOB = 102 | Output tag of the encryption operation, which is used for integrity check.|


## Function Description

### 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|
| -- | -- |
| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) **params | Pointer to the symmetric encryption/decryption parameter instance.|

**Returns**

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

### OH_CryptoSymCipherParams_SetParam()

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

**Description**

Sets symmetric encryption/decryption parameters.

**Since**: 12


**Parameters**

| Name| Description|
| -- | -- |
| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the symmetric encryption/decryption parameter instance.|
| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) paramsType | Name of the parameter to set.|
| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *value | Pointer to the parameter value set.|

**Returns**

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

### OH_CryptoSymCipherParams_Destroy()

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

**Description**

Destroys a symmetric encryption/decryption parameter instance.

**Since**: 12


**Parameters**

| Name| Description|
| -- | -- |
| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the symmetric encryption/decryption parameter instance.|

### OH_CryptoSymCipher_Create()

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

**Description**

Creates a symmetric encryption/decryption instance based on the given algorithm name.

**Since**: 12


**Parameters**

| Name| Description|
| -- | -- |
| const char *algoName | Pointer to the algorithm used to generate a cipher instance.<br> For example, **'AES128\|GCM\|PKCS7'**.| | |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) **ctx | Pointer to the symmetric cipher instance created.|

**Returns**

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

### 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 encryption/decryption instance.

**Since**: 12


**Parameters**

| Name| Description|
| -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric key cipher instance.|
| [Crypto_CipherMode](capi-crypto-common-h.md#crypto_ciphermode) mod | Operation to perform, encryption or decryption.|
| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *key | Pointer to the symmetric key.|
| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | Pointer to the parameters for encryption or decryption.|

**Returns**

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

**Reference**

[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update)

[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final)


### 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|
| -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.|
| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the data to be encrypted or decrypted.|
| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the data updated.|

**Returns**

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

**Reference**

[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init)

[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final)


### 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|
| -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric key cipher instance.|
| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the data to be encrypted or decrypted.|
| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the remaining data encrypted or decrypted.|

**Returns**

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

**Reference**

[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|
| -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.|

**Returns**

| Type| Description|
| -- | -- |
| const char * | Symmetric key encryption algorithm obtained.|

### OH_CryptoSymCipher_Destroy()

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

**Description**

Destroys a symmetric encryption/decryption instance.

**Since**: 12


**Parameters**

| Name| Description|
| -- | -- |
| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | Pointer to the symmetric cipher instance to destroy.|