--- title: 密钥管理类 description: "本章节主要介绍了密钥管理类接口及其扩展接口的功能和相关规格限制。" url: https://www.hikunpeng.com/document/detail/zh/kunpengcctrustzone/cca/devg/Kunpeng_ommercialcryptography_16_0027.html sourcePath: /source/zh/kunpengcctrustzone/cca/devg/Kunpeng_ommercialcryptography_16_0027.html indexId: 41acdd1bf7a05acebf06c7e26382df98221cdf55acc22ad5d4fb44d1f1d54c0381 --- # 密钥管理类 本章节主要介绍了密钥管理类接口及其扩展接口的功能和相关规格限制。 密钥管理类接口支持如下，接口定义符合GM/T 0018-2023标准，接口参数与返回值可参考标准文档，算法标识描述可参考GM/T 0006-2023。 ``` int SDF_ExportSignPublicKey_ECC(void *hSessionHandle, unsigned int uiKeyIndex, ECCrefPublicKey *pucPublicKey); int SDF_ExportEncPublicKey_ECC(void *hSessionHandle, unsigned int uiKeyIndex, ECCrefPublicKey *pucPublicKey); int SDF_GenerateKeyPair_ECC(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKeyBits, ECCrefPublicKey *pucPublicKey, ECCrefPrivateKey *pucPrivateKey); int SDF_GenerateKeyWithIPK_ECC(void *hSessionHandle, unsigned int uiIPKIndex, unsigned int uiKeyBits, ECCCipher *pucKey, void **phKeyHandle); int SDF_GenerateKeyWithEPK_ECC(void *hSessionHandle, unsigned int uiKeyBits, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, ECCCipher *pucKey, void **phKeyHandle); int SDF_ImportKeyWithISK_ECC(void *hSessionHandle, unsigned int uiISKIndex, ECCCipher *pucKey, void **phKeyHandle); int SDF_ExchangeDigitEnvelopeBaseOnECC(void *hSessionHandle, unsigned int uiKeyIndex, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, ECCCipher *pucEncDataIn, ECCCipher *pucEncDataOut); int SDF_GenerateAgreementDataWithECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned int uiKeyBits, unsigned char *pucSponsorID, unsigned int uiSponsorIDLength, ECCrefPublicKey *pucSponsorPublicKey, ECCrefPublicKey *pucSponsorTmpPublicKey, void **phAgreementHandle); int SDF_GenerateKeyWithECC(void *hSessionHandle, unsigned char *pucResponseID, unsigned int uiResponseIDLength, ECCrefPublicKey *pucResponsePublicKey, ECCrefPublicKey *pucResponseTmpPublicKey, void *hAgreementHandle, void **phKeyHandle); int SDF_GenerateAgreementDataAndKeyWithECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned int uiKeyBits, unsigned char *pucResponseID, unsigned int uiResponseIDLength, unsigned char *pucSponsorID, unsigned int uiSponsorIDLength, ECCrefPublicKey *pucSponsorPublicKey, ECCrefPublicKey *pucSponsorTmpPublicKey, ECCrefPublicKey *pucResponsePublicKey, ECCrefPublicKey *pucResponseTmpPublicKey, void **phKeyHandle); int SDF_GenerateKeyWithKEK(void *hSessionHandle, unsigned int uiKeyBits, unsigned int uiAlgID, unsigned int uiKEKIndex, unsigned char *pucKey, unsigned int *puiKeyLength, void **phKeyHandle); int SDF_ImportKeyWithKEK(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKEKIndex, unsigned char *pucKey, unsigned int puiKeyLength, void **phKeyHandle); int SDF_DestroyKey(void *hSessionHandle, void *hKeyHandle); ``` #### 规格限制 - SDF_GenerateKeyPair_ECC算法标识目前仅支持：SGD_SM2_3、SGD_SM2_1、SGD_SM2。 - ECC密钥仅支持SM2，因此公钥长度仅支持256bit，即公钥和私钥结构体中的bits值只能为256。 - 生成的会话密钥长度当前仅支持128bit。 - SDF_GenerateKeyWithEPK_ECC算法标识目前仅支持：SGD_SM2_3、SGD_SM2_1。 - ECCCipher结构体密文长度不大于20K。 - 协商密钥长度范围限制为8~128bit，用户ID标识长度限制不大于64字节。 - SDF_ExchangeDigitEnvelopeBaseOnECC算法标识仅支持：SGD_SM2_3。 - 密钥加密密钥索引支持范围：1~2048。密钥加密密钥接口的算法标识仅支持SGD_SM4_CBC、SGD_SM4_ECB。输入密文长度不大于256字节。 - 会话密钥句柄最大个数为300000。 - SDF_DestroyKey会自动释放hKeyHandle，不需要再次释放。 ECB模式为不安全的密码运算，建议使用CBC模式，CBC可以结合MAC保证TLCP协议的完整性以及机密性。 #### 自定义接口 - 扩展接口，将会话密钥设置到会话密钥句柄中。 ``` int SDF_ImportKey(void *hSessionHandle, unsigned char *pucKey, unsigned int uiKeyLength, void **phKeyHandle); ``` **表1 参数说明** | 参数 | 描述 | | --- | --- | | hSessionHandle[in] | 与设备建立的会话句柄 | | pucKey[in] | 缓冲区指针，用于存放输入的会话密钥明文 | | uiKeyLength[in] | 输入的会话密钥长度（小于等于256字节） | | phKeyHandle[out] | 缓冲区指针，用于存放输出的会话密钥句柄 | **表2 返回值说明** | 返回值 | 说明 | | --- | --- | | 0 | 成功 | | 非0 | 失败，返回错误码 | - 扩展接口， 可用于打开或初始化设备。 ``` int SDF_OpenDeviceWithConf(void **phDeviceHandle, const char* configFile); ``` **表3 参数说明** | 参数 | 描述 | | --- | --- | | phDeviceHandle[in] | 与设备建立的会话句柄 | | configFile[in] | 配置文件指针，如果为NULL，则执行默认配置，如果指定的配置文件不存在或者无法打开，函数返回失败 | **表4 返回值说明** | 返回值 | 说明 | | --- | --- | | 0 | 成功 | | 非0 | 失败，返回错误码 | 其中配置文件的格式可参考下方示例。 ``` workers: 16 timeout: 1000 ta_cpu_set: 0,2-4,6 ca_cpu_set: 0-15 selftest:true key_access:true perf_stat:false ``` - workers表示设备申请TEE worker线程数目， 合法值在1~32之间， 系统默认值为16。如果值非法，则系统会将该值置为16。 - timeout表示TEE的worker线程多久收不到新任务就会睡眠， 单位是ms， 合法值要大于0， 系统默认值为1000。 其他无效字段会被忽略，workers或者timeout如果配置了多个有效值，以最后一个为准。 - ta_cpu_set用于指定TA应用绑定到的CPU核心，默认初始化绑核numa0上16-31号CPU。该配置项接受一个以逗号分隔的CPU标识符列表，其中每个元素可以是以下形式之一： - 单个CPU：一个非负整数，表示单个CPU核心（例如：0、1、5）。 - CPU范围：两个整数之间用连字符分隔，表示一个连续的CPU范围（包含两端，例如：0-3表示CPU 0、1、2和3）。 - 混合格式：单个CPU与范围的任意组合（例如：0,2-4,6,8-10）。 - ca_cpu_set用于指定CA应用绑定的CPU核心，格式请参考ta_cpu_set，默认初始化绑核numa0上0-15号CPU。 - selftest表示是否执行自测试，默认值为false，详见特殊规格中 算法自测试 。 - key_access表示是否需要通过调用SDF_GetKEKAccessRight接口获取sm4密钥的使用权限，默认为true，若设置为false，则无需调用该接口，也可使用sm4密钥，请根据需求合理设置该配置项。受此影响的接口包括SDF_GenerateKeyWithKEK和SDF_ImportKeyWithKEK。 - perf_stat表示是否开启内置的算法性能统计，默认为false。设置为true时，每个device在关闭device时将输出本周期内相关算法的性能和时延数据到CA侧日志文件/var/log/teec.log，各个device数据独立互不干扰。涉及的算法包括sm2内部密钥签名验签、sm2内部密钥加解密、sm4加解密、sm4-gcm加解密，hmac和cmac。 绑核配置项数字和分隔符之间允许存在空格，解析时将被忽略。非法值和非法字符将导致绑核失败，退化为默认初始化绑核策略。 configFile为NULL时，将尝试解析默认配置文件/etc/sdf.conf。若默认配置文件不存在，各项配置均会被设置为系统默认值。 - 获取密码设备内部存储的指定索引密钥加密密钥的使用权。 ``` int SDF_GetKEKAccessRight(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword,unsigned int uiPwdLength); ``` **表5 参数说明** | 参数 | 说明 | | --- | --- | | void \*hSessionHandle[in] | 与密码设备已建立的会话句柄 | | unsigned int uiKeyIndex[in] | 密码设备存储密钥加密密钥的索引值 | | unsigned char \*pucPassword[in] | 使用密钥加密密钥权限的标识码 | | unsigned int uiPwdLength[in] | 密钥加密密钥访问控制码长度 | **表6 返回值说明** | 返回值 | 说明 | | --- | --- | | 0 | 成功 | | 非0 | 失败，返回错误码 | 本文涉及密码设备的密钥索引值的起始索引值为1，最大为n，密码设备的实际存储容量决定n值，现配置值为2048。 多次调用相同索引成功时不返回错误。 非root用户连续500次由于密码错误导致获取权限失败时，系统会删除对应密钥的访问权限。 密钥加密密钥访问控制码的长度不应少于8字节。 - 释放密码设备存储的指定索引密钥的使用授权。 ``` int SDF_ReleasePrivateKeyAccessRight(void *hSessionHandle, unsigned int uiKeyIndex); ``` **表7 参数说明** | 参数 | 说明 | | --- | --- | | void \*hSessionHandle[in] | 与密码设备已建立的会话句柄 | | unsigned int uiKeyIndex[in] | 密码设备存储密钥索引值 | **表8 返回值说明** | 返回值 | 说明 | | --- | --- | | 0 | 成功 | | 非0 | 失败，返回错误码 |