密钥管理工具接口

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

• 管理工具创建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_SetAccessRight(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucAccessInfo, unsigned char *pucPassword, unsigned int uiPwdLength);

  表15 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  pucAccessInfo[in]	缓冲区指针，用于存放允许访问的应用hash值，长度固定32字节
  pucPassword[out]	使用私钥权限的标识码
  uiPwdLength[in]	使用私钥权限标识码的长度，长度8~128字节

  表16 返回值说明

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

  

  CA应用的hash值计算方式为：SHA256（CA的路径||用户名），即CA路径拼接上用户名，再计算SHA256得到的值。注意用户名长度需固定为256字节，长度不足时需补零。

• 删除可以访问内置密钥的应用路径。

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

  表17 参数说明

  参数	描述
  hSessionHandle[in]	与设备建立的会话句柄
  uiKeyIndex[in]	密码设备存储私钥的索引值，由密钥类型与索引下标组成
  pucAccessInfo[in]	缓冲区指针，用于存放允许访问的应用hash值，长度固定32字节
  pucPassword[out]	使用私钥权限的标识码
  uiPwdLength[in]	使用私钥权限标识码的长度，长度8~128字节

  表18 返回值说明

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

• 恢复出厂设置。

  int ECM_FactoryReset();

  表19 返回值说明

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