跳转至

security_symc

SYMC (Symmetric Cipher) 提供对称加解密功能,支持单段和分段加解密模式,涵盖 ECB、CBC、CTR、OFB、CFB、CCM、GCM 等工作模式。

头文件清单

#include "include/driver/security_unified/security_symc.h"

接口清单

接口名称 功能简述
uapi_drv_cipher_symc_crypt 单段对称加解密
uapi_drv_cipher_symc_setup 初始化分段加解密上下文句柄
uapi_drv_cipher_symc_ecb_update ECB模式分段加解密
uapi_drv_cipher_symc_cbc_update CBC模式分段加解密
uapi_drv_cipher_symc_ctr_update CTR模式分段加解密
uapi_drv_cipher_symc_ofb_update OFB模式分段加解密
uapi_drv_cipher_symc_cfb8_update CFB8模式分段加解密
uapi_drv_cipher_symc_cfb128_update CFB128模式分段加解密
uapi_drv_cipher_symc_teardown 销毁分段加解密句柄
uapi_drv_cipher_symc_ccm_encrypt CCM加密并计算tag
uapi_drv_cipher_symc_ccm_decrypt_verify CCM解密并校验tag
uapi_drv_cipher_symc_ccm_setup 初始化CCM分段加解密上下文句柄
uapi_drv_cipher_symc_ccm_set_lengths 设置CCM附加数据长度、数据长度和tag长度
uapi_drv_cipher_symc_ccm_update_ad 为CCM增加附加数据
uapi_drv_cipher_symc_ccm_update CCM模式分段加解密
uapi_drv_cipher_symc_ccm_finish CCM获取tag值
uapi_drv_cipher_symc_ccm_teardown CCM销毁句柄
uapi_drv_cipher_symc_gcm_encrypt GCM加密并计算tag
uapi_drv_cipher_symc_gcm_decrypt_verify GCM解密并校验tag
uapi_drv_cipher_symc_gcm_setup 初始化GCM分段加解密上下文句柄
uapi_drv_cipher_symc_gcm_update_ad 为GCM增加附加数据
uapi_drv_cipher_symc_gcm_update GCM模式分段加解密
uapi_drv_cipher_symc_gcm_finish GCM获取tag值
uapi_drv_cipher_symc_gcm_teardown GCM销毁句柄
uapi_drv_cipher_symc_dma_copy DMA数据拷贝

Functions

uapi_drv_cipher_symc_crypt

errcode_t uapi_drv_cipher_symc_crypt(uint32_t alg, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t iv[16], const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, bool is_encrypt
)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 提供单段对称加解密能力,一次调用完成全部数据的加解密操作
  • 通过alg组合值指定加密算法、工作模式和密钥位宽
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uint32_t 组合值,包含算法、工作模式、密钥位宽,可通过 uapi_compat_symc_alg 宏组合 uapi_compat_symc_alg(alg, work_mode, bit_width) 生成
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX,传入0接口返回成功
iv uint8_t[16] 初始向量,输入为初始向量,输出为更新后的向量 ECB模式不需要
key const uint8_t * 对称密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 对称密钥长度,单位Byte 由算法和位宽决定
keyslot_handle uint32_t 保存key的句柄,通过KM模块创建和销毁 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
is_encrypt bool 是否加密 true/false

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
iv uint8_t[16] 更新后的向量(非ECB模式)

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_setup

errcode_t uapi_drv_cipher_symc_setup(cipher_handle_t *ctx, uint32_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, bool is_encrypt
)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 初始化分段加解密的上下文句柄,用于后续多段update操作
  • 通过alg组合值指定加密算法、工作模式和密钥位宽
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uint32_t 组合值,包含算法、工作模式、密钥位宽 uapi_compat_symc_alg(alg, work_mode, bit_width) 生成
key const uint8_t * 对称密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 对称密钥长度,单位Byte 由算法和位宽决定
keyslot_handle uint32_t 保存key的句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
is_encrypt bool 是否加密 true/false

出参

名称 数据类型 输出说明
ctx cipher_handle_t * 创建的加解密句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ecb_update

errcode_t uapi_drv_cipher_symc_ecb_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • ECB模式下的分段加解密操作
  • 需配合uapi_drv_cipher_symc_setup初始化的上下文句柄使用
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_cbc_update

