1.hks_access.h

hks_access.c是在hks_access.h的基础上对具体函数的定义操作，因此其中用到了access.h中对各个功能结构体的定义，尤其值得注意的是：

//hw_keystore_sdk中cmd的类型成员
enum hks_cmd_type {
    HKS_GENERATE_KEY = 0,//生成密匙
    HKS_GENERATE_KEY_EX, //生成密匙对
    HKS_SIGN,            //hks标志
    HKS_VERIFY,          //hks核实
    HKS_ENCRYPT,         //hks加密
    HKS_DECRYPT,         //hks解密
    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 */
};

//sec_mod_msg中有安全模式下所有的类型以及函数变量定义外加一个状态标记
struct sec_mod_msg {
    enum hks_cmd_type cmd_id;   //选择hks存取功能
    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;
};

hks_access.h具体内容见：hks_access.h的代码标注讲解的链接

2.__hks_handle_secure_call

__hks_handle_secure_call是access.c中非常重要的一个函数模块，主要实现了hks处理安全请求时的操作功能，其中msg_box由结构体sec_mod_msg定义，sec_mod_msg中包含了对hks_cmd_type、函数共用体以及状态status的定义，是整个函数中的关键内容。详细代码评注如下：

//hks处理安全请求
static void __hks_handle_secure_call(struct sec_mod_msg *msg_box)
{
    if (msg_box == NULL)
        return;
    //请求处理的安全操作为hks_cmd_type中的0-13项功能之一则执行
    if (msg_box->cmd_id < HKS_CMD_MAX) {
        if (g_hks_handle_func[msg_box->cmd_id])
            g_hks_handle_func[msg_box->cmd_id](msg_box);
    } else {
        msg_box->status = HKS_ERROR_NOT_SUPPORTED; //状态变为“不支持Mbedtls错误”
    }
}

//选择处理函数选项共有0-13个可选项
hks_handle_func_p g_hks_handle_func[HKS_CMD_MAX] = {
#ifndef _CUT_AUTHENTICATE_      //减少验证
    hks_handle_generate_key,
    hks_handle_generate_key_ex,
    hks_handle_sign,
    hks_handle_verify,
    hks_handle_encrypt,
    hks_handle_decrypt,
    hks_handle_import,
    hks_handle_export,
    hks_handle_get_random,
    hks_handle_key_agreement,
    hks_handle_key_deviration,
    hks_handle_hmac,
    hks_handle_hash,
    hks_handle_bn_exp_mod,
#else
    NULL,
    NULL,
    NULL,
    NULL,
    hks_handle_encrypt,
    hks_handle_decrypt,
    NULL,
    NULL,
    hks_handle_get_random,
    NULL,
    hks_handle_key_deviration,
    hks_handle_hmac,
    NULL,
    hks_handle_bn_exp_mod,
#endif
};

3.几个关键函数的定义

进入安全模式函数

hks_enter_secure_mode

//hks进入安全模式函数
void hks_enter_secure_mode(struct sec_mod_msg *msg)
{
    if (msg == NULL)
        return;
    //调用处理安全请求函数并传参msg
    __hks_handle_secure_call(msg);
}

获取权限初始化、存取权限销毁、更新密匙信息

hks_access_init、hks_access_destroy

//hks获取权限初始化
int32_t hks_access_init(void)
{
    //将状态设置成hks服务密匙信息初始化的返回值，如果成功初始化则返回sucess否则返回error
    int32_t status = hks_service_key_info_init();
    //判断状态是否为error
    hks_if_status_error_return(status);

    return status;
}

//hks存取权限摧毁（回收）
void hks_access_destroy(void)
{
    //hks服务销毁
    hks_service_destroy();
}

//hks存取更新密匙信息，该函数与hks_access_init类似
int32_t hks_access_refresh_key_info(void)
{
    int32_t status = hks_service_refresh_key_info();

    hks_if_status_error_return(status);

    return status;
}

生成密匙信息（对）

hks_access_generate_key、hks_access_generate_key_ex

