目录

使用AES对称密钥加解密(C/C++)

对应的算法规格请查看对称密钥加解密算法规格:AES。

在CMake脚本中链接相关动态库

target_link_libraries(entry PUBLIC libohcrypto.so)

开发步骤

[h2]使用AES对称密钥(GCM模式)加解密

加密

  1. 调用OH_CryptoSymKeyGenerator_Create和OH_CryptoSymKeyGenerator_Generate,生成密钥算法为AES、密钥长度为128位的对称密钥(OH_CryptoSymKey)。

    生成AES对称密钥,参考以下示例,并结合对称密钥生成和转换规格:AES和随机生成对称密钥理解。注意,参考文档与示例可能有入参差异。

  2. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|GCM|PKCS7',创建对称密钥类型为AES128、分组模式为GCM、填充模式为PKCS7的Cipher实例,用于完成加密操作。

  3. 调用OH_CryptoSymCipherParams_Create创建参数对象,调用OH_CryptoSymCipherParams_SetParam设置对应的加密参数。

  4. 调用OH_CryptoSymCipher_Init,设置模式为加密(CRYPTO_ENCRYPT_MODE),指定对称密钥(OH_CryptoSymKey)和GCM模式对应的加密参数(OH_CryptoSymCipherParams),以初始化加密Cipher实例。

  5. 调用OH_CryptoSymCipher_Update,更新数据(明文)。

    当前单次update长度没有限制,开发者可以根据数据量判断如何调用update。

    • 当数据量较小时,可以在init完成后直接调用final。
    • 当数据量较大时,可以多次调用update,即分段加解密。
  6. 调用OH_CryptoSymCipher_Final,获取加密后的数据。

    • 由于已使用update传入数据,此处data传入null。
    • final输出结果可能为null,在访问具体数据前,需要先判断结果是否为null,避免产生异常。

    在GCM模式下,一次加密流程中,将每次update和最后final的结果拼接起来,会得到“密文 + authTag”,authTag为末尾的16字节。其余部分均为密文。如果final的data参数传入null,则final的结果就是authTag。

解密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|GCM|PKCS7',创建对称密钥类型为AES128、分组模式为GCM、填充模式为PKCS7的Cipher实例,用于完成解密操作。

  2. 使用OH_CryptoSymCipherParams_SetParam设置authTag,作为解密的认证信息。

  3. 调用OH_CryptoSymCipher_Init,设置模式为解密(CRYPTO_DECRYPT_MODE),指定解密密钥(OH_CryptoSymKey)和GCM模式对应的解密参数(OH_CryptoSymCipherParams),初始化解密Cipher实例。

  4. 调用OH_CryptoSymCipher_Update,更新数据(密文)。

    • 当数据量较小时,可以在init完成后直接调用final。
    • 当数据量较大时,可以多次调用update,即分段解密。
    • 用户可以根据数据量大小自行决定操作方式。例如,当数据量超过1KB时,使用update。
  5. 调用OH_CryptoSymCipher_Final,获取解密数据。

销毁对象

调用OH_CryptoSymKeyGenerator_Destroy、OH_CryptoSymCipher_Destroy、OH_CryptoSymCipherParams_Destroy销毁对象。

示例如下:

#include "CryptoArchitectureKit/crypto_common.h"
#include "CryptoArchitectureKit/crypto_sym_cipher.h"
#include <cstring>
#include "file.h"

OH_Crypto_ErrCode doTestAesGcm()
{
    OH_CryptoSymKeyGenerator *genCtx = nullptr;
    OH_CryptoSymCipher *encCtx = nullptr;
    OH_CryptoSymCipher *decCtx = nullptr;
    OH_CryptoSymKey *keyCtx = nullptr;
    OH_CryptoSymCipherParams *params = nullptr;

    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};

    uint8_t aad[8] = {1, 2, 3, 4, 5, 6, 7, 8};
    uint8_t tag[16] = {0};
    uint8_t iv[12] = {1, 2, 4, 12, 3, 4, 2, 3, 3, 2, 0, 4}; // iv使用安全随机数生成
    Crypto_DataBlob ivData = {.data = iv, .len = sizeof(iv)};
    Crypto_DataBlob aadData = {.data = aad, .len = sizeof(aad)};
    Crypto_DataBlob tagData = {.data = tag, .len = sizeof(tag)};
    Crypto_DataBlob tagOutPut = {.data = nullptr, .len = 0};
    char *plainText = const_cast<char *>("this is test!");
    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};

    // 生成对称密钥
    OH_Crypto_ErrCode ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 设置参数
    ret = OH_CryptoSymCipherParams_Create(&params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_AAD_DATABLOB, &aadData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 加密
    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &encCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Update(encCtx, &msgBlob, &outUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(encCtx, nullptr, &tagOutPut);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 解密
    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &decCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagOutPut);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

end:
    OH_CryptoSymCipherParams_Destroy(params);
    OH_CryptoSymCipher_Destroy(encCtx);
    OH_CryptoSymCipher_Destroy(decCtx);
    OH_CryptoSymKeyGenerator_Destroy(genCtx);
    OH_CryptoSymKey_Destroy(keyCtx);
    OH_Crypto_FreeDataBlob(&outUpdate);
    OH_Crypto_FreeDataBlob(&decUpdate);
    OH_Crypto_FreeDataBlob(&tagOutPut);
    return ret;
}

