security_km

KM (Key Management) 提供密钥管理功能，支持 keyslot 句柄的创建与销毁、明文密钥与硬件密钥的设置。

头文件清单

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

接口清单

接口名称	功能简述
uapi_drv_keyslot_setup	创建一个 keyslot 句柄
uapi_drv_keyslot_teardown	销毁一个 keyslot 句柄
uapi_drv_keyslot_set_clear_key	向指定的 keyslot 句柄设置明文密钥
uapi_drv_keyslot_set_hard_key	向指定的 keyslot 句柄设置硬件密钥

Functions

uapi_drv_keyslot_setup

drv_keyslot_setup uapi drv keyslot setup uapi_drv_keyslot_setup

errcode_t uapi_drv_keyslot_setup(uint32_t *keyslot_handle, uapi_drv_keyslot_type_t keyslot_type)

头文件清单

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

功能说明

• 创建一个 keyslot 句柄，用于后续密钥操作
• 根据 keyslot_type 参数指定 keyslot 的类型（MCIPHER/HMAC/FLASH）
• 创建成功后通过出参 keyslot_handle 返回句柄

前置条件

• 调用时序约束：当前接口需在安全模块初始化完成后调用
• 依赖关系：当前接口依赖安全模块已正常初始化

入参

名称	参数类型	详细说明	约束取值范围
keyslot_type	uapi_drv_keyslot_type_t	keyslot 类型	UAPI_DRV_KEYSLOT_TYPE_MCIPHER(0) / UAPI_DRV_KEYSLOT_TYPE_HMAC(1) / UAPI_DRV_KEYSLOT_TYPE_FLASH(2)

出参

名称	数据类型	输出说明
keyslot_handle	uint32_t *	创建的 keyslot 句柄，由调用方分配内存、函数填充

返回值

• 返回类型：errcode_t

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

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SECURITY_UNIFIED_SUPPORT_KM	编译参与宏	控制 km 相关文件参与编译	n

uapi_drv_keyslot_teardown

drv_keyslot_teardown uapi drv keyslot teardown uapi_drv_keyslot_teardown

errcode_t uapi_drv_keyslot_teardown(uint32_t keyslot_handle)

头文件清单

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

功能说明

• 销毁一个 keyslot 句柄，释放对应的资源
• 销毁后该 keyslot 句柄不再有效
• 调用后对应的 keyslot 资源被释放回收

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_keyslot_setup 成功返回后调用
• 依赖关系：传入的 keyslot_handle 必须为有效的 keyslot 句柄

入参

名称	参数类型	详细说明	约束取值范围
keyslot_handle	uint32_t	待销毁的 keyslot 句柄	uapi_drv_keyslot_setup 返回的有效句柄

返回值

• 返回类型：errcode_t

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

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SECURITY_UNIFIED_SUPPORT_KM	编译参与宏	控制 km 相关文件参与编译	n

uapi_drv_keyslot_set_clear_key

drv_keyslot_set_clear_key uapi drv keyslot set clear key uapi_drv_keyslot_set_clear_key

errcode_t uapi_drv_keyslot_set_clear_key(uint32_t keyslot_handle, uapi_drv_klad_engine_t klad_engine,
    const uint8_t *key, uint32_t key_len)

头文件清单

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

功能说明

• 向指定的 keyslot 句柄设置明文密钥
• 通过 klad_engine 参数指定密钥对应的算法引擎
• 密钥长度根据目标算法引擎类型有不同约束

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_keyslot_setup 成功返回后调用
• 依赖关系：传入的 keyslot_handle 必须为有效的 keyslot 句柄

入参

名称	参数类型	详细说明	约束取值范围
keyslot_handle	uint32_t	指定的 keyslot 句柄	uapi_drv_keyslot_setup 返回的有效句柄
klad_engine	uapi_drv_klad_engine_t	指定的算法引擎	UAPI_DRV_KLAD_ENGINE_AES(0x20) / UAPI_DRV_KLAD_ENGINE_LAE(0x40) / UAPI_DRV_KLAD_ENGINE_SM4(0x50) / UAPI_DRV_KLAD_ENGINE_TDES(0x70) / UAPI_DRV_KLAD_ENGINE_SHA1_HMAC(0xA0) / UAPI_DRV_KLAD_ENGINE_SHA2_HMAC(0xA1) / UAPI_DRV_KLAD_ENGINE_SM3_HMAC(0xA2)
key	const uint8_t *	明文密钥	不为NULL
key_len	uint32_t	明文密钥的长度，单位是 byte	MCIPHER/FLASH: 16、24、32；HMAC: 1 ~ 128

返回值

• 返回类型：errcode_t

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

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SECURITY_UNIFIED_SUPPORT_KM	编译参与宏	控制 km 相关文件参与编译	n

uapi_drv_keyslot_set_hard_key

drv_keyslot_set_hard_key uapi drv keyslot set hard key uapi_drv_keyslot_set_hard_key

errcode_t uapi_drv_keyslot_set_hard_key(uint32_t keyslot_handle,
    uapi_drv_keyslot_hard_key_type_t hard_key_type, uapi_drv_klad_engine_t klad_engine,
    const uint8_t *salt, uint32_t salt_len, uint32_t key_len)

头文件清单

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

功能说明

• 向指定的 keyslot 句柄设置硬件密钥
• 通过 hard_key_type 参数选择硬件密钥类型
• 通过 salt 参数提供盐值用于派生工作密钥

前置条件

• 调用时序约束：当前接口必须在 uapi_drv_keyslot_setup 成功返回后调用
• 依赖关系：传入的 keyslot_handle 必须为有效的 keyslot 句柄

