security_mac

MAC (Message Authentication Code) 提供基于对称加密算法的消息认证码计算能力，支持 CBC MAC 和 CMAC 两种计算模式，涵盖单段计算和分段计算场景。

头文件清单

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

接口清单

接口名称	功能简述
uapi_drv_cipher_cbc_mac	CBC MAC 单段计算
uapi_drv_cipher_cbc_mac_start	初始化 CBC MAC 分段计算的上下文句柄
uapi_drv_cipher_cbc_mac_update	CBC MAC 分段计算
uapi_drv_cipher_cbc_mac_finish	CBC MAC 计算 MAC 值
uapi_drv_cipher_cbc_mac_destroy	销毁 CBC MAC 句柄
uapi_drv_cipher_cmac	CMAC 单段计算
uapi_drv_cipher_cmac_start	初始化 CMAC 分段计算的上下文句柄
uapi_drv_cipher_cmac_update	CMAC 分段计算
uapi_drv_cipher_cmac_finish	CMAC 计算 MAC 值
uapi_drv_cipher_cmac_destroy	销毁 CMAC 句柄

Functions

uapi_drv_cipher_cbc_mac

drv_cipher_cbc_mac uapi drv cipher cbc mac uapi_drv_cipher_cbc_mac

errcode_t uapi_drv_cipher_cbc_mac(uapi_drv_cipher_symc_alg_t alg, const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, const uint8_t *data, uint32_t data_len, uint8_t out_mac[16])

头文件清单

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

功能说明

• 提供 CBC MAC 单段计算能力，对消息数据计算 MAC 值
• 支持通过 key/key_len 组合或 keyslot_handle/key_len 组合两种方式设置密钥
• 输出 16 字节 MAC 值

前置条件

• 调用时序约束：当前接口依赖安全加密模块已初始化
• 依赖关系：使用 keyslot_handle 方式时，依赖 KM 模块已创建 keyslot 句柄；若不使用 keyslot，需将 keyslot_handle 设置为 UAPI_DRV_INVALID_KEY_SLOT

入参

名称	参数类型	详细说明	约束取值范围
alg	uapi_drv_cipher_symc_alg_t	加解密算法	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(0x5) / UAPI_DRV_CIPHER_SYMC_ALG_INVALID(0xFFFFFFFF)
key	const uint8_t *	对称密钥	使用 key/key_len 组合时传入密钥数据；使用 keyslot_handle 方式时传 NULL
key_len	uint32_t	对称密钥长度，单位 Byte	1 ~ 4294967295
keyslot_handle	uint32_t	用于保存 key 的句柄	不使用时设置为 UAPI_DRV_INVALID_KEY_SLOT
data	const uint8_t *	消息数据	非空指针
data_len	uint32_t	消息数据长度，单位 Byte	0 ~ 4294967295

出参

名称	数据类型	输出说明
out_mac	uint8_t[16]	输出的 MAC 值

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CBC_MAC	功能宏	支持 CBC MAC 接口功能	n

uapi_drv_cipher_cbc_mac_start

drv_cipher_cbc_mac_start uapi drv cipher cbc mac start uapi_drv_cipher_cbc_mac_start

errcode_t uapi_drv_cipher_cbc_mac_start(mac_handle_t *ctx, uapi_drv_cipher_symc_alg_t alg, const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle)

头文件清单

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

功能说明

• 初始化 CBC MAC 分段计算的上下文句柄
• 支持通过 key/key_len 组合或 keyslot_handle/key_len 组合两种方式设置密钥
• 创建 MAC 句柄用于后续分段计算

前置条件

• 调用时序约束：当前接口依赖安全加密模块已初始化
• 依赖关系：使用 keyslot_handle 方式时，依赖 KM 模块已创建 keyslot 句柄；若不使用 keyslot，需将 keyslot_handle 设置为 UAPI_DRV_INVALID_KEY_SLOT

入参

名称	参数类型	详细说明	约束取值范围
alg	uapi_drv_cipher_symc_alg_t	加解密算法	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(0x5) / UAPI_DRV_CIPHER_SYMC_ALG_INVALID(0xFFFFFFFF)
key	const uint8_t *	对称密钥	使用 key/key_len 组合时传入密钥数据；使用 keyslot_handle 方式时传 NULL
key_len	uint32_t	对称密钥长度，单位 Byte	1 ~ 4294967295
keyslot_handle	uint32_t	用于保存 key 的句柄	不使用时设置为 UAPI_DRV_INVALID_KEY_SLOT

出参

名称	数据类型	输出说明
ctx	mac_handle_t *	创建的 MAC 句柄

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CBC_MAC	功能宏	支持 CBC MAC 接口功能	n

