security_huks模块下hks_rkc.h代码评注

本篇综述

本篇主要讲解hks_rkc头文件代码的主要内容。hks_rkc.h中主要定义了有关RKC（root key component）根密钥组件相关的一系列结构体、枚举类型、预编译以及函数声明部分，对hks_rkc.h的了解有助于我们进一步对hks_rkc.c的理解。因此，本篇我们会重点讲解hks_rkc.h中含有的关键定义，为hks_rkc.c的解读打下基础。

代码框架

• 头文件引入
• 枚举类型定义
• 预编译模块
• 结构体定义
• 函数声明

关键代码展开

1. 枚举类型定义

该部分共定义了两个枚举类型：hks_rkc_state 和 hks_rkc_storage_type ，分别代表了根密钥组件的状态、根密钥组件存储类型。详细代码及评注如下：

/* 定义枚举类型：根密钥组件的状态*/
/* the state of root key component */
enum hks_rkc_state {
    HKS_RKC_STATE_INIT = 0,     //未初始化
    HKS_RKC_STATE_ON_INIT = 1,  //已初始化
    HKS_RKC_STATE_FAIL = 2,     //失败
    HKS_RKC_STATE_RUNNING = 3,  //正在运行
    HKS_RKC_STATE_ON_DEL = 4    //已删除（不存在）
};

/* 定义枚举类型：根密钥组件存储类型*/
/* the storage type of root key component */
enum hks_rkc_storage_type {
    /* file system 文件系统 */
    HKS_RKC_STORAGE_FILE_SYS = 0,
    /* flash */
    HKS_RKC_STORAGE_FLASH = 1
};

2. 预编译模块

该模块唯一需要注意的地方在于：长度==所占字节数，即length翻译成长度但实际意义在某文件所占有字节数。详细代码及评注如下：

/* the keystore file number of root key component 根密钥组件的密钥库文件数 */
#define HKS_RKC_KSF_NUM 2
/* the keystore file number of root key component in hilink product 链接产品中根密钥组件的密钥存储库文件号 */
#define HKS_RKC_KSF_NUM_HILINK 1

/* the max length of keystore filename 密钥库文件名的最大长度*/
#define HKS_RKC_KSF_NAME_LEN_MAX 256
/* the length of keystore buffer 密钥库缓冲区的长度 */
#define HKS_RKC_KSF_BUF_LEN 258

/* the length of keystore file flag 密钥存储库文件标志的长度 */
#define HKS_RKC_KSF_FLAG_LEN 8

/* the source number of keystore file 密钥存储库文件的源数 */
#define HKS_RKC_KSF_HASH_SRC_NUM 1

/* the material number of root key component 根密钥组件材料数 */
#define HKS_RKC_MATERIAL_NUM 2

/* the hash source number of root key component material 根密钥组件材料的哈希源数 */
#define HKS_RKC_MATERIAL_HASH_SRC_NUM 4
#define HKS_RKC_MATERIAL_HASH_SRC_NUM_NO_E 3

/* the index of sequence number 序列号的索引*/
#define HKS_RKC_MATERIAL_HASH_SRC_SN 0
/* the index of random number #1 随机数#1的索引*/
#define HKS_RKC_MATERIAL_HASH_SRC_R1 1
/* the index of random number #2 随机数#1的索引*/
#define HKS_RKC_MATERIAL_HASH_SRC_R2 2
/* the index of external entropy 外熵的索引*/
#define HKS_RKC_MATERIAL_HASH_SRC_E 3

/* the index of material1 材料1的索引*/
#define HKS_RKC_HASH_RESULT_MATERIAL1 0
/* the index of material2 材料1的索引*/
#define HKS_RKC_HASH_RESULT_MATERIAL2 1

/* the sequence number of material1 材料1的序列号*/
#define HKS_RKC_MATERIAL1_SN 1
/* the sequence number of material2 材料2的序列号*/
#define HKS_RKC_MATERIAL2_SN 2

/* the material length of root key component 根密钥组件材料长度*/
#define HKS_RKC_MATERIAL_LEN 32

/* the raw key length of root key component 根密钥组件原始密钥长度*/
#define HKS_RKC_RAW_KEY_LEN 64

