密码卡API手册

一、概述

该密码卡支持高速国产标准密码算法，支持真随机数产生。具有安全有效的密钥管理功能和设备管理功能，具有安全有效的保护措施。其API接口支持《GM/T 0018-2012 密码设备应用接口规范》。

适用范围

此手册适用于派科信安的如下PCIe密码卡：

• A系列：A1、A2、A3
• C系列：C1

适用于派科信安的如下Mini PCIe密码卡：

• M10、M10U
• M11、M11U
• M12、M12U
• M13
• M50

二、接口使用说明

2.1 定义

2.1.1 设备信息定义

字段名称	数据长度（字节）	含义
IssuerName	40	设备生产厂商名称
DeviceName	16	设备型号
DeviceSerial	16	设备编号，包含：日期（8字符）、批次号（3字符）、流水号（5字符）
DeviceVersion	4	密码设备内部软件的版本号
StandardVersion	4	密码设备支持的接口规范版本号
AsymAlgAbility	8	前4字节表示支持的算法,表示方法为非对称算法标识按位或的结果；后4字节表示算法的最大模长，表示方法为支持的模长按位或的结果
SymAlgAbility	4	所有支持的对称算法，表示方法为对称算法标识按位或运算结果
HashAlgAbility	4	所有支持的杂凑算法，表示方法为杂凑算法标识按位或运算结果
BufferSize	4	支持的最大文件存储空间（单位字节）

实际数据结构定义：

typedef struct DeviceInfo_st{
    unsigned char IssuerName[40];
    unsigned char DeviceName[16];
    unsigned char DeviceSerial[16]
    unsigned int  DeviceVersion;
    unsigned int  StandardVersion;
    unsigned int  AsymAlgAbility[2];
    unsigned int  SymAlgAbility;
    unsigned int  HashAlgAbility;
    unsigned int  BufferSize; 
}DEVICEINFO;

2.1.2 算法标识定义

对称算法标识：

宏描述	预定义值	说明
#define SGD_SM1_ECB	0x00000101	SM1算法ECB加密模式
#define SGD_SM1_CBC	0x00000102	SM1算法CBC加密模式
#define SGD_SM1_CFB	0x00000104	SM1算法CFB加密模式
#define SGD_SM1_OFB	0x00000108	SM1算法OFB加密模式
#define SGD_SM1_MAC	0x00000110	SM1算法MAC加密模式
#define SGD_SSF33_ECB	0x00000201	SSF33算法ECB加密模式
#define SGD_SSF33_CBC	0x00000202	SSF33算法CBC加密模式
#define SGD_SSF33_CFB	0x00000204	SSF33算法CFB加密模式
#define SGD_SSF33_OFB	0x00000208	SSF33算法OFB加密模式
#define SGD_SSF33_MAC	0x00000210	SSF33算法MAC加密模式
#define SGD_SM4_ECB	0x00000401	SM4算法ECB加密模式
#define SGD_SM4_CBC	0x00000402	SM4算法CBC加密模式
#define SGD_SM4_CFB	0x00000404	SM4算法CFB加密模式
#define SGD_SM4_OFB	0x00000408	SM4算法OFB加密模式
#define SGD_3DES_ECB	0x00002001	3DES算法ECB加密模式
#define SGD_3DES_CBC	0x00002002	3DES算法CBC加密模式
#define SGD_3DES_CFB	0x00002004	3DES算法CFB加密模式
#define SGD_3DES_OFB	0x00002008	3DES算法OFB加密模式
#define SGD_3DES_MAC	0x00002010	3DES算法MAC加密模式
0x00001000—0x00080000		为其它算法预留，包括国际标准算法或自实现算法

非对称算法标识：

宏描述	预定义值	说明
#define SGD_RSA	0x00010000	RSA算法
#define SGD_SM2-1	0x00020100	椭圆曲线签名算法
#define SGD_SM2-2	0x00020200	椭圆曲线密钥交换协议
#define SGD_SM2-3	0x00020400	椭圆曲线加密算法

杂凑算法标识：

宏描述	预定义值	说明
#define SGD_SM3	0x00000001	SM3杂凑算法
#define SGD_SHA1	0x00000002	SHA1杂凑算法
#define SGD_SHA256	0x00000004	SHA256杂凑算法
#define SGD_SHA512	0x00000008	SHA512杂凑算法

2.1.3 密钥分类及存储定义

密钥存储区，用于非对称密钥对的存放，索引号从0开始检索，每个索引号对应一个签名密钥对和一个加密密钥对。其中，索引号为0表示设备密钥。索引号1开始表示用户密钥。

设备密钥只能在设备初始化时生成或安装，用户密钥通过密码设备管理工具生成或安装。

密钥对索引号	公钥	私钥
0x00	设备签名公钥	设备签名私钥
设备加密公钥	设备加密私钥
0x01	用户签名公钥	用户签名私钥
用户加密公钥	用户加密私钥
……	……	……
……	……

密钥加密密钥通过密码设备管理工具生成或安装，存储区可存储密钥长度为128位的密钥加密密钥，使用索引号从1开始。

密钥索引号	密钥加密密钥
0x01	密钥加密密钥001
……	……

会话密钥长度为128位，使用设备接口函数生成或导入，会话密钥使用句柄检索。

2.1.4 密码设备权限

密码设备分为三种权限，超级管理员权限、管理员权限和操作员权限，三种模式拥有不同的权限，可以对密码设备的各类密钥进行不同的操作。

对应权限密码卡配有超级管理员权限一名，管理员一名，操作员0～2名，管理员拥有管理员权限，所有的操作员拥有相同的操作员权限，详见各函数备注和《用户手册》。

应用模式定义

宏描述	预定义值	说明
#define SUPPER_ADMIN	0x00000001	超级管理员权限
#define ADMIN	0x00000002	管理员权限
#define ASSISTANT1	0x00000003	操作员1
#define ASSISTANT2	0x00000004	操作员2

2.1.5 密码设备状态

出厂的密码设备分为三种状态，出厂状态、初始化状态、就绪状态。

宏描述	预定义值	说明
#define ST_FAC	0x00000001	出厂状态
#define ST_INT	0x00000002	初始化状态
#define ST_READY	0x00000003	就绪状态

2.1.6 密码卡各类数据结构定义

RSA结构定义

公钥数据结构定义
字段名称	数据长度（字节）	含义
bits	4	模长
M	256	模N
E	256	公钥指数
私钥数据结构定义
字段名称	字段名称	字段名称
bits	4	模长
M	256	模N
E	256	公钥指数
D	256	私钥指数
prime[2]	128×2	素数p和q
pexp[2]	128×2	Dp和Dq
Coef	128	系数i

#define RSAref_MAX_BITS 2048
#define RSAref_MAX_LEN ((RSAref_MAX_BITS +7)/8)
#define RSAref_MAX_PBITS ((RSAref_MAX_BITS +1)/2)
#define RSAref_MAX_PLEN ((RSAref_MAX_PBITS +7)/8)

typedef struct RSArefPublicKey_st
{
    unsigned int  bits;
    unsigned char m[RSAref_MAX_LEN];
    unsigned char e[RSAref_MAX_LEN];
} RSArefPublicKey;

typedef struct RSArefPrivateKey_st
{
    unsigned  int  bits;
    unsigned char m[RSAref_MAX_LEN];
    unsigned char e[RSAref_MAX_LEN];
    unsigned char d[RSAref_MAX_LEN];
    unsigned char prime[2][RSAref_MAX_PLEN];
    unsigned char pexp[2][RSAref_MAX_PLEN];
    unsigned char coef[RSAref_MAX_PLEN];
} RSArefPrivateKey;

ECC结构定义

公钥数据结构定义
字段名称	数据长度（字节）	含义
bits	4	密钥长度
x	ECCref_MAX_LEN	公钥x坐标
y	ECCref_MAX_LEN	公钥y坐标
私钥数据结构定义
字段名称	字段名称	字段名称
bits	4	密钥长度
K	ECCref_MAX_LEN	私钥

#define ECCref_MAX_BITS 512
#define ECCref_MAX_LEN ((ECCref_MAX_BITS+7)/8)

typedef struct ECCrefPublicKey_st
{
    unsigned int  bits;
    unsigned char x[ECCref_MAX_LEN];
    unsigned char y[ECCref_MAX_LEN];
}ECCrefPublicKey;

typedef struct ECCrefPrivateKey_st
{
    unsigned int  bits;
    unsigned char K[ECCref_MAX_LEN];
    }ECCrefPrivateKey;

ECC加密数据结构定义

公钥数据结构定义
字段名称	数据长度（字节）	含义
x	ECCref_MAX_LEN	X分量
y	ECCref_MAX_LEN	Y分量
M	32	明文杂凑
L	4	明文数据长度
C	L	密文值

typedef struct ECCCipher_st
{
    unsigned char x[ECCref_MAX_LEN];
    unsigned char y[ECCref_MAX_LEN];
    unsigned char M[32];
    unsigned int  L;
    unsigned char C[1];
}ECCCipher;

ECC签名数据结构定义

签名数据结构定义
字段名称	数据长度（字节）	含义
r	ECCref_MAX_LEN	签名的r部分
s	ECCref_MAX_LEN	签名的s部分

typedef struct ECCSignature_st
{
    unsigned char r[ECCref_MAX_LEN];
    unsigned char s[ECCref_MAX_LEN];
}ECCSignature;

