• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Encryption and Decryption with an AES Symmetric Key (CCM 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|CCM'** to create a **Cipher** instance. The key type is AES128, and the block cipher mode is CCM.
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 CCM 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 **OH_CryptoSymCipher_Update** is not limited. You can determine how to pass in data based on the data volume.
30
31   The CCM mode does not support segment-based encryption and decryption.
32
336. Use [OH_CryptoSymCipher_Final](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_final) to generate the ciphertext.
34   - If data has been passed in by **OH_CryptoSymCipher_Update**, pass in **null** in the **data** parameter of **OH_CryptoSymCipher_Final**.
35   - The output of **OH_CryptoSymCipher_Final** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data.
36
377. 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.
38
39   In CCM mode, extract the last 12 bytes from the encrypted data as the authentication information for initializing the **Cipher** instance in decryption. In the example, **authTag** is of 12 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**Decryption**
44
45
461. 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 CCM mode.
47
482. Use [OH_CryptoSymCipher_Final](../../reference/apis-crypto-architecture-kit/_crypto_sym_cipher_api.md#oh_cryptosymcipher_final) to generate the plaintext.
49
50**Example **
51
52```c++
53#include "CryptoArchitectureKit/crypto_common.h"
54#include "CryptoArchitectureKit/crypto_sym_cipher.h"
55#include <string.h>
56
57static OH_Crypto_ErrCode doTestAesCcm()
58{
59    OH_CryptoSymKeyGenerator *genCtx = nullptr;
60    OH_CryptoSymCipher *encCtx = nullptr;
61    OH_CryptoSymCipher *decCtx = nullptr;
62    OH_CryptoSymKey *keyCtx = nullptr;
63    OH_CryptoSymCipherParams *params = nullptr;
64
65    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
66    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};
67
68    uint8_t aad[8] = {1, 2, 3, 4, 5, 6, 7, 8};
69    uint8_t tag[12] = {0};
70    uint8_t iv[7] = {1, 2, 4, 12, 3, 4, 2}; // iv is generated from an array of secure random numbers.
71    Crypto_DataBlob ivData = {.data = iv, .len = sizeof(iv)};
72    Crypto_DataBlob aadData = {.data = aad, .len = sizeof(aad)};
73    Crypto_DataBlob tagData = {.data = tag, .len = sizeof(tag)};
74    Crypto_DataBlob tagOutPut = {.data = nullptr, .len = 0};
75    char *plainText = const_cast<char *>("this is test!");
76    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};
77    // Generate a symmetric key.
78    OH_Crypto_ErrCode ret;
79    ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
80    if (ret != CRYPTO_SUCCESS) {
81        goto end;
82    }
83    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
84    if (ret != CRYPTO_SUCCESS) {
85        goto end;
86    }
87
88    // Set parameters.
89    ret = OH_CryptoSymCipherParams_Create(&params);
90    if (ret != CRYPTO_SUCCESS) {
91        goto end;
92    }
93    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivData);
94    if (ret != CRYPTO_SUCCESS) {
95        goto end;
96    }
97    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_AAD_DATABLOB, &aadData);
98    if (ret != CRYPTO_SUCCESS) {
99        goto end;
100    }
101    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagData);
102    if (ret != CRYPTO_SUCCESS) {
103        goto end;
104    }
105
106    // Encrypt data.
107    ret = OH_CryptoSymCipher_Create("AES128|CCM", &encCtx);
108    if (ret != CRYPTO_SUCCESS) {
109        goto end;
110    }
111    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
112    if (ret != CRYPTO_SUCCESS) {
113        goto end;
114    }
115    ret = OH_CryptoSymCipher_Update(encCtx, &msgBlob, &outUpdate);
116    if (ret != CRYPTO_SUCCESS) {
117        goto end;
118    }
119    ret = OH_CryptoSymCipher_Final(encCtx, nullptr, &tagOutPut);
120    if (ret != CRYPTO_SUCCESS) {
121        goto end;
122    }
123
124    // Decrypt data.
125    ret = OH_CryptoSymCipher_Create("AES128|CCM", &decCtx);
126    if (ret != CRYPTO_SUCCESS) {
127        goto end;
128    }
129    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagOutPut);
130    if (ret != CRYPTO_SUCCESS) {
131        goto end;
132    }
133    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
134    if (ret != CRYPTO_SUCCESS) {
135        goto end;
136    }
137    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
138    if (ret != CRYPTO_SUCCESS) {
139        goto end;
140    }
141
142end:
143    OH_CryptoSymCipherParams_Destroy(params);
144    OH_CryptoSymCipher_Destroy(encCtx);
145    OH_CryptoSymCipher_Destroy(decCtx);
146    OH_CryptoSymKeyGenerator_Destroy(genCtx);
147    OH_CryptoSymKey_Destroy(keyCtx);
148    OH_Crypto_FreeDataBlob(&outUpdate);
149    OH_Crypto_FreeDataBlob(&decUpdate);
150    OH_Crypto_FreeDataBlob(&tagOutPut);
151    return ret;
152}
153```
154