跳转至
项目
版本
全文检索

security_kdf

KDF (Key Derivation Function) 提供密钥派生功能，支持 PBKDF2 和 HKDF (HMAC-based Key Derivation Function) 两种密钥派生算法。

头文件清单

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

接口清单

接口名称 功能简述
uapi_drv_cipher_pbkdf2 使用PBKDF2算法派生密钥
uapi_drv_cipher_hkdf_extract 提取HKDF伪随机密钥
uapi_drv_cipher_hkdf_expand 拓展HKDF输出密钥材料
uapi_drv_cipher_hkdf 执行HKDF完整流程（提取+拓展）

Functions

uapi_drv_cipher_pbkdf2 

errcode_t uapi_drv_cipher_pbkdf2(const uapi_drv_cipher_kdf_pbkdf2_param_t *param, uint8_t *out, const uint32_t out_len)

头文件清单

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

功能说明

  • 使用PBKDF2算法根据输入口令和盐值派生密钥
  • 支持通过参数结构体指定Hash算法类型、迭代次数等派生参数
  • 派生结果写入输出缓冲区

前置条件

  • 调用时序约束：需在安全引擎初始化完成后调用
  • 依赖关系：依赖CONFIG_SECURITY_UNIFIED_SUPPORT_PBKDF2宏开启

入参

名称 参数类型 详细说明 约束取值范围
param const uapi_drv_cipher_kdf_pbkdf2_param_t * PBKDF2算法参数结构体指针 非NULL
out_len const uint32_t 输出密钥缓冲区长度 大于0

出参

名称 数据类型 输出说明
out uint8_t * 派生密钥输出缓冲区，长度为out_len字节

返回值

  • 返回类型：errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 PBKDF2密钥派生成功
Other 其他错误码，参考errcode_t 执行失败

参考案例

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SECURITY_UNIFIED_SUPPORT_PBKDF2 功能宏 支持PBKDF2密钥派生功能 y

uapi_drv_cipher_hkdf_extract 

errcode_t uapi_drv_cipher_hkdf_extract(uapi_drv_cipher_hkdf_extract_t *extract_param, uint8_t *prk, uint32_t *prk_length)

头文件清单

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

功能说明

  • 执行HKDF-Extract阶段，从原始密钥材料和盐值中提取固定长度的伪随机密钥
  • 支持通过参数结构体指定HMAC算法类型、盐值和原始密钥材料
  • 提取结果写入伪随机密钥输出缓冲区

前置条件

  • 调用时序约束：需在安全引擎初始化完成后调用
  • 依赖关系：依赖CONFIG_HASH_SUPPORT_HKDF宏开启

入参

名称 参数类型 详细说明 约束取值范围
extract_param uapi_drv_cipher_hkdf_extract_t * 密钥提取参数结构体指针 非NULL

出参

名称 数据类型 输出说明
prk uint8_t * 提取的伪随机密钥输出缓冲区
prk_length uint32_t * 提取的伪随机密钥实际长度

返回值

  • 返回类型：errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 HKDF-Extract执行成功
Other 其他错误码，参考errcode_t 执行失败

参考案例

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_HASH_SUPPORT_HKDF 功能宏 支持HKDF密钥派生功能 y

uapi_drv_cipher_hkdf_expand 

errcode_t uapi_drv_cipher_hkdf_expand(const uapi_drv_cipher_hkdf_expand_t *expand_param, uint8_t *okm, uint32_t okm_length)

头文件清单

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

功能说明

  • 执行HKDF-Expand阶段，将伪随机密钥拓展为指定长度的输出密钥材料
  • 支持通过参数结构体指定HMAC算法类型、伪随机密钥和信息字段
  • 拓展结果写入输出密钥材料缓冲区

前置条件

  • 调用时序约束：需在安全引擎初始化完成后调用；需在uapi_drv_cipher_hkdf_extract成功提取伪随机密钥后调用
  • 依赖关系：依赖CONFIG_HASH_SUPPORT_HKDF宏开启

入参