errcode_t uapi_drv_cipher_symc_cbc_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t iv[16])

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CBC模式下的分段加解密操作
  • 支持初始向量的输入与更新输出
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
iv uint8_t[16] 输入为初始向量,输出为更新后的向量 16字节

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
iv uint8_t[16] 更新后的向量

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ctr_update

errcode_t uapi_drv_cipher_symc_ctr_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t nonce_counter[16], uint8_t *nc_off, uint8_t stream_block[16])

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CTR模式下的分段加解密操作
  • 支持nonce_counter、nc_off和stream_block的输入与更新输出
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄
  • 上下文限制:nc_off初始值应为0

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
nonce_counter uint8_t[16] 输入为初始128位nonce和counter,输出为更新后的值 16字节
nc_off uint8_t * 在当前stream_block中的偏移量 流开始时为0

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
nonce_counter uint8_t[16] 更新后的128位nonce和counter
nc_off uint8_t * 更新后的偏移量
stream_block uint8_t[16] 更新后的当前stream_block

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ofb_update

errcode_t uapi_drv_cipher_symc_ofb_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t iv[16], uint8_t *iv_off)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • OFB模式下的分段加解密操作
  • 支持初始向量和iv偏移量的输入与更新输出
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
iv uint8_t[16] 输入为初始向量,输出为更新后的向量 16字节
iv_off uint8_t * 在当前iv中的偏移量 用于恢复计算

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
iv uint8_t[16] 更新后的向量
iv_off uint8_t * 更新后的偏移量

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_cfb8_update

errcode_t uapi_drv_cipher_symc_cfb8_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t iv[16], uint8_t *iv_off)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CFB8模式下的分段加解密操作
  • 支持初始向量和iv偏移量的输入与更新输出
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
iv uint8_t[16] 输入为初始向量,输出为更新后的向量 16字节
iv_off uint8_t * 在当前iv中的偏移量 用于恢复计算

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
iv uint8_t[16] 更新后的向量
iv_off uint8_t * 更新后的偏移量

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_cfb128_update

errcode_t uapi_drv_cipher_symc_cfb128_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len,
    uint8_t iv[16], uint8_t *iv_off)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CFB128模式下的分段加解密操作
  • 支持初始向量和iv偏移量的输入与更新输出
  • 传入数据长度为0时接口返回成功

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
iv uint8_t[16] 输入为初始向量,输出为更新后的向量 16字节
iv_off uint8_t * 在当前iv中的偏移量 用于恢复计算

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出
iv uint8_t[16] 更新后的向量
iv_off uint8_t * 更新后的偏移量

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_teardown

errcode_t uapi_drv_cipher_symc_teardown(cipher_handle_t ctx)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 销毁分段加解密上下文句柄,释放相关资源
  • 销毁后句柄不可再使用

前置条件

  • 调用时序约束:需在分段加解密操作全部完成后调用,当前接口需要在uapi_drv_cipher_symc_setup成功返回后调用
  • 依赖关系:ctx句柄需为setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 要销毁的symc句柄 setup阶段创建的有效句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_encrypt

