security_huks模块下hks_rkc.c代码评注第六部分
本篇概述
本篇是接着:
- security_huks模块下hks_rkc.c代码评注第一部分
- security_huks模块下hks_rkc.c代码评注第二部分
- security_huks模块下hks_rkc.c代码评注第三部分
- security_huks模块下hks_rkc.c代码评注第四部分
- security_huks模块下hks_rkc.c代码评注第五部分
在讲解完密钥的生成、为密钥加掩码、密钥内存的恢复相关操作后,本篇将继续讲述hks_rkc.c代码中有关初始化工作的最后一部分代码。
代码框架
hks_rkc.c
│ └── hks_rkc_chk_init_para
│ └── hks_rkc_init_ksf
│ └── hks_rkc_init
│ └── hks_rkc_destroy
│ └── hks_rkc_chk_kek_para
│ └── hks_rkc_get_kek
代码详解
1. hks_rkc_chk_init_para
-
函数功能:检查初始化参数
root key component - check initialization parameter -
参数说明:初始化参数
parameter:
init_para - [in] - initialization parameter. -
返回值:成功或错误代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_chk_init_para(const struct hks_rkc_init_para *init_para)
{
//这个函数仅仅被用作检查函数hks_rkc_init()的参数
/* This function is only used for the parameter check of hks_rkc_init() */
//检查根密钥组件的存储类型
if ((init_para->storage_type != HKS_RKC_STORAGE_FILE_SYS) &&
(init_para->storage_type != HKS_RKC_STORAGE_FLASH)) {
log_error("invalid para,storage_type=%u", init_para->storage_type);
return HKS_ERROR_INVALID_ARGUMENT;
}
//检查派生根主密钥的迭代次数
if ((init_para->rmk_iter == 0) ||
(init_para->rmk_iter > HKS_RKC_RMK_ITER_MAX)) {
log_error("invalid para,rmk_iter=%u", init_para->rmk_iter);
return HKS_ERROR_INVALID_ARGUMENT;
}
//检查派生根主密钥使用的hash算法是否为SHA256
if (init_para->rmk_hash_alg != HKS_RKC_RMK_HMAC_SHA256) {
log_error("invalid para,rmk_hash_alg=%u",
init_para->rmk_hash_alg);
return HKS_ERROR_INVALID_ARGUMENT;
}
//检查密钥库文件个数
if ((init_para->ksf_attr.num == 0) ||
(init_para->ksf_attr.num > HKS_RKC_KSF_NUM)) {
log_error("invalid para,num=%u", init_para->ksf_attr.num);
return HKS_ERROR_INVALID_ARGUMENT;
}
return HKS_STATUS_OK;
}
2. hks_rkc_init_ksf
-
函数功能:初始化密钥库文件
root key component - initialize -
参数说明:密钥信息存在性
parameter:
is_key_info_exist - [in] - is key info exist. -
返回值:成功或错误代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_init_ksf(int32_t is_key_info_exist)
{
//从密钥库文件中载入根密钥组件数据,调用函数hks_rkc_load_ksf
/* load the root key component data from keystore file. */
int32_t rc = hks_rkc_load_ksf(NULL);//载入密钥库文件
//如果密钥库文件载入失败并且没有密钥存在,尝试去重新创建它,调用函数hks_rkc_create_ksf
/*
* if the keystore file is failed to load and no key is exist,
* try to recreate it.
*/
if ((rc != HKS_STATUS_OK) && (is_key_info_exist == HKS_BOOL_FALSE))
rc = hks_rkc_create_ksf();//创建密钥库文件
return rc;
}
3. hks_rkc_init
-
函数功能:初始化(集成)
root key component - initialize -
参数说明:初始化参数、密钥信息存在性
parameter:
init_para - [in] - initialization 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)
{
//定义根密钥组件初始化参数结构体指针init_para_inner,并做赋值
const struct hks_rkc_init_para *init_para_inner = init_para;
//检查传入参数是否为空
if (init_para_inner == NULL)
init_para_inner = &g_hks_rkc_def_init_para;
//检查初始化参数
int32_t rc = hks_rkc_chk_init_para(init_para_inner);
if (rc != HKS_STATUS_OK)
return rc;
//检查根密钥组件的配置状态
if (g_hks_rkc_cfg.state != HKS_RKC_STATE_INIT)
return HKS_STATUS_OK;
//日志信息写入,并做好根密钥组件配置信息的赋值
log_info("RKC init:begin, is_key_info_exist=%d", is_key_info_exist);
do {
g_hks_rkc_cfg.state = HKS_RKC_STATE_ON_INIT;
g_hks_rkc_cfg.version = init_para_inner->version;
g_hks_rkc_cfg.storage_type = init_para_inner->storage_type;
g_hks_rkc_cfg.rmk_iter = init_para_inner->rmk_iter;
g_hks_rkc_cfg.rmk_hash_alg = init_para_inner->rmk_hash_alg;
g_hks_rkc_cfg.mk_encrypt_alg = init_para_inner->mk_encrypt_alg;
g_hks_rkc_cfg.kek_hash_alg = init_para_inner->kek_hash_alg;
g_hks_rkc_cfg.kek_iter = init_para_inner->kek_iter;
//初始化密钥库文件的属性
/* Initialize the attribute of keystore file */
rc = hks_rkc_init_ksf_attr(&(init_para_inner->ksf_attr));
if (rc != HKS_STATUS_OK)
break;
//初始化熵
/* Initialize entropy */
rc = hks_rkc_init_entropy(init_para_inner->entropy,
init_para_inner->entropy_len);
if (rc != HKS_STATUS_OK)
break;
//初始化密钥库文件的根密钥组件
/* Initialize the keystore file of root key component. */
rc = hks_rkc_init_ksf(is_key_info_exist);
if (rc != HKS_STATUS_OK)
break;
g_hks_rkc_cfg.state = HKS_RKC_STATE_RUNNING;
log_info("root key component init success");
} while (0);
//进行内存空间的销毁以保证密钥的安全性
if (rc != HKS_STATUS_OK) {
g_hks_rkc_cfg.state = HKS_RKC_STATE_FAIL;
hks_rkc_destroy();
}
log_info("RKC init:end,rc=%d", rc);
return rc;
}
4. hks_rkc_destroy
-
函数功能:销毁工作
root key component - destory -
无传参
parameter: none -
无返回值
return value: none
详细代码及评注如下:
void hks_rkc_destroy(void)
{
//更改根密钥组件配置状态为已删除状态
g_hks_rkc_cfg.state = HKS_RKC_STATE_ON_DEL;
uint32_t i = 0;
//安全删除密钥库文件属性名中的部分
for (; i < HKS_RKC_KSF_NUM; ++i)
hks_file_del_s(g_hks_rkc_cfg.ksf_attr.name[i]);
//清除内存空间
hks_rkc_clear_mem();
}
5. hks_rkc_clear_mem
-
函数功能:清理内存
root key component - clear memory -
无传参
parameter: none -
无返回值
return value: none
详细代码及评注如下:
void hks_rkc_clear_mem(void)
{
uint32_t i = 0;
//对已申请所有密钥库文件空间的释放
for (; i < HKS_RKC_KSF_NUM; ++i)
hks_free_ptr(g_hks_rkc_cfg.ksf_attr.name[i]);
//对熵的释放
hks_free_ptr(g_hks_rkc_cfg.entropy);
//将根密组件配置内的信息置零
(void)memset_s(&g_hks_rkc_cfg, sizeof(g_hks_rkc_cfg), 0,
sizeof(g_hks_rkc_cfg));
//将根密钥组件的主密钥内存空间信息置零
(void)memset_s(&g_hks_rkc_mk, sizeof(g_hks_rkc_mk), 0,
sizeof(g_hks_rkc_mk));
}
6. hks_rkc_chk_kek_para
-
函数功能:检查密钥加密密钥的参数
root key component - check the parameter of key-encrypting key -
参数说明:盐化值、密钥加密密钥
parameter:
salt - [in] - salt,
kek - [in] - key-encrypting key, -
返回值:成功或失败代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_chk_kek_para(const struct hks_blob *salt,
const struct hks_blob *kek)
{
//检查盐化值是否为空
if (salt == NULL) {
log_error("invalid salt");
return HKS_ERROR_NULL_POINTER;
}
//检查盐化值内是否有数据
if (salt->data == NULL) {
log_error("invalid salt data");
return HKS_ERROR_NULL_POINTER;
}
//检查盐化值大小是否合规
if ((salt->size > HKS_RKC_KEK_SALT_LEN_MAX) ||
(salt->size < HKS_RKC_KEK_SALT_LEN_MIN)) {
log_error("invalid salt size=%u", salt->size);
return HKS_ERROR_INVALID_ARGUMENT;
}
//检查密钥加密密钥是否为空
if (kek == NULL) {
log_error("invalid kek");
return HKS_ERROR_NULL_POINTER;
}
//检查密钥加密密钥是否有数据
if (kek->data == NULL) {
log_error("invalid kek data");
return HKS_ERROR_NULL_POINTER;
}
//检查密钥加密密钥是否大小合规
if (kek->size != HKS_RKC_KEK_LEN) {
log_error("invalid kek size=%u", kek->size);
return HKS_ERROR_INVALID_ARGUMENT;
}
return HKS_STATUS_OK;
}
7. hks_rkc_get_kek
-
函数功能:获取密钥加密密钥
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)
{
//检查主密钥是否有效
if (g_hks_rkc_mk.is_valid == HKS_BOOL_FALSE) {
log_error("mk is valid");
return HKS_ERROR_INVALID_KEY_FILE;
}
//检查密钥加密密钥的参数
int32_t rc = hks_rkc_chk_kek_para(salt, kek);
if (rc != HKS_STATUS_OK)
return rc;
//定义主密钥结构体
struct hks_blob mk;
//主密钥的初始化
rc = hks_blob_init(&mk, sizeof(uint8_t), HKS_RKC_MK_LEN,
HKS_BLOB_TYPE_KEY);
if (rc != HKS_STATUS_OK)
return rc;
//定义并初始化主密钥掩码以及带着主密钥掩码的主密钥
struct hks_blob mk_mask = { HKS_BLOB_TYPE_KEY, g_hks_rkc_cfg.mk_mask, HKS_RKC_MK_LEN };
struct hks_blob mk_with_mask = { HKS_BLOB_TYPE_KEY, g_hks_rkc_mk.mk_with_mask, HKS_RKC_MK_LEN };
//掩码的移动,利用异或将mk_with_mask和mk_mask异或结果存入主密钥mk中
/* remove mask */
hks_xor(&mk_with_mask, &mk_mask, &mk);
//使用pbkdf2_hmac算法获取派生密钥
/* derive kek with PBKDF2-HMAC */
rc = hks_rkc_pbkdf2_hmac(g_hks_rkc_cfg.kek_hash_alg, &mk, salt,
g_hks_rkc_cfg.kek_iter, kek);
//将主密钥内存空间销毁
hks_blob_destroy(&mk);
return rc;
}
本篇小结
有关根密钥组件相关算法、定义以及操作相关函数已经全部讲解完毕,欢迎大家阅读及评论!