uapi_drv_cipher_cbc_mac_update

drv_cipher_cbc_mac_update uapi drv cipher cbc mac update uapi_drv_cipher_cbc_mac_update

errcode_t uapi_drv_cipher_cbc_mac_update(mac_handle_t ctx, const uint8_t *data, uint32_t data_len)

头文件清单

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

功能说明

• CBC MAC 分段计算，对消息数据进行分段 MAC 计算
• 需与 uapi_drv_cipher_cbc_mac_start 配合使用
• 可多次调用以处理分段的消息数据

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cbc_mac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cbc_mac_start 创建的有效句柄
data	const uint8_t *	消息数据	非空指针
data_len	uint32_t	消息数据长度，单位 Byte	0 ~ 4294967295

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CBC_MAC	功能宏	支持 CBC MAC 接口功能	n

uapi_drv_cipher_cbc_mac_finish

drv_cipher_cbc_mac_finish uapi drv cipher cbc mac finish uapi_drv_cipher_cbc_mac_finish

errcode_t uapi_drv_cipher_cbc_mac_finish(mac_handle_t ctx, uint8_t out_mac[16])

头文件清单

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

功能说明

• CBC MAC 计算 MAC 值，完成分段计算并输出最终 MAC 结果
• 需与 uapi_drv_cipher_cbc_mac_start、uapi_drv_cipher_cbc_mac_update 配合使用
• 输出 16 字节 MAC 值

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cbc_mac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cbc_mac_start 创建的有效句柄

出参

名称	数据类型	输出说明
out_mac	uint8_t[16]	输出的 MAC 值

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CBC_MAC	功能宏	支持 CBC MAC 接口功能	n

uapi_drv_cipher_cbc_mac_destroy

drv_cipher_cbc_mac_destroy uapi drv cipher cbc mac destroy uapi_drv_cipher_cbc_mac_destroy

errcode_t uapi_drv_cipher_cbc_mac_destroy(mac_handle_t ctx)

头文件清单

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

功能说明

• 销毁 CBC MAC 句柄，释放资源
• 需与 uapi_drv_cipher_cbc_mac_start 配合使用
• 句柄销毁后不可再用于后续操作

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cbc_mac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cbc_mac_start 创建的有效句柄

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	销毁成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CBC_MAC	功能宏	支持 CBC MAC 接口功能	n

uapi_drv_cipher_cmac

drv_cipher_cmac uapi drv cipher cmac uapi_drv_cipher_cmac

errcode_t uapi_drv_cipher_cmac(uapi_drv_cipher_symc_alg_t alg, const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle, const uint8_t *data, uint32_t data_len, uint8_t out_mac[16])

头文件清单

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

功能说明

• 提供 CMAC 单段计算能力，对消息数据计算 MAC 值
• 仅支持 AES 算法；不支持传入长度为 0 的消息数据
• 支持通过 key/key_len 组合或 keyslot_handle/key_len 组合两种方式设置密钥

前置条件

• 调用时序约束：当前接口依赖安全加密模块已初始化
• 依赖关系：使用 keyslot_handle 方式时，依赖 KM 模块已创建 keyslot 句柄；若不使用 keyslot，需将 keyslot_handle 设置为 UAPI_DRV_INVALID_KEY_SLOT

入参

名称	参数类型	详细说明	约束取值范围
alg	uapi_drv_cipher_symc_alg_t	加解密算法，仅支持 AES	UAPI_DRV_CIPHER_SYMC_ALG_AES(0x1)
key	const uint8_t *	对称密钥	使用 key/key_len 组合时传入密钥数据；使用 keyslot_handle 方式时传 NULL
key_len	uint32_t	对称密钥长度，单位 Byte	1 ~ 4294967295
keyslot_handle	uint32_t	用于保存 key 的句柄	不使用时设置为 UAPI_DRV_INVALID_KEY_SLOT
data	const uint8_t *	消息数据	非空指针
data_len	uint32_t	消息数据长度，单位 Byte	1 ~ 4294967295（CMAC 不支持传入长度为 0）

出参

名称	数据类型	输出说明
out_mac	uint8_t[16]	输出的 MAC 值

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CMAC	功能宏	支持 CMAC 接口功能	n

uapi_drv_cipher_cmac_start

drv_cipher_cmac_start uapi drv cipher cmac start uapi_drv_cipher_cmac_start

errcode_t uapi_drv_cipher_cmac_start(mac_handle_t *ctx, uapi_drv_cipher_symc_alg_t alg, const uint8_t *key, uint32_t key_len, uint32_t keyslot_handle)

头文件清单

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