[h2]使用AES对称密钥(CCM模式)加解密

创建对象

调用OH_CryptoSymKeyGenerator_Create、OH_CryptoSymKeyGenerator_Generate,生成密钥算法为AES、密钥长度为128位的对称密钥(OH_CryptoSymKey)。

如何生成AES对称密钥,开发者可参考下文示例,并结合对称密钥生成和转换规格:AES和随机生成对称密钥理解,参考文档与当前示例可能存在入参差异,请在阅读时注意区分。

加密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|CCM',创建对称密钥类型为AES128、分组模式为CCM的Cipher实例,用于完成加密操作。

  2. 调用OH_CryptoSymCipherParams_Create创建参数对象,调用OH_CryptoSymCipherParams_SetParam设置对应的加密参数。

  3. 调用OH_CryptoSymCipher_Init,设置模式为加密(CRYPTO_ENCRYPT_MODE),指定加密密钥(OH_CryptoSymKey)和CCM模式对应的加密参数(OH_CryptoSymCipherParams),初始化加密Cipher实例。

  4. 调用OH_CryptoSymCipher_Update,更新数据(明文)。

    当前单次update没有长度限制,根据明文长度判断单次调用update输入的数据长度。

    CCM模式不支持分段加解密。

  5. 调用OH_CryptoSymCipher_Final,获取加密后的数据。

    • 已使用update传入数据,此处data传入null。
    • final输出结果可能为null,访问数据前需先判断结果是否为null。

      在CCM模式下,final设置authTag作为解密时的初始化认证信息,需要保存。

  6. 使用OH_CryptoSymCipherParams_Create创建Params,使用OH_CryptoSymCipherParams_SetParam设置authTag,作为解密的认证信息。

    在CCM模式下,算法库支持12字节的authTag,用于解密时的初始化认证。示例中authTag为12字节。

解密

  1. 调用OH_CryptoSymCipher_Create,指定参数 'AES128|CCM',创建对称密钥类型为AES128、分组模式为CCM的Cipher实例,用于解密操作。

  2. 解密时需使用OH_CryptoSymCipherParams_SetParam设置authTag,作为初始化的认证信息。

  3. 调用OH_CryptoSymCipher_Init,设置模式为解密,指定解密密钥和CCM模式的解密参数,初始化解密Cipher实例。

  4. 调用OH_CryptoSymCipher_Update,更新数据(密文)。

    当前单次update长度没有限制,开发者可以根据密文长度判断单次调用update输入的数据长度。

    CCM模式不支持分段加解密。

    当数据量较小时,可以在init完成后直接调用final。

  5. 调用OH_CryptoSymCipher_Final,获取解密后的数据。

    若使用update传入数据,此处data传入null。

    在访问final输出结果的具体数据前,需要先判断结果是否为null,以避免异常。

销毁对象

调用OH_CryptoSymKeyGenerator_Destroy、OH_CryptoSymCipher_Destroy、OH_CryptoSymKey_Destroy、OH_Crypto_FreeDataBlob释放申请的内存,销毁对称密钥、Cipher实例和Params。

示例如下:

#include "CryptoArchitectureKit/crypto_common.h"
#include "CryptoArchitectureKit/crypto_sym_cipher.h"
#include <cstring>
#include "file.h"

