---
title: 密钥管理工具接口
description: "为了方便客户定制化管理密钥，提供了密钥管理工具接口供用户调用。"
url: https://www.hikunpeng.com/document/detail/zh/kunpengcctrustzone/cca/devg/Kunpeng_ommercialcryptography_16_0032.html
sourcePath: /source/zh/kunpengcctrustzone/cca/devg/Kunpeng_ommercialcryptography_16_0032.html
indexId: d09ca1c83101c796bc31ea87feb836f0e167822b5e9ef70e995dbc634c28d9b481
---
# 密钥管理工具接口

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

- 管理工具创建session用户。

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


**表1 参数说明**

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


**表2 返回值说明**

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


  关闭ECM_OpenSession打开的session，请使用SDF_CloseSession接口


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

```
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 | 失败，返回错误码 |


  恢复出厂设置后ECM密码也会被删除，再次使用时需创建新密码。

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

```
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 | 失败，返回错误码 |


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

  查询ECM密码是否存在。

```
int ECM_QueryECMPasswd(void *hSessionHandle);
```


**表24 参数说明**

| 参数 | 描述 |
| --- | --- |
| void \*hSessionHandle[in] | 管理session句柄 |


**表25 返回值说明**

| 返回值 | 说明 |
| --- | --- |
| 0 | 密码不存在 |
| 1 | 密码存在 |


  核查输入的ECM密码是否正确。

```
int ECM_CheckECMPasswd(void *hSessionHandle, char *input_ecm_passwd, size_t input_ecm_passwd_len);
```


**表26 参数说明**

| 参数 | 描述 |
| --- | --- |
| void \*hSessionHandle[in] | 管理session句柄 |
| char \*input\_ecm\_passwd[in] | 输入的ECM密码 |
| size\_t input\_ecm\_passwd\_len[in] | 输入的ECM密码长度 |


**表27 返回值说明**

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


  修改ECM密码。

```
int ECM_ChangeECMPasswd(void *hSessionHandle, char *new_password, size_t new_password_len);
```


**表28 参数说明**

| 参数 | 描述 |
| --- | --- |
| void \*hSessionHandle[in] | 管理session句柄 |
| char \*new\_password[in] | 新ECM密码 |
| size\_t new\_password\_len[in] | 新ECM密码长度 |


**表29 返回值说明**

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


  首次使用ECM工具时，会创建ECM密码。为增强安全性，建议定期修改密码。 密码需要满足以下格式要求： 口令必须包含如下至少两种字符的组合。 至少一个小写字母。 至少一个大写字母。 至少一个数字。 至少一个特殊字符：`~!@#$%^&*()-_=+\|[{}];:'",<.>/? 和空格。 长度最少8字节，最多128字节。


#### 规格限制

集成这些接口的应用应以root用户执行，并能在Host上以及虚拟机上运行。