//生成密匙信息（传入密匙别名和对应参数）
int32_t hks_access_generate_key(const struct hks_blob *key_alias,
    const struct hks_key_param *key_param)
{
    //定义一个sec_mod_msg类型的结构体
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    //录入信息
    struct hks_generate_key_msg *msg = &msg_box.msg_data.generate_key_msg;

    msg_box.cmd_id = HKS_GENERATE_KEY;
    msg->key_alias = key_alias;
    msg->key_param = key_param;
    hks_enter_secure_mode(&msg_box);

    //返回状态
    return msg_box.status;
}

//生成密匙对（与hks_access_generate_key雷同）
int32_t hks_access_generate_key_ex(const struct hks_key_param *key_param, struct hks_blob *priv_key,
    struct hks_blob *pub_key)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_generate_ex_msg *msg = &msg_box.msg_data.generate_ex_msg;

    msg_box.cmd_id = HKS_GENERATE_KEY_EX;
    msg->key_param = key_param;
    msg->priv_key = priv_key;
    msg->pub_key = pub_key;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

存取签名信息使能、存取证实信息使能

hks_access_sign、hks_access_verify

//hks存取签署信息，将hash规则和签名写入msg_box
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_sign_verify_msg *msg = &msg_box.msg_data.sign_verify_msg;

    msg_box.cmd_id = HKS_SIGN;//存取签署信息
    msg->key = key_alias;
    msg->key_param = key_param;
    msg->message = hash;
    msg->signature = signature;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks存取证实，核对签名信息是否正确
int32_t hks_access_verify(const struct hks_blob *key_alias, const struct hks_blob *hash,
    const struct hks_blob *signature)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_sign_verify_msg *msg = &msg_box.msg_data.sign_verify_msg;

    msg_box.cmd_id = HKS_VERIFY;//存取证实
    msg->key = key_alias;
    msg->message = hash;
    msg->signature = (struct hks_blob *)signature;
    hks_enter_secure_mode(&msg_box);
    return msg_box.status;
}

存取aead加密解密

hks_access_aead_encrypt、hks_access_aead_decrypt

//hks存取aead加密
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_encrypt_decrypt_msg *msg = &msg_box.msg_data.encrypt_decrypt_msg;

    msg_box.cmd_id = HKS_ENCRYPT;//存取加密
    msg->key = key;
    msg->key_param = key_param;
    msg->crypt_param = crypt_param;
    msg->plain_text = (struct hks_blob *)plain_text;
    msg->cipher_text_with_tag = cipher_text_with_tag;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks存取aead解密
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_encrypt_decrypt_msg *msg = &msg_box.msg_data.encrypt_decrypt_msg;

    msg_box.cmd_id = HKS_DECRYPT;//存取解密
    msg->key = key;
    msg->key_param = key_param;
    msg->crypt_param = crypt_param;
    msg->plain_text = plain_text;
    msg->cipher_text_with_tag = (struct hks_blob *)cipher_text_with_tag;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

密匙信息存取控制系列函数

hks_access_import_key、hks_access_export_key、hks_access_delete_key、hks_access_is_key_exist、hks_access_get_key_param、hks_access_get_pub_key_alias_list

//hks存取导入密匙信息
#ifndef _CUT_AUTHENTICATE_
int32_t hks_access_import_key(const struct hks_blob *key_alias, const struct hks_key_param *key_param,
    const struct hks_blob *key)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_import_key_msg *msg = &msg_box.msg_data.import_key_msg;

    msg_box.cmd_id = HKS_IMPORT_KEY;//存取导入密匙
    msg->key_alias = key_alias;
    msg->key_param = key_param;
    msg->key_data = key;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks获得存取出口密匙的权限
int32_t hks_access_export_key(const struct hks_blob *key_alias, struct hks_blob *key)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_export_key_msg *msg = &msg_box.msg_data.export_key_msg;

    msg_box.cmd_id = HKS_EXPORT_KEY;//存取出口密匙
    msg->key_alias = key_alias;
    msg->key_data = key;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks获得执行删除密匙操作的权限
int32_t hks_access_delete_key(const struct hks_blob *key_alias)
{
    int32_t status = hks_service_delete_key(key_alias);

    hks_if_status_error_return(status);

    return status;
}

//hks获得判断密匙是否存在权限
int32_t hks_access_is_key_exist(const struct hks_blob *key_alias)
{
    //hks
    int32_t status = hks_service_is_key_exist(key_alias);

    hks_if_status_error_return(status);

    return status;
}

