security_symc
SYMC (Symmetric Cipher) 提供对称加解密功能,支持单段和分段加解密模式,涵盖 ECB、CBC、CTR、OFB、CFB、CCM、GCM 等工作模式。
头文件清单
接口清单
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
)
头文件清单
功能说明
- 提供单段对称加解密能力,一次调用完成全部数据的加解密操作
- 通过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
)
头文件清单
功能说明
- 初始化分段加解密的上下文句柄,用于后续多段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)
头文件清单
功能说明
- 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])
头文件清单
功能说明
- 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])
头文件清单
功能说明
- 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)
头文件清单
功能说明
- 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)
头文件清单
功能说明
- 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)
头文件清单
功能说明
- 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
头文件清单
功能说明
- 销毁分段加解密上下文句柄,释放相关资源
- 销毁后句柄不可再使用
前置条件
- 调用时序约束:需在分段加解密操作全部完成后调用,当前接口需要在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)
头文件清单
功能说明
- 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 | 16、24、32 |
| 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 | 4、6、8、10、12、14、16 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| 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)
头文件清单
功能说明
- 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 | 16、24、32 |
| 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 | 4、6、8、10、12、14、16 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| 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)
头文件清单
功能说明
- 初始化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 | 16、24、32 |
| 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)
头文件清单
功能说明
- 为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 | 4、6、8、10、12、14、16 |
返回值
- 返回类型: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)
头文件清单
功能说明
- 为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)
头文件清单
功能说明
- 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
头文件清单
功能说明
- 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 | 4、6、8、10、12、14、16 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| tag | uint8_t * | 输出的tag |
返回值
- 返回类型:errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 操作成功 |
| Other | 其他错误码,参考errcode_t | 执行失败 |
uapi_drv_cipher_symc_ccm_teardown
头文件清单
功能说明
- 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)
头文件清单
功能说明
- 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 | 16、24、32 |
| 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)
头文件清单
功能说明
- 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 | 16、24、32 |
| 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)
头文件清单
功能说明
- 初始化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 | 16、24、32 |
| 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)
头文件清单
功能说明
- 为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)
头文件清单
功能说明
- 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
头文件清单
功能说明
- 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
头文件清单
功能说明
- 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
头文件清单
功能说明
- 通过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
使用说明
本模块所有接口的返回值类型 [SDK公共基础类型]
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))