密钥管理工具接口

为了方便客户定制化管理密钥，提供了密钥管理工具接口供用户调用。

• 管理工具创建session用户。

  int ECM_OpenSession(void *hDeviceHandle, void **phSessionHandle);

  表1 参数说明

  参数	描述
  hDeviceHandle[in]	已打开的设备句柄
  phSessionHandle[out]	与密码设备已建立的会话句柄

  表2 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 创建设备内置密钥并设置密码。

  int ECM_GenerateKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int uiPwdLength);

  表3 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，包括密钥类型与索引下标
  pucPassword[in]	使用私钥权限的标识码
  uiPwdLength[in]	使用私钥权限标识码的长度，范围8~128字节

  表4 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

  

  • uiKeyIndex[in]：内部密钥索引信息，长度32位bit，高12位表示key的类型，低20位表示key的下标。

    key的类型中，当前可选类型为：

    • SDF_SM2_SIGN：签名密钥对。
    • SDF_SM2_ENC：加密密钥对。
    • SDF_SM4：SM4加密密钥。
  • 用户密钥包括加密密钥对和签名密钥对，因此调用此接口时应调用两次才能完成用户密钥的生成。

• 删除指定内置密钥。

  int ECM_DeleteKey(void *hSessionHandle, unsigned int uiKeyIndex);

  表5 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成

  表6 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 查询内置密钥状态。

  int ECM_QueryKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned int *uiKeyInfo);

  表7 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  uiKeyInfo[out]	密码设备内置密钥信息 0：密钥存在 非0：密钥不存在

  表8 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 修改指定私钥的权限标识码。

  int ECM_ChangePassword(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *prePassword, unsigned int prePasswordLen, unsigned char *newPassword, unsigned int newPasswordLen);

  表9 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  prePassword[in]	当前使用私钥权限的标识码
  prePasswordLen[in]	当前私钥权限标识码的长度，范围8-128字节
  newPassword[in]	新设置的私钥权限标识码
  newPasswordLen[in]	新设置的私钥权限标识码长度，范围8~128字节

  表10 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 导出对应内置密钥。

  int ECM_ExportKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *keyFileBuffer, unsigned int *keyBufferLength, unsigned char *keySalt);

  表11 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  keyFileBuffer[out]	缓冲区指针，用于存放导出的内置密钥密文
  keyBufferLength[out]	导出的内置密钥密文长度
  keySalt[in]	加密盐值，最大长度为16字节

  表12 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 导入密钥到指定索引下标。

  int ECM_ImportKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *keyFileBuffer, unsigned int keyBufferLength, unsigned char *keySalt);

  表13 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  keyFileBuffer[in]	缓冲区指针，用于存放准备导入的密钥密文
  keyBufferLength[out]	待导入的密钥密文长度
  keySalt[in]	解密盐值，最大长度16字节

  表14 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 恢复出厂设置。

  int ECM_FactoryReset();

  表15 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 将明文形式的密钥导入设备内部。

  int ECM_ImportKeyPair_ECC(void* hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int uiPwdLength, ECCrefPublicKey* pucPublicKey, ECCrefPrivateKey* pucPrivateKey);

  表16 参数说明

  参数	描述
  void *hSessionHandle[in]	管理session句柄
  unsigned int uiKeyIndex[in]	指定内部密钥的索引值
  unsigned char *prePassword[in]	密钥口令
  unsigned int prePasswordLen[in]	口令长度
  ECCrefPublicKey* pucPublicKey[in]	设备内部密钥公钥结构体
  ECCrefPrivateKey* pucPrivateKey[in]	设备内部密钥私钥结构体

  表17 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

  

  1. 将用户传入的明文ECC公私钥结构体内容导入到密码模块内部。对应公私钥对需匹配，否则返回失败。

  2. 导入密钥的密钥口令需要满足强度限制，参考特殊规格说明。

  3. 相同索引值的密钥不能重复导入。

• 明文导入密钥加密密钥。

  int ECM_ImportKEK(void* hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int uiPwdLength, unsigned char *KEKBuf, unsigned int KEKLen);

  表18 参数说明

  参数	描述
  void *hSessionHandle[in]	管理session句柄
  unsigned int uiKeyIndex[in]	指定内部密钥的索引值
  unsigned char *prePassword[in]	密钥口令
  unsigned int prePasswordLen[in]	口令长度
  unsigned int *KEKBuf[in]	导入KEK密钥内容
  unsigned int KEKLen[in]	导入KEK密钥长度（16字节）

  表19 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

  

  1. 用户明文传入KEK密钥，密钥长度固定为16字节。

  2. 导入密钥的密钥口令需要满足强度限制，参考特殊规格说明。

  3. 相同索引值的密钥不能重复导入。

• 数字信封形式导入设备内部密钥。

  int ECM_ImportKeyWithEnvelop(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int pucPasswordLen, ECCEnvelopedKey *pucEnvelopKey);

  表20 参数说明

  参数	描述
  void *hSessionHandle[in]	管理session句柄
  unsigned int uiKeyIndex[in]	指定导入内部密钥的索引值
  unsigned char *pucPassword[in]	密钥口令
  unsigned int pucPasswordLen[in]	口令长度
  ECCEnvelopedKey *pucEnvelopKey[in]	导入数字信封入参，该数字信封需使用本设备0号密钥对应公钥加密生成

  表21 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

  

  1. 将用户传入的数字信封使用0号密钥私钥解密后，导入到密码模块内部，作为指定索引密钥内容。

  2. 导入密钥的密钥口令需要满足强度限制，参考特殊规格说明。

  3. 相同索引值的密钥不能重复导入，对应索引已存在密钥时导入失败。

  数字信封形式导出设备内部密钥。

  int ECM_ExportKeyWithEnvelop(void *hSessionHandle, unsigned int uiKeyIndex, unsignedchar*pucPassword, unsigned int pucPasswordLen, ECCrefPublicKey *pucPublicKey, ECCEnvelopedKey *pucEnvelopKey);

  表22 参数说明

  参数	描述
  void *hSessionHandle[in]	管理session句柄
  unsigned int uiKeyIndex[in]	待导出的内部密钥的索引值
  unsigned char *prePassword[in]	待导出的内部密钥对应密钥口令
  unsigned int prePasswordLen[in]	口令长度
  ECCrefPublicKey* pucPublicKey[in]	加密数字信封的公钥结构体
  ECCEnvelopedKey *pucEnvelopKey[out]	导出的数字信封

  表23 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

  

  导出为数字信封前需检测输入的密码是否与指定索引值匹配，匹配后使用入参公钥加密生成数字信封，设备中不存在对应索引值的密钥时返回失败。