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代码中有关密钥初始化、销毁以及检查的部分功能。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值