/* the IV length of root key component 根密钥组件的IV长度*/
#define HKS_RKC_IV_LEN 32

/* the salt length of root key component 根密钥组件椒盐化长度*/
#define HKS_RKC_SALT_LEN 32

/* the hash value length of root key component 根密钥组件hash值长度*/
#define HKS_RKC_HASH_LEN 32

/* the iterator number of times which derive Root Master Key 派生根主密钥的迭代次数*/
#define HKS_RKC_RMK_ITER 1
#define HKS_RKC_RMK_ITER_MAX 10000

/* the hash algorithm which derive Root Master Key 派生根主密钥使用的hash算法*/
#define HKS_RKC_RMK_HMAC_SHA256 1

/* the version of root key component 根密钥组件的版本*/
#define HKS_RKC_VER 1

/* the length of root master key 根主密钥的长度*/
#define HKS_RKC_RMK_LEN 64

/* the encryption key length of root master key 根主密钥加密密钥的长度*/
#define HKS_RKC_RMK_EK_LEN 32
/* the integrity key length of root master key 根主密钥完整密钥长度*/
#define HKS_RKC_RMK_IK_LEN 32

/* the HMAC flag of root master key 根主密钥HMAC标记*/
#define HKS_RKC_RMK_HMAC_FLAG 1

/* the max length of external entropy 最大外熵大小*/
#define HKS_RKC_ENTROPY_LEN_MAX 256

/* the reserve length of the system configuration 系统配置预留长度*/
#define HKS_RKC_CFG_RSV_LEN 32

/* the reserve length of the keystore file data 密钥库文件数据预留长度*/
#define HKS_RKC_KSF_DATA_RSV_LEN 8

/* the delete flag of the keystore file 密钥库文件删除标记*/
#define HKS_RKC_KSF_NO_DEL_FLAG 0
#define HKS_RKC_KSF_DEL_FLAG 1

/* the length of master key 主密钥长度*/
#define HKS_RKC_MK_LEN 32

/* the encrypt algorithm of master key 主密钥加密算法*/
#define HKS_RKC_MK_CRYPT_ALG_AES256_GCM 1
/* the cipher length of master key 主密钥的密码长度*/
#define HKS_RKC_MK_CIPHERTEXT_LEN 48
/* the tag length of master key 主密钥的tag长度*/
#define HKS_RKC_MK_TAG_LEN 16
/* the iv length of master key 主密钥的iv长度*/
#define HKS_RKC_MK_IV_LEN 16
/* the additional data length of master key 主密钥的附加数据长度*/
#define HKS_RKC_MK_ADD_DATA_LEN 8

/* the max length of salt for key-encrypting key 加密密钥椒盐化的最长长度*/
#define HKS_RKC_KEK_SALT_LEN_MAX 32
/* the min length of salt for key-encrypting key 加密密钥椒盐化的最短长度*/
#define HKS_RKC_KEK_SALT_LEN_MIN 8
/* the length of key-encrypting key 加密密钥的长度*/
#define HKS_RKC_KEK_LEN 32
/* the iterator number for key-encrypting key 加密密钥的迭代次数*/
#define HKS_RKC_KEK_ITER 1

/* the crypt operation 加密操作 */
#define HKS_RKC_ENCRYPT 0
#define HKS_RKC_DECRYPT 1

/* the length of root key 根密钥长度 */
#define HKS_ROOT_KEY_LEN 32

3. 结构体定义

• hks_rkc_mk 和 hks_rkc_rmk
  这两个结构体定义了主密钥、根主密钥的相关信息，详细代码及评注如下：

/* 定义结构体：主密钥（键）*/
/* master key */
struct hks_rkc_mk {
    /* whether master key is valid 主密钥是否合法*/
    uint8_t is_valid;
    /* the created time of master key 主密钥的创建时间 */
    struct hks_time mk_created_time;
    /* the expired time of master key 主密钥的过期时间 */
    struct hks_time mk_expired_time;
    /* the master key with mask 主密钥掩码 */
    uint8_t mk_with_mask[HKS_RKC_MK_LEN];
};

