鸿蒙源码分析（十五）

security_huks模块framework中hks_access.h分析

本文主要分析hks_access.h所定义的一些结构体
文件路径"\security_huks\frameworks\huks_lite\source\hks_access.h"

一、结构体

1. hks_types.h中结构体变量定义

hks_blob该结构体在hks_access.h常用来定义密钥变量，主要有三个参数组成：type类型，data数组，size大小。

struct hks_blob {
    uint8_t type;
    uint8_t *data;
    uint32_t size;
};

hks_key_para结构体用来存放密钥相关信息（长度、模式、范围等等）

struct hks_key_param {
    uint32_t key_type; /* 算法 */
    uint32_t key_len; // 密钥长度
    uint32_t key_usage; /* 用法 */
    uint32_t key_pad;  /* 填充模式 */
    uint32_t key_mode; /* 群组模式 */
    uint16_t key_domain; //作用域
    int32_t key_digest;
    struct hks_key_param_ext key_param_ext;
};

hks_encrypt_material结构体用来存放加密材料。

struct hks_encrypt_material {
    struct hks_blob *cipher_text;
    struct hks_blob *nonce_blob; /* Nonce value or iv vector */
    struct hks_blob *aad_blob;
    struct hks_blob *plain_text;
    struct hks_storage_key_info *key_info;
    uint32_t sealing_alg;
};

以上为hks_types.h主要的部分结构体定义，下面分析hks_access.h中定义

2. hks_access.h结构体

hks_cmd_type定义一个命令提示符类型的枚举变量，将不同情况分别赋值。

enum hks_cmd_type {//定义一个枚举类型
    HKS_GENERATE_KEY = 0,
    HKS_GENERATE_KEY_EX,
    HKS_SIGN,//标记值
    HKS_VERIFY,//验证
    HKS_ENCRYPT,
    HKS_DECRYPT,
    HKS_IMPORT_KEY,
    HKS_EXPORT_KEY,
    HKS_GENERATE_RANDOM,
    HKS_KEY_AGREEMENT,
    HKS_KEY_DERIVATION,
    HKS_HMAC,
    HKS_HASH,
    HKS_BN_EXP_MOD,

    HKS_CMD_MAX, /* new cmd type must be added before HKS_CMD_MAX */
};

一下为一些和密钥信息相关的结构体，注释解析均在代码注释当中

struct hks_generate_key_msg {//生成密钥信息的结构体
    const struct hks_blob *key_alias;//密钥别名
    const struct hks_key_param *key_param;//密钥参数
    struct hks_encrypt_material *key_material;//加密后的密钥材料，加密后的字符串
};

struct hks_generate_ex_msg {
    const struct hks_key_param *key_param;
    struct hks_blob *priv_key;//定义一个私钥
    struct hks_blob *pub_key;//定义一个公钥
};

struct hks_sign_verify_msg {//标记验证的结构体
    const struct hks_blob *key;
    const struct hks_key_param *key_param;
    const struct hks_blob *message;//定义消息
    struct hks_blob *signature;
    struct hks_encrypt_material *encrypt_material;
};

struct hks_encrypt_decrypt_msg {//加密解密 
    const struct hks_blob *key;
    const struct hks_key_param *key_param;
    const struct hks_crypt_param *crypt_param;//加密参数
    struct hks_blob *plain_text; //纯文本
    struct hks_blob *cipher_text_with_tag;//带有tag的密文
};

struct hks_import_key_msg {//导入密钥
    const struct hks_blob *key_alias;
    const struct hks_key_param *key_param;
    const struct hks_blob *key_data;
    struct hks_encrypt_material *key_material;
};

struct hks_export_key_msg {//扩展加密密钥
    const struct hks_blob *key_alias;
    struct hks_blob *key_data;
    struct hks_encrypt_material *encrypt_material;
};

struct hks_delete_key_msg {//删除密钥信息
    const struct hks_blob *key_alias;
};

struct hks_get_key_param_msg {//获取密钥信息
    const struct hks_blob *key_alias;
    struct hks_key_param *key_param;
};

struct hks_key_exist_msg {//密钥是否存在
    const struct hks_blob *key_alias;
};

struct hks_generate_random_msg {//生成随机消息
    struct hks_blob *random;
};

struct hks_key_agreement_msg {//密钥认证通过
    struct hks_blob *agreed_key;
    const struct hks_key_param *key_param;
    uint32_t agreement_alg;
    const struct hks_blob *priv_key;
    const struct hks_blob *pub_key;
};

struct hks_key_derivation_msg {//派生密钥
    struct hks_blob *derived_key;
    const struct hks_key_param *key_param;
    const struct hks_blob *kdf_key;
    const struct hks_blob *salt;
    const struct hks_blob *label;
};

struct hks_hmac_msg {//哈希运算消息认证码
    const struct hks_blob *key;
    uint32_t alg;
    const struct hks_blob *src_data;//源数据
    struct hks_blob *output;//输出
};

