本篇综述
本篇主要讲解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中具体函数的定义的将会更加充分也更容易理解。欢迎大家的阅读与点赞!