//定义结构体：根主密钥（键）
/* the root master key*/
//rkc:root key component. rmk:root master key 
struct hks_rkc_rmk {
    /* the encryption key 加密密钥 */
    uint8_t ek[HKS_RKC_RMK_EK_LEN];
    /* the integrity key 完整密钥 */
    uint8_t ik[HKS_RKC_RMK_EK_LEN];
};

• hks_rkc_init_para
  该结构体定义了根密钥组件的初始化参数相关的信息，详细代码及评注如下：

/* 定义结构体：根密钥组件的初始化参数 */
/* the initialization parameter of root key component */
struct hks_rkc_init_para {
    /* the version of root key component 根密钥组件版本 */
    uint16_t version;
    /* the storage type of root key component 根密钥组件的存储类型 */
    uint8_t storage_type;
    /* the attribute of keystore file 密钥库文件的属性 */
    struct hks_rkc_ksf_attr ksf_attr;
    /* the iterator number of times which derive Root Master Key 派生根主密钥（键）的迭代次数 */
    uint32_t rmk_iter;
    /* the hash algorithm which derive Root Master Key 派生根主密钥（键）使用的hash算法 */
    uint32_t rmk_hash_alg;
    /* external entropy, optionally, it could be empty 外部熵，可为空 */
    uint8_t *entropy;
    /* the length external entropy 外部熵的长度 */
    uint32_t entropy_len;
    /* the encrption algorithm of master key 主密钥的加密算法 */
    uint32_t mk_encrypt_alg;
    /* the hash algorithm for key-encrypting key 密钥加密密钥的哈希算法 */
    uint32_t kek_hash_alg;
    /* the iterator number for key-encrypting key 密钥加密密钥的迭代次数 */
    uint32_t kek_iter;
};

• hks_rkc_cfg
  该结构体定义了根密钥组件的配置的相关信息，详细代码及评注如下：

/* 定义结构体：根密钥组件的配置 */
/* the configuration of root key component */
struct hks_rkc_cfg {
    /* system state 系统状态 */
    uint8_t state;
    /* the version of root key component 根密钥组件版本 */
    uint16_t version;
    /* the storage type of root key component 根密钥组件的存储类型 */
    uint8_t storage_type;
    /* the created time of rook key 根密钥的建立时间 */
    struct hks_time rk_created_time;    //hks_time结构体类型从年精确到秒
    /* the expired time of rook key 根密钥的过期时间 */
    struct hks_time rk_expired_time;
    /* the attribute of keystore file 密钥库文件的属性 */
    struct hks_rkc_ksf_attr ksf_attr;
    /* the iterator number of times which derive Root Master Key 派生根主密钥（键）的迭代次数 */
    uint32_t rmk_iter;
    /* the hash algorithm which derive Root Master Key 派生根主密钥（键）使用的hash算法 */
    uint32_t rmk_hash_alg;
    /* external entropy 外熵 */
    uint8_t *entropy;
    /* the length external entropy 外熵的长度 */
    uint32_t entropy_len;
    /* the mask of master key 主密钥（键）掩码*/
    uint8_t mk_mask[HKS_RKC_MK_LEN];
    /* the encrption algorithm of master key 主密钥的加密算法 */
    uint32_t mk_encrypt_alg;
    /* the hash algorithm for key-encrypting key 密钥加密密钥的哈希算法 */
    uint32_t kek_hash_alg;
    /* the iterator number for key-encrypting key 密钥加密密钥的迭代次数*/
    uint32_t kek_iter;
    /* reserve data, 32 byte 保留数据，32个字节*/
    uint8_t reserve[HKS_RKC_CFG_RSV_LEN];
};

• hks_rkc_ksf_data
  该结构体定义了根密钥组件的密钥库文件数据相关信息，详细代码及评注如下：