//hks获得密匙参数信息
int32_t hks_access_get_key_param(const struct hks_blob *key_alias,
    struct hks_key_param *key_param)
{
    int32_t status = hks_service_get_key_param(key_alias, key_param);

    hks_if_status_error_return(status);

    return status;
}

//hks获取共有密匙别名list
int32_t hks_access_get_pub_key_alias_list(struct hks_blob *key_alias_list, uint32_t *list_count)
{
    int32_t status = hks_service_get_pub_key_alias_list(key_alias_list, list_count);

    hks_if_status_error_return(status);

    return status;
}
#endif

加密规则与算法相关函数

hks_access_get_random、hks_access_hmac、hks_access_hash、hks_access_key_agreement、hks_access_key_derivation、hks_access_bn_exp_mod

//hks获取随机数
int32_t hks_access_get_random(struct hks_blob *random)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_generate_random_msg *msg = &msg_box.msg_data.generate_random_msg;

    msg_box.cmd_id = HKS_GENERATE_RANDOM;
    msg->random = random;
    hks_enter_secure_mode(&msg_box);//外源（输入的）安全模式

    return msg_box.status;
}

//hks获取哈希运算验证码
int32_t hks_access_hmac(const struct hks_blob *key,
    uint32_t alg, const struct hks_blob *src_data, struct hks_blob *output)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_hmac_msg *msg = &msg_box.msg_data.hmac_msg;

    msg_box.cmd_id = HKS_HMAC;//选择获取验证码对应的功能
    msg->alg = alg;
    msg->key = key;
    msg->src_data = src_data;
    msg->output = output;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

hks使能哈希算法
int32_t hks_access_hash(uint32_t alg, const struct hks_blob *src_data,
    struct hks_blob *hash)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_hash_msg *msg = &msg_box.msg_data.hash_msg;

    msg_box.cmd_id = HKS_HASH;
    msg->alg = alg;
    msg->src_data = src_data;
    msg->hash = hash;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks获取密匙协议
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_key_agreement_msg *msg = &msg_box.msg_data.key_agreement_msg;

    msg_box.cmd_id = HKS_KEY_AGREEMENT;
    msg->agreed_key = agreed_key;
    msg->key_param = private_key_param;
    msg->agreement_alg = agreement_alg;
    msg->priv_key = private_key;
    msg->pub_key = peer_public_key;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks获取密匙派生信息
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_key_derivation_msg *msg = &msg_box.msg_data.key_derivation_msg;

    msg_box.cmd_id = HKS_KEY_DERIVATION;
    msg->derived_key = derived_key;
    msg->key_param = key_params;
    msg->kdf_key = kdf_key;
    msg->salt = salt;
    msg->label = label;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

//hks使能大整数模幂运算
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)
{
    struct sec_mod_msg msg_box;

    (void)memset_s(&msg_box, sizeof(msg_box), 0, sizeof(msg_box));

    struct hks_bn_exp_mod_msg *msg = &msg_box.msg_data.bn_exp_mod_msg;

    msg_box.cmd_id = HKS_BN_EXP_MOD;
    msg->x = x;
    msg->a = a;
    msg->e = e;
    msg->n = n;
    hks_enter_secure_mode(&msg_box);

    return msg_box.status;
}

对应功能函数的执行函数

//hks处理生成密匙信息
#ifndef _CUT_AUTHENTICATE_
static void hks_handle_generate_key(struct sec_mod_msg *msg_box)
{
    //修改msg中hks_generate_key_msg的信息
    struct hks_generate_key_msg *msg = &msg_box->msg_data.generate_key_msg;

    msg_box->status = hks_service_generate_key(msg->key_alias, msg->key_param);
}

static void hks_handle_sign(struct sec_mod_msg *msg_box)
{
    struct hks_sign_verify_msg *msg = &msg_box->msg_data.sign_verify_msg;

    msg_box->status = hks_service_asymmetric_sign(msg->key, msg->key_param, msg->message, msg->signature);
}

static void hks_handle_import(struct sec_mod_msg *msg_box)
{
    struct hks_import_key_msg *msg = &msg_box->msg_data.import_key_msg;

    msg_box->status = hks_service_import_public_key(msg->key_alias, msg->key_param, msg->key_data);
}

