KM#
KM(Key Manager)子模块提供 Keyslot、KLAD(Key Ladder)、KDF(Key Derivation Function)三类密钥管理能力,包括密钥槽句柄的创建与销毁、Key Ladder 通道的创建、属性配置与密钥派生下发、根密钥更新等接口。该模块通过统一的对外句柄抽象,由应用层发起调用,完成对称密钥与 HMAC(Hash-based Message Authentication Code)密钥的安全派生与下发。
模块公共头文件
#include "include/driver/security_unified/km.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化 KM 模块 |
|
去初始化 KM 模块 |
|
创建 keyslot 句柄 |
|
销毁 keyslot 句柄 |
|
创建 Key Ladder 通道句柄 |
|
销毁 Key Ladder 通道句柄 |
|
将 keyslot 句柄与 klad 通道关联 |
|
将 keyslot 句柄与 klad 通道解关联 |
|
设置 Key Ladder 通道属性 |
|
获取 Key Ladder 通道属性 |
|
设置硬件派生密钥参数 |
|
设置明文密钥 |
|
更新根密钥 |
Functions#
uapi_drv_km_init #
errcode_t uapi_drv_km_init(void)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
初始化 KM(Key Manager)模块运行所需的内部资源与状态。
成功初始化后本模块 Keyslot、KLAD(Key Ladder)、KDF(Key Derivation Function)接口方可使用。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在应用使用任意 Keyslot / KLAD / KDF 接口之前调用。
依赖关系:当前接口依赖 security_unified 模块底层驱动已就绪。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
成功初始化 |
Other |
其他错误码,参考errcode_t |
初始化失败 |
参考案例
src/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_km_deinit #
errcode_t uapi_drv_km_deinit(void)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
去初始化 KM 模块,释放初始化阶段占用的资源。
恢复模块至未初始化状态(与 uapi_drv_km_init 配对使用)。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_km_init 成功返回后调用。
依赖关系:当前接口依赖 KM 模块已初始化。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
成功去初始化 |
Other |
其他错误码,参考errcode_t |
去初始化失败 |
参考案例
src/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_keyslot_create #
errcode_t uapi_drv_keyslot_create(uint32_t *keyslot_handle, uapi_drv_keyslot_type_t keyslot_type)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
按指定用途类型创建一个 keyslot 句柄,用于保存密钥。
成功创建后通过出参返回句柄,供后续 KLAD 关联或销毁使用。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_km_init 成功返回后调用。
依赖关系:当前接口依赖 KM 模块已初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
keyslot_type |
keyslot 的用途类型 |
UAPI_DRV_KEYSLOT_TYPE_MCIPHER(0); |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
keyslot_handle |
uint32_t * |
成功创建的 keyslot 句柄,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
keyslot 成功创建 |
Other |
其他错误码,参考errcode_t |
创建失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_keyslot_destroy #
errcode_t uapi_drv_keyslot_destroy(uint32_t keyslot_handle)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
销毁指定的 keyslot 句柄,释放其占用的通道资源。
销毁后该句柄不再可用,需重新创建才能再次使用。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_keyslot_create 成功返回后调用。
依赖关系:当前接口依赖待销毁的 keyslot 句柄有效。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
keyslot_handle |
uint32_t |
待销毁的 keyslot 通道句柄 |
由 uapi_drv_keyslot_create 返回的有效句柄 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
keyslot 成功销毁 |
Other |
其他错误码,参考errcode_t |
销毁失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_klad_create #
errcode_t uapi_drv_klad_create(uint32_t *klad_handle)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
创建一个 Key Ladder 通道句柄,用于后续密钥派生与下发。
成功创建后通过出参返回句柄。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_km_init 成功返回后调用。
依赖关系:当前接口依赖 KM 模块已初始化。
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
klad_handle |
uint32_t * |
成功创建的 Key Ladder 通道句柄,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
Key Ladder 通道创建成功 |
Other |
其他错误码,参考errcode_t |
创建失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_klad_destroy #
errcode_t uapi_drv_klad_destroy(uint32_t klad_handle)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
销毁指定的 Key Ladder 通道句柄,释放其占用的通道资源。
销毁后该句柄不再可用,需重新创建才能再次使用。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_create 成功返回后调用。
依赖关系:当前接口依赖待销毁的 klad 通道句柄有效。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
待销毁的 Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
Key Ladder 通道销毁成功 |
Other |
其他错误码,参考errcode_t |
销毁失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_klad_attach #
errcode_t uapi_drv_klad_attach(uint32_t klad_handle, uapi_drv_klad_dest_t klad_type, uint32_t keyslot_handle)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
将指定 keyslot 句柄与 Key Ladder 通道建立关联关系。
通过 klad_type 指定密钥送出的目标模块。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_create 与 uapi_drv_keyslot_create 成功返回后调用。
依赖关系:当前接口依赖待关联的 klad 通道与 keyslot 句柄均有效。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
要关联的 Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
klad_type |
klad 目标模块类型 |
uapi_drv_klad_dest_t 全体成员 |
|
keyslot_handle |
uint32_t |
要关联的 keyslot 通道句柄 |
由 uapi_drv_keyslot_create 返回的有效句柄 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
关联成功 |
Other |
其他错误码,参考errcode_t |
关联失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_klad_detach #
errcode_t uapi_drv_klad_detach(uint32_t klad_handle, uapi_drv_klad_dest_t klad_type, uint32_t keyslot_handle)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
将指定 keyslot 句柄与 Key Ladder 通道解除关联关系。
通过 klad_type 指定密钥送出的目标模块。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_attach 成功返回后调用。
依赖关系:当前接口依赖待解关联的 klad 通道与 keyslot 句柄均有效。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
要解关联的 Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
klad_type |
klad 目标模块类型 |
uapi_drv_klad_dest_t 全体成员 |
|
keyslot_handle |
uint32_t |
要解关联的 keyslot 通道句柄 |
由 uapi_drv_keyslot_create 返回的有效句柄 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
解关联成功 |
Other |
其他错误码,参考errcode_t |
解关联失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.c
uapi_drv_klad_set_attr #
errcode_t uapi_drv_klad_set_attr(uint32_t klad_handle, const uapi_drv_klad_attr_t *attr)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
设置 Key Ladder 通道的配置属性,包括 Key Ladder 配置、工作密钥配置与工作密钥安全配置。
设置完成后影响后续派生密钥的属性与安全策略。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_create 成功返回后调用。
依赖关系:当前接口依赖待配置的 klad 通道句柄有效,attr 指针非空。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
attr |
const uapi_drv_klad_attr_t * |
Key Ladder 配置属性指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
属性设置成功 |
ERRCODE_INVALID_PARAM:0x80000001 |
参数无效 |
attr 为 NULL |
Other |
其他错误码,参考errcode_t |
设置失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.csrc/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_klad_get_attr #
errcode_t uapi_drv_klad_get_attr(uint32_t klad_handle, uapi_drv_klad_attr_t *attr)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
获取 Key Ladder 通道当前配置属性,包括 Key Ladder 配置、工作密钥配置与工作密钥安全配置。
获取结果通过出参 attr 返回。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_create 成功返回后调用。
依赖关系:当前接口依赖待查询的 klad 通道句柄有效,attr 指针非空。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
attr |
当前 Key Ladder 通道配置属性,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
属性获取成功 |
ERRCODE_INVALID_PARAM:0x80000001 |
参数无效 |
attr 为 NULL |
Other |
其他错误码,参考errcode_t |
获取失败 |
uapi_drv_klad_set_effective_key #
errcode_t uapi_drv_klad_set_effective_key(uint32_t klad_handle, const uapi_drv_klad_effective_key_t *key)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
设置 Key Ladder 通道硬件派生密钥参数,包括派生 HMAC 算法、主密钥类型、密钥长度、盐值与单向性配置。
设置完成后触发硬件密钥派生并下发至目标引擎。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_set_attr 成功返回后调用。
依赖关系:当前接口依赖待配置的 klad 通道句柄有效,key 指针及其 salt 字段非空。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
key |
const uapi_drv_klad_effective_key_t * |
硬件派生密钥参数指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
硬件派生密钥设置成功 |
ERRCODE_INVALID_PARAM:0x80000001 |
参数无效 |
key 为 NULL |
ERRCODE_FAIL:0xFFFFFFFF |
执行失败 |
salt 拷贝失败 |
Other |
其他错误码,参考errcode_t |
设置失败 |
参考案例
src/middleware/chips/ws53/nv/nv_porting/nv_crypto.c
uapi_drv_klad_set_clear_key #
errcode_t uapi_drv_klad_set_clear_key(uint32_t klad_handle, const uapi_drv_klad_clear_key_t *key)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
设置 Key Ladder 通道的明文密钥,包括明文密钥内容、长度、奇偶属性与 HMAC 算法类型。
设置完成后将明文密钥下发至目标引擎。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_klad_set_attr 成功返回后调用。
依赖关系:当前接口依赖待配置的 klad 通道句柄有效,key 指针及其 key 字段非空。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
klad_handle |
uint32_t |
Key Ladder 通道句柄 |
由 uapi_drv_klad_create 返回的有效句柄 |
key |
const uapi_drv_klad_clear_key_t * |
明文密钥参数指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
明文密钥设置成功 |
ERRCODE_INVALID_PARAM:0x80000001 |
参数无效 |
key 为 NULL |
ERRCODE_FAIL:0xFFFFFFFF |
执行失败 |
明文密钥拷贝失败 |
Other |
其他错误码,参考errcode_t |
设置失败 |
参考案例
src/drivers/drivers/driver/security_unified/service_layer/cipher_simple.c
uapi_drv_kdf_update #
errcode_t uapi_drv_kdf_update(uapi_drv_kdf_otp_key_t otp_key, uapi_drv_kdf_update_alg_t alg)
声明头文件
#include "include/driver/security_unified/km.h"
功能说明
更新指定的 OTP(One-Time Programmable)根密钥。
通过 alg 指定更新所使用的对称算法。
返回执行结果状态码。
前置条件
调用时序约束:当前接口必须在 uapi_drv_km_init 成功返回后调用。
依赖关系:当前接口依赖 KM 模块已初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
otp_key |
要更新的 OTP 根密钥类型 |
UAPI_DRV_KDF_OTP_KEY_MRK1(0); |
|
alg |
更新时使用的对称算法类型 |
UAPI_DRV_KDF_UPDATE_ALG_AES(0); |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
根密钥更新成功 |
Other |
其他错误码,参考errcode_t |
更新失败 |
Type definitions#
typedef_errcode_t #
// errcode_t 定义于 include/errcode.h,为错误码枚举类型别名
typedef uint32_t errcode_t;
使用说明
本模块全部 13 个对外接口的返回值类型均为 errcode_t,表示接口执行结果状态码。
Enumerations#
enum_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 |
对称加解密密钥槽 |
UAPI_DRV_KEYSLOT_TYPE_HMAC |
1 |
HMAC 密钥槽 |
UAPI_DRV_KEYSLOT_TYPE_FLASH |
2 |
Flash 在线解密密钥槽 |
enum_uapi_drv_kdf_otp_key_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KDF_OTP_KEY_MRK1 = 0,
UAPI_DRV_KDF_OTP_KEY_MRK0,
UAPI_DRV_KDF_OTP_KEY_RUSK,
UAPI_DRV_KDF_OTP_KEY_USK
} uapi_drv_kdf_otp_key_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KDF_OTP_KEY_MRK1 |
0 |
主根密钥 1 |
UAPI_DRV_KDF_OTP_KEY_MRK0 |
1 |
主根密钥 0 |
UAPI_DRV_KDF_OTP_KEY_RUSK |
2 |
根用户会话密钥 |
UAPI_DRV_KDF_OTP_KEY_USK |
3 |
用户会话密钥 |
enum_uapi_drv_kdf_update_alg_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KDF_UPDATE_ALG_AES = 0,
UAPI_DRV_KDF_UPDATE_ALG_SM4
} uapi_drv_kdf_update_alg_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KDF_UPDATE_ALG_AES |
0 |
KDF 密钥派生使用 AES(Advanced Encryption Standard)对称算法 |
UAPI_DRV_KDF_UPDATE_ALG_SM4 |
1 |
KDF 密钥派生使用 SM4 对称算法 |
enum_uapi_drv_kdf_hard_key_type_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK0 = 0x03000000,
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK2,
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK2,
UAPI_DRV_KDF_HARD_KEY_TYPE_DRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_DRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_PSK,
UAPI_DRV_KDF_HARD_KEY_TYPE_FDRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_ODRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_ODRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_OARK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK0,
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK1,
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK2,
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK3,
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK_REE,
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK_TEE,
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK_REE,
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK_TEE,
} uapi_drv_kdf_hard_key_type_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK0 |
0x03000000 |
静态启动根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK1 |
0x3000001 |
静态启动根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_SBRK2 |
0x3000002 |
静态启动根密钥 2 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK0 |
0x3000003 |
动态启动根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK1 |
0x3000004 |
动态启动根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK2 |
0x3000005 |
动态启动根密钥 2 |
UAPI_DRV_KDF_HARD_KEY_TYPE_DRK0 |
0x3000006 |
设备根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_DRK1 |
0x3000007 |
设备根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK0 |
0x3000008 |
REE(Rich Execution Environment)设备根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK1 |
0x3000009 |
REE 设备根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_PSK |
0x300000A |
预共享密钥 |
UAPI_DRV_KDF_HARD_KEY_TYPE_FDRK0 |
0x300000B |
Flash 设备根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ODRK0 |
0x300000C |
OTP 设备根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ODRK1 |
0x300000D |
OTP 设备根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_OARK0 |
0x300000E |
OTP 鉴权根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK0 |
0x300000F |
多媒体设备根密钥 0 |
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK1 |
0x3000010 |
多媒体设备根密钥 1 |
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK2 |
0x3000011 |
多媒体设备根密钥 2 |
UAPI_DRV_KDF_HARD_KEY_TYPE_MDRK3 |
0x3000012 |
多媒体设备根密钥 3 |
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK_REE |
0x3000013 |
动态启动根密钥 REE |
UAPI_DRV_KDF_HARD_KEY_TYPE_ABRK_TEE |
0x3000014 |
动态启动根密钥 TEE |
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK_REE |
0x3000015 |
REE 设备根密钥 REE |
UAPI_DRV_KDF_HARD_KEY_TYPE_RDRK_TEE |
0x3000016 |
REE 设备根密钥 TEE |
enum_uapi_drv_kdf_hard_alg_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KDF_HARD_ALG_SHA256 = 0,
UAPI_DRV_KDF_HARD_ALG_SM3,
UAPI_DRV_KDF_HARD_ALG_MAX
} uapi_drv_kdf_hard_alg_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KDF_HARD_ALG_SHA256 |
0 |
硬件 PBKDF2 算法使用 SHA256 |
UAPI_DRV_KDF_HARD_ALG_SM3 |
1 |
硬件 PBKDF2(Password-Based Key Derivation Function 2)算法使用 SM3 哈希算法 |
UAPI_DRV_KDF_HARD_ALG_MAX |
2 |
算法类型上限,无效值 |
enum_uapi_drv_kdf_master_key_type #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_MRK0 = 0,
UAPI_DRV_MRK1,
} uapi_drv_kdf_master_key_type;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_MRK0 |
0 |
主根密钥 0 |
UAPI_DRV_MRK1 |
1 |
主根密钥 1 |
enum_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_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 |
三重 DES(Triple Data Encryption Standard)算法引擎 |
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 |
引擎类型上限,无效值 |
enum_uapi_drv_klad_dest_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KLAD_DEST_MCIPHER = 0,
UAPI_DRV_KLAD_DEST_HMAC,
UAPI_DRV_KLAD_DEST_FLASH,
UAPI_DRV_KLAD_DEST_NPU,
UAPI_DRV_KLAD_DEST_AIDSP,
UAPI_DRV_KLAD_DEST_MAX,
} uapi_drv_klad_dest_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KLAD_DEST_MCIPHER |
0 |
目标为对称加解密模块 |
UAPI_DRV_KLAD_DEST_HMAC |
1 |
目标为 HMAC 模块 |
UAPI_DRV_KLAD_DEST_FLASH |
2 |
目标为 Flash 在线解密模块 |
UAPI_DRV_KLAD_DEST_NPU |
3 |
目标为 NPU(Neural Processing Unit)模块 |
UAPI_DRV_KLAD_DEST_AIDSP |
4 |
目标为 AIDSP 模块 |
UAPI_DRV_KLAD_DEST_MAX |
5 |
目标模块类型上限,无效值 |
enum_uapi_drv_klad_key_size_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KLAD_KEY_SIZE_128BIT,
UAPI_DRV_KLAD_KEY_SIZE_192BIT,
UAPI_DRV_KLAD_KEY_SIZE_256BIT,
UAPI_DRV_KLAD_KEY_SIZE_INVALID = 0xffffffff
} uapi_drv_klad_key_size_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KLAD_KEY_SIZE_128BIT |
0 |
128 位对称密钥 |
UAPI_DRV_KLAD_KEY_SIZE_192BIT |
1 |
192 位对称密钥 |
UAPI_DRV_KLAD_KEY_SIZE_256BIT |
2 |
256 位对称密钥 |
UAPI_DRV_KLAD_KEY_SIZE_INVALID |
0xffffffff |
无效密钥长度 |
enum_uapi_drv_klad_hmac_type_t #
// 源码原始定义,无修改、无补充
typedef enum {
UAPI_DRV_KLAD_HMAC_TYPE_SHA1 = 0x20,
UAPI_DRV_KLAD_HMAC_TYPE_SHA224,
UAPI_DRV_KLAD_HMAC_TYPE_SHA256,
UAPI_DRV_KLAD_HMAC_TYPE_SHA384,
UAPI_DRV_KLAD_HMAC_TYPE_SHA512,
UAPI_DRV_KLAD_HMAC_TYPE_SM3 = 0x30,
UAPI_DRV_KLAD_HMAC_TYPE_MAX,
UAPI_DRV_KLAD_HMAC_TYPE_INVALID = 0xffffffff,
} uapi_drv_klad_hmac_type_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
UAPI_DRV_KLAD_HMAC_TYPE_SHA1 |
0x20 |
HMAC 使用 SHA1 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_SHA224 |
0x21 |
HMAC 使用 SHA224 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_SHA256 |
0x22 |
HMAC 使用 SHA256 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_SHA384 |
0x23 |
HMAC 使用 SHA384 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_SHA512 |
0x24 |
HMAC 使用 SHA512 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_SM3 |
0x30 |
HMAC 使用 SM3 算法 |
UAPI_DRV_KLAD_HMAC_TYPE_MAX |
0x31 |
算法类型上限,无效值 |
UAPI_DRV_KLAD_HMAC_TYPE_INVALID |
0xffffffff |
无效 HMAC 算法类型 |
Structures#
struct_uapi_drv_klad_clear_key_t #
// 源码原始定义,保留注释
typedef struct {
uint8_t *key; /*!< 明文key内容。 */
uint32_t key_length; /*!< 明文key长度,单位为字节。
对于对称算法,只能是16/24/32;
对于HMAC-SH1/SHA224/SHA256/SM3,长度不超过64;
对于HMAC-SHA384/SHA512,长度不超过128。*/
bool key_parity; /*!< key的奇偶属性。当目标为对称算法引擎且key_length为16时生效。 */
uapi_drv_klad_hmac_type_t hmac_type; /*!< hmac 算法。当目标为HMAC算法引擎时生效。 */
} uapi_drv_klad_clear_key_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
key |
uint8_t * |
明文密钥内容指针,对称算法仅可取 16 / 24 / 32 Bytes;HMAC-SHA1/SHA224/SHA256/SM3 不超过 64;HMAC-SHA384/SHA512 不超过 128 |
key_length |
uint32_t |
明文密钥长度,单位 Bytes |
key_parity |
bool |
密钥奇偶属性,当目标为对称算法引擎且 key_length 为 16 时生效 |
hmac_type |
uapi_drv_klad_hmac_type_t |
HMAC 算法类型,仅当目标为 HMAC 算法引擎时生效 |
struct_uapi_drv_klad_config_t #
// 源码原始定义,保留注释
typedef struct {
uapi_drv_kdf_hard_key_type_t rootkey_type; /*!< 要生成的根密钥的类型。 */
} uapi_drv_klad_config_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
rootkey_type |
uapi_drv_kdf_hard_key_type_t |
要生成的根密钥类型,对硬件密钥有效 |
struct_uapi_drv_klad_key_config_t #
// 源码原始定义,保留注释
typedef struct {
uapi_drv_klad_engine_t engine; /*!< 工作密钥可用于加密引擎的哪种算法。 */
bool decrypt_support; /*!< 工作密钥可用于解密。 */
bool encrypt_support; /*!< 工作密钥可用于加密。 */
} uapi_drv_klad_key_config_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
engine |
uapi_drv_klad_engine_t |
工作密钥适用的加密引擎算法 |
decrypt_support |
bool |
工作密钥是否可用于解密 |
encrypt_support |
bool |
工作密钥是否可用于加密 |
struct_uapi_drv_klad_key_secure_config_t #
// 源码原始定义,保留注释
typedef struct {
bool key_sec; /*!< 安全密钥只能由TEE CPU和AIDSP锁定的对称通道或哈希通道使用。 */
bool master_only_enable; /*!< 只有与Keylader相同的CPU锁定的密码或哈希通道才能使用此密钥,当TEE CPU或AIDSP时生效。 */
bool dest_buf_sec_support; /*!< 目标引擎的目标缓冲区可以是安全的。 */
bool dest_buf_non_sec_support; /*!< 目标引擎的目标缓冲区可以是非安全的。 */
bool src_buf_sec_support; /*!< 目标引擎的源缓冲区可以是安全的。 */
bool src_buf_non_sec_support; /*!< 目标引擎的源缓冲区可以是非安全的。 */
} uapi_drv_klad_key_secure_config_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
key_sec |
bool |
是否为安全密钥,安全密钥只能由 TEE CPU 与 AIDSP 锁定的对称通道或哈希通道使用 |
master_only_enable |
bool |
是否仅允许与 Key Ladder 相同 CPU 锁定的密码或哈希通道使用该密钥,仅对 TEE CPU 或 AIDSP 生效 |
dest_buf_sec_support |
bool |
目标引擎的目标缓冲区是否可为安全 |
dest_buf_non_sec_support |
bool |
目标引擎的目标缓冲区是否可为非安全 |
src_buf_sec_support |
bool |
目标引擎的源缓冲区是否可为安全 |
src_buf_non_sec_support |
bool |
目标引擎的源缓冲区是否可为非安全 |
struct_uapi_drv_klad_attr_t #
// 源码原始定义,保留注释
typedef struct {
uapi_drv_klad_config_t klad_cfg; /*!< KeyLader配置,对硬件密钥有效。 */
uapi_drv_klad_key_config_t key_cfg; /*!< 工作密钥配置。 */
uapi_drv_klad_key_secure_config_t key_sec_cfg; /*!< 工作密钥安全配置。 */
uint32_t rkp_sw_cfg; /*!< NPU模块使用,其他模块不需要配置。 */
} uapi_drv_klad_attr_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
klad_cfg |
uapi_drv_klad_config_t |
Key Ladder 配置,对硬件密钥有效 |
key_cfg |
uapi_drv_klad_key_config_t |
工作密钥配置 |
key_sec_cfg |
uapi_drv_klad_key_secure_config_t |
工作密钥安全配置 |
rkp_sw_cfg |
uint32_t |
NPU 模块使用的软件配置,其他模块不需要配置 |
struct_uapi_drv_klad_effective_key_t #
// 源码原始定义,保留注释
typedef struct {
uapi_drv_kdf_hard_alg_t kdf_hard_alg; /*!< key派生时使用的hmac算法。 */
uapi_drv_kdf_master_key_type master_key_type;
bool key_parity; /*!< key的奇偶属性。当目标为对称算法引擎且key_length为16时生效。 */
uapi_drv_klad_key_size_t key_size; /*!< 需要派生的key的长度。 */
uint8_t *salt; /*!< 盐值内容。作为用户输入材料参与密钥派生,盐值不同,最终的工作密钥也不同。 */
uint32_t salt_length; /*!< 盐值长度,单位是字节。只能为28。 */
bool oneway; /*!< 密钥派生的单一性,默认为0。如果设置为1,即使使用相同的密钥派生材料也无法派生出相同的密钥。 */
} uapi_drv_klad_effective_key_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
kdf_hard_alg |
uapi_drv_kdf_hard_alg_t |
密钥派生使用的 HMAC 算法 |
master_key_type |
uapi_drv_kdf_master_key_type |
主密钥类型 |
key_parity |
bool |
密钥奇偶属性,当目标为对称算法引擎且 key_length 为 16 时生效 |
key_size |
uapi_drv_klad_key_size_t |
需要派生的密钥长度 |
salt |
uint8_t * |
盐值内容指针,作为用户输入材料参与密钥派生,盐值不同最终工作密钥不同 |
salt_length |
uint32_t |
盐值长度,单位 Bytes,只能为 28 |
oneway |
bool |
密钥派生单向性,默认为 0;设置为 1 时即使使用相同派生材料也无法派生出相同密钥 |
Macros#
ERRCODE_SUCC #
#define ERRCODE_SUCC 0UL
ERRCODE_FAIL #
#define ERRCODE_FAIL 0xFFFFFFFF
ERRCODE_INVALID_PARAM #
#define ERRCODE_INVALID_PARAM 0x80000001