ECC加密密钥对保护结构

数据项	类型	意义	备注
ulAsymmAlgID	unsigned long	保护对称密钥的非对称算法标识
ulSymmAlgID	unsigned long	对称算法标识	必须为ECB模式
ECCCipherBlob	ECCCIPHERBLOB	对称密钥密文
PubKey	ECCPUBLICKEYBLOB	加密密钥对的公钥
cbEncryptedPrivKey	无符号数组	加密密钥对的私钥密文，其有效值为原文的(ulBits+7)/8	私钥原文为ECCPRIVATEKEYBLOB结构中的PrivateKey

typedef struct SDF_ENVELOPEDKEYBLOB
{
    unsigned long  ulAsymmAlgID;
    unsigned long  ulSymmAlgID;
    ECCCipher  ECCCipherBlob;
    ECCrefPublicKey  PubKey;
    Unsigned char cbEncryptedPriKey[64];
}ENVELOPEDKEYBLOB,*PENVELOPEDKEYBLOB;

RSA加密密钥对保护结构

数据项	类型	意义	备注
ulAsymmAlgID	unsigned long	保护对称密钥的非对称算法标识
ulSymmAlgID	unsigned long	对称算法标识	必须为ECB模式
RSACipherBlob	无符号数组	对称密钥密文
PubKey	RSAPUBLICKEYBLOB	加密密钥对的公钥
cbEncryptedPrivKey	无符号数组	加密密钥对的私钥密文，其有效值为原文的(ulBits+7)/8	私钥原文为ECCPRIVATEKEYBLOB结构中的PrivateKey

typedef struct SDF_RSAENVELOPEDKEYBLOB
{
    unsigned long  ulAsymmAlgID;
    unsigned long  ulSymmAlgID;
    unsigned char  RSACipherBlob[256];
    RSArefPublicKey  PubKey;
    Unsigned char  cbEncryptedPriKey[896];
}RSAENVELOPEDKEYBLOB,*PRSAENVELOPEDKEYBLOB;

2.2 设备接口描述

2.2.1 设备管理类函数

打开设备 SDF_OpenDevice

int SDF_OpenDevice(void **phDeviceHandle);

描述
打开密码设备

参数
phDeviceHandle[out]	返回设备句柄

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

备注
1、 phDeviceHandle由函数初始化并填写内容
2、不受状态和权限限制

关闭设备SDF_CloseDevice

int SDF_CloseDevice(void *hDeviceHandle);

描述
关闭密码设备，并释放相关资源

参数
phDeviceHandle[in]	已打开的设备句柄

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

备注
不受状态和权限限制

创建会话 SDF_OpenSession

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

描述
创建与密码设备的会话

参数
phDeviceHandle[in]	已打开的设备句柄
phSessionHandle[out]	返回与密码设备建立的新会话句柄

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

备注
在初始化和就绪状态，不限权限可以使用

关闭会话 SDF_CloseSession

int SDF_CloseSession(void *hSessionHandle); 

描述
关闭与密码设备已建立的会话，并释放相关资源

参数
ulDeviceHandle[in]	与密码设备已建立的会话句柄

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

备注
在初始化和就绪状态，不限权限可以使用

获取设备信息 SDF_GetDeviceInfo

int SDF_GetDeviceInfo(void *hSessionHandle, DEVICEINFO *pstDeviceInfo); 

描述
获取密码设备能力描述

参数
hSessionHandle[in]	与设备建立的会话句柄
pstDeviceInfo [out]	设备能力描述信息，内容及格式见设备信息定义

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

备注
不受状态和权限限制

产生随机数 SDF_GenerateRandom

int SDF_GenerateRandom(
    void *hSessionHandle,
    unsigned int uiLength,
    unsigned char *pucRandom); 

描述
获取随机数

参数：
hSessionHandle[in]	与设备建立的会话句柄
uiLength[in]	欲获取的随机数长度
pucRandom[out]	缓冲区指针，用于存放获取的随机数

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

备注
1 、获取随机数的长度不限
2 、在就绪状态，不限权限可以使用

获取私钥使用权限 SDF_GetPrivateKeyAccessRight

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

描述
获取密码设备内部存储的指定索引私钥的使用授权

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex[in]	密码设备存储私钥索引值（0～KEYPAIR_MAX_INDEX）
pucPassword[in]	使用私钥权限标识码
uiPwdLength[in]	私钥权限标识码长度，不少于8字节

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

备注
1、密码设备存储的密钥对索引值的的起始索引值为0，最大为KEYPAIR_MAX_INDEX，密钥权限初始密码为”3.1415926”
2、0号密钥在初始化、就绪状态，此函数不限权限可以调用，密钥实际使用还需登录管理员权限
3、其他密钥在就绪状态，此函数不限权限可以调用，密钥实际使用还需登录管理员或操作员权限

释放私钥使用权限 SDF_ReleasePrivateKeyAccessRight

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

描述
释放密码设备存储的指定索引私钥的使用授权

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex[in]	密码设备存储私钥索引值

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

备注
1、密码设备存储的密钥对索引值的的起始索引值为0，最大为KEYPAIR_MAX_INDEX
2、0号密钥在初始化、就绪状态，管理员权限下可以调用
3、其他密钥在就绪状态，不限权限可以调用

2.2.2 密钥管理类函数

导出ECC签名公钥SDF_ExportSignPublicKey_ECC

int SDF_ExportSignPublicKey_ECC(
    void *hSessionHandle,
    unsigned int  uiKeyIndex,
    ECCrefPublicKey *pucPublicKey);

描述
导出密码设备内部存储的指定索引位置的签名公钥

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex[in]	密码设备存储私钥索引值
pucPublicKey[out]	ECC公钥结构

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

备注
1、0<= uiKeyIndex<=KEYPAIR_MAX_INDEX
2、0号密钥在就绪状态，管理员权限下可以调用
3、其他密钥在就绪状态，管理员或操作员权限可以调用

导出ECC加密公钥SDF_ExportEncPublicKey_ECC

int SDF_ExportEncPublicKey_ECC(
    void *hSessionHandle,
    unsigned int  uiKeyIndex,
    ECCrefPublicKey *pucPublicKey);

描述
导出密码设备内部存储的指定索引位置的加密公钥

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex[in]	密码设备存储私钥索引值
pucPublicKey[out]	ECC公钥结构

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

备注
1、0<= uiKeyIndex<=KEYPAIR_MAX_INDEX
2、0号密钥在就绪状态，管理员权限下可以调用
3、其他密钥在就绪状态，管理员或操作员权限可以调用

产生ECC密钥对并输出SDF_GenerateKeyPair_ECC

int SDF_GenerateKeyPair_ECC(
    void *hSessionHandle,
    unsigned int  uiAlgID,
    unsigned int  uiKeyBits,
    ECCrefPublicKey *pucPublicKey,
    ECCrefPrivateKey *pucPrivateKey);

描述
请求密码设备产生指定类型和模长的非对称密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID[in]	指定算法标识
uiKeyBits [in]	指定密钥比特长度
pucPublicKey[out]	ECC公钥结构
pucPrivateKey[out]	ECC私钥结构

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

备注
在就绪状态，不限权限可以调用

生成会话密钥用内部ECC公钥加密输出SDF_GenerateKeyWithIPK_ECC

int SDF_GenerateKeyWithIPK_ECC(
    void *hSessionHandle,
    unsigned int uiIPKIndex,
    unsigned int  uiKeyBits,
    ECCCipher *pucKey,
    void **phKeyHandle);

描述
生成会话密钥并用指定索引的内部加密公钥加密输出，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
uiIPKIndex[in]	密码设备内部存储公钥的索引值
uiKeyBits[in]	产生会话密钥的bit长度
pucKey[out]	缓冲区指针，用于存放返回的密钥密文
phKeyHandle[out]	返回的密钥句柄

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

备注
1、uiIPKIndex<=KEYPAIR_MAX_INDEX
2、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
3、0号公钥在就绪状态，管理员权限下可以调用
4、其他公钥在就绪状态，管理员或操作员权限可以调用

生成会话密钥用外部ECC公钥加密输出SDF_GenerateKeyWithEPK_ECC

int SDF_GenerateKeyWithEPK_ECC(
    void *hSessionHandle,
    unsigned int uiKeyBits,
    unsigned int uiAlgID,
    ECCrefPublicKey *pucPublicKey,
    ECCCipher *pucKey,
    void **phKeyHandle);

描述
生成会话密钥并用内部公钥加密输出，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyBits[in]	产生会话密钥的bit长度
uiAlgID[in]	外部 ECC 公钥的算法标识
pucPublicKey[in]	输入的外部ECC公钥结构
pucKey[out]	缓冲区指针，用于存放返回的密钥密文
phKeyHandle[out]	返回的密钥句柄

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

备注
1、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
2、在就绪状态，不限权限可以调用
3、uiAlgID支持SGD_SM2_3

导入会话密钥并用内部ECC私钥解密SDF_ImportKeyWithISK_ECC

int SDF_ImportKeyWithISK_ECC(
    void *hSessionHandle,
    unsigned int uiISKIndex,
    ECCCipher *pucKey,
    void **phKeyHandle);

描述
导入会话密钥并用内部私钥解密，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex[in]	密码设备内部存储加密私钥的索引值，对应于加密时的公钥
pucKey[in]	缓冲区指针，用于存放输入的密钥密文
phKeyHandle[out]	返回的密钥句柄

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