static void hks_handle_export(struct sec_mod_msg *msg_box)
{
    struct hks_export_key_msg *msg = &msg_box->msg_data.export_key_msg;

    msg_box->status = hks_service_export_public_key(msg->key_alias, msg->key_data);
}

static void hks_handle_generate_key_ex(struct sec_mod_msg *msg_box)
{
    struct hks_generate_ex_msg *msg = &msg_box->msg_data.generate_ex_msg;

    msg_box->status = hks_service_generate_asymmetric_key(msg->key_param, msg->priv_key, msg->pub_key);
}

static void hks_handle_verify(struct sec_mod_msg *msg_box)
{
    struct hks_sign_verify_msg *msg = &msg_box->msg_data.sign_verify_msg;

    msg_box->status = hks_service_asymmetric_verify(msg->key, msg->message, msg->signature);
}
#endif

static void hks_handle_encrypt(struct sec_mod_msg *msg_box)
{
    struct hks_encrypt_decrypt_msg *msg = &msg_box->msg_data.encrypt_decrypt_msg;

    msg_box->status = hks_service_aead_encrypt_ex(msg->key, msg->key_param, msg->crypt_param, msg->plain_text,
        msg->cipher_text_with_tag);
}

static void hks_handle_decrypt(struct sec_mod_msg *msg_box)
{
    struct hks_encrypt_decrypt_msg *msg = &msg_box->msg_data.encrypt_decrypt_msg;

    msg_box->status = hks_service_aead_decrypt_ex(msg->key, msg->key_param, msg->crypt_param,
        msg->cipher_text_with_tag, msg->plain_text);
}

static void hks_handle_get_random(struct sec_mod_msg *msg_box)
{
    struct hks_generate_random_msg *msg = &msg_box->msg_data.generate_random_msg;

    msg_box->status = hks_service_get_random(msg->random);
}

#ifndef _CUT_AUTHENTICATE_
static void hks_handle_key_agreement(struct sec_mod_msg *msg_box)
{
    struct hks_key_agreement_msg *msg = &msg_box->msg_data.key_agreement_msg;

    msg_box->status = hks_service_key_agreement(msg->agreed_key, msg->key_param,
        msg->priv_key, msg->pub_key, msg->agreement_alg);
}
#endif

static void hks_handle_key_deviration(struct sec_mod_msg *msg_box)
{
    struct hks_key_derivation_msg *msg = &msg_box->msg_data.key_derivation_msg;

    msg_box->status = hks_service_key_derivation(msg->derived_key, msg->kdf_key, msg->salt, msg->label, msg->key_param);
}

static void hks_handle_hmac(struct sec_mod_msg *msg_box)
{
    struct hks_hmac_msg *msg = &msg_box->msg_data.hmac_msg;

    msg_box->status = hks_service_hmac_ex(msg->key, msg->alg, msg->src_data, msg->output);
}

#ifndef _CUT_AUTHENTICATE_
static void hks_handle_hash(struct sec_mod_msg *msg_box)
{
    struct hks_hash_msg *msg = &msg_box->msg_data.hash_msg;

    msg_box->status = hks_service_hash(msg->alg, msg->src_data, msg->hash);
}
#endif

static void hks_handle_bn_exp_mod(struct sec_mod_msg *msg_box)
{
    struct hks_bn_exp_mod_msg *msg = &msg_box->msg_data.bn_exp_mod_msg;

    msg_box->status = hks_service_bn_exp_mod(msg->x, msg->a, msg->e, msg->n);
}

知识提点

MBEDTLS
mbedTLS（前身 PolarSSL）是一个由 ARM 公司开源和维护的 SSL/TLS 算法库。其使用 C 编程语言以最小的编码占用空间实现了 SSL/TLS 功能及各种加密算法，易于理解、使用、集成和扩展，方便开发人员轻松地在嵌入式产品中使用 SSL/TLS 功能。
access
access的中文翻译有：存取、访问、使用权（权限）等等，而在本篇中的access我的理解是“使能”，对hks相关函数功能的定义可以理解成为一种权限的使能，整篇代码中我们也能够发现，函数的功能申明与执行是两个过程，两个过程的独立能让代码更加清晰具有更强的鲁棒性，调用起来更加灵活可控。