1# Encryption and Decryption with an AES Symmetric Key (GCM Mode) (C/C++)
2
3
4For details about the algorithm specifications, see [AES](crypto-sym-encrypt-decrypt-spec.md#aes).
5
6
7## Adding the Dynamic Library in the CMake Script
8```txt
9   target_link_libraries(entry PUBLIC libohcrypto.so)
10```
11
12## How to Develop
13
14**Encryption**
15
16
171. Use [OH_CryptoSymKeyGenerator_Create](../../reference/apis-crypto-architecture-kit/_crypto_sym_key_api.md#oh_cryptosymkeygenerator_create) and [OH_CryptoSymKeyGenerator_Generate](../../reference/apis-crypto-architecture-kit/_crypto_sym_key_api.md#oh_cryptosymkeygenerator_generate) to generate a 128-bit AES symmetric key (**OH_CryptoSymKey**).
18
19   In addition to the example in this topic, [AES](crypto-sym-key-generation-conversion-spec.md#aes) and [Randomly Generating a Symmetric Key](crypto-generate-sym-key-randomly-ndk.md) may help you better understand how to generate an AES symmetric key. Note that the input parameters in the reference documents may be different from those in the example below.
20
212. Use [OH_CryptoSymCipher_Create](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_create) with the string parameter **'AES128|GCM|PKCS7'** to create a **Cipher** instance. The key type is **AES128**, block cipher mode is **GCM**, and the padding mode is **PKCS7**.
22
233. Use [OH_CryptoSymCipherParams_Create](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipherparams_create) to create a symmetric cipher parameter instance, and use [OH_CryptoSymCipherParams_SetParam](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipherparams_setparam) to set cipher parameters.
24
254. Use [OH_CryptoSymCipher_Init](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_init) to initialize the **Cipher** instance. Specifically, set **mode** to **CRYPTO_ENCRYPT_MODE**, and specify the key for encryption (**OH_CryptoSymKey**) and the encryption parameter instance (**OH_CryptoSymCipherParams**) corresponding to the GCM mode.
26
275. Use [OH_CryptoSymCipher_Update](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_update) to update the data (plaintext) to be encrypted.
28
29   Currently, the amount of data to be passed in by a single **update()** is not limited. You can determine how to pass in data based on the data volume.
30
31   - If a small amount of data is to be encrypted, you can use **OH_CryptoSymCipher_Final()** immediately after **OH_CryptoSymCipher_Init()**.
32   - If a large amount of data is to be encrypted, you can call **OH_CryptoSymCipher_Update()** multiple times to pass in the data by segment.
33
346. Use [OH_CryptoSymCipher_Final](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_final) to generate the ciphertext.
35   - If data has been passed in by **OH_CryptoSymCipher_Update()**, pass in **null** in the **data** parameter of **OH_CryptoSymCipher_Final**.
36   - The output of **OH_CryptoSymCipher_Final** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data.
37
387. Use [OH_CryptoSymCipherParams_Create](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipherparams_create) to create a **Params** instance, and use [OH_CryptoSymCipherParams_SetParam](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipherparams_setparam) to set **authTag** as the authentication information for decryption.
39   In GCM mode, extract the last 16 bytes from the encrypted data as the authentication information for initializing the **Cipher** instance in decryption. In the example, **authTag** is of 16 bytes.
40
418. Use [OH_CryptoSymKeyGenerator_Destroy](../../reference/apis-crypto-architecture-kit/_crypto_sym_key_api.md#oh_cryptosymkeygenerator_destroy), [OH_CryptoSymCipher_Destroy](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_destroy), and [OH_CryptoSymCipherParams_Destroy](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipherparams_destroy) to destroy the instances created.
42
43
44**Decryption**
45
46
471. Use [OH_CryptoSymCipher_Init](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_init) to initialize the **Cipher** instance. Specifically, set **mode** to **CRYPTO_DECRYPT_MODE**, and specify the key for decryption (**OH_CryptoSymKey**) and the decryption parameter instance (**OH_CryptoSymCipherParams**) corresponding to the GCM mode.
48
492. Use [OH_CryptoSymCipher_Update](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_update) to update the data (ciphertext) to be decrypted.
50
513. Use [OH_CryptoSymCipher_Final](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_final) to generate the plaintext.
52
53
54**Example **
55
56```c++
57#include "CryptoArchitectureKit/crypto_common.h"
58#include "CryptoArchitectureKit/crypto_sym_cipher.h"
59#include <string.h>
60
61static OH_Crypto_ErrCode doTestAesGcm()
62{
63    OH_CryptoSymKeyGenerator *genCtx = nullptr;
64    OH_CryptoSymCipher *encCtx = nullptr;
65    OH_CryptoSymCipher *decCtx = nullptr;
66    OH_CryptoSymKey *keyCtx = nullptr;
67    OH_CryptoSymCipherParams *params = nullptr;
68
69    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
70    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};
71
72    uint8_t aad[8] = {1, 2, 3, 4, 5, 6, 7, 8};
73    uint8_t tag[16] = {0};
74    uint8_t iv[12] = {1, 2, 4, 12, 3, 4, 2, 3, 3, 2, 0, 4}; // iv is generated from an array of secure random numbers.
75    Crypto_DataBlob ivData = {.data = iv, .len = sizeof(iv)};
76    Crypto_DataBlob aadData = {.data = aad, .len = sizeof(aad)};
77    Crypto_DataBlob tagData = {.data = tag, .len = sizeof(tag)};
78    Crypto_DataBlob tagOutPut = {.data = nullptr, .len = 0};
79    char *plainText = const_cast<char *>("this is test!");
80    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};
81
82    // Generate a symmetric key.
83    OH_Crypto_ErrCode ret;
84    ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
85    if (ret != CRYPTO_SUCCESS) {
86        goto end;
87    }
88    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
89    if (ret != CRYPTO_SUCCESS) {
90        goto end;
91    }
92
93    // Set parameters.
94    ret = OH_CryptoSymCipherParams_Create(&params);
95    if (ret != CRYPTO_SUCCESS) {
96        goto end;
97    }
98    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivData);
99    if (ret != CRYPTO_SUCCESS) {
100        goto end;
101    }
102    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_AAD_DATABLOB, &aadData);
103    if (ret != CRYPTO_SUCCESS) {
104        goto end;
105    }
106    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagData);
107    if (ret != CRYPTO_SUCCESS) {
108        goto end;
109    }
110
111      // Encrypt data.
112    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &encCtx);
113    if (ret != CRYPTO_SUCCESS) {
114        goto end;
115    }
116    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
117    if (ret != CRYPTO_SUCCESS) {
118        goto end;
119    }
120    ret = OH_CryptoSymCipher_Update(encCtx, &msgBlob, &outUpdate);
121    if (ret != CRYPTO_SUCCESS) {
122        goto end;
123    }
124    ret = OH_CryptoSymCipher_Final(encCtx, nullptr, &tagOutPut);
125    if (ret != CRYPTO_SUCCESS) {
126        goto end;
127    }
128
129    // Decrypt data.
130    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &decCtx);
131    if (ret != CRYPTO_SUCCESS) {
132        goto end;
133    }
134    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagOutPut);
135    if (ret != CRYPTO_SUCCESS) {
136        goto end;
137    }
138    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
139    if (ret != CRYPTO_SUCCESS) {
140        goto end;
141    }
142    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
143    if (ret != CRYPTO_SUCCESS) {
144        goto end;
145    }
146
147end:
148    OH_CryptoSymCipherParams_Destroy(params);
149    OH_CryptoSymCipher_Destroy(encCtx);
150    OH_CryptoSymCipher_Destroy(decCtx);
151    OH_CryptoSymKeyGenerator_Destroy(genCtx);
152    OH_CryptoSymKey_Destroy(keyCtx);
153    OH_Crypto_FreeDataBlob(&outUpdate);
154    OH_Crypto_FreeDataBlob(&decUpdate);
155    OH_Crypto_FreeDataBlob(&tagOutPut);
156    return ret;
157}
158```
159