备注
1、uiISKIndex <=KEYPAIR_MAX_INDEX
2、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
3、0号私钥在就绪状态，管理员权限下可以调用
4、其他私钥在就绪状态，管理员或操作员权限可以调用

生成密钥协商参数并输出 SDF_GenerateAgreementDataWithECC

int SDF_GenerateAgreementDataWithECC(
    void *hSessionHandle,
    unsigned int uiISKIndex，
    unsigned int uiKeyBits，
    unsigned char *pucSponsorID,
    unsigned int uiSponsorIDLength,
    ECCrefPublicKey *pucSponsorPublicKey,
    ECCrefPublicKey *pucSponsorTmpPublicKey,
    void ** phAgreementHandle);

描述
密钥协商第一步，密钥协商的发起方首先调用本函数。如果在具体的应用中，协商双方没有统一分配的ID，可以将ID设定为常量。

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex [in]	密码设备内部存储加密私钥的索引值，该私钥用于参与密钥协商
uiKeyBits[in]	要求协商的密钥长度
pucSponsorID[in]	参与密钥协商的发起方ID值
uiSponsorIDLength[in]	发起方ID长度
pucSponsorPublicKey[out]	返回的发起方ECC公钥结构
pucSponsorTmpPublicKey[out]	返回的发起方临时ECC公钥结构
phAgreementHandle[out]	返回的协商句柄，用于计算协商密钥

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

备注
1、 uiKeyBits为128bit。如果发起方或者响应方ID长度为零，则函数使用默认ID，为32字节0xff
2、 uiISKIndex<=KEYPAIR_MAX_INDEX
3、 uiISKIndex=0时，在就绪状态管理员权限下可以使用
4、 uiISKIndex不等于0时，在就绪状态下，管理员或操作员权限可以使用

计算会话密钥SDF_GenerateKeyWithECC

int SDF_GenerateKeyWithECC (
    void *hSessionHandle,
    unsigned char *pucResponseID，
    unsigned int uiResponseIDLength，
    ECCrefPublicKey *pucResponsePublicKey,
    ECCrefPublicKey *pucResponseTmpPublicKey,
    void *hAgreementHandle,
    void **phKeyHandle);

描述
密钥协商第三步，密钥协商的发起方调用本函数。如果在具体的应用中，协商双方没有统一分配的ID，可以将ID设定为常量。

参数
hSessionHandle[in]	与设备建立的会话句柄
pucResponseID[in]	响应方ID值
uiResponseIDLength[in]	响应方ID长度
pucResponsePublicKey[in]	响应方ECC公钥结构
pucResponseTmpPublicKey[in]	响应方临时ECC公钥结构
hAgreementHandle[in]	协商句柄，用于计算协商密钥
phKeyHandle[out]	返回的密钥句柄

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

备注
1、 uiKeyBits为128bit。如果发起方或者响应方ID长度为零，则函数使用默认ID，为32字节0xff
2、在就绪状态下，管理员或操作员权限可以使用

产生协商参数并计算会话密钥SDF_GenerateAgreementDataAndKeyWithECC

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);

描述
密钥协商第二步，密钥协商的响应方调用本函数。如果在具体的应用中，协商双方没有统一分配的ID，可以将ID设定为常量。

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex [in]	密码设备内部存储加密私钥的索引值，该私钥用于参与密钥协商
uiKeyBits[in]	要求协商的密钥长度
pucResponseID[in]	响应方ID值
uiSponsorIDLength[in]	响应方ID长度
pucSponsorID[in]	参与密钥协商的发起方ID值
uiSponsorIDLength[in]	发起方ID长度
pucSponsorPublicKey[in]	输入的发起方ECC公钥结构
pucSponsorTmpPublicKey[in]	输入的发起方临时ECC公钥结构
pucResponsePublicKey[out]	返回的响应方ECC公钥结构
pucResponseTmpPublicKey[out]	返回的响应方ECC临时公钥结构
phKeyHandle [out]	返回的密钥句柄

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

备注
1、uiKeyBits为128bit。如果发起方或者响应方ID长度为零，则函数使用默认ID，为32字节0xff
2、uiISKIndex<=KEYPAIR_MAX_INDEX
3、uiISKIndex=0时，在就绪状态管理员权限下可以使用
4、uiISKIndex不等于0时，在就绪状态下，管理员或操作员权限可以使用

销毁密钥协商参数句柄SPII_DestroyAgreementHandle

int SPII_DestroyAgreementHandle (
    void *hSessionHandle,
    void *hAgreementHandle);

描述
用于销毁不使用的密钥协商参数。

参数
hSessionHandle[in]	与设备建立的会话句柄
hAgreementHandle[in]	协商句柄，用于计算协商密钥

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

备注
1、在就绪状态下，管理员或操作员权限可以使用

基于ECC算法的数字信封转换SDF_ExchangeDigitEnvelopeBaseOnECC

int SDF_ExchangeDigitEnvelopeBaseOnECC(
                        IN  HANDLE hSessionHandle, 
                        IN  unsigned int  uiKeyIndex,
                        IN  unsigned int  uiAlgID,
                        IN  ECCrefPublicKey *pucPublicKey,
                        IN  ECCCipher *pucEncDataIn,
                        OUT ECCCipher *pucEncDataOut
                        );

描述
将由内部加密公钥加密的会话密钥转换为由外部指定的公钥加密，可用于数字信封转换

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex [in]	密码设备存储的ECC 密钥对索引值
uiAlgID[in]	外部ECC公钥的算法标识
pucPublicKey[in]	外部ECC公钥结构
pucEncDataIn[in]	缓冲区指针，用于存放输入的会话密钥密文
pucEncDataOut[out]	缓冲区指针，用于存放输出的会话密钥密文

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

备注
1、uiISKIndex<=KEYPAIR_MAX_INDEX
2、uiISKIndex=0时，在就绪状态管理员权限下可以使用
3、uiISKIndex不等于0时，在就绪状态下，管理员或操作员权限可以使用

生成会话密钥并用密钥加密密钥加密输出SDF_GenerateKeyWithKEK

int SDF_GenerateKeyWithKEK (
    void *hSessionHandle,
    unsigned int uiKeyBits,
    unsigned int  uiAlgID,
    unsigned int uiKEKIndex,
    unsigned char *pucKey,
    unsigned int *puiKeyLength,
    void **phKeyHandle);

描述
生成会话密钥并用密钥加密密钥加密输出，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyBits[in]	指定产生的会话密钥长度
uiAlgID[in]	算法标识，指定对称加密算法
uiKEKIndex[in]	密码设备内部存储密钥加密密钥的索引值
pucKey[out]	缓冲区指针，用于存放返回的密钥密文
puiKeyLength[out]	返回的密钥密文字节长度
phKeyHandle[out]	返回的密钥句柄

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

备注
1、加密模式默认使用ECB模式
2、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
3、0<uiKEKIndex<=KEK_MAX_INDEX
4、在就绪状态下，管理员或操作员权限可以使用

导入会话密钥并用密钥加密密钥解密SDF_ImportKeyWithKEK

int SDF_ImportKeyWithKEK (
    void *hSessionHandle,
    unsigned int  uiAlgID,
    unsigned int uiKEKIndex,
    unsigned char *pucKey,
    unsigned int *puiKeyLength,
    void **phKeyHandle);

描述
导入会话密钥并用密钥加密密钥解密，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID[in]	算法标识，指定对称加密算法
uiKEKIndex[in]	密码设备内部存储密钥加密密钥的索引值
pucKey[in]	缓冲区指针，用于存放输入的密钥密文
puiKeyLength[in]	输入的密钥密文字节长度
phKeyHandle[out]	返回的密钥句柄

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

备注
1、加密模式默认使用ECB模式
2、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
3、0<uiKEKIndex<=KEK_MAX_INDEX
4、在就绪状态下，管理员或操作员权限可以使用

导入明文会话密钥SDF_ImportKey

int SDF_ImportKey (
    void *hSessionHandle,
    unsigned char *pucKey,
    unsigned int uiKeyLength,
    void **phKeyHandle);

描述
导入明文会话密钥，同时返回密钥句柄

参数
hSessionHandle[in]	与设备建立的会话句柄
pucKey[in]	缓冲区指针，用于存放输入的密钥明文
puiKeyLength[in]	输入的密钥明文字节长度
phKeyHandle[out]	返回的密钥句柄

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

备注
1、会话密钥的实际长度为16字节，会话密钥用于对称加解密，见函数SDF_Encrypt和SDF_Decrypt
2、在就绪状态下，不限权限可以使用

销毁会话密钥SDF_DestroyKey

int SDF_DestroyKey (
    void *hSessionHandle,
    void *hKeyHandle);

描述
销毁密钥句柄，并释放为密钥句柄分配的内存等资源。

参数
hSessionHandle[in]	与设备建立的会话句柄
hKeyHandle[in]	输入的密钥句柄

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

备注
1、在运算完成后应调用本函数销毁密钥句柄
2、在就绪状态下，不限权限可以使用

2.2.3 非对称算法运算类函数

外部密钥ECC签名SDF_ExternalSign_ECC

int SDF_ExternalSign_ECC(
    void * hSessionHandle,
    unsigned int uiAlgID,
    ECCrefPrivateKey *pucPrivateKey,
    unsigned char *pucData,
    unsigned int  uiDataLength,
    ECCSignature *pucSignature);

