交易安全认证系统开发接口V.docx
《交易安全认证系统开发接口V.docx》由会员分享，可在线阅读，更多相关《交易安全认证系统开发接口V.docx（85页珍藏版）》请在冰豆网上搜索。
交易安全认证系统开发接口V
交易安全认证系统接口
[编写：
]
[评审：
]
[批准：
]
项目名称：
日期：
2012年3月2日
文档修订记录
版本号
修改日期
编写
评审
修改内容
1.0
2012-03-02
创建文档
1文档说明
本文档预期读者为交易业务系统的系统设计、开发、测试人员。
2应用场景
本系统作为交易业务系统的安全支撑系统，主要提供以下功能：
2.1管理服务功能
✓随机生成密钥
✓打印密钥
2.2联机服务功能
✓工作密钥TAK、TPK更新
✓文件加密、解密
✓数据加密、解密
✓MAC计算、校验
✓PIN转加密
✓证书处理
3联机服务接口
3.1密钥管理接口
3.1.1工作密钥更新
3.1.1.1接口定义
intHisuApplyKeyByZMK（
char*designID,
char*nodeID,
char*keyModelID,
char*nodeID01,
char*keyModelID01,
char*keyValue,
intsizeOfKeyValue,
char*checkValue,
intsizeOfCheckValue
）;
3.1.1.2接口说明
3.1.1.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
保护密钥方案标识
nodeID
安全系统提供（可配置）
保护密钥节点标识
keyModelID
安全系统提供（可配置）
保护密钥模板标识
nodeID01
安全系统提供（可配置）
工作密钥节点标识（
keyModelID01
安全系统提供（可配置）
工作密钥模板标识
sizeOfKeyValue
业务系统提供
密钥接收缓冲区大小
sizeOfCheckValue
业务系统提供
密钥校验值接收缓冲区大小
3.1.1.2.2输出参数
域标识值
域值
备注
keyValue
安全系统返回
ZMK加密的工作密钥密文，十六进制表示
checkValue
安全系统返回
工作密钥校验值，十六进制表示
3.1.1.2.3返回值
Ø>=0正确
Ø<0错误
3.1.1.3接口示例
3.1.2保护密钥更新
3.1.2.1接口定义
intHisuApplyZMKByZMK（
char*designID,
char*nodeID,
char*keyModelID,
char*keyValue,
intsizeOfKeyValue,
char*checkValue,
intsizeOfCheckValue
）;
3.1.2.2接口说明
3.1.2.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
保护密钥节点标识
keyModelID
安全系统提供（可配置）
保护密钥模板标识
sizeOfKeyValue
业务系统提供
密钥接收缓冲区大小
sizeOfCheckValue
业务系统提供
密钥校验值接收缓冲区大小
3.1.2.2.2输出参数
域标识值
域值
备注
keyValue
安全系统返回
旧ZMK加密的ZMK密钥密文，十六进制表示
checkValue
安全系统返回
ZMK密钥的密钥校验值，十六进制表示
3.1.2.2.3返回值
Ø>=0正确
Ø<0错误
3.1.2.3接口示例
3.1.3保存ZMK加密的密钥
3.1.3.1接口定义
intHisuStoreKeyByZMK（
char*designID,
char*nodeID,
char*keyModelID,
char*designID01,
char*nodeID01,
char*keyModelID01,
char*keyValue,
char*checkValue
）;
3.1.3.2接口说明
3.1.3.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
ZMK安全方案
nodeID
安全系统提供（可配置）
ZMK节点标识
keyModelID
安全系统提供（可配置）
ZMK密钥模板标识
designID01
安全系统提供（可配置）
WK安全方案
nodeID01
安全系统提供（可配置）
WK节点标识
keyModelID01
安全系统提供（可配置）
WK密钥模板标识
keyValue
业务系统提供
密钥值
checkValue
业务系统提供
密钥校验值
3.1.3.2.2输出参数
域标识值
域值
备注
3.1.3.2.3返回值
Ø>=0正确
Ø<0错误
3.1.3.3接口示例
3.1.4生成TSSC的RSA对
3.1.4.1接口定义
intHisuApplyRSA（
char*designID,
char*nodeID,
char*keyModelID,
intlenOfRSA,
char*PK,
intsizeOfPK
）;
3.1.4.2接口说明
3.1.4.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
保护密钥节点标识
keyModelID
安全系统提供（可配置）
保护密钥模板标识
lenOfRSA
业务系统提供
768～4096，为-1时，读取后台的配置强度
sizeOfPK
业务系统提供
公钥接收缓冲区大小
3.1.4.2.2输出参数
域标识值
域值
备注
PK
安全系统返回
裸公钥
3.1.4.2.3返回值
Ø>=0正确
Ø<0错误
3.1.5数据信封申请ZMK
3.1.5.1接口定义
intHisuApplyZMKByRSA（
char*designID,
char*nodeID,
char*keyModelID,
char*designID01,
char*nodeID01,
char*keyModelID01,
char*keyByPK,
char*keyValue,
intsizeOfKeyValue,
char*checkValue,
intsizeOfCheckValue
）;
3.1.5.2接口说明
3.1.5.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
RSA密钥对方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
RSA密钥对节点标识
keyModelID
安全系统提供（可配置）
RSA密钥对密钥模板标识
designID01
安全系统提供（可配置）
ZMK密钥方案标识（根据实际配置调整）
nodeID01
业务系统提供
ZMK密钥节点标识（终端号）
keyModelID01
安全系统提供（可配置）
ZMK密钥密钥模板标识
keyByPK
业务系统提供
RSA对公钥加密的密钥密文
sizeOfKeyValue
业务系统提供
密钥接收缓冲区大小
sizeOfCheckValue
业务系统提供
密钥校验值接收缓冲区大小
3.1.5.2.2输出参数
域标识值
域值
备注
keyValue
安全系统返回
会话密钥加密的ZMK密钥密文，十六进制表示
checkValue
安全系统返回
ZMK密钥的密钥校验值，十六进制表示
3.1.5.2.3返回值
Ø>=0正确
Ø<0错误
3.1.5.3接口示例
3.1.6创建节点实例并用指定ZMK导出节点保护密钥
3.1.6.1接口定义
intHisuCreateKeyInstanceThenExpZMKByZMK（
char*designID,
char*nodeID,
char*keyModelID,
char*nodeModelID,
char*designID01,
char*nodeID01,
char*keyModelID01,
char*keyValue,
intsizeOfKeyValue,
char*checkValue,
intsizeOfCheckValue
）;
3.1.6.2接口说明
3.1.6.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
方案标识
nodeID
业务系统提供
节点标识
keyModelID
安全系统提供（可配置）
节点保护密钥的密钥模板标识
nodeModelID
安全系统提供（可配置）
节点模板标识
designID01
安全系统提供（可配置）
导出节点保护密钥的ZMK方案标识
nodeID01
安全系统提供（可配置）
导出节点保护密钥的ZMK节点标识
keyModelID01
安全系统提供（可配置）
导出节点保护密钥的ZMK密钥模板标识
sizeOfKeyValue
业务系统提供
密钥接收缓冲区大小
sizeOfCheckValue
业务系统提供
密钥校验值接收缓冲区大小
3.1.6.2.2输出参数
域标识值
域值
备注
keyValue
安全系统返回
使用指定ZMK加密的节点保护密钥密文
checkValue
安全系统返回
节点保护密钥校验值
3.1.6.2.3返回值
Ø>=0正确
Ø<0错误
3.1.6.3接口示例
3.1.7根据节点文件创建ZMK保护的节点保护密钥文件
3.1.7.1接口定义
intHisuCreateNodeZmkFileFromNodeFile（
char*designID,
char*keyModelID,
char*nodeModelID,
char*nodeFile,
char*designID01,
char*nodeID01,
char*keyModelID01,
char*nodeZmkFile
）;
3.1.7.2接口说明
3.1.7.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
方案标识
keyModelID
安全系统提供（可配置）
节点保护密钥的密钥模板标识
nodeModelID
安全系统提供（可配置）
节点模板标识
nodeFile
业务系统提供
节点清单文件路径，文件格式为：
一个节点标识一行
designID01
安全系统提供（可配置）
导出节点保护密钥的ZMK方案标识
nodeID01
安全系统提供（可配置）
导出节点保护密钥的ZMK节点标识
keyModelID01
安全系统提供（可配置）
导出节点保护密钥的ZMK密钥模板标识
nodeZmkFile
业务系统提供
节点保护密钥清单文件路径，该文件格式为：
一个节点保护密钥密文一行，每行的格式为“节点标识（与节点清单文件一致）|ZMK加密的节点保护密钥密文|节点保护密钥校验值|”
3.1.7.2.2输出参数
返回的所有数据，写入到nodeZmkFile参数指定的文件中。
3.1.7.2.3返回值
Ø>=0正确
Ø<0错误
3.1.7.3接口示例
3.1.8生成第三方RSA对
3.1.8.1接口定义
intHisuGenThirdPartyRSA（
char*designID,
char*nodeID,
char*keyModelID,
intlenOfRSA,
intexponentOfPK,
char*designID01,
char*nodeID01,
char*keyModelID01,
intencMode,
char*dOfVK,
intsizeOfDOfVK,
char*pOfVK,
intsizeOfPOfVK,
char*qOfVK,
intsizeOfQOfVK,
char*dmp1OfVK,
intsizeOfDmp1OfVK,
char*dmq1OfVK,
intsizeOfDmq1OfVK,
char*iqmpOfVK,
intsizeOfIqmpOfVK,
char*PKByDER,
intsizeOfPKByDER,
char*exponentOfPK,
intsizeOfExponentOfPK
）;
3.1.8.2接口说明
3.1.8.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
IC卡方案标识
nodeID
业务系统提供
节点的唯一标识
keyModelID
安全系统提供（可配置）
RSA密钥模板标识
lenOfRSA
业务系统提供
IC卡RSA对长度
exponentOfPK
业务系统提供
公钥指数，取值为3或者65537
designID01
安全系统提供（可配置）
保护密钥方案标识
nodeID01
安全系统提供（可配置）
保护密钥节点标识
keyModelID01
安全系统提供（可配置）
保护密钥模板标识
encMode
业务系统提供
私钥成分加密标识：
0，DES_ECB；1，DES_CBC；2，DES_ECB_P；
3.1.8.2.2输出参数
域标识值
域值
备注
dOfVK
安全系统返回
私钥的D分量
pOfVK
安全系统返回
私钥的P分量
qOfVK
安全系统返回
私钥的Q分量
dmp1OfVK
安全系统返回
私钥的DMP1分量
dmq1OfVK
安全系统返回
私钥的DMQ1分量
iqmpOfVK
安全系统返回
私钥的IQMP分量
PKByDER
安全系统返回
DER编码的公钥
3.1.8.2.3返回值
Ø>=0正确
Ø<0错误
3.1.8.3接口示例
3.2数据处理接口
3.2.1数据加密
3.2.1.1接口定义
intHisuEncryptDataBySpecKey（
char*designID,
char*nodeID,
char*keyModelID,
intdataTypeFlag,
intencMode,
char*IV,
intlenOfPlainText,
char*plainText,
char*cipherText,
intsizeOfCipherText
）;
3.2.1.2接口说明
3.2.1.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
工作密钥节点标识（即：
终端号或者第三方系统的系统标识号）
keyModelID
安全系统提供（可配置）
工作密钥模板标识（密钥标识：
ZEK）
dataTypeFlag
业务系统提供
0:
二进制
1:
十六进制
2:
请求二进制，返回十六进制
3:
按照2的方式处理数据，并按照内部规则处理0x800x00填充
encMode
业务系统提供
模式标识：
0：
DES_ECB
1:
DES_CBC
IV
业务系统提供
encMode不为1时，输入NULL
lenOfPlainText
业务系统提供
二进制表示的输入数据的长度
plainText
业务系统提供
二进制表示的输入数据
sizeOfCipherText
业务系统提供
密文数据缓冲区大小，返回数据为十六进制形式表示
3.2.1.2.2输出参数
域标识值
域值
备注
cipherText
安全系统返回
密文数据，十六进制表示
3.2.1.2.3返回值
Ø>=0正确
Ø<0错误
3.2.1.3接口示例
3.2.2数据解密
3.2.2.1接口定义
intHisuDecryptDataBySpecKey（
char*designID,
char*nodeID,
char*keyModelID,
intdataTypeFlag,
intencMode,
char*IV,
intlenOfCipherText,
char*cipherText,
char*plainText,
intsizeOfPlainText
）;
3.2.2.2接口说明
3.2.2.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
工作密钥节点标识（即：
终端号或者第三方系统的系统标识号）
keyModelID
安全系统提供（可配置）
工作密钥模板标识（密钥标识：
ZEK）
dataTypeFlag
业务系统提供
0:
二进制
1:
十六进制
2:
请求十六进制，返回二进制
3:
按照2的方式处理数据，并按照内部规则处理0x800x00填充
encMode
业务系统提供
模式标识：
0：
DES_ECB
1:
DES_CBC
IV
业务系统提供
encMode不为1时，输入NULL
lenOfCipherText
业务系统提供
密文数据长度
cipherText
业务系统提供
密文数据
sizeOfPlainText
业务系统提供
密文数据缓冲区大小，返回数据为二进制形式表示
3.2.2.2.2输出参数
域标识值
域值
备注
plainText
安全系统返回
明文数据，二进制表示
3.2.2.2.3返回值
Ø>=0正确
Ø<0错误
3.2.2.3接口示例
3.2.3HMAC计算
3.2.3.1接口定义
intHisuCalculateDigestBySpecKey（
char*designID,
char*nodeID,
char*keyModelID,
intdigestMode,
char*dataToHMAC,
intlenOfDataToHMAC,
char*HMAC,
intsizeOfHMAC
）;
3.2.3.2接口说明
3.2.3.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
工作密钥节点标识（即：
终端号或者第三方系统的系统标识号）
keyModelID
安全系统提供（可配置）
工作密钥模板标识（密钥标识：
ZEK）
digestMode
业务系统提供
摘要算法:
1－SHA1
2－SHA-224
3－SHA-256
dataToHMAC
业务系统提供
计算摘要的数据
lenOfDataToHMAC
业务系统提供
计算摘要的数据长度
sizeOfHMAC
业务系统提供
摘要结果接收缓冲区大小
3.2.3.2.2输出参数
域标识值
域值
备注
HMAC
安全系统返回
摘要结果
3.2.3.2.3返回值
Ø>=0正确
Ø<0错误
3.2.3.3接口示例
3.2.4HMAC校验
3.2.4.1接口定义
intHisuVerifyDigestBySpecKey（
char*designID,
char*nodeID,
char*keyModelID,
intdigestMode,
char*dataToHMAC,
intlenOfDataToHMAC,
char*HMAC,
intlenOfHMAC
）;
3.2.4.2接口说明
3.2.4.2.1输入参数
域标识值
域值
备注
designID
安全系统提供（可配置）
密钥方案标识（根据实际配置调整）
nodeID
安全系统提供（可配置）
工作密钥节点标识（即：
终端号或者第三方系统的系统标识号）
keyModelID
安全系统提供（可配置）
工作密钥模板标识（密钥标识：
ZEK）
digestMode
业务系统提供
摘要算法:
1－SHA1
2－SHA-224
3－SHA-256
dataToHMAC
业务系统提供
计算摘要的数据
lenOfDataToHMAC
业务系统提供
计算摘要的数据长度
HMAC
业务系统提供
摘要结果
lenOfHMAC
业务系统提供
摘要结果长度
3.2.4.2.2输出参数
域标识值
域值
备注
3.2.4.2.3返回值
Ø>=0正确
Ø<0错误
3.2.4.3接口示例
3.3文件处理接口
3.3.1文件加密
3.3.1.1接口定义
intHisuEncryptFileInBinaryBySpecKey（
char*designID,
char*nodeID,
char*zekKeyModelID,
char*zakKeyModelID,
char*plainTextFileName,
char*cipherTextFileName
）;
3.3.1.2接口说明
3.3.
升级会员 