名称 参数类型 详细说明 约束取值范围
expand_param const uapi_drv_cipher_hkdf_expand_t * 密钥拓展参数结构体指针 非NULL
okm_length uint32_t 输出密钥材料长度 大于0

出参

名称 数据类型 输出说明
okm uint8_t * 拓展的输出密钥材料缓冲区，长度为okm_length字节

返回值

  • 返回类型：errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 HKDF-Expand执行成功
Other 其他错误码，参考errcode_t 执行失败

参考案例

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_HASH_SUPPORT_HKDF 功能宏 支持HKDF密钥派生功能 y

uapi_drv_cipher_hkdf 

errcode_t uapi_drv_cipher_hkdf(uapi_drv_cipher_hkdf_t *hkdf_param, uint8_t *okm, uint32_t okm_length)

头文件清单

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

功能说明

  • 执行HKDF完整流程，包括密钥提取（Extract）和密钥拓展（Expand）两步
  • 支持通过参数结构体指定HMAC算法类型、盐值、原始密钥材料和信息字段
  • 派生结果写入输出密钥材料缓冲区

前置条件

  • 调用时序约束：需在安全引擎初始化完成后调用
  • 依赖关系：依赖CONFIG_HASH_SUPPORT_HKDF宏开启

入参

名称 参数类型 详细说明 约束取值范围
hkdf_param uapi_drv_cipher_hkdf_t * HKDF参数结构体指针 非NULL
okm_length uint32_t 输出密钥材料长度 大于0

出参

名称 数据类型 输出说明
okm uint8_t * 派生的输出密钥材料缓冲区，长度为okm_length字节

返回值

  • 返回类型：errcode_t
返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 HKDF密钥派生成功
Other 其他错误码，参考errcode_t 执行失败

参考案例

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_HASH_SUPPORT_HKDF 功能宏 支持HKDF密钥派生功能 y

Type definitions

errcode_t 

typedef uint32_t errcode_t;

使用说明

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

Enumerations

uapi_drv_cipher_hash_type_t 

typedef enum {
    UAPI_DRV_CIPHER_HASH_TYPE_SHA1 = 0xf690a0,
    UAPI_DRV_CIPHER_HASH_TYPE_SHA224 = 0x10690e0,
    UAPI_DRV_CIPHER_HASH_TYPE_SHA256 = 0x1169100,
    UAPI_DRV_CIPHER_HASH_TYPE_SHA384 = 0x127a180,
    UAPI_DRV_CIPHER_HASH_TYPE_SHA512 = 0x137a200,
    UAPI_DRV_CIPHER_HASH_TYPE_SM3 = 0x2169100,

    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA1 = 0x10f690a0,
    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA224 = 0x110690e0,
    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA256 = 0x11169100,
    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA384 = 0x1127a180,
    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA512 = 0x1137a200,
    UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SM3 = 0x12169100,

    UAPI_DRV_CIPHER_HASH_TYPE_INVALID = 0xffffffff,
} uapi_drv_cipher_hash_type_t;
枚举成员 取值 描述
UAPI_DRV_CIPHER_HASH_TYPE_SHA1 0xf690a0 SHA1哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_SHA224 0x10690e0 SHA224哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_SHA256 0x1169100 SHA256哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_SHA384 0x127a180 SHA384哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_SHA512 0x137a200 SHA512哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_SM3 0x2169100 SM3哈希算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA1 0x10f690a0 HMAC-SHA1算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA224 0x110690e0 HMAC-SHA224算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA256 0x11169100 HMAC-SHA256算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA384 0x1127a180 HMAC-SHA384算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SHA512 0x1137a200 HMAC-SHA512算法
UAPI_DRV_CIPHER_HASH_TYPE_HMAC_SM3 0x12169100 HMAC-SM3算法
UAPI_DRV_CIPHER_HASH_TYPE_INVALID 0xffffffff 无效哈希算法类型

Structures

uapi_drv_cipher_kdf_pbkdf2_param_t 