描述
ECC外部私钥签名

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID [in]	算法标记，支持SGD_SM2_1
pucPrivateKey[in]	私钥结构指针
pucData [in]	签名数据
uiDataLength [in]	签名数据长度
pucSignature[out]	签名值结构

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

备注
1、ECC默认长度为256bit
2、签名数据长度固定为32byte，对原文的杂凑运算，在函数外部完成。
3、在就绪状态下，不限权限可以使用

外部密钥ECC验证SDF_ExternalVerify_ECC

int SDF_ExternalVerify_ECC(
    void *hSessionHandle,
    unsigned int uiAlgID,
    ECCrefPublicKey *pucPublicKey,
    unsigned char *pucDataInput,
    unsigned int  uiInputLength,
    ECCSignature *pucSignature);

描述
使用ECC公钥对ECC签名值进行验证运算

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID[in]	算法标识，指定使用的ECC算法，支持SGD_SM2_1
pucPublicKey[in]	外部ECC公钥结构
pucData[in]	缓冲区指针，用于存放外部输入的数据
uiDataLength[in]	输入的数据字节长度
pucSignature[in]	缓冲区指针，用于存放输入的签名值数据

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

备注
1、对原文的杂凑运算，在函数外部完成。
2、就绪状态下，不限权限可以使用

内部密钥ECC签名SDF_InternalSign_ECC

int SDF_InternalSign_ECC(
    void *hSessionHandle,
    unsigned int  uiISKIndex,
    unsigned char *pucData,
    unsigned int  uiDataLength,
    ECCSignature *pucSignature);

描述
使用ECC私钥对数据进行签名运算

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex [in]	密码设备内部存储的ECC签名私钥的索引值
pucData[in]	缓冲区指针，用于存放外部输入的数据
uiDataLength[in]	输入的数据字节长度
pucSignature [out]	缓冲区指针，用于存放输出的签名值数据

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

备注
1、对原文的杂凑运算，在函数外部完成。
2、 uiISKIndex<=KEYPAIR_MAX_INDEX
3、 uiISKIndex =0时，就绪状态下，管理员权限可以使用
4、 uiISKIndex >0时，就绪状态下，管理员或操作员权限可以使用

内部密钥ECC验证SDF_InternalVerify_ECC

int SDF_InternalVerify_ECC(
    void *hSessionHandle,
    unsigned int  uiISKIndex,
    unsigned char *pucData,
    unsigned int  uiDataLength,
    ECCSignature *pucSignature);

描述
使用ECC公钥对ECC签名值进行验证运算

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex [in]	密码设备内部存储的ECC签名公钥的索引值
pucData[in]	缓冲区指针，用于存放外部输入的数据
uiDataLength[in]	输入的数据字节长度
pucSignature[in]	缓冲区指针，用于存放输入的签名值数据

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

备注
1、对原文的杂凑运算，在函数外部完成。
2、 uiISKIndex<=KEYPAIR_MAX_INDEX
3、 uiISKIndex =0时，就绪状态下，管理员权限可以使用
4、 uiISKIndex >0时，就绪状态下，管理员或操作员权限可以使用

外部密钥ECC加密SDF_ExternalEncrypt_ECC

int SDF_ExternalEncrypt_ECC(
    void *hSessionHandle,
    unsigned int uiAlgID,
    ECCrefPublicKey *pucPublicKey,
    unsigned char *pucData,
    unsigned int  uiDataLength,
    ECCCipher *pucEncData);

描述
使用外部ECC公钥对数据进行加密运算

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID[in]	算法标识，指定使用的ECC算法，支持SGD_SM2_3
pucPublicKey[in]	外部ECC公钥结构
pucData[in]	缓冲区指针，用于存放外部输入的数据
uiDataLength[in]	输入的数据长度
pucEncData[out]	缓冲区指针，用于存放输出的数据密文

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

备注
1、输入的数据长度uiDataLength<=MAX_DATALEN。
2、在就绪状态下，不限权限可以使用

外部密钥ECC解密SDF_ExternalDecrypt_ECC

SDF_ExternalDecrypt_ECC(
    void * hSessionHandle,
    unsigned int uiAlgID,
    ECCrefPrivateKey *pucPrivateKey,
    ECCCipher *pucEncData,
    unsigned char *pucData,
    unsigned int *puiDataLength);

描述
ECC外部密钥解密

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID [in]	算法标记，支持SGD_SM2_3
pucPrivateKey[in]	私钥结构指针
pucEncData[in]	密文结构指针
pucData[out]	明文指针
puiDataLength[out]	明文指针长度

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

备注
1、在就绪状态下，不限权限可以使用

内部密钥ECC加密SDF_InternalEncrypt_ECC

int SDF_InternalEncrypt_ECC(
    void *hSessionHandle,
    unsigned int uiIPKIndex,
    unsigned int uiAlgID,
    unsigned char *pucData,
    unsigned int uiDataLength,
    ECCCipher *pucEncData);;

描述
使用内部ECC公钥对数据进行加密运算，非国密标准接口

参数
hSessionHandle[in]	与设备建立的会话句柄
uiIPKIndex[in]	密码设备内部存储的ECC加密公钥的索引值
uiAlgID[in]	算法标识，指定使用的ECC算法，支持SGD_SM2_3
pucData[in]	缓冲区指针，用于存放外部输入的数据
uiDataLength[in]	输入的数据长度
pucEncData[out]	缓冲区指针，用于存放输出的数据密文

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

备注
1、输入的数据长度uiDataLength<=MAX_DATALEN。
2、uiIPKIndex<=KEYPAIR_MAX_INDEX
3、在就绪状态下，管理员或操作员权限可以使用

内部密钥ECC解密SDF_InternalDecrypt_ECC

int SDF_InternalDecrypt_ECC(
    void *hSessionHandle,
    unsigned int uiISKIndex,
    unsigned int uiAlgID,
    ECCCipher *pucEncData,
    unsigned char *pucData,
    unsigned int *puiDataLength);

描述
内部ECC私钥解密，非国密标准接口

参数
hSessionHandle[in]	与设备建立的会话句柄
uiISKIndex[in]	密码设备内部存储的EC加密公钥的索引值
uiAlgID [in]	算法标记，支持SGD_SM2_3
pucEncData[in]	密文结构指针
pucData[out]	明文指针
puiDataLength[out]	明文指针长度

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

备注
1、在就绪状态下，不限权限可以使用
2、 uiISKIndex<=KEYPAIR_MAX_INDEX
3、 uiISKIndex =0时，就绪状态下，管理员权限可以使用
4、 uiISKIndex >0时，就绪状态下，管理员或操作员权限可以使用

2.2.4 对称算法运算类函数

对称加密SDF_Encrypt

int SDF_Encrypt(
    void *hSessionHandle,
    void *hKeyHandle,
    unsigned int uiAlgID,
    unsigned char *pucIV,
    unsigned char *pucData,
    unsigned int uiDataLength,
    unsigned char *pucEncData,
    unsigned int *puiEncDataLength);

描述
使用指定的密钥句柄和IV对数据进行对称加密运算

参数
hSessionHandle[in]	与设备建立的会话句柄
hKeyHandle[in]	指定的密钥句柄
uiAlgID[in]	算法标识，指定对称加密算法
pucIV[in|out]	缓冲区指针，用于存放输入和返回的IV数据
pucData[in]	缓冲区指针，用于存放输入的数据明文
uiDataLength[in]	输入的数据明文的字节长度
pucEncData[out]	缓冲区指针，用于存放输出的数据密文
puiEncDataLength[out]	输出的数据密文字节长度

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

备注
1、此函数不对数据进行填充处理，输入的数据必须是指定算法分组长度（16字节）的整数倍。
2、此函数对数据进行分包处理，输入数据最大长度不限，CBC模式多包数据IV向量由函数外部自行控制
3、在就绪状态下，不限权限可以使用

对称解密SDF_Decrypt

int SDF_Decrypt (
    void *hSessionHandle,
    void *hKeyHandle,
    unsigned int uiAlgID,
    unsigned char *pucIV,
    unsigned char *pucEncData,
    unsigned int  uiEncDataLength,
    unsigned char *pucData,
    unsigned int *puiDataLength);

描述
使用指定的密钥句柄和IV对数据进行对称解密运算

参数
hSessionHandle[in]	与设备建立的会话句柄
hKeyHandle[in]	指定的密钥句柄
uiAlgID[in]	算法标识，指定对称加密算法
pucIV[in|out]	缓冲区指针，用于存放输入和返回的IV数据
pucEncData[in]	缓冲区指针，用于存放输入的数据密文
uiEncDataLength[in]	输入的数据密文字节长度
pucData[out]	缓冲区指针，用于存放输出的数据明文
puiDataLength[out]	输出的数据明文字节长度

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

备注
1、此函数不对数据进行填充处理，输入的数据必须是指定算法分组长度（16字节）的整数倍。
2、此函数对数据进行分包处理，输入数据最大长度不限，CBC模式多包数据IV向量由函数外部自行控制
3、在就绪状态下，不限权限可以使用

计算MAC SDF_CalculateMAC

int SDF_CalculateMAC(
    void *hSessionHandle,
    void *hKeyHandle,
    unsigned int uiAlgID,
    unsigned char *pucIV,
    unsigned char *pucData,
    unsigned int uiDataLength,
    unsigned char *pucMAC,
    unsigned int *puiMACLength);