功能说明

• 初始化 CMAC 分段计算的上下文句柄
• 支持通过 key/key_len 组合或 keyslot_handle/key_len 组合两种方式设置密钥
• 创建 MAC 句柄用于后续分段计算

前置条件

• 调用时序约束：当前接口依赖安全加密模块已初始化
• 依赖关系：使用 keyslot_handle 方式时，依赖 KM 模块已创建 keyslot 句柄；若不使用 keyslot，需将 keyslot_handle 设置为 UAPI_DRV_INVALID_KEY_SLOT

入参

名称	参数类型	详细说明	约束取值范围
alg	uapi_drv_cipher_symc_alg_t	加解密算法	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(0x5) / UAPI_DRV_CIPHER_SYMC_ALG_INVALID(0xFFFFFFFF)
key	const uint8_t *	对称密钥	使用 key/key_len 组合时传入密钥数据；使用 keyslot_handle 方式时传 NULL
key_len	uint32_t	对称密钥长度，单位 Byte	1 ~ 4294967295
keyslot_handle	uint32_t	用于保存 key 的句柄	不使用时设置为 UAPI_DRV_INVALID_KEY_SLOT

出参

名称	数据类型	输出说明
ctx	mac_handle_t *	创建的 MAC 句柄

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CMAC	功能宏	支持 CMAC 接口功能	n

uapi_drv_cipher_cmac_update

drv_cipher_cmac_update uapi drv cipher cmac update uapi_drv_cipher_cmac_update

errcode_t uapi_drv_cipher_cmac_update(mac_handle_t ctx, const uint8_t *data, uint32_t data_len)

头文件清单

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

功能说明

• CMAC 分段计算，对消息数据进行分段 MAC 计算
• 需与 uapi_drv_cipher_cmac_start 配合使用
• 可多次调用以处理分段的消息数据

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cmac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cmac_start 创建的有效句柄
data	const uint8_t *	消息数据	非空指针
data_len	uint32_t	消息数据长度，单位 Byte	0 ~ 4294967295

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CMAC	功能宏	支持 CMAC 接口功能	n

uapi_drv_cipher_cmac_finish

drv_cipher_cmac_finish uapi drv cipher cmac finish uapi_drv_cipher_cmac_finish

errcode_t uapi_drv_cipher_cmac_finish(mac_handle_t ctx, uint8_t out_mac[16])

头文件清单

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

功能说明

• CMAC 计算 MAC 值，完成分段计算并输出最终 MAC 结果
• 需与 uapi_drv_cipher_cmac_start、uapi_drv_cipher_cmac_update 配合使用
• 输出 16 字节 MAC 值

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cmac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄；若未调用 uapi_drv_cipher_cmac_update 或调用 uapi_drv_cipher_cmac_update 传入的 data_len 为 0，则返回失败

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cmac_start 创建的有效句柄

出参

名称	数据类型	输出说明
out_mac	uint8_t[16]	输出的 MAC 值

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	计算成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CMAC	功能宏	支持 CMAC 接口功能	n

uapi_drv_cipher_cmac_destroy

drv_cipher_cmac_destroy uapi drv cipher cmac destroy uapi_drv_cipher_cmac_destroy

errcode_t uapi_drv_cipher_cmac_destroy(mac_handle_t ctx)

头文件清单

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

功能说明

• 销毁 CMAC 句柄，释放资源
• 需与 uapi_drv_cipher_cmac_start 配合使用
• 句柄销毁后不可再用于后续操作

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_cipher_cmac_start 成功返回后调用
• 依赖关系：依赖有效的 MAC 句柄

入参

名称	参数类型	详细说明	约束取值范围
ctx	mac_handle_t	MAC 句柄	uapi_drv_cipher_cmac_start 创建的有效句柄

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	销毁成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SYMC_SUPPORT_CMAC	功能宏	支持 CMAC 接口功能	n

Type definitions

mac_handle_t

typedef uintptr_t mac_handle_t;

使用说明

作为 CBC MAC 和 CMAC 分段计算接口的上下文句柄类型，用于 start 接口出参创建句柄、update/finish/destroy 接口入参传入句柄

errcode_t

errcode t errcode_t

typedef uint32_t errcode_t;

使用说明

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

Enumerations

uapi_drv_cipher_symc_alg_t

drv_cipher_symc_alg_t uapi drv cipher symc alg t 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	无效算法类型

Macros

UAPI_DRV_INVALID_KEY_SLOT

drv_invalid_key_slot uapi drv invalid key slot uapi_drv_invalid_key_slot

#define UAPI_DRV_INVALID_KEY_SLOT    0xFFFFFFFF