typedef struct {
    uapi_drv_cipher_hash_type_t hash_type;  /*!< PBKDF2使用的hash算法类型。 */
    uint8_t *password;      /*!< PBKDF2的输入口令。 */
    uint32_t plen;          /*!< PBKDF2的输入口令长度。 */
    uint8_t *salt;          /*!< PBKDF2的盐值。 */
    uint32_t slen;          /*!< PBKDF2的盐值长度。 */
    uint16_t count;         /*!< PBKDF2的迭代次数。 */
} uapi_drv_cipher_kdf_pbkdf2_param_t;

成员说明

成员名称 数据类型 描述
hash_type uapi_drv_cipher_hash_type_t PBKDF2使用的Hash算法类型
password uint8_t * PBKDF2的输入口令
plen uint32_t PBKDF2的输入口令长度
salt uint8_t * PBKDF2的盐值
slen uint32_t PBKDF2的盐值长度
count uint16_t PBKDF2的迭代次数

uapi_drv_cipher_hkdf_extract_t 

typedef struct {
    uapi_drv_cipher_hash_type_t hmac_type;    /*!< 提取密钥的HMAC算法类型。 */
    uint8_t *salt;    /*!< 提取密钥的盐值。 */
    uint32_t salt_length;    /*!< 提取密钥的盐值长度。 */
    uint8_t *ikm;           /*!< 提取密钥的原始密钥材料。 */
    uint32_t ikm_length;    /*!< 提取密钥的原始密钥材料长度。 */
} uapi_drv_cipher_hkdf_extract_t;

成员说明

成员名称 数据类型 描述
hmac_type uapi_drv_cipher_hash_type_t 提取密钥的HMAC算法类型
salt uint8_t * 提取密钥的盐值
salt_length uint32_t 提取密钥的盐值长度
ikm uint8_t * 提取密钥的原始密钥材料
ikm_length uint32_t 提取密钥的原始密钥材料长度

uapi_drv_cipher_hkdf_expand_t 

typedef struct {
    uapi_drv_cipher_hash_type_t hmac_type;    /*!< 拓展密钥的HMAC算法类型。 */
    uint8_t *prk;    /*!< 拓展密钥的伪随机密钥。 */
    uint32_t prk_length;    /*!< 拓展密钥的伪随机密钥长度。 */
    uint8_t *info;    /*!< 拓展密钥的信息。 */
    uint32_t info_length;   /*!< 拓展密钥的信息长度。 */
} uapi_drv_cipher_hkdf_expand_t;

成员说明

成员名称 数据类型 描述
hmac_type uapi_drv_cipher_hash_type_t 拓展密钥的HMAC算法类型
prk uint8_t * 拓展密钥的伪随机密钥
prk_length uint32_t 拓展密钥的伪随机密钥长度
info uint8_t * 拓展密钥的信息
info_length uint32_t 拓展密钥的信息长度

uapi_drv_cipher_hkdf_t 

typedef struct {
    uapi_drv_cipher_hash_type_t hmac_type;    /*!< 提起、拓展密钥的HMAC算法类型。 */
    uint8_t *salt;    /*!< 提取密钥的盐值。 */
    uint32_t salt_length;    /*!< 提取密钥的盐值长度。 */
    uint8_t *ikm;    /*!< 提取密钥的原始密钥材料。 */
    uint32_t ikm_length;    /*!< 提取密钥的原始密钥材料长度。 */
    uint8_t *info;    /*!< 拓展密钥的信息。 */
    uint32_t info_length;    /*!< 拓展密钥的信息长度。 */
} uapi_drv_cipher_hkdf_t;

成员说明

成员名称 数据类型 描述
hmac_type uapi_drv_cipher_hash_type_t 提取、拓展密钥的HMAC算法类型
salt uint8_t * 提取密钥的盐值
salt_length uint32_t 提取密钥的盐值长度
ikm uint8_t * 提取密钥的原始密钥材料
ikm_length uint32_t 提取密钥的原始密钥材料长度
info uint8_t * 拓展密钥的信息
info_length uint32_t 拓展密钥的信息长度