struct hks_hash_msg {//哈希算法
    uint32_t alg;
    const struct hks_blob *src_data;
    struct hks_blob *hash;
};

struct hks_bn_exp_mod_msg {
    struct hks_blob *x;
    const struct hks_blob *a;//基数
    const struct hks_blob *e;//指数
    const struct hks_blob *n;//模数
};

struct hks_get_pub_key_list_msg {//获取公钥列表
    uint32_t *list_count;
    struct hks_blob *key_alias_list;
};

struct hks_encrypt_decrypt_text {//加密和解密文本
    const struct hks_blob *input_text;//输入
    struct hks_blob *output_text;//输出
};

struct sec_mod_msg {
    enum hks_cmd_type cmd_id;//枚举类型cmd_id
    int32_t status;
    union {//对数据定义一个共用体，节省空间
        struct hks_generate_key_msg generate_key_msg;
        struct hks_generate_ex_msg generate_ex_msg;
        struct hks_encrypt_decrypt_msg encrypt_decrypt_msg;
        struct hks_sign_verify_msg sign_verify_msg;
        struct hks_import_key_msg import_key_msg;
        struct hks_export_key_msg export_key_msg;
        struct hks_delete_key_msg delete_key_msg;
        struct hks_get_key_param_msg get_key_param_msg;
        struct hks_key_exist_msg key_exist_msg;
        struct hks_generate_random_msg generate_random_msg;
        struct hks_key_agreement_msg key_agreement_msg;
        struct hks_key_derivation_msg key_derivation_msg;
        struct hks_hmac_msg hmac_msg;
        struct hks_hash_msg hash_msg;
        struct hks_bn_exp_mod_msg bn_exp_mod_msg;
        struct hks_get_pub_key_list_msg get_pub_key_list_msg;
    } msg_data;
};

二、函数声明

下面主要为该目录下函数调用的声明

//下面为一些要用到的函数声明
typedef void (*hks_handle_func_p)(struct sec_mod_msg *msg_box);
void hks_enter_secure_mode(struct sec_mod_msg *msg);
void hks_handle_secure_call(void);

int32_t hks_access_init(void);
void hks_access_destroy(void);
int32_t hks_access_refresh_key_info(void);
int32_t hks_access_generate_key(const struct hks_blob *key_alias,
    const struct hks_key_param *key_param);
int32_t hks_access_generate_key_ex(
    const struct hks_key_param *key_param, struct hks_blob *priv_key, struct hks_blob *pub_key);
int32_t hks_access_sign(const struct hks_blob *key_alias,
    const struct hks_key_param *key_param, const struct hks_blob *hash, struct hks_blob *signature);
int32_t hks_access_verify(const struct hks_blob *key_alias,
    const struct hks_blob *hash, const struct hks_blob *signature);
int32_t hks_access_aead_encrypt(const struct hks_blob *key,
    const struct hks_key_param *key_param, const struct hks_crypt_param *crypt_param,
    const struct hks_blob *plain_text, struct hks_blob *cipher_text_with_tag);
int32_t hks_access_aead_decrypt(const struct hks_blob *key,
    const struct hks_key_param *key_param, const struct hks_crypt_param *crypt_param,
    const struct hks_blob *cipher_text_with_tag, struct hks_blob *plain_text);
int32_t hks_access_import_key(const struct hks_blob *key_alias,
    const struct hks_key_param *key_param, const struct hks_blob *key);
int32_t hks_access_export_key(const struct hks_blob *key_alias, struct hks_blob *key);
int32_t hks_access_delete_key(const struct hks_blob *key_alias);
int32_t hks_access_is_key_exist(const struct hks_blob *key_alias);
int32_t hks_access_get_key_param(const struct hks_blob *key_alias,
    struct hks_key_param *key_param);
int32_t hks_access_get_random(struct hks_blob *random);
int32_t hks_access_hmac(const struct hks_blob *key,
    uint32_t alg, const struct hks_blob *src_data, struct hks_blob *output);
int32_t hks_access_hash(uint32_t alg, const struct hks_blob *src_data, struct hks_blob *hash);
int32_t hks_access_key_agreement(struct hks_blob *agreed_key,
    const struct hks_key_param *private_key_param, const struct hks_blob *private_key,
    const struct hks_blob *peer_public_key, const uint32_t agreement_alg);
int32_t hks_access_key_derivation(struct hks_blob *derived_key,
    const struct hks_blob *kdf_key, const struct hks_blob *salt,
    const struct hks_blob *label, const struct hks_key_param *key_params);
int32_t hks_access_bn_exp_mod(struct hks_blob *x,
    const struct hks_blob *a, const struct hks_blob *e, const struct hks_blob *n);
int32_t hks_access_get_pub_key_alias_list(
    struct hks_blob *key_alias_list, uint32_t *list_count);

#endif /* HKS_ACCESS_H */

以上为hks_access.h头文件介绍，下一篇开始分析主要应用的源代码。