OH_Crypto_ErrCode doTestAesCcm()
{
    OH_CryptoSymKeyGenerator *genCtx = nullptr;
    OH_CryptoSymCipher *encCtx = nullptr;
    OH_CryptoSymCipher *decCtx = nullptr;
    OH_CryptoSymKey *keyCtx = nullptr;
    OH_CryptoSymCipherParams *params = nullptr;

    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};

    uint8_t aad[8] = {1, 2, 3, 4, 5, 6, 7, 8};
    uint8_t tag[12] = {0};
    uint8_t iv[7] = {1, 2, 4, 12, 3, 4, 2}; // iv使用安全随机数生成
    Crypto_DataBlob ivData = {.data = iv, .len = sizeof(iv)};
    Crypto_DataBlob aadData = {.data = aad, .len = sizeof(aad)};
    Crypto_DataBlob tagData = {.data = tag, .len = sizeof(tag)};
    Crypto_DataBlob tagOutPut = {.data = nullptr, .len = 0};
    char *plainText = const_cast<char *>("this is test!");
    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};
    // 生成对称密钥
    OH_Crypto_ErrCode ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 设置参数
    ret = OH_CryptoSymCipherParams_Create(&params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_AAD_DATABLOB, &aadData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagData);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 加密
    ret = OH_CryptoSymCipher_Create("AES128|CCM", &encCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Update(encCtx, &msgBlob, &outUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(encCtx, nullptr, &tagOutPut);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 解密
    ret = OH_CryptoSymCipher_Create("AES128|CCM", &decCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagOutPut);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

end:
    OH_CryptoSymCipherParams_Destroy(params);
    OH_CryptoSymCipher_Destroy(encCtx);
    OH_CryptoSymCipher_Destroy(decCtx);
    OH_CryptoSymKeyGenerator_Destroy(genCtx);
    OH_CryptoSymKey_Destroy(keyCtx);
    OH_Crypto_FreeDataBlob(&outUpdate);
    OH_Crypto_FreeDataBlob(&decUpdate);
    OH_Crypto_FreeDataBlob(&tagOutPut);
    return ret;
}

[h2]使用AES对称密钥(CBC模式)加解密

创建对象

调用OH_CryptoSymKeyGenerator_Create和OH_CryptoSymKeyGenerator_Generate,生成密钥算法为AES、密钥长度为128位的对称密钥(OH_CryptoSymKey)。

如何生成AES对称密钥,请参考以下示例,并结合对称密钥生成和转换规格:AES和随机生成对称密钥理解,参考文档与当前示例可能存在入参差异,请注意区分。

加密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|CBC|PKCS7',创建对称密钥类型为AES128、分组模式为CBC、填充模式为PKCS7的Cipher实例,用于加密操作。

  2. 调用OH_CryptoSymCipherParams_Create创建参数对象,并调用OH_CryptoSymCipherParams_SetParam设置加密参数。

  3. 调用OH_CryptoSymCipher_Init,设置模式为加密(CRYPTO_ENCRYPT_MODE),指定加密密钥(OH_CryptoSymKey)和CBC模式对应的加密参数(OH_CryptoSymCipherParams),初始化加密Cipher实例。

  4. 加密内容较短时,可以直接调用OH_CryptoSymCipher_Final,无需调用OH_CryptoSymCipher_Update,获取加密后的数据。

解密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|CBC|PKCS7',创建对称密钥类型为AES128、分组模式为CBC、填充模式为PKCS7的Cipher实例,用于解密操作。

  2. 调用OH_CryptoSymCipher_Init,设置模式为解密(CRYPTO_DECRYPT_MODE),指定解密密钥(OH_CryptoSymKey)和CBC模式对应的解密参数(OH_CryptoSymCipherParams),初始化解密Cipher实例。

  3. 解密内容较短时,可直接调用OH_CryptoSymCipher_Final,无需调用OH_CryptoSymCipher_Update,获取解密后的数据。

销毁对象

调用OH_CryptoSymKeyGenerator_Destroy、OH_CryptoSymCipher_Destroy、OH_CryptoSymKey_Destroy、OH_Crypto_FreeDataBlob释放申请的内存,销毁对象。

示例如下:

#include "CryptoArchitectureKit/crypto_common.h"
#include "CryptoArchitectureKit/crypto_sym_cipher.h"
#include <cstring>
#include "file.h"

OH_Crypto_ErrCode doTestAesCbc()
{
    OH_CryptoSymKeyGenerator *genCtx = nullptr;
    OH_CryptoSymCipher *encCtx = nullptr;
    OH_CryptoSymCipher *decCtx = nullptr;
    OH_CryptoSymKey *keyCtx = nullptr;
    OH_CryptoSymCipherParams *params = nullptr;
    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};
    char *plainText = const_cast<char *>("this is test!");
    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};
    uint8_t iv[16] = {1, 2, 4, 12, 3, 4, 2, 3, 3, 2, 0, 4, 3, 1, 0, 10}; // iv使用安全随机数生成
    Crypto_DataBlob ivBlob = {.data = iv, .len = sizeof(iv)};
    // 生成对称密钥
    OH_Crypto_ErrCode ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 设置参数
    ret = OH_CryptoSymCipherParams_Create(&params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivBlob);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 加密
    ret = OH_CryptoSymCipher_Create("AES128|CBC|PKCS7", &encCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(encCtx, &msgBlob, &outUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 解密
    ret = OH_CryptoSymCipher_Create("AES128|CBC|PKCS7", &decCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

end:
    OH_CryptoSymCipherParams_Destroy(params);
    OH_CryptoSymCipher_Destroy(encCtx);
    OH_CryptoSymCipher_Destroy(decCtx);
    OH_CryptoSymKeyGenerator_Destroy(genCtx);
    OH_CryptoSymKey_Destroy(keyCtx);
    OH_Crypto_FreeDataBlob(&outUpdate);
    OH_Crypto_FreeDataBlob(&decUpdate);
    return ret;
}

[h2]使用AES对称密钥(ECB模式)加解密

创建对象

调用OH_CryptoSymKeyGenerator_Create和OH_CryptoSymKeyGenerator_Generate,生成AES算法、128位的对称密钥(OH_CryptoSymKey)。

如何生成AES对称密钥,开发者可参考下文示例,并结合对称密钥生成和转换规格:AES和随机生成对称密钥理解,参考文档与当前示例可能存在入参差异,请在阅读时注意区分。

加密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|ECB|PKCS7',创建对称密钥类型为AES128、分组模式为ECB、填充模式为PKCS7的Cipher实例,用于完成加密操作。

  2. 调用OH_CryptoSymCipher_Init,设置模式为加密(CRYPTO_ENCRYPT_MODE),指定加密密钥(OH_CryptoSymKey),初始化加密Cipher实例。ECB模式无需设置额外加密参数,创建空的参数对象传入即可。

  3. 加密内容较短时,可以直接调用OH_CryptoSymCipher_Final获取加密后的数据,无需调用OH_CryptoSymCipher_Update。

解密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|ECB|PKCS7',创建对称密钥类型为AES128、分组模式为ECB、填充模式为PKCS7的Cipher实例,用于解密操作。

  2. 调用OH_CryptoSymCipher_Init,设置模式为解密(CRYPTO_DECRYPT_MODE),指定解密密钥(OH_CryptoSymKey),初始化解密Cipher实例。ECB模式无需设置额外加密参数,创建空的参数对象传入即可。

  3. 当解密内容较短时,可以直接调用OH_CryptoSymCipher_Final获取解密后的数据,无需调用OH_CryptoSymCipher_Update。

销毁对象

调用OH_CryptoSymKeyGenerator_Destroy销毁密钥生成器。调用OH_CryptoSymCipher_Destroy销毁密码对象。

示例如下:

#include "CryptoArchitectureKit/crypto_common.h"
#include "CryptoArchitectureKit/crypto_sym_cipher.h"
#include <cstring>
#include "file.h"

OH_Crypto_ErrCode doTestAesEcb()
{
    OH_CryptoSymKeyGenerator *genCtx = nullptr;
    OH_CryptoSymCipher *encCtx = nullptr;
    OH_CryptoSymCipher *decCtx = nullptr;
    OH_CryptoSymKey *keyCtx = nullptr;
    OH_CryptoSymCipherParams *params = nullptr;
    char *plainText = const_cast<char *>("this is test");
    Crypto_DataBlob input = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};
    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};

    // 随机生成对称密钥
    OH_Crypto_ErrCode ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    // 创建参数
    ret = OH_CryptoSymCipherParams_Create(&params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 加密操作
    ret = OH_CryptoSymCipher_Create("AES128|ECB|PKCS7", &encCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(encCtx, &input, &outUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 解密操作
    ret = OH_CryptoSymCipher_Create("AES128|ECB|PKCS7", &decCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(decCtx, &outUpdate, &decUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

end:
    OH_CryptoSymCipherParams_Destroy(params);
    OH_CryptoSymCipher_Destroy(encCtx);
    OH_CryptoSymCipher_Destroy(decCtx);
    OH_CryptoSymKeyGenerator_Destroy(genCtx);
    OH_CryptoSymKey_Destroy(keyCtx);
    OH_Crypto_FreeDataBlob(&outUpdate);
    OH_Crypto_FreeDataBlob(&decUpdate);
    return ret;
}

[h2]使用AES对称密钥(GCM模式)分段加解密

创建对象

调用OH_CryptoSymKeyGenerator_Create和OH_CryptoSymKeyGenerator_Generate,生成密钥算法为AES、密钥长度为128位的对称密钥(OH_CryptoSymKey)。

如何生成AES对称密钥,开发者可参考下文示例,并结合对称密钥生成和转换规格:AES和随机生成对称密钥文档进行理解。参考文档与当前示例可能存在入参差异,请注意区分。

加密

  1. 调用OH_CryptoSymCipher_Create,指定字符串参数'AES128|GCM|PKCS7',创建对称密钥算法为AES128、分组模式为GCM、填充模式为PKCS7的Cipher实例,用于完成加密操作。

  2. 调用OH_CryptoSymCipherParams_Create创建参数对象,调用OH_CryptoSymCipherParams_SetParam设置对应的加密参数。

  3. 调用OH_CryptoSymCipher_Init,设置模式为加密(CRYPTO_ENCRYPT_MODE),指定对称密钥(OH_CryptoSymKey)和GCM模式的加密参数(OH_CryptoSymCipherParams),以初始化加密 Cipher 实例。

  4. 将一次传入数据量设置为20字节,多次调用OH_CryptoSymCipher_Update,更新数据(明文)。

    • 当前单次update没有长度限制,开发者可根据数据量判断如何调用update。

    • 建议开发者对每次update的结果都判断是否为null,并在结果不为null时取出其中的密文进行拼接,形成完整的密文。因为在不同的模式下,update的结果可能会受到不同影响。

      1)例如ECB和CBC模式,始终以分组为基本单位进行加密,并输出本次更新产生的加密分组结果。即当本次更新操作凑满一个分组时,输出密文;若未凑满,则本次更新输出null,将未加密的数据与下次输入的数据拼接后,再进行分组输出。最后进行final操作时,将未加密的数据根据指定的填充模式进行填充,再输出剩余加密结果。解密过程中的update操作同理。

      2)对于流加密模式(比如CTR和OFB模式),通常密文长度和明文长度相等。

  5. 调用OH_CryptoSymCipher_Final,获取密文。

    • 由于已使用update传入数据,此处传入null。
    • final输出结果可能为null,在访问具体数据前,需要先判断结果是否为null,以避免产生异常。

    在GCM模式下,一次加密流程中,将每次update和最后final的结果拼接起来,会得到“密文 + authTag”,authTag为末尾的16字节。其余部分均为密文。如果final的data参数传入null,则final的结果就是authTag。

解密

  1. 调用OH_CryptoSymCipher_Create,指定参数'AES128|GCM|PKCS7',创建对称密钥类型为AES128、分组模式为GCM、填充模式为PKCS7的Cipher实例,完成解密操作。

  2. 调用OH_CryptoSymCipherParams_SetParam设置authTag作为解密的认证信息。

    在GCM模式下,从加密后的数据中取出末尾16字节,作为解密时初始化的认证信息。示例中authTag恰好为16字节。

  3. 调用OH_CryptoSymCipher_Init,设置模式为解密(CRYPTO_DECRYPT_MODE),指定解密密钥(OH_CryptoSymKey)和GCM模式对应的解密参数(OH_CryptoSymCipherParams),初始化解密Cipher实例。

  4. 调用OH_CryptoSymCipher_Final获取解密数据。

销毁对象

调用OH_CryptoSymKeyGenerator_Destroy、OH_CryptoSymCipher_Destroy和OH_CryptoSymCipherParams_Destroy销毁各对象。

示例如下:

#include <cstring>
#include "CryptoArchitectureKit/crypto_common.h"
#include "CryptoArchitectureKit/crypto_sym_cipher.h"
#include "file.h"

#define OH_CRYPTO_GCM_TAG_LEN 16
#define OH_CRYPTO_MAX_TEST_DATA_LEN 128
OH_Crypto_ErrCode doTestAesGcmSeg()
{
    OH_CryptoSymKeyGenerator *genCtx = nullptr;
    OH_CryptoSymCipher *encCtx = nullptr;
    OH_CryptoSymCipher *decCtx = nullptr;
    OH_CryptoSymKey *keyCtx = nullptr;
    OH_CryptoSymCipherParams *params = nullptr;

    char *plainText = const_cast<char *>("aaaaa.....bbbbb.....ccccc.....ddddd.....eee");
    Crypto_DataBlob msgBlob = {.data = (uint8_t *)(plainText), .len = strlen(plainText)};

    uint8_t aad[8] = {1, 2, 3, 4, 5, 6, 7, 8};
    uint8_t tagArr[16] = {0};
    uint8_t iv[12] = {1, 2, 4, 12, 3, 4, 2, 3, 3, 2, 0, 4}; // iv使用安全随机数生成
    Crypto_DataBlob tag = {.data = nullptr, .len = 0};
    Crypto_DataBlob ivBlob = {.data = iv, .len = sizeof(iv)};
    Crypto_DataBlob aadBlob = {.data = aad, .len = sizeof(aad)};
    Crypto_DataBlob outUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob decUpdate = {.data = nullptr, .len = 0};
    Crypto_DataBlob tagInit = {.data = tagArr, .len = sizeof(tagArr)};
    int32_t cipherLen = 0;
    int blockSize = 20;
    int32_t randomLen = strlen(plainText);
    int cnt = randomLen / blockSize;
    int rem = randomLen % blockSize;
    uint8_t cipherText[OH_CRYPTO_MAX_TEST_DATA_LEN] = {0};
    Crypto_DataBlob cipherBlob;
    
    // 生成密钥
    OH_Crypto_ErrCode ret = OH_CryptoSymKeyGenerator_Create("AES128", &genCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymKeyGenerator_Generate(genCtx, &keyCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    
    // 设置参数
    ret = OH_CryptoSymCipherParams_Create(&params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_IV_DATABLOB, &ivBlob);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_AAD_DATABLOB, &aadBlob);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tagInit);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    
    // 加密
    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &encCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(encCtx, CRYPTO_ENCRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    
    for (int i = 0; i < cnt; i++) {
        msgBlob.len = blockSize;
        ret = OH_CryptoSymCipher_Update(encCtx, &msgBlob, &outUpdate);
        if (ret != CRYPTO_SUCCESS) {
            goto end;
        }
        msgBlob.data += blockSize;
        memcpy(&cipherText[cipherLen], outUpdate.data, outUpdate.len);
        cipherLen += outUpdate.len;
        OH_Crypto_FreeDataBlob(&outUpdate);
    }
    if (rem > 0) {
        msgBlob.len = rem;
        ret = OH_CryptoSymCipher_Update(encCtx, (Crypto_DataBlob *)&msgBlob, &outUpdate);
        if (ret != CRYPTO_SUCCESS) {
            goto end;
        }
        memcpy(&cipherText[cipherLen], outUpdate.data, outUpdate.len);
        cipherLen += outUpdate.len;
        OH_Crypto_FreeDataBlob(&outUpdate);
    }
    ret = OH_CryptoSymCipher_Final(encCtx, nullptr, &tag);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

    // 解密
    cipherBlob = {.data = reinterpret_cast<uint8_t *>(cipherText), .len = (size_t)cipherLen};
    msgBlob.data -= strlen(plainText) - rem;
    msgBlob.len = strlen(plainText);
    ret = OH_CryptoSymCipher_Create("AES128|GCM|PKCS7", &decCtx);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipherParams_SetParam(params, CRYPTO_TAG_DATABLOB, &tag);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Init(decCtx, CRYPTO_DECRYPT_MODE, keyCtx, params);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }
    ret = OH_CryptoSymCipher_Final(decCtx, &cipherBlob, &decUpdate);
    if (ret != CRYPTO_SUCCESS) {
        goto end;
    }

end:
    OH_CryptoSymCipherParams_Destroy(params);
    OH_CryptoSymCipher_Destroy(encCtx);
    OH_CryptoSymCipher_Destroy(decCtx);
    OH_CryptoSymKeyGenerator_Destroy(genCtx);
    OH_CryptoSymKey_Destroy(keyCtx);
    OH_Crypto_FreeDataBlob(&outUpdate);
    OH_Crypto_FreeDataBlob(&tag);
    OH_Crypto_FreeDataBlob(&decUpdate);
    return ret;
}