入参

名称	参数类型	详细说明	约束取值范围
keyslot_handle	uint32_t	指定的 keyslot 句柄	uapi_drv_keyslot_setup 返回的有效句柄
hard_key_type	uapi_drv_keyslot_hard_key_type_t	选择的硬件密钥类型	UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_REE(0) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_HISI(1) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_TEE(2) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_SEC_STORE(3) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_REE(4) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_TEE(5) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_REE(6) / UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_TEE(7)
klad_engine	uapi_drv_klad_engine_t	指定的算法引擎	UAPI_DRV_KLAD_ENGINE_AES(0x20) / UAPI_DRV_KLAD_ENGINE_LAE(0x40) / UAPI_DRV_KLAD_ENGINE_SM4(0x50) / UAPI_DRV_KLAD_ENGINE_TDES(0x70) / UAPI_DRV_KLAD_ENGINE_SHA1_HMAC(0xA0) / UAPI_DRV_KLAD_ENGINE_SHA2_HMAC(0xA1) / UAPI_DRV_KLAD_ENGINE_SM3_HMAC(0xA2)
salt	const uint8_t *	盐值，用于派生工作密钥	不为NULL
salt_len	uint32_t	盐值的长度，单位是 byte	0 ~ 28
key_len	uint32_t	派生的工作密钥长度，单位是 byte	16、24、32

返回值

• 返回类型：errcode_t

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

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SECURITY_UNIFIED_SUPPORT_KM	编译参与宏	控制 km 相关文件参与编译	n

Type definitions

errcode_t

errcode t errcode_t

typedef uint32_t errcode_t;

使用说明

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

Enumerations

uapi_drv_keyslot_hard_key_type_t

drv_keyslot_hard_key_type_t uapi drv keyslot hard key type t uapi_drv_keyslot_hard_key_type_t

typedef enum {
    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_REE = 0,
    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_HISI,
    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_TEE,

    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_SEC_STORE,

    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_REE,
    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_TEE,

    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_REE,
    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_TEE,

    UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_INVALID  = 0xFFFFFFFF
} uapi_drv_keyslot_hard_key_type_t;

枚举成员	取值	描述
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_REE	0	BOOT REE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_HISI	1	BOOT HISI 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_BOOT_TEE	2	BOOT TEE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_SEC_STORE	3	安全存储硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_REE	4	ODRK REE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_ODRK_TEE	5	ODRK TEE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_REE	6	USER REE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_USER_TEE	7	USER TEE 硬件密钥类型
UAPI_DRV_KEYSLOT_HARD_KEY_TYPE_INVALID	0xFFFFFFFF	无效硬件密钥类型

uapi_drv_keyslot_type_t

drv_keyslot_type_t uapi drv keyslot type t uapi_drv_keyslot_type_t

typedef enum {
    UAPI_DRV_KEYSLOT_TYPE_MCIPHER = 0,
    UAPI_DRV_KEYSLOT_TYPE_HMAC,
    UAPI_DRV_KEYSLOT_TYPE_FLASH,
} uapi_drv_keyslot_type_t;

枚举成员	取值	描述
UAPI_DRV_KEYSLOT_TYPE_MCIPHER	0	对称加解密 keyslot 类型
UAPI_DRV_KEYSLOT_TYPE_HMAC	1	HMAC keyslot 类型
UAPI_DRV_KEYSLOT_TYPE_FLASH	2	Flash 在线解密 keyslot 类型

uapi_drv_klad_engine_t

drv_klad_engine_t uapi drv klad engine t uapi_drv_klad_engine_t

typedef enum {
    UAPI_DRV_KLAD_ENGINE_AES = 0x20,
    UAPI_DRV_KLAD_ENGINE_LAE = 0x40,
    UAPI_DRV_KLAD_ENGINE_SM4 = 0x50,
    UAPI_DRV_KLAD_ENGINE_TDES = 0x70,
    UAPI_DRV_KLAD_ENGINE_SHA1_HMAC = 0xA0,
    UAPI_DRV_KLAD_ENGINE_SHA2_HMAC = 0xA1,
    UAPI_DRV_KLAD_ENGINE_SM3_HMAC = 0xA2,
    UAPI_DRV_KLAD_ENGINE_MAX,
    UAPI_DRV_KLAD_ENGINE_INVALID = 0xffffffff,
} uapi_drv_klad_engine_t;

枚举成员	取值	描述
UAPI_DRV_KLAD_ENGINE_AES	0x20	AES 算法引擎
UAPI_DRV_KLAD_ENGINE_LAE	0x40	LAE 算法引擎
UAPI_DRV_KLAD_ENGINE_SM4	0x50	SM4 算法引擎
UAPI_DRV_KLAD_ENGINE_TDES	0x70	TDES 算法引擎
UAPI_DRV_KLAD_ENGINE_SHA1_HMAC	0xA0	SHA1 HMAC 算法引擎
UAPI_DRV_KLAD_ENGINE_SHA2_HMAC	0xA1	SHA2 HMAC 算法引擎
UAPI_DRV_KLAD_ENGINE_SM3_HMAC	0xA2	SM3 HMAC 算法引擎
UAPI_DRV_KLAD_ENGINE_MAX	0xA3	算法引擎最大值
UAPI_DRV_KLAD_ENGINE_INVALID	0xFFFFFFFF	无效算法引擎

Macros

ERRCODE_SUCC [SDK公共共享宏]

errcode succ errcode_succ

#define ERRCODE_SUCC                                        0UL