密钥管理工具接口
为了方便客户定制化管理密钥，提供了密钥管理工具接口供用户调用。
- 管理工具创建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
失败，返回错误码
- 删除指定内置密钥。
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
失败，返回错误码
- 明文导入密钥加密密钥。
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
失败，返回错误码
- 数字信封形式导入设备内部密钥。
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上以及虚拟机上运行。