/* 定义结构体：根密钥组件的密钥库文件数据 */
/* the keystore file data of root key component */
struct hks_rkc_ksf_data {
    /* version 版本（号）*/
    uint16_t version;
    /* the created time of rook key 根密钥的建立时间 */
    struct hks_time rk_created_time;
    /* the expired time of rook key 根密钥的过期时间 */
    struct hks_time rk_expired_time;
    /* the first material of root key 根密钥的第一个材料 */
    uint8_t rk_material1[HKS_RKC_MATERIAL_LEN];
    /* the second material of root key 根密钥的第二个材料 */
    uint8_t rk_material2[HKS_RKC_MATERIAL_LEN];
    /* the iterator number of times which derive root master key 派生根主密钥（键）的迭代次数 */
    uint32_t rmk_iter;
    /* the salt which derive root master key 派生根主密钥的椒盐化*/
    uint8_t rmk_salt[HKS_RKC_SALT_LEN];
    /* the hash algorithm which derive root master key 派生根主密钥（键）使用的hash算法 */
    uint32_t rmk_hash_alg;
    /* mk_rsv data for root key, 32 byte 根密钥的主密钥rsv数据，32字节*/
    uint8_t rk_rsv[HKS_RKC_KSF_DATA_RSV_LEN];
    /* the created time of master key 主密钥的创建时间*/
    struct hks_time mk_created_time;
    /* the expired time of master key 主密钥的过期时间*/
    struct hks_time mk_expired_time;
    /* the encrption algorithm of master key 主密钥使用的加密算法*/
    uint32_t mk_encrypt_alg;
    /* the IV of master key 主密钥的IV */
    uint8_t mk_iv[HKS_RKC_MK_IV_LEN];
    /* the ciphertext of master key 主密钥的密文 */
    uint8_t mk_ciphertext[HKS_RKC_MK_CIPHERTEXT_LEN];
    /* mk_rsv data for master key, 32 byte 主密钥的主密钥rsv数据，32字节*/
    uint8_t mk_rsv[HKS_RKC_KSF_DATA_RSV_LEN];
};

• ks_rkc_ksf_attr
  结构体定义了密钥库文件属性，详细代码及评注如下：

/*定义结构体：密钥库文件属性*/
/* the attribute of keystore file */
struct hks_rkc_ksf_attr {
    uint8_t num;                //标识码
    char *name[HKS_RKC_KSF_NUM];//密钥库文件名
};

4. 函数声明

声明的函数分别是：

• hks_rkc_init
• hks_rkc_destroy
• hks_rkc_clear_mem
• hks_rkc_get_kek

这4个函数的函数功能分别是根密钥组件的初始化、根密钥组件的销毁、根密钥组件的内存清理以及获取密钥加密密钥，它们的传入参数以及返回值见下面的代码评注：

/* 函数名：根密钥组件-初始化
 * root key component - initialize
 * 
 * 传入参数：根密钥组件初始化参数、密钥信息的存在参数
 * parameter:
 *     init_para          - [in] - the system initialize parameter.
 *     is_key_info_exist  - [in] - is key info exist.
 * 
 * 返回值：成功或错误代码
 * return value:
 *     success or error code
 */
//
int32_t hks_rkc_init(const struct hks_rkc_init_para *init_para,
    int32_t is_key_info_exist);

/* 函数名：根密钥组件-销毁
 * root key component - destroy
 * 
 * 传入参数：无
 * parameter: none
 * 
 * 返回值：无
 * return value: none
 */
void hks_rkc_destroy(void);

/*函数名：根密钥组件-内存清理
 * root key component - clear memory
 * 
 * 传入参数：无
 * parameter: none
 * 
 * 返回值：无
 * return value: none
 */
void hks_rkc_clear_mem(void);

/*函数名：根密钥组件-获取密钥加密密钥
 * root key component - get the key-encrypting key
 * 
 * 传入参数：椒盐化密钥、密钥加密密钥
 * parameter:
 *     salt      - [in]  - salt,
 *     kek       - [out] - key-encrypting key,
 *     使用后必须由调用者清除  it must be cleared by caller after use.
 * 
 * 返回值：成功或错误代码
 * return value:
 *     success or error code
 */
int32_t hks_rkc_get_kek(const struct hks_blob *salt, struct hks_blob *kek);

本篇小结

本篇主要内容集中在对密钥组件结构体的定义以及函数的声明上，在充分了解了这些变量与函数后，对hks_rkc.c中具体函数的定义的将会更加充分也更容易理解。欢迎大家的阅读与点赞！