描述
使用指定的密钥句柄和IV对数据进行MAC运算

参数
hSessionHandle[in]	与设备建立的会话句柄
hKeyHandle[in]	指定的密钥句柄
uiAlgID[in]	算法标识，指定MAC加密算法
pucIV[in|out]	缓冲区指针，用于存放输入和返回的IV数据
pucData[in]	缓冲区指针，用于存放输出的数据明文
uiDataLength[in]	输出的数据明文字节长度
pucMAC[out]	缓冲区指针，用于存放输出的MAC值
puiMACLength[out]	输出的MAC值字节长度

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

备注
1、此函数不对数据进行填充处理，输入的数据必须是指定算法分组长度（16字节）的整数倍。
2、此函数对数据进行分包处理，输入数据最大长度不限。
3、在就绪状态下，不限权限可以使用

外部密钥对称加密SPII_EncryptEx

int SPII_EncryptEx(
    HANDLE hSessionHandle,
    unsigned char *data,
    int len,
    unsigned char *keybuf,
    int keylen,
    unsigned char *IV,
    int IVLen,
    int uiAlgID,
    unsigned char *endata,
    int *enlen);

描述
使用指定的外部密钥和IV对数据进行对称加密运算

参数
hSessionHandle[in]	与设备建立的会话句柄
data[in]	缓冲区指针，用于存放输入的数据明文
len[in]	输入的数据明文的字节长度
keybuf[in]	缓冲区指针，用于存放输入的密钥数据
keylen[in]	输入的密钥的字节长度
IV[in|out]	缓冲区指针，用于存放输入和返回的IV数据
IVLen[in]	输入的IV的字节长度
uiAlgID[in]	算法标识，指定对称加密算法
endata[out]	缓冲区指针，用于存放输出的数据密文
enlen[out]	输出的数据密文字节长度

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

备注
1、此函数不对数据进行填充处理，输入的数据必须是指定算法分组长度（16字节）的整数倍。
2、此函数对数据进行分包处理，输入数据最大长度不限，CBC模式多包数据IV向量由函数外部自行控制
3、在就绪状态下，不限权限可以使用

外部密钥对称解密SPII_DecryptEx

int SPII_DecryptEx(
    HANDLE hSessionHandle,
    unsigned char *endata,
    int enlen,
    unsigned char *keybuf,
    int keylen,
    unsigned char *IV,
    int IVLen,
    int uiAlgID,
    unsigned char *data,
    int *len);

描述
使用指定的外部密钥和IV对数据进行对称解密运算

参数
hSessionHandle[in]	与设备建立的会话句柄
endata[in]	缓冲区指针，用于存放输入的数据密文
enlen[in]	输入的数据密文的字节长度
keybuf[in]	缓冲区指针，用于存放输入的密钥数据
keylen[in]	输入的密钥的字节长度
IV[in|out]	缓冲区指针，用于存放输入和返回的IV数据
IVLen[in]	输入的IV的字节长度
uiAlgID[in]	算法标识，指定对称加密算法
data[out]	缓冲区指针，用于存放输出的数据明文
len[out]	输出的数据明文字节长度

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

备注
1、此函数不对数据进行填充处理，输入的数据必须是指定算法分组长度（16字节）的整数倍。
2、此函数对数据进行分包处理，输入数据最大长度不限，CBC模式多包数据IV向量由函数外部自行控制
3、在就绪状态下，不限权限可以使用

2.2.5 杂凑运算类函数

杂凑运算初始化SDF_HashInit

int SDF_HashInit(
    void *hSessionHandle,
    unsigned int uiAlgID
    ECCrefPublicKey *pucPublicKey,
    unsigned char *pucID,
    unsigned int uiIDLength);

描述
三步式数据杂凑运算第一步

参数
hSessionHandle[in]	与设备建立的会话句柄
uiAlgID[in]	指定杂凑算法标识
pucPublicKey[in]	签名者的ECC公钥，产生用于ECC签名的杂凑值时有效
pucID[in]	签名者的ID值，产生用于ECC签名的杂凑值时有效
uiIDLength[in]	签名者的ID长度

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

备注
1、当pucPublicKey或者pucID为NULL时，算法为SM3的无ID杂凑运算
2、在就绪状态下，不限权限可以使用

多包杂凑运算SDF_HashUpdate

int SDF_HashUpdate(
    void *hSessionHandle,
    unsigned char *pucData,
    unsigned int  uiDataLength);

描述
三步式数据杂凑运算第二步，对输入的明文进行杂凑运算

参数
hSessionHandle[in]	与设备建立的会话句柄
pucData[in]	缓冲区指针，用于存放输入的数据明文
uiDataLength[in]	输入的数据明文长度

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

备注
在就绪状态下，不限权限可以使用

杂凑运算结束SDF_HashFinal

int SDF_HashFinal(
    void *hSessionHandle,
    unsigned char *pucHash,
    unsigned int *puiHashLength);

描述
三步式数据杂凑运算第三步，杂凑运算结束返回杂凑数据并清除中间数据

参数
hSessionHandle[in]	与设备建立的会话句柄
pucHash[out]	缓冲区指针，用于存放输出的杂凑数据
puiHashLength[out]	返回的杂凑数据长度

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

备注
在就绪状态下，不限权限可以使用

2.2.6 用户文件操作类函数

创建文件SDF_CreateFile

int SDF_CreateFile(
    void *hSessionHandle,
    unsigned char *pucFileName，
    unsigned int uiNameLen，
    unsigned int uiFileSize);

描述
在密码设备内部创建用于存储用户数据的文件，目前支持最大25个文件

参数
hSessionHandle[in]	与设备建立的会话句柄
pucFileName[in]	缓冲区指针，用于存放输入的文件名，最大长度128字节
uiNameLen[in]	文件名字节长度
uiFileSize[in]	文件所占存储空间的长度

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

备注
在就绪状态下，不限权限可以使用

读取文件SDF_ReadFile

int SDF_ReadFile(
    void *hSessionHandle,
    unsigned char *pucFileName，
    unsigned int uiNameLen，
    unsigned int uiOffset,
    unsigned int *puiFileLength,
    unsigned char *pucBuffer);

描述
读取在密码设备内部存储用户数据的文件的内容

参数
hSessionHandle[in]	与设备建立的会话句柄
pucFileName[in]	缓冲区指针，用于存放输入的文件名，最大长度128字节
uiNameLen[in]	文件名长度
puiFileLength[in|out]	入参时指定读取文件内容的字节长度；出参时返回实际读取文件内容的字节长度
pucBuffer[out]	缓冲区指针，用于存放读取的文件数据

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

备注
在就绪状态下，不限权限可以使用

写文件SDF_WriteFile

int SDF_WriteFile(
    void *hSessionHandle,
    unsigned char *pucFileName,
    unsigned int uiNameLen,
    unsigned int uiOffset,
    unsigned int uiFileLength,
    unsigned char *pucBuffer);

描述
向密码设备内部存储用户数据的文件中写入内容

参数
hSessionHandle[in]	与设备建立的会话句柄
pucFileName[in]	缓冲区指针，用于存放输入的文件名，最大长度128字节
uiNameLen[in]	文件名字节长度
uiFileLength[in]	指定写入文件内容的字节长度
pucBuffer[in]	缓冲区指针，用于存放输入的写文件数据

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

备注
在就绪状态下，不限权限可以使用

删除文件SDF_DeleteFile

int SDF_DeleteFile(
    void *hSessionHandle,
    unsigned char *pucFileName，
    unsigned int uiNameLen);

描述
删除指定文件名的密码设备内部存储用户数据的文件

参数
hSessionHandle[in]	与设备建立的会话句柄
pucFileName[in]	缓冲区指针，用于存放输入的文件名，最大长度128字节
uiNameLen[in]	文件名字节长度

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

备注
在就绪状态下，不限权限可以使用

2.2.7 密码卡密钥管理函数

更改私钥使用权限SPII_ChangePrivateKeyAccessRight

int SPII_ChangePrivateKeyAccessRight(
    void * hSessionHandle,
    unsigned int  uiKeyIndex,
    unsigned char *oldpucPassword,
    unsigned int uioldPwdlength,
    unsigned char *newpucPassword,
    unsigned int  uiPwdLength);

描述
修改私钥使用权限

参数
hSessionHandle [in]	与设备建立的会话句柄
uiKeyIndex[in]	密钥索引号
oldpucPassword[in]	原有口令指针
uioldPwdlength[in]	原有口令指针长度
newpucPassword [in]	更新口令指针
uiPwdLength [in]	更新口令指针长度

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

备注
无

内部产生加密ECC密钥对SPII_GenerateEncKeyPair_ECC

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

描述
请求密码设备产生指定类型和模长的非对称密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号

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

备注
1、ECC默认长度为256bit

内部产生签名ECC密钥对SPII_GenerateSignKeyPair_ECC

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

描述
请求密码设备产生指定类型和模长的非对称密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号

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

备注
1、ECC默认长度为256bit

内部产生密钥加密密钥KEK SPII_GenerateKEK

int SPII_GenerateKEK (
    void *hSessionHandle,
    unsigned int uiKeyIndex
    unsigned int byteslen);

描述
请求密码设备产生指定类型和模长的非对称密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
byteslen[in]	密钥字节长度

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

备注
1、密钥bit长度支持128bit即16Bytes
2、在就绪状态、管理员权限下可以调用