errcode_t uapi_drv_cipher_symc_ccm_encrypt(uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len,
    const uint8_t *aad, uint32_t aad_len,
    const uint8_t *plain_text, uint8_t *cipher_text, uint32_t data_len,
    uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CCM模式加密并计算tag,一次调用完成全部加密操作
  • 支持附加认证数据(AAD)的输入
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 加密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 加密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存加密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 非NULL
iv_len uint32_t 初始向量长度,单位Byte 7 ~ 13
aad const uint8_t * 附加认证信息 支持传NULL
aad_len uint32_t 附加认证信息长度,单位Byte 0 ~ UINT32_MAX
plain_text const uint8_t * 输入的明文 非NULL
data_len uint32_t 数据长度,单位Byte iv_len为13时不超过65535,iv_len为12时不超过16777215
tag_len uint32_t 期望的tag长度,单位Byte 46810121416

出参

名称 数据类型 输出说明
cipher_text uint8_t * 输出的密文
tag uint8_t * 输出的tag

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_decrypt_verify

errcode_t uapi_drv_cipher_symc_ccm_decrypt_verify(uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len,
    const uint8_t *aad, uint32_t aad_len,
    const uint8_t *cipher_text, uint8_t *plain_text, uint32_t data_len,
    const uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CCM模式解密并校验tag,一次调用完成全部解密操作
  • 支持附加认证数据(AAD)的输入和tag校验
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 解密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 解密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存解密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 非NULL
iv_len uint32_t 初始向量长度,单位Byte 7 ~ 13
aad const uint8_t * 附加认证信息 支持传NULL
aad_len uint32_t 附加认证信息长度,单位Byte 0 ~ UINT32_MAX
cipher_text const uint8_t * 输入的密文 非NULL
data_len uint32_t 数据长度,单位Byte iv_len为13时不超过65535,iv_len为12时不超过16777215
tag const uint8_t * 待校验的tag 非NULL
tag_len uint32_t tag长度,单位Byte 46810121416

出参

名称 数据类型 输出说明
plain_text uint8_t * 输出的明文

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_setup

errcode_t uapi_drv_cipher_symc_ccm_setup(cipher_handle_t *ctx, uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len, bool is_encrypt)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 初始化CCM分段加解密的上下文句柄,用于后续多段操作
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合
  • 需配合ccm_set_lengths、ccm_update_ad、ccm_update、ccm_finish完成分段操作

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 加密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 加密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存加密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 非NULL
iv_len uint32_t 初始向量长度,单位Byte 7 ~ 13
is_encrypt bool 是否加密 true/false

出参

名称 数据类型 输出说明
ctx cipher_handle_t * 创建的加解密句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_set_lengths

errcode_t uapi_drv_cipher_symc_ccm_set_lengths(cipher_handle_t ctx, uint32_t total_aad_len,
    uint32_t data_len, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 为CCM模式设置附加数据总长度、数据总长度和tag长度
  • 需在ccm_update_ad和ccm_update之前调用
  • tag长度仅支持4、6、8、10、12、14或16字节

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_ccm_setup成功返回后调用
  • 依赖关系:ctx句柄需为ccm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 ccm_setup阶段创建的有效句柄
total_aad_len uint32_t 附加数据的总长度,单位Byte 0 ~ UINT32_MAX
data_len uint32_t 加密或解密数据的总长度,单位Byte 0 ~ UINT32_MAX
tag_len uint32_t 生成的tag值的长度,单位Byte 46810121416

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_update_ad

errcode_t uapi_drv_cipher_symc_ccm_update_ad(cipher_handle_t ctx, const uint8_t *aad, uint32_t aad_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 为CCM增加附加认证数据,可零次、一次或多次调用传递分段的附加数据
  • 需在ccm_set_lengths之后、ccm_update之前调用
  • 支持分段传入AAD数据

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_ccm_set_lengths成功返回后调用
  • 依赖关系:ctx句柄需为ccm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 ccm_setup阶段创建的有效句柄
aad const uint8_t * 附加数据 非NULL
aad_len uint32_t 此次附加数据的长度,单位Byte 0 ~ UINT32_MAX

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_update

errcode_t uapi_drv_cipher_symc_ccm_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CCM模式下的分段加解密操作
  • 传入数据长度为0时接口返回成功
  • 需配合ccm_setup和ccm_set_lengths使用

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_ccm_setup和ccm_set_lengths成功返回后调用
  • 依赖关系:ctx句柄需为ccm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 ccm_setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_finish

errcode_t uapi_drv_cipher_symc_ccm_finish(cipher_handle_t ctx, uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CCM获取tag值,在分段加解密数据全部输入后调用
  • tag长度仅支持4、6、8、10、12、14或16字节
  • 完成后需调用ccm_teardown销毁句柄

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_ccm_update完成后调用
  • 依赖关系:ctx句柄需为ccm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 ccm_setup阶段创建的有效句柄
tag_len uint32_t 生成的tag值的长度,单位Byte 46810121416

出参

名称 数据类型 输出说明
tag uint8_t * 输出的tag

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_ccm_teardown

errcode_t uapi_drv_cipher_symc_ccm_teardown(cipher_handle_t ctx)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • CCM销毁分段加解密上下文句柄,释放相关资源
  • 销毁后句柄不可再使用

前置条件

  • 调用时序约束:需在CCM分段加解密操作全部完成后调用,当前接口需要在uapi_drv_cipher_symc_ccm_setup成功返回后调用
  • 依赖关系:ctx句柄需为ccm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 要销毁的symc句柄 ccm_setup阶段创建的有效句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_encrypt

errcode_t uapi_drv_cipher_symc_gcm_encrypt(uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len,
    const uint8_t *aad, uint32_t aad_len,
    const uint8_t *plain_text, uint8_t *cipher_text, uint32_t data_len,
    uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • GCM模式加密并计算tag,一次调用完成全部加密操作
  • 支持附加认证数据(AAD)的输入,支持iv传NULL
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 加密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 加密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存加密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 支持传NULL
iv_len uint32_t 初始向量长度,单位Byte 支持任意长度
aad const uint8_t * 附加认证信息 支持传NULL
aad_len uint32_t 附加认证信息长度,单位Byte 0 ~ UINT32_MAX
plain_text const uint8_t * 输入的明文 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
tag_len uint32_t 期望的tag长度,单位Byte 由具体需求决定

出参

名称 数据类型 输出说明
cipher_text uint8_t * 输出的密文
tag uint8_t * 输出的tag

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_decrypt_verify

errcode_t uapi_drv_cipher_symc_gcm_decrypt_verify(uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len,
    const uint8_t *aad, uint32_t aad_len,
    const uint8_t *cipher_text, uint8_t *plain_text, uint32_t data_len,
    const uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • GCM模式解密并校验tag,一次调用完成全部解密操作
  • 支持附加认证数据(AAD)的输入和tag校验,支持iv传NULL
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 解密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 解密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存解密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 支持传NULL
iv_len uint32_t 初始向量长度,单位Byte 支持任意长度
aad const uint8_t * 附加认证信息 支持传NULL
aad_len uint32_t 附加认证信息长度,单位Byte 0 ~ UINT32_MAX
cipher_text const uint8_t * 输入的密文 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX
tag const uint8_t * 待校验的tag 非NULL
tag_len uint32_t tag长度,单位Byte 由具体需求决定

出参

名称 数据类型 输出说明
plain_text uint8_t * 输出的明文

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_setup

errcode_t uapi_drv_cipher_symc_gcm_setup(cipher_handle_t *ctx, uapi_drv_cipher_symc_alg_t alg,
    const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle,
    const uint8_t *iv, uint32_t iv_len, bool is_encrypt)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 初始化GCM分段加解密的上下文句柄,用于后续多段操作
  • 支持两种密钥设置方式:key/key_len组合或keyslot_handle/key_len组合
  • 需配合gcm_update_ad、gcm_update、gcm_finish完成分段操作

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:若使用keyslot_handle方式,需要先通过KM模块创建keyslot句柄

入参

名称 参数类型 详细说明 约束取值范围
alg uapi_drv_cipher_symc_alg_t 加解密算法 UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1) / UAPI_DRV_CIPHER_SYMC_ALG_SM4(0x2)
key const uint8_t * 加密密钥 使用keyslot_handle方式时传NULL
key_len uint32_t 加密密钥长度,单位Byte 162432
keyslot_handle uint32_t 保存加密密钥的keyslot句柄 不需要时设置为 UAPI_DRV_INVALID_KEY_SLOT
iv const uint8_t * 初始向量 -
iv_len uint32_t 初始向量长度,单位Byte 0 ~ UINT32_MAX
is_encrypt bool 是否加密 true/false

出参

名称 数据类型 输出说明
ctx cipher_handle_t * 创建的加解密句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_update_ad

errcode_t uapi_drv_cipher_symc_gcm_update_ad(cipher_handle_t ctx, const uint8_t *aad, uint32_t aad_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 为GCM增加附加认证数据,可零次、一次或多次调用传递分段的附加数据
  • 需在gcm_setup之后、gcm_update之前调用
  • 支持分段传入AAD数据

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_gcm_setup成功返回后调用
  • 依赖关系:ctx句柄需为gcm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 gcm_setup阶段创建的有效句柄
aad const uint8_t * 附加数据 非NULL
aad_len uint32_t 此次附加数据的长度,单位Byte 0 ~ UINT32_MAX

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_update

errcode_t uapi_drv_cipher_symc_gcm_update(cipher_handle_t ctx, const uint8_t *src, uint8_t *dst, uint32_t data_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • GCM模式下的分段加解密操作
  • 传入数据长度为0时接口返回成功
  • 需配合gcm_setup使用

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_gcm_setup成功返回后调用
  • 依赖关系:ctx句柄需为gcm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 gcm_setup阶段创建的有效句柄
src const uint8_t * 源数据指针 非NULL
data_len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX

出参

名称 数据类型 输出说明
dst uint8_t * 目的数据,加解密结果输出

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_finish

errcode_t uapi_drv_cipher_symc_gcm_finish(cipher_handle_t ctx, uint8_t *tag, uint32_t tag_len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • GCM获取tag值,在分段加解密数据全部输入后调用
  • 完成后需调用gcm_teardown销毁句柄
  • 输出tag的长度由tag_len指定

前置条件

  • 调用时序约束:当前接口需要在uapi_drv_cipher_symc_gcm_update完成后调用
  • 依赖关系:ctx句柄需为gcm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 加解密句柄 gcm_setup阶段创建的有效句柄
tag_len uint32_t 获取的tag长度,单位Byte 0 ~ UINT32_MAX

出参

名称 数据类型 输出说明
tag uint8_t * 输出的tag

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_gcm_teardown

errcode_t uapi_drv_cipher_symc_gcm_teardown(cipher_handle_t ctx)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • GCM销毁分段加解密上下文句柄,释放相关资源
  • 销毁后句柄不可再使用

前置条件

  • 调用时序约束:需在GCM分段加解密操作全部完成后调用,当前接口需要在uapi_drv_cipher_symc_gcm_setup成功返回后调用
  • 依赖关系:ctx句柄需为gcm_setup阶段创建的有效句柄

入参

名称 参数类型 详细说明 约束取值范围
ctx cipher_handle_t 要销毁的symc句柄 gcm_setup阶段创建的有效句柄

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

uapi_drv_cipher_symc_dma_copy

errcode_t uapi_drv_cipher_symc_dma_copy(uint64_t src_addr, uint64_t dst_addr, uint32_t len)

头文件清单

#include "include/driver/security_unified/security_symc.h"

功能说明

  • 通过DMA方式从源数据地址拷贝数据到目的数据地址
  • 利用安全引擎DMA通道完成数据搬运
  • 支持指定数据长度进行拷贝

前置条件

  • 调用时序约束:当前接口需要在安全引擎初始化完成后调用
  • 依赖关系:源地址和目的地址需为有效的物理地址

入参

名称 参数类型 详细说明 约束取值范围
src_addr uint64_t 源数据地址 有效物理地址
dst_addr uint64_t 目的数据地址 有效物理地址
len uint32_t 数据长度,单位Byte 0 ~ UINT32_MAX

返回值

  • 返回类型:errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 操作成功
Other 其他错误码,参考errcode_t 执行失败

Type definitions

errcode_t

typedef uint32_t errcode_t;

使用说明

本模块所有接口的返回值类型 [SDK公共基础类型]

cipher_handle_t

typedef uintptr_t cipher_handle_t;

使用说明

用于本模块所有接口的上下文句柄类型,作为setup接口的出参和update/teardown接口的入参

Enumerations

uapi_drv_cipher_symc_alg_t

typedef enum {
    UAPI_DRV_CIPHER_SYMC_ALG_TDES = 0x0,
    UAPI_DRV_CIPHER_SYMC_ALG_AES = 0x1,
    UAPI_DRV_CIPHER_SYMC_ALG_SM4 = 0x2,
    UAPI_DRV_CIPHER_SYMC_ALG_LEA = 0x3,
    UAPI_DRV_CIPHER_SYMC_ALG_DMA = 0x4,
    UAPI_DRV_CIPHER_SYMC_ALG_MAX,
    UAPI_DRV_CIPHER_SYMC_ALG_INVALID = 0xffffffff,
} uapi_drv_cipher_symc_alg_t;
枚举成员 取值 描述
UAPI_DRV_CIPHER_SYMC_ALG_TDES 0x0 TDES对称加密算法(不建议使用)
UAPI_DRV_CIPHER_SYMC_ALG_AES 0x1 AES对称加密算法
UAPI_DRV_CIPHER_SYMC_ALG_SM4 0x2 SM4对称加密算法
UAPI_DRV_CIPHER_SYMC_ALG_LEA 0x3 LEA对称加密算法
UAPI_DRV_CIPHER_SYMC_ALG_DMA 0x4 DMA模式
UAPI_DRV_CIPHER_SYMC_ALG_MAX 0x5 算法类型最大值
UAPI_DRV_CIPHER_SYMC_ALG_INVALID 0xffffffff 无效算法类型

uapi_drv_cipher_symc_work_mode_t

typedef enum {
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_ECB = 0x0,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CTR,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_OFB,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CFB,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CCM,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_GCM,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC_MAC,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_CMAC,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_MAX,
    UAPI_DRV_CIPHER_SYMC_WORK_MODE_INVALID = 0xffffffff,
} uapi_drv_cipher_symc_work_mode_t;
枚举成员 取值 描述
UAPI_DRV_CIPHER_SYMC_WORK_MODE_ECB 0x0 ECB工作模式(不建议使用)
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC 0x1 CBC工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CTR 0x2 CTR工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_OFB 0x3 OFB工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CFB 0x4 CFB工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CCM 0x5 CCM工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_GCM 0x6 GCM工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CBC_MAC 0x7 CBC_MAC工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_CMAC 0x8 CMAC工作模式
UAPI_DRV_CIPHER_SYMC_WORK_MODE_MAX 0x9 工作模式最大值
UAPI_DRV_CIPHER_SYMC_WORK_MODE_INVALID 0xffffffff 无效工作模式

uapi_drv_cipher_symc_bit_width_t

typedef enum {
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_1BIT = 0x0,
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_8BIT = 0x1,
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_64BIT = 0x2,
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_128BIT = 0x3,
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_MAX,
    UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_INVALID = 0xffffffff,
} uapi_drv_cipher_symc_bit_width_t;
枚举成员 取值 描述
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_1BIT 0x0 1位密钥位宽
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_8BIT 0x1 8位密钥位宽
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_64BIT 0x2 64位密钥位宽
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_128BIT 0x3 128位密钥位宽
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_MAX 0x4 密钥位宽最大值
UAPI_DRV_CIPHER_SYMC_BIT_WIDTH_INVALID 0xffffffff 无效密钥位宽

Macros

uapi_compat_symc_alg

/* compat symc alg */
#define uapi_compat_symc_alg(alg, work_mode, bit_width)   \
    ((((alg) & 0xFF) << 16) + (((work_mode) & 0Xff) << 8) + (bit_width))

UAPI_DRV_SYMC_AES_ECB_ALG

/* AES-ECB */
#define UAPI_DRV_SYMC_AES_ECB_ALG     0x10003

UAPI_DRV_SYMC_AES_CBC_ALG

/* AES-CBC */
#define UAPI_DRV_SYMC_AES_CBC_ALG     0x10103

UAPI_DRV_SYMC_AES_CTR_ALG

/* AES-CTR */
#define UAPI_DRV_SYMC_AES_CTR_ALG     0x10203

UAPI_DRV_SYMC_AES_OFB_ALG

/* AES-OFB */
#define UAPI_DRV_SYMC_AES_OFB_ALG     0x10303

UAPI_DRV_SYMC_AES_CFB1_ALG

/* AES-CFB1 */
#define UAPI_DRV_SYMC_AES_CFB1_ALG    0x10400

UAPI_DRV_SYMC_AES_CFB8_ALG

/* AES-CFB8 */
#define UAPI_DRV_SYMC_AES_CFB8_ALG    0x10401

UAPI_DRV_SYMC_AES_CFB128_ALG

/* AES-CFB128 */
#define UAPI_DRV_SYMC_AES_CFB128_ALG  0x10403

UAPI_DRV_SYMC_SM4_ECB_ALG

/* SM4-ECB */
#define UAPI_DRV_SYMC_SM4_ECB_ALG     0x20003

UAPI_DRV_SYMC_SM4_CBC_ALG

/* SM4-CBC */
#define UAPI_DRV_SYMC_SM4_CBC_ALG     0x20103

UAPI_DRV_SYMC_SM4_CTR_ALG

/* SM4-CTR */
#define UAPI_DRV_SYMC_SM4_CTR_ALG     0x20203

UAPI_DRV_SYMC_SM4_OFB_ALG

/* SM4-OFB */
#define UAPI_DRV_SYMC_SM4_OFB_ALG     0x20303

UAPI_DRV_SYMC_SM4_CFB1_ALG

/* SM4-CFB1 */
#define UAPI_DRV_SYMC_SM4_CFB1_ALG    0x20400

UAPI_DRV_SYMC_SM4_CFB8_ALG

/* SM4-CFB8 */
#define UAPI_DRV_SYMC_SM4_CFB8_ALG    0x20401

UAPI_DRV_SYMC_SM4_CFB128_ALG

/* SM4-CFB128 */
#define UAPI_DRV_SYMC_SM4_CFB128_ALG  0x20403

UAPI_DRV_INVALID_KEY_SLOT [SDK公共共享宏]

#define UAPI_DRV_INVALID_KEY_SLOT 0xFFFFFFFF

ERRCODE_SUCC [SDK公共共享宏]

#define ERRCODE_SUCC                                        0UL