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_mk_crypt
│ └── hks_rkc_mask_mk
│ └── hks_rkc_make_mk
│ └── hks_rkc_create_ksf
├── 密钥内存恢复
│ └── hks_rkc_recover_mk_mem
│ └── hks_rkc_recover_rk_mem
│ └── hks_rkc_load_ksf
密钥加密、生成与掩码
1. hks_rkc_mk_crypt
-
函数功能:为主密钥做加密操作
root key component - do crypt operation for master key -
参数说明:为密钥库文件载入的数据、主密钥对应明文(输入输出)、主密钥对应密文(输入输出)、操作(包含根密钥组件的加密与解密)
parameter:
ksf_data - [in] - the data which loaded from keystore file.
plaintext - [in,out] - the plaintext of master key
ciphertext - [in,out] - the ciphertext of master key
operation - [in] - operation, HKS_RKC_ENCRYPT or HKS_RKC_DECRYPT. -
返回值:成功或错误代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_mk_crypt(struct hks_rkc_ksf_data *ksf_data,
struct hks_blob *plaintext, struct hks_blob *ciphertext,
uint8_t operation)
{
//为根主密钥开辟存储空间
uint8_t *rmk = (uint8_t *)HKS_MALLOC(HKS_RKC_RMK_LEN);
//检查是否成功开辟空间
if (rmk == NULL) {
log_error("malloc rmk fail");
return HKS_ERROR_MALLOC_FAIL;
}
int32_t rc;
do {
//获取派生根主密钥,将根主密钥存放在rmk中
rc = hks_rkc_derive_rmk(ksf_data, rmk, HKS_RKC_RMK_LEN);
if (rc != HKS_STATUS_OK)
break;
//创建变量key,内部存放根主密钥数据
struct hks_blob key = { HKS_BLOB_TYPE_KEY, rmk, HKS_RKC_RMK_EK_LEN };
//创建密钥参数、aead数据等变量
size_t output_len = 0;
struct hks_key_param key_param;
struct hks_aead_data aead_data;
//将key_param、aead_data的内存数据初始化为0
(void)memset_s(&key_param, sizeof(key_param), 0, sizeof(key_param));
(void)memset_s(&aead_data, sizeof(aead_data), 0, sizeof(aead_data));
//将一系列默认参数,与明文密文信息写入
key_param.key_len = HKS_MAX_KEY_LEN_256;
key_param.key_type = HKS_KEY_TYPE_AES;
key_param.key_mode = HKS_ALG_GCM;
aead_data.nonce = ksf_data->mk_iv;
aead_data.nonce_length = HKS_RKC_MK_IV_LEN;
aead_data.additional_data = g_hks_rkc_mk_add_data;
aead_data.additional_data_length = HKS_RKC_MK_ADD_DATA_LEN;
aead_data.ciphertext = ciphertext->data;
aead_data.ciphertext_length = ciphertext->size;
aead_data.plaintext = plaintext->data;
aead_data.plaintext_length = plaintext->size;
//依据传入参数operation来决定是进行主密钥对应密文的加密还是解密
if (operation == HKS_RKC_ENCRYPT) {
//调用aead算法加密
rc = hks_mbedtls_aead_encrypt(&key, &key_param,
&aead_data, &output_len);
} else if (operation == HKS_RKC_DECRYPT) {
//调用aead算法解密
rc = hks_mbedtls_aead_decrypt(&key, &key_param,
&aead_data, &output_len);
} else {
//错误操作判定
log_error("invalid operation=%u", operation);
rc = HKS_ERROR_INVALID_ARGUMENT;
break;
}
if (rc != HKS_STATUS_OK) {
log_error("mbedtls aead encrypt fail, rc=%d", rc);
break;
}
} while (0);
//根密钥的数据在使用后应清除
/* the data of root key should be cleared after use */
(void)memset_s(rmk, HKS_RKC_RMK_LEN, 0, HKS_RKC_RMK_LEN);
hks_free_ptr(rmk);
return rc;
}
2. hks_rkc_mask_mk
- 函数功能:对主密钥进行掩码
root key component - mask master key - 参数说明:输入掩码参数
parameter:
mk - [in] - mask. - 返回值:无
return value: none
详细代码及评注如下:
static void hks_rkc_mask_mk(const struct hks_blob *mk)
{
//定义有关主密钥掩码的结构体变量
//g_hks_rkc_cfg.mk_mask为根密钥组件的配置中的主密钥掩码
//g_hks_rkc_mk.mk_with_mask为主密钥的数据中的主密钥掩码
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 };
hks_xor(mk, &mk_mask, &mk_with_mask);
//将主密钥设置为合法
g_hks_rkc_mk.is_valid = HKS_BOOL_TRUE;
}
该部分中的掩码操作实质上就是异或操作,主要代码调用了hks_common.c中的函数hks_xor,下面给出函数hks_xor的详细解释:
- 函数功能:异或操作
XOR operation - 参数说明:1号和2号数据源、结果
parameter:
src1 - [in] - source data #1.
src2 - [in] - source data #2.
result - [out] - result. - 返回值:无
return value: none
详细代码如下:
void hks_xor(const struct hks_blob* src1, const struct hks_blob* src2,
struct hks_blob* result)
{
//判空操作
if ((src1 == NULL) || (src2 == NULL) || (result == NULL))
return;
//确定异或操作的位数,取更小的为xor_len
uint32_t xor_len = (src1->size < src2->size) ? src1->size : src2->size;
if (xor_len > result->size)
xor_len = result->size;
uint32_t i;
//执行异或操作
for (i = 0; i < xor_len; ++i)
result->data[i] = src1->data[i] ^ src2->data[i];
}
3. hks_rkc_make_mk
-
函数功能:生成主密钥
root key component - make master key -
参数说明:为密钥库文件载入的数据
parameter:
ksf_data - [in,out] - the data which loaded from keystore file. -
返回值:成功或错误代码
return value:
success or error code
生成主密钥的主要思路是利用生成随机数函数hks_gen_random生成主密钥的掩码、IV以及主密钥本身,然后对定义好的密文数据调用为主密钥加密函数hks_rkc_mk_crypt,使用aead算法对其进行解密,得到最终的数据即为我们想要的主密钥。详细代码及评注如下:
static int32_t hks_rkc_make_mk(struct hks_rkc_ksf_data *ksf_data)
{
//定义并初始化主密钥mk
struct hks_blob mk;
int32_t rc = hks_blob_init(&mk, sizeof(uint8_t), HKS_RKC_MK_LEN,
HKS_BLOB_TYPE_KEY);
//检查初始化状态
if (rc != HKS_STATUS_OK) {
log_error("init mk fail");
return HKS_ERROR_MALLOC_FAIL;
}
do {
//将主密钥的加密算法写入ksf_data中
ksf_data->mk_encrypt_alg = g_hks_rkc_cfg.mk_encrypt_alg;
//生成主密钥掩码(利用生成随机数函数hks_gen_random)
/* generate the mask of master key */
rc = hks_gen_random(g_hks_rkc_cfg.mk_mask, HKS_RKC_MK_LEN);
if (rc != HKS_STATUS_OK)
break;
//生成主密钥
/* generate master key */
rc = hks_gen_random(mk.data, mk.size);
if (rc != HKS_STATUS_OK)
break;
//生成主密钥IV
/* generate the IV of master key */
rc = hks_gen_random(ksf_data->mk_iv, HKS_RKC_MK_IV_LEN);
if (rc != HKS_STATUS_OK)
break;
//定义并初始化主密钥密文
struct hks_blob ciphertext = { HKS_BLOB_TYPE_KEY, ksf_data->mk_ciphertext, HKS_RKC_MK_CIPHERTEXT_LEN };
//调用为主密钥加密函数hks_rkc_mk_crypt,使用aead算法对其进行解密
rc = hks_rkc_mk_crypt(ksf_data, &mk, &ciphertext,
HKS_RKC_ENCRYPT);
if (rc != HKS_STATUS_OK)
break;
//在内存中的主密钥需要做掩码操作
/* the master key in memory should be masked */
hks_rkc_mask_mk(&mk);
} while (0);
//释放主密钥内存空间
hks_blob_destroy(&mk);
return rc;
}
4. hks_rkc_create_ksf
-
函数功能:创建密钥库文件
root key component - creat keystore file -
无参数
parameter: none -
返回值:成功或错误代码
return value:
success or error code
创建密钥库文件的思路是生成一个新的密钥库文件数据(包括:版本号、根主密钥迭代次数、根主密钥使用的hash算法、两个材料、盐化值、主密钥),接着调用函数hks_rkc_write_all_ksf将根密钥组件数据写入所有的密钥库文件中。详细代码及评注如下:
static int32_t hks_rkc_create_ksf(void)
{
//定义根密钥组件的密钥库文件数据结构体变量new_ksf_data并做内存空间分配
struct hks_rkc_ksf_data *new_ksf_data =
(struct hks_rkc_ksf_data *)HKS_MALLOC(HKS_RKC_KSF_DATA_SIZE);
if (new_ksf_data == NULL) {
log_error("malloc ksf data fail");
return HKS_ERROR_MALLOC_FAIL;
}
//根密钥组件数据在一开始必须被清除(置零)
/* The root key component data must be clear firstly. */
(void)memset_s(new_ksf_data, HKS_RKC_KSF_DATA_SIZE, 0,
HKS_RKC_KSF_DATA_SIZE);
int32_t rc;
do {
//填写一些固定的数据,包括版本号、根主密钥迭代次数、根主密钥使用的hash算法
/* Fill some fixed field. */
new_ksf_data->version = g_hks_rkc_cfg.version;
new_ksf_data->rmk_iter = g_hks_rkc_cfg.rmk_iter;
new_ksf_data->rmk_hash_alg = g_hks_rkc_cfg.rmk_hash_alg;
//两个材料都是由随机数生成
/* Two material are generated by random number. */
rc = hks_rkc_make_random_material(new_ksf_data);
if (rc != HKS_STATUS_OK) {
log_error("generate material fail,rc=%d", rc);
break;
}
//盐化值也是由随机数生成
/* The salt value is generated by random number. */
rc = hks_gen_random(new_ksf_data->rmk_salt, HKS_RKC_SALT_LEN);
if (rc != HKS_STATUS_OK) {
log_error("generate rmk_salt fail,rc=%d", rc);
break;
}
//创建主密钥
/* make master key. */
rc = hks_rkc_make_mk(new_ksf_data);
if (rc != HKS_STATUS_OK) {
log_error("make mk fail,rc=%d", rc);
break;
}
//将根密钥组件数据写入所有的密钥库文件中
/* Write the root key component data into all keystore files */
rc = hks_rkc_write_all_ksf(new_ksf_data);
if (rc != HKS_STATUS_OK)
break;
//更新日志信息
log_info("create root key component success");
} while (0);
//根密钥数据需要在使用完后被清理
/* the data of root key should be cleared after use */
(void)memset_s(new_ksf_data, HKS_RKC_KSF_DATA_SIZE, 0,
HKS_RKC_KSF_DATA_SIZE);
hks_free_ptr(new_ksf_data);//释放内存空间
return rc;
}
密钥内存恢复
1. hks_rkc_recover_mk_mem
-
函数功能:恢复主密钥内存
root key component - recover master key memory -
参数说明:为密钥库文件载入的数据
parameter:
ksf_data - [in] - the data which loaded from keystore file. -
返回值:成功或错误代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_recover_mk_mem(struct hks_rkc_ksf_data *ksf_data)
{
//将ksf_data中的主密钥创建时间复制到事先定义好的主密钥数据g_hks_rkc_mk中
int32_t rc = memcpy_s(&(g_hks_rkc_mk.mk_created_time),
sizeof(g_hks_rkc_mk.mk_created_time),
&(ksf_data->mk_created_time),
sizeof(ksf_data->mk_created_time));
if (rc != HKS_STATUS_OK)
return HKS_ERROR_INTERNAL_UNKOWN;
将ksf_data中的主密钥过期时间复制到事先定义好的主密钥数据g_hks_rkc_mk中
rc = memcpy_s(&(g_hks_rkc_mk.mk_expired_time),
sizeof(g_hks_rkc_mk.mk_expired_time),
&(ksf_data->mk_expired_time),
sizeof(ksf_data->mk_expired_time));
if (rc != HKS_STATUS_OK)
return HKS_ERROR_INTERNAL_UNKOWN;
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) {
log_error("init mk fail");
return HKS_ERROR_MALLOC_FAIL;
}
do {
//调用生成随机数函数生成主密钥的掩码
/* generate the mask of master key */
rc = hks_gen_random(g_hks_rkc_cfg.mk_mask, HKS_RKC_MK_LEN);
if (rc != HKS_STATUS_OK)
break;
struct hks_blob ciphertext = { HKS_BLOB_TYPE_KEY, ksf_data->mk_ciphertext, HKS_RKC_MK_CIPHERTEXT_LEN };
//为主密钥做解密操作HKS_RKC_DECRYPT
rc = hks_rkc_mk_crypt(ksf_data, &mk, &ciphertext,
HKS_RKC_DECRYPT);
if (rc != HKS_STATUS_OK) {
rc = HKS_ERROR_INVALID_KEY_FILE;
break;
}
//在内存中的主密钥需要做掩码操作
/* the master key in memory should be masked */
hks_rkc_mask_mk(&mk);
} while (0);
//释放主密钥空间
hks_blob_destroy(&mk);
return rc;
}
2. hks_rkc_recover_rk_mem
-
函数功能:恢复根密钥内存
root key component - recover root key memory -
参数说明:为密钥库文件载入的数据
parameter:
ksf_data - [in] - the data which loaded from keystore file. -
返回值:成功或错误代码
return value:
success or error code
详细代码及评注如下:
static int32_t hks_rkc_recover_rk_mem(const struct hks_rkc_ksf_data *ksf_data)
{
//将ksf_data中的根密钥创建时间复制到事先定义好的根密钥组件配置g_hks_rkc_cfg中
int32_t rc = memcpy_s(&(g_hks_rkc_cfg.rk_created_time),
sizeof(g_hks_rkc_cfg.rk_created_time),
&(ksf_data->rk_created_time),
sizeof(ksf_data->rk_created_time));
if (rc != HKS_STATUS_OK)
return HKS_ERROR_INTERNAL_UNKOWN;
将ksf_data中的根密钥过期时间复制到事先定义好的根密钥组件配置g_hks_rkc_cfg中
rc = memcpy_s(&(g_hks_rkc_cfg.rk_expired_time),
sizeof(g_hks_rkc_cfg.rk_expired_time),
&(ksf_data->rk_expired_time),
sizeof(ksf_data->rk_expired_time));
if (rc != HKS_STATUS_OK)
return HKS_ERROR_INTERNAL_UNKOWN;
return HKS_STATUS_OK;
}
3. hks_rkc_load_ksf
-
函数功能:载入密钥库文件
root key component - load keystore file -
参数说明:密钥库文件数据
parameter:
ksf_data - [out] - the data of keystore file. -
返回值:成功或错误代码
return value:
success or error code
该部分是对上面定义函数的一个封装,包括读取所有密钥库文件、恢复根密钥内存、恢复主密钥内存、检查所有密钥库文件等。详细代码及评注如下:
static int32_t hks_rkc_load_ksf(struct hks_rkc_ksf_data *ksf_data)
{
int32_t all_ksf_rc[HKS_RKC_KSF_NUM] = {0};
uint32_t data_size = HKS_RKC_KSF_DATA_SIZE * HKS_RKC_KSF_NUM;
//定义hks_rkc_ksf_data结构体变量all_ksf_data以放所有密钥库文件数据,并做内存空间的分配
struct hks_rkc_ksf_data *all_ksf_data =
(struct hks_rkc_ksf_data *)HKS_MALLOC(data_size);
if (all_ksf_data == NULL) {
log_error("malloc all ksf data fail");
return HKS_ERROR_MALLOC_FAIL;
}
//将all_ksf_data中的数据置零
(void)memset_s(all_ksf_data, data_size, 0, data_size);
int32_t rc;
do {
uint32_t valid_ksf_index = 0;
//定义根密钥组件密钥库文件数据结构体变量valid_ksf_data并制空
struct hks_rkc_ksf_data *valid_ksf_data = NULL;
//读取所有密钥库文件到all_ksf_data中
rc = hks_rkc_read_all_ksf(all_ksf_rc, all_ksf_data,
&valid_ksf_data,
&valid_ksf_index);
if (rc != HKS_STATUS_OK)
break;
//检查有效密钥库文件数据
if (valid_ksf_data == NULL) {
log_error("all ksf file are invalid");
rc = HKS_ERROR_INVALID_KEY_FILE;
break;
}
//恢复根密钥内存
rc = hks_rkc_recover_rk_mem(valid_ksf_data);
if (rc != HKS_STATUS_OK)
break;
//恢复主密钥内存
rc = hks_rkc_recover_mk_mem(valid_ksf_data);
if (rc != HKS_STATUS_OK)
break;
//检查所有密钥库文件
rc = hks_rkc_chk_all_ksf(all_ksf_rc, all_ksf_data,
valid_ksf_data,
valid_ksf_index);
if (rc != HKS_STATUS_OK)
break;
//将有效密钥库文件数据valid_ksf_data复制到ksf_data中
if (ksf_data != NULL) {
rc = memcpy_s(ksf_data, HKS_RKC_KSF_DATA_SIZE,
valid_ksf_data,
HKS_RKC_KSF_DATA_SIZE);
if (rc != HKS_STATUS_OK)
break;
}
//更新日志:成功载入密钥库文件
log_info("load ksf success");
} while (0);
//内存数据置零接着释放
(void)memset_s(all_ksf_data, data_size, 0, data_size);
hks_free_ptr(all_ksf_data);
return rc;
}
本章小结
本篇继续讲述了hks_rkc.c代码中有关密钥的生成、为密钥加掩码、密钥内存的恢复相关操作,下一篇将继续更新hks_rkc.c代码中有关密钥初始化、销毁以及检查的部分功能。