第三方密钥管理机构导入加密密钥对SPII_NVELOPEDKEY

int SPII_NVELOPEDKEY(
    void * hSessionHandle,
    unsigned int uiKEKIndex,
    unsigned int ulAsymmAlgID,
    unsigned int ulSymmAlgID,
    ECCCipher *ECCCipherBlob,
    ECCrefPublicKey *PubKey,
    unsigned char *cbEncryptedPriKey,
    unsigned int cbEncryptedPriKeylen);

描述
使用卡内的签名私钥，解密并导入第三方密钥管理机构生成的加密密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKEKIndex [in]	加密密钥索引号
ulAsymmAlgID [in]	非对称密钥包算法标识
ulSymmAlgID[in]	对称密钥包算法标识
ECCCipherBlob [in]	非对称加密包指针
PubKey[in]	加密公钥结构指针
cbEncryptedPriKey[in]	加密私钥密文指针
cbEncryptedPriKeylen[in]	加密私钥密文指针长度

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

备注
无

备份保护密钥SPII_BackUpBK

int SPII_BackUpBK (
    void * pSessionHandle,
    unsigned int Ukeyflag,
    unsigned char *Password,
    unsigned int PasswordLen,
    unsigned int  UkeyNun,
    ECCrefPublicKey *pk,
    ECCCipher *Enbk);

描述
恢复保护密钥

参数
hSessionHandle[in]	与设备建立的会话句柄
Ukeyflag[in]	表示Ukey是否在线
Password[in]	Ukey的Pin口令指针
PasswordLen[in]	Ukey的Pin口令指针长度
UkeyNun[in]	表示分量组号
Pk[in]	加密保护分量的公钥
Enbk [out]	公钥加密的保护密钥分量

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

备注
1、Ukeyflag 为0时，表示Ukey直接与密码卡相连，非0时表示Ukey与系统相连，密码卡需要与Ukey建立安全通道才能通过Ukey进行管理。
2、Ukeyflag为0时，Password与PasswordLength有效，非0时，pk，Enbk有效。

备份加密ECC密钥对SPII_BackUpECCEnc

int SPII_BackUpECCEnc(
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncECCKeyPair,
    unsigned int *EncECCKeyPairLength);

描述
备份ECC加密密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncECCKeyPair[out]	加密后的密钥文件指针
EncECCKeyPairLength[out]	加密后的密钥文件指针长度

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

备注
无

备份签名ECC密钥对SPII_BackUpECCSign

int SPII_BackUpECCSign(
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncECCKeyPair,
    unsigned int *EncECCKeyPairLength);

描述
备份ECC签名密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncECCKeyPair[out]	加密后的密钥文件指针
EncECCKeyPairLength[out]	加密后的密钥文件指针长度

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

备注
无

备份KEK密钥SPII_BackUpKEK

int SPII_BackUpKEK(
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncKEK,
    unsigned int *EncKEKLength);

描述
备份ECC签名密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncKEK [out]	加密后的密钥文件指针
EncKEKLength [out]	加密后的密钥文件指针长度

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

备注
无

生成临时ECC密钥对SPII_GenerateTmpPK

int SPII_GenerateTmpPK(
    void * pSessionHandle,
    ECCrefPublicKey *pucPublicKey);

描述
生成密钥恢复过程中临时传输保护密钥对的生成，需在恢复保护密钥之前执行

参数
hSessionHandle[in]	与设备建立的会话句柄
pucPublicKey [out]	导出的临时密钥

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

备注
1、ECC默认长度为256bit

恢复保护密钥SPII_RestoreBK

int SPII_RestoreBK(
    void * pSessionHandle,
    unsigned int Ukeyflag,
    unsigned char *Password,
    unsigned int PasswordLen,
    ECCCipher *Enbk);

描述
恢复保护密钥

参数
hSessionHandle[in]	与设备建立的会话句柄
Ukeyflag[in]	表示Ukey是否在线
Password[in]	Ukey的Pin口令指针
PasswordLen[in]	Ukey的Pin口令指针长度
Enbk [in]	临时密钥加密的保护密钥分量

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

备注
1、Ukeyflag 为0时，表示Ukey直接与密码卡相连，非0时表示Ukey与系统相连，密码卡需要与Ukey建立安全通道才能通过Ukey进行管理。
2、Ukeyflag为0时，Password与PasswordLength有效，非0时，Enbk有效。
3、执行该函数前需执行SPII_GenerateTmpPK。

恢复加密ECC密钥对SPII_RestoreECCEnc

int SPII_ RestoreECCEnc (
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncECCKeyPair,
    unsigned int EncECCKeyPairLength);

描述
恢复ECC加密密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncECCKeyPair[in]	加密后的密钥文件指针
EncECCKeyPairLength[in]	加密后的密钥文件指针长度

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

备注
无

恢复签名ECC密钥对SPII_RestoreECCSign

int SPII_RestoreECCSign (
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncECCKeyPair,
    unsigned int EncECCKeyPairLength);

描述
恢复ECC签名密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncECCKeyPair[in]	加密后的密钥文件指针
EncECCKeyPairLength[in]	加密后的密钥文件指针长度

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

备注
无

恢复KEK密钥SPII_RestoreKEK

int SPII_ RestoreKEK (
    void * hSessionHandle,
    unsigned int keyIndex,
    unsigned char *EncKEK,
    unsigned int EncKEKLength);

描述
恢复ECC签名密钥对

参数
hSessionHandle[in]	与设备建立的会话句柄
uiKeyIndex [in]	密钥索引号
EncKEK [in]	加密后的密钥文件指针
EncKEKLength [in]	加密后的密钥文件指针长度

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

备注
无

2.2.8 密码卡用户管理函数

获取加密卡登录状态SPII_GetDeviceStatus

int SPII_GetDeviceStatus(
    void * phDeviceHandle,
    unsigned short *CardStatus,
    unsigned short *PermissionStatus);

描述
获取加密卡登录状态

参数
hdeviceHandle [in]	与设备句柄
CardStatus[out]	状态标记
PermissionStatus[out]	权限标记

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

备注
无

身份注册函数SPII_Regsvr

int SPII_Regsvr(
    void * pSessionHandle,
    unsigned int Ukeyflag,
    unsigned char *Password,
    unsigned int PasswordLength,
    ECCrefPublicKey *enpk,
    ECCrefPublicKey *signpk,
    unsigned int UserID);

描述
注册身份

参数
hSessionHandle[in]	与设备建立的会话句柄
Ukeyflag [in]	表示Ukey是否在线
Password[in]	Ukey口令/用户口令
PasswordLength[in]	Ukey口令长度/用户口令长度
Enpk[in]	加密公钥结构指针
Signpk[in]	签名公钥结构指针
UserID[in]	注册身份ID

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

备注
1、 Ukeyflag 为0时，表示Ukey直接与密码卡相连，1时表示Ukey与系统相连，密码卡需要与Ukey建立安全通道才能通过Ukey进行管理
2、 Ukeyflag为0时，Password与PasswordLength有效，1时，Enpk与Signpk有效，为Ukey的加密、签名公钥。
3、 Ukeyflag为2时，使用口令方式注册用户，Password与PasswordLength有效。
4、 UserID 为1时表示注册的是超级管理员，2时表示注册是管理员，3时表示注册的是操作员1，4时表示注册的是操作员2。

身份登录步骤1函数SPII_LoadinStepF

int SPII_LoadinStepF(
    void * pSessionHandle,
    unsigned int Ukeyflag,
    unsigned char *Password,
    unsigned int PasswordLength,
    ECCrefPublicKey *enpk,
    ECCrefPublicKey *entpk,
    ECCCipher *enR,
    ECCCipher *enmk);

描述
身份登录步骤1

参数
hSessionHandle[in]	与设备建立的会话句柄
Ukeyflag [in]	表示Ukey是否在线
Password[in]	Ukey口令
PasswordLength[in]	Ukey口令长度
Enpk[in]	注册时的加密公钥结构指针
entpk [out]	密码卡生成的临时公钥
enR [out]	用Enpk加密的随机数R值
Enmk[out]	用Enpk加密的管理密钥

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

备注
1、 Ukeyflag 为0时，表示Ukey直接与密码卡相连，1时表示Ukey与系统相连，密码卡需要与Ukey建立安全通道才能通过Ukey进行管理
2、 Ukeyflag为0时，Password与PasswordLength有效，1时，Enpk、entpk、enR、Enmk有效。

身份登录步骤2函数SPII_LoadinStepS

int SPII_LoadinStepS(
    void * pSessionHandle,
    unsigned int Ukeyflag,
    unsigned char *Password,
    unsigned int PasswordLength,
    ECCSignature *signR,
    ECCCipher *enmk);

描述
身份登录步骤2

参数
hSessionHandle[in]	与设备建立的会话句柄
Ukeyflag [in]	表示Ukey是否在线
Password[in]	Ukey口令
PasswordLength[in]	Ukey口令长度
signR [in]	注册时的签名公钥对应的私钥结构签名指针
enmk [in]	密码卡临时公钥加密的管理密钥

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

备注
1、 Ukeyflag 为0时，表示Ukey直接与密码卡相连，1时表示Ukey与系统相连，密码卡需要与Ukey建立安全通道才能通过Ukey进行管理
2、 Ukeyflag为0时，Password与PasswordLength有效，1时，signR、enmk有效。

口令方式身份登录函数SPII_LoadinWithPassword

int SPII_LoadinWithPassword(
    void * pSessionHandle,
    unsigned char *Password,
    unsigned int PasswordLength,
    unsigned int UserID);

描述
口令方式身份登录

参数
hSessionHandle[in]	与设备建立的会话句柄
Password[in]	口令（Password/Pin）
PasswordLength[in]	口令长度
UserID[in]	登录身份ID

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

备注
1、 使用该函数前需用PiicoToolWP工具注册用户
2、 UserID 为1时表示登录超级管理员，2时表示登录管理员，3时表示登录操作员1，4时表示登录操作员2。

修改身份登录口令函数SPII_ModifyPin

int SPII_ModifyPin(
        HANDLE pSessionHandle,
        unsigned char *pOldPin,
        unsigned int nOldPinLen,    
        unsigned char *pNewPin, 
        unsigned int nNewPinLen);

描述
修改身份登录口令

参数
hSessionHandle[in]	与设备建立的会话句柄
pOldPin[in]	旧口令（Password/Pin）
nOldPinLen[in]	旧口令长度
pNewPin[in]	新口令（Password/Pin）
nNewPinLen[in]	新口令长度
UserID[in]	登录身份ID

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

备注
1、 使用该函数前需用PiicoToolWP工具注册用户
2、 UserID 为1时表示修改超级管理员口令，2时表示修改管理员口令，3时表示修改操作员1口令，4时表示修改操作员2口令。

修改UKey登录口令函数SPII_ChangeUkeyPin

int SPII_ChangeUkeyPin(
        void * pSessionHandle,
        unsigned char* OldPassword,
        unsigned int OldPasswordLen,
        unsigned char *NewPassword,
        unsigned int NewPasswordLen);

描述
修改UKey的登录口令

参数
hSessionHandle[in]	与设备建立的会话句柄
OldPassword[in]	旧口令（Password/Pin）
OldPasswordLen[in]	旧口令长度
NewPassword[in]	新口令（Password/Pin）
NewPasswordLen[in]	新口令长度

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

备注
1、 用于修改连接到密码卡USB口的身份UKey和备份Ukey的登录口令

2.2.9 密码卡初始化相关函数

初始化加密卡SPII_Init_Device

int SPII_Init_Device (
    void * hdeviceHandle
);

描述
初始化加密卡，多用于重置密码卡回到出厂状态

参数
hdeviceHandle [in]	与设备建立的会话句柄

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

备注
1、超级管理员权限才能调用

初始化密钥容器空间SPII_Init_KeyContainerWithPrivateKeyAccessRight

int SPII_Init_KeyContainerWithPrivateKeyAccessRight (
    void * hdeviceHandle,
    unsigned int keyIndex,
    unsigned char *pucPassword,
    unsigned int  uiPwdLength
);

描述
初始化密钥容器空间，并设置密钥权限码初始值

参数
hdeviceHandle [in]	与设备句柄
uiKeyIndex [in]	密钥索引号
pucPassword[in]	私钥权限码
uiPwdLength	私钥权限码长度

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

备注
1、在密码卡出厂状态并超级管理权限才能调用

初始化文件系统SPII_Init_FileSystem

int SPII_Init_FileSystem (
    void * hsessionHandle
);

描述
初始化文件系统

参数
hsessionHandle [in]	与设备建立的会话句柄

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

备注
1、在密码卡出厂状态并超级管理员权限才能调用

三、常见错误及解决方法

	现象	原因	常用解决方法
1	找不到密码卡	可能密码卡金手指有污渍	使用橡皮檫拭密码卡金手指，去除污渍后再正确插入卡槽
2	OpenDevice返回0x80000001	未曾创建设备节点	创建设备节点
3	S_GetErrorInfo返回0x00002019	权限错误	获取相关使用权限
4	S_GetErrorInfo返回0x00002006	卡内存储的密钥校验失败	1、获取管理权限2、重新恢复相关密钥
5	S_GetErrorInfo返回0x00002053	目前状态不支持此操作	切换相关状态
6	S_GetErrorInfo返回0x00001009	无此通信协议	切换密码卡状态
7	S_GetErrorInfo返回0x80000002	送入参数错误	修正送入参数
8	S_GetErrorInfo返回0x0000000C	ECC参数验证失败	修正送入ECC相关参数
9	S_GetErrorInfo返回0x00002050	密钥不存在或未获得权限	取得管理权限后再试；若已取得管理权限，表明密钥不存在可生成密钥后再使用。
10	S_GetErrorInfo返回0x00001017	密钥协商参数产生后未释放	发起方产生协商参数后（SDF_GenerateAgreementDataWithECC），正常情况下回执行密钥协商第三步（SDF_GenerateKeyWithECC）自动释放协商参数，若第三步没执行或执行失败，需执行销毁协商参数句柄（SPII_DestroyAgreementHandle）手动释放协商参数。返回0x00001017后需复位密码卡。
11	S_GetErrorInfo返回0x00001004	会话密钥已分配完	会话密钥用完需销毁（SDF_DestroyKey）。正常使用时，返回0x00001004后可以重试。测试时若未正常销毁使会话密钥没法释放，返回0x00001004后需复位密码卡。

附录A （规范性附录）错误代码定义

详见头文件piico_error.h：

#define SR_SUCCESSFULLY             0               //函数返回成功          
#define SR_CANNOT_OPEN_DEVICE       0x80000001      //无法打开设备          
#define SR_INVALID_PARAMETER        0x80000002      //参数错误              
#define SR_WRITE_TO_DEVICE          0x80000003      //写往内核错误          
#define SR_CANNOT_RESETCARD         0x80000004      //卡不能复位            
#define SR_CANNOT_CLEAN_MODULE      0x80000005      //模块不能卸载                 
#define SR_WRITE_TIMEOUT            0x80000006      //写超时错误              
#define SR_READ_TIMEOUT             0x80000007      //读超时错误                        
#define SR_RETURN_ERROR             0x80000008      //从卡中返回数据有误    
#define SR_GENERAL_ERROR            0x80000009      //未知的错误            
#define SR_VERIFY_FAILURE           0x8000000a      //未通过验证            
#define SR_FUNCTION_NOT_SUPPLIED    0x8000000b      //此函数暂不提供        
#define SR_PARAMETER_LENGTH_ERROR   0x8000000c      //参数长度错误
#define SR_HOST_MEMORY              0x8000000d      //内存错误                        
#define SR_ID_OUTRANGE              0x8000000e      //ID超出范围                     
#define SR_RSA_KEYLEN_ERROR         0x8000000f      //RSA密钥长度错误       
#define SR_SMALL_BUFFER             0x80000010      //缓冲区不足                        
#define SR_INVALID_PINLEN           0x80000011      //无效的PIN口令长度     
#define SR_INVALID_FLAG             0x80000012      //无效的FLAG标识        
#define SR_INVALID_KEYLEN           0x80000013      //密钥长度有误          
#define SR_BLOCK_ENCRY_DATALENGTH   0x80000014      //分组加密数据长度错误
#define SR_BLOCK_DECRY_DATALENGTH   0x80000015      //分组解密数据长度错误
#define SR_SESSION_OUTRANGE         0x80000016      //SKID超出范围
#define SR_DATALEN_OUTRANGE         0x80000017      //数据超出范围
#define SR_INVALID_DATALEN          0x80000018      //无效的数据长度
#define SR_INVALID_HOST             0x80000019      //无效的主机
#define SR_INVALID_MKID             0x8000001a      //无效的MKID
#define SR_DEVICE_BUSYING           0x8000001b      //设备忙
#define SR_TOO_MANY_COMUCATION_DEVICE   0x8000001c  //同时通信的设备太多，产生的SK大于1024      
#define SR_INSUFFICIENT_MEMORY      0x8000001d      //内存不足
#define SR_RSA_OUT_DATA             0x8000001e      //RSA算法中数据长度超过128Bytes
#define SR_READ_FROM_DEVICE         0x8000001f      //从内核读出错误
#define SR_INVALID_RSA_VK           0x80000020      //表示私钥未曾注入，或者注入的私钥错误
#define SR_RSA_KEY_ERROR            0x80000021      //其它操作加密的程序未释放某些资源而出错
#define SR_TIME_OUT                 0x80000022      //超时错误
#define SR_NOT_SUPPORT_OSVERSOIN    0x80000023      //不支持此版本的操作系统
#define SR_COMMAND_IC_ERROR         0x80000024      //IC卡命令字错误 
#define SR_CANNOT_OPEN_IC           0x80000025      //不能打开IC卡
#define SR_SESSION_KEY_LEN_ERR      0x80000026
#define SR_ECC_DATA_LEN_ERR         0x80000027
#define SR_KEY_INDEX_ERR            0x80000028
#define SR_RSA_ERASEPADDING_ERR     0x80000029
#define SR_RSA_PADDING_ERR          0x8000002a
#define SR_ECC_DECRYPT_ERR          0x8000002b
#define SR_NOT_SUPPORT_ALGORITHM    0x8000002c
#define SR_RETURN_LENGTH_ERR        0x8000002d
#define SR_NOT_SUPPORT_TYPE         0x8000002e

/* 卡内返回 */
/////////////////////////////////////////////////////////////////////////////////////
#define CCR_SUCCESS                         0x00000000
#define CCR_LENGTH_WRONG                    0x00000001            //格式长度错误
#define CCR_UNKNOWN_ALG                     0x00000005            //未知算法
#define CCR_UNKNOWN_MODE                    0x00000006            //未知算法模式
#define CCR_FLASH_OVER                      0x00000002            //FLASH溢出 (offset+inlen)>=0x1000   
#define CCR_FLASH_FAN_ERROR                 0x00000003            //使用了不可用的扇区
#define CCR_FLASH_OFFSET_ERROR              0x00000004
#define CCR_NO_ICCARD                       0x00000007            //无IC卡
#define CCR_IC_ERROR                        0x00000008            //IC返回数据错
#define CCR_ECC_FAIL                        0x00000009            //ECC操作失败
#define CCR_ECC_VERIFY_FAIL                 0x0000000A            //ECC验证失败
#define CCR_ECC_PARA_ERR                    0x0000000B            //ECC参数错
#define CCR_ECC_ENCRYPT_FAIL                0x0000000C
#define CCR_ECC_DECRYPT_FAIL                0x0000000D
#define CCR_ECC_KEYAGREEMENT_FAIL           0x0000000E
#define CCR_HASH_INIT_FAIL                  0x0000000F
#define CCR_HASH_FAIL                       0x00000010
#define CCR_FLASH_WRITE_ERR                 0x00000012            //
#define CCR_ERASEPADDING_FAIL               0x00000013                      //
#define CCR_FLASH_CHECK_FAIL                0x00000014
#define CCR_FLASH_READ_ERR                  0x00000015 

#define CCR_UKEY_FAIL                       0x00000201
#define CCR_UKEY_UNKOWNERR                  0x00000202
#define CCR_UKEY_NOTSUPPORTYETERR           0x00000203
#define CCR_UKEY_FILEERR                    0x00000204
#define CCR_UKEY_INVALIDHANDLEERR           0x00000205
#define CCR_UKEY_INVALIDPARAMERR            0x00000206
#define CCR_UKEY_READFILEERR                0x00000207
#define CCR_UKEY_WRITEFILEERR               0x00000208
#define CCR_UKEY_NAMELENERR                 0x00000209
#define CCR_UKEY_KEYUSAGEERR                0x0000020A
#define CCR_UKEY_MODULUSLENERR              0x0000020B
#define CCR_UKEY_NOTINITIALIZEERR           0x0000020C
#define CCR_UKEY_OBJERR                     0x0000020D
#define CCR_UKEY_MEMORYERR                  0x0000020E
#define CCR_UKEY_TIMEOUTERR                 0x0000020F
#define CCR_UKEY_INDATALENERR               0x00000210
#define CCR_UKEY_INDATAERR                  0x00000211
#define CCR_UKEY_GENRANDERR                 0x00000212
#define CCR_UKEY_HASHOBJERR                 0x00000213
#define CCR_UKEY_HASHERR                    0x00000214
#define CCR_UKEY_GENRSAKEYERR               0x00000215
#define CCR_UKEY_RSAMODULUSLENERR           0x00000216
#define CCR_UKEY_CSPIMPRTPUBKEYERR          0x00000217
#define CCR_UKEY_RSAENCERR                  0x00000218
#define CCR_UKEY_RSADECERR                  0x00000219
#define CCR_UKEY_HASHNOTEQUALERR            0x0000021A
#define CCR_UKEY_KEYNOTFOUNTERR             0x0000021B
#define CCR_UKEY_CERTNOTFOUNTERR            0x0000021C
#define CCR_UKEY_NOTEXPORTERR               0x0000021D
#define CCR_UKEY_DECRYPTPADERR              0x0000021E
#define CCR_UKEY_MACLENERR                  0x0000021F
#define CCR_UKEY_BUFFER_TOO_SMALL           0x00000220
#define CCR_UKEY_KEYINFOTYPEERR             0x00000221
#define CCR_UKEY_NOT_EVENTERR               0x00000222
#define CCR_UKEY_DEVICE_REMOVED             0x00000223
#define CCR_UKEY_PIN_INCORRECT              0x00000224
#define CCR_UKEY_PIN_LOCKED                 0x00000225
#define CCR_UKEY_PIN_INVALID                0x00000226
#define CCR_UKEY_PIN_LEN_RANGE              0x00000227
#define CCR_UKEY_USER_ALREADY_LOGGED_IN     0x00000228
#define CCR_UKEY_USER_PIN_NOT_INITIALIZED   0x00000229
#define CCR_UKEY_USER_TYPE_INVALID          0x0000022A
#define CCR_UKEY_APPLICATION_NAME_INVALID   0x0000022B
#define CCR_UKEY_APPLICATION_EXISTS         0x0000022C
#define CCR_UKEY_USER_NOT_LOGGED_IN         0x0000022D
#define CCR_UKEY_APPLICATION_NOT_EXISTS     0x0000022E
#define CCR_UKEY_FILE_ALREADY_EXIST         0x0000022F
#define CCR_UKEY_NO_ROOM                    0x00000230
#define CCR_UKEY_FILE_NOT_EXIST             0x00000231
#define CCR_UKEY_REACH_MAX_CONTAINER_COUNT  0x00000232

#define CCR_INDEX_OUT_OF_RANGE                  0x00001001            //数值超出范围
#define CCR_PIN_CHECK_ERR                       0x00001002            //PIN码校验失败
#define CCR_RSA_DATALEN_ERR                     0x00001003            //数据长度错误
#define CCR_CMD_FAIL                            0x00000001            //失败返回
#define CCR_SESSION_KEY_EMPTY                   0x00001004            //会话密钥句柄已经分配完毕  
#define CCR_SECTOR_OUT_OF_RANGE                 0x00001006            //扇区编号越界（0～23） 
#define CCR_SESSION_KEY_OUT_OF_RANGE            0x00001007            //SESSION KEY编号越界（0～1023）
#define CCR_SESSION_KEY_IS_EMPTY                0x00001008            //SESSION KEY 为空
#define CCR_CMD_ERR                             0x00001009            //无效的命令字
#define CCR_PRIVATE_KEY_ACCESSRIGHT_VERIFY_ERR  0x00001010            //私钥权限校验失败
#define CCR_RSA_PRIVATE_KEY_FLAG_ERR            0x00001011            //无效的RSA私钥类型。
#define CCR_KEY_IS_EMPTY                        0x00001012            //密钥为空。
#define CCR_AUTHORITY_ERR                       0x00001013            //权限验证错误
#define CCR_PARAMETER_ERR                       0x00001016
#define CCR_WEAK_PIN_CHECK_ERR                  0x00002001            //PIN码校验错误
#define CCR_CHECK_DATA_ERR                      0x00002006            //数据校验失败
#define CCR_GEN_SM2_KEYPAIR_FAIL                0x00002007            //ECC获取密钥对
#define CCR_NO_ADMIN_PERMITION                  0x00002008            //未获得管员权限
#define CCR_SM2_KEY_INDEX_ERR                   0x0000200C
#define CCR_BAKUP_UKEY_ERR                      0x0000200E            //备份卡的类型错误
#define CCR_KEK_INDEX_ERR                       0x0000200F            //
#define CCR_RESTORE_PROTECTKEY_NOT_EXIST        0x00002010            //没有恢复PPK
#define CCR_DEVICEKEY_NOT_PREPARED              0x00002015            //未初始化
#define CCR_BAKUP_PROTECTKEY_NOT_EXIST          0x00002016            //PPK未产生
#define CCR_PERMISSION_FAIL                     0x00002019            //权限错误
#define CCR_UKEY_CHECK_ERR                      0x000020A1            //UKEY校验错误
#define CCR_KEY_PAIRE_EMPTY                     0x00002050            //密钥对不存在
#define CCR_USER_NOT_READY                      0x00002051
#define CCR_CARD_STATUS_ERR                     0x00002053
#define CCR_UKEY_REPEAT                         0x00002054
#define CCR_CMD_CANNOT_EXEC_AT_CURRUNT_STATUS   0x00002063

///////////////////////国密标准错误返回////////////////////////////////////
#define SDR_OK                  0x0
#define SDR_UNKNOWERR           0x01000001
#define SDR_NOTSUPPORT          0x01000002
#define SDR_COMMFAIL            0x01000003
#define SDR_HARDFAIL            0x01000004
#define SDR_OPENDEVICE          0x01000005
#define SDR_OPENSESSION         0x01000006
#define SDR_PARDENY             0x01000007
#define SDR_KEYNOTEXIST         0x01000008
#define SDR_ALGNOTSUPPORT       0x01000009
#define SDR_ALGMODNOTSUPPORT    0x01000010
#define SDR_PKOPERR             0x01000011
#define SDR_SKOPERR             0x01000012
#define SDR_SIGNERR             0x01000013
#define SDR_VERIFYERR           0x01000014
#define SDR_SYMOPERR            0x01000015
#define SDR_STEPERR             0x01000016
#define SDR_FILESIZEERR         0x01000017
#define SDR_FILENOEXIST         0x01000018
#define SDR_FILEOFSERR          0x01000019
#define SDR_KEYTYPEERR          0x01000020
#define SDR_KEYERR              0x01000021
#define SDR_FILENOROOM          0x01000022
#define SDR_FILEEXIST           0x01000023
#define SDR_POPEDOMERR          0x01000024
#define SDR_KEYISEMPTYERR       0x01000025
#define SDR_INITCardERR         0x01000026