云加密机接口调用-实践教程-文档中心-腾讯云

操作场景
本文主要介绍 Java 接口调用，实现集成 SDK 至业务系统中。
说明
更多接口详情请 联系我们 获取 EVSM 应用开发手册和 EVSM 接口开发文档。
SDK 初始化
hsmGeneralFinance api = hsmGeneralFinance. getInstance(“./cacipher.ini”);
调用接口
1. 生成工作密钥（A0）。
hsmGeneralFinance api = hsmGeneralFinance. getInstance(“./cacipher.ini”);
2. 导入工作密钥（A6）。
String[] keys = api. genWorkKeyEnc(“001”, ‘R’, “R75C5203DAADCB18DF465044E4E1CE4C2”, 1, “testKey”);
3. 将 PIN 由 ZPK1 转换为 ZPK2 加密。
String pinZPK12ZPK2 = api. TransferPinZPK12ZPK2(“RD28F24D145AE11DB41FB7B21387B37CA”, “RB185C33B7AB1A53FBEBA58013E603AD3”,
4. 生成数据 MAC。
String mac = api. calMAC(1, 8, “008”, “R3E5329FD6CD64ECC5D9026E243AA611C”, “”, 0, “”, 1, “112233445566”, “00000000000000000000000000000000”);
5. 验证交易数据 MAC。
Boolean result = api. verifyMAC(1, 8, “008”, “R3E5329FD6CD64ECC5D9026E243AA611C”, “”, 0, “”, 1, “112233445566”, “00000000000000000000000000000000”, “0294FCF00259E28D”);
配置文件
方式1：通过文件形式配置
接口初始化支持直接将配置文件路径传入初始化接口内，指明绝对路径即可。
格式说明
1. 注释行以符号“#”起始，不支持行内注释。
2. 配置域以方括号“[”和“]”标识。
3. 配置项格式为“键名（Key）=键值（Value）”。
4. 配置域与键名不区分大小写，但为了直观建议配置域名使用大写。
5. 支持使用空白字符（空格或制表符）等对内容进行对齐操作。
6. 可在接口内拼装字符串传递配置，使用“{”和“}”包括所有内容，可使用“;”表示换行。
属性字段说明
接口基本配置属性域包括日志属性和 EVSM 属性，常用设置属性如下：
日志属性（“[LOGGER]”）：设置有关接口记录日志的属性。
参数名称
描述
logsw
设置日志类别的开关，每类日志通过独立的关键字开启，可支持类别有 error、debug。
logPath
设置日志文件的保存路径，需确保配置的目录已经存在，且应用系统具有写入权限。
EVSM 属性（“[HOSTn]”）：每个 EVSM 的属性，其中“n”为该 EVSM 在当前配置中从1开始的序号，接口会按顺序读取多个 EVSM 属性，直到序号无法连续。
参数名称
描述
hsmModel
EVSM 类型标识，用于指定 EVSM 驱动（此接口全部使用“SRJ1303”）。
linkNum
与此设备建立长连接数量。缺省值为-10，数字前的负号‘-’表示仅使用连接池，否则为优先使用连接池，优先使用连接池时若业务并发过高则接口中可能会创建短连接以用于业务处理，可能会对系统资源造成较大影响。
host
EVSM 主机服务 IP 地址，支持以域名的形式设置。
port
EVSM 主机服务端口。
timeout
超时时间设置（默认单位为秒，缺省值为6秒）。
connTimeout
指定接口与逃生服务器建立网络连接的超时时间（不存在时使用“timeout”取值）。
readTimeout
指定接口从逃生服务器读取信息的读超时时间（不存在时使用“timeout”取值）。
socketProtocol
通讯协议，默认为 TCP，支持 TLSv1.2等。
示例
[LOGGER]
logsw=error
logPath=./
﻿
[HOST1]
hsmModel=SJJ1310
linkNum=-5
host=192.168.19.19
port=8018
timeout=5
方式2：通过内容形式配置
可以直接将配置信息以字符串的形式传入初始化接口内。属性字段 同上述内容一致。
Stringconfig=
"{"
+"[LOGGER];"
+"logsw=error;logPath=./;"
+"[HOST1];"
+"hsmModel=SJJ1310;"
+"host=192.168.19.19;"
+"port=8018;"
+"connTimeout=5;"
+"}";
函数调用
步骤1：生成工作密钥 (A0)
返回
[0]：LMK 加密的密钥密文。
[1]：ZMK 加密的密钥密文。
[2]：新产生密钥的校验值。
抛出
 cn.tass.exceptions.TAException - 接口自定义异常
接口定义
(1)public String[] genWorkKeyEnc(String keyType,
                                       char keyFlag,
                                       Object ZMKKey,
                                       int storeKeyIndex,
                                       String storeKeyLabel)
                                throws cn.tass.exceptions.TAException
(2)public String[] genWorkKeyEnc(String keyType,
                                       char LmkKeyFlag,
                                       Object ZMKKey,
                                       char ZMKKeyFlag,
                                       int storeKeyIndex,
                                       String storeKeyLabel)
                                throws cn.tass.exceptions.TAException
功能介绍
  生成工作密钥，并在输出 ZMK 下加密的密文。
请求参数
名称
类型
描述
keyType
String
密钥类型,支持密钥类型代码和密钥类型名称两种格式，如“MDK”密钥可以传入“109”或“MDK”两种格式。支持类型如下：
000 - ZMK/KEK
001 - ZPK
002 - PVK/TPK/TMK
003 - TAK
008 - ZAK
009 - BDK
00A - ZEK/DEK
00B - TEK 
011 - KMC
109 - MK-AC/MDK
10C - HMAC
209 - MK-SMI
309 - MK-SMC
402 - CVK
409 - MK-DAK
509 - MK-DN
keyFlag
char
密钥 LMK 下加密的密钥标识。支持类型如下：
Z - 单倍长 DES 密钥
X - 双倍长 3DES 密钥
Y - 三倍长 3DES 密钥
U - 双倍长的 3DES 算法密钥
T - 三倍长的 3DES 算法密钥
R - 16字节 SM4 密钥
P - 16字节 SM1 密钥
L - 16字节 AES 密钥
 M - AES-192 算法密钥
N - AES-256 算法密钥
ZMKKey
Object
ZMK 密钥索引或密文（管理工具合成 ZMK 返回的 LMK 加密的密文）。
storeKeyIndex
int
密钥存储索引，范围为1-2048，其他值时不存储。
storeKeyLabel
String
密钥存储标签，用于在密钥存储内部存储时标记密钥的说明标签，0-16个 ASII 字符。
LmkKeyFlag
char
LMK 密钥标识。
ZMKKeyFlag
char
ZMK下 加密的密钥密文标识 。
传参示例
keyType：001
keyFlag：R
ZMKKey：R75C5203DAADCB18DF465044E4E1CE4C2
storeKeyIndex：1
storeKeyLabel：testKey
步骤2：导入工作密钥 (A6)
返回
[0]：LMK 下加密的密钥密文。
[1]：密钥校验值。
抛出
cn.tass.exceptions.TAException - 接口自定义异常
接口定义
public String[] importWorkKey(String importedKeyType,
                                       Object zmkKey,
                                       String importKeyCipherByZmk,
                                       char importedKeyAlgFlag,
                                       int storeKeyIndex,
                                       String storeKeyLabel)
                                throws cn.tass.exceptions.TAException
功能介绍
 导入工作密钥，导入ZMK 加密的密钥，即 ZMK 加密的密钥转换为 LMK 下加密。
请求参数
名称
类型
描述
importedKeyType
String
被导入的密钥类型，支持密钥类型名称和密钥类型编码两种格式,如"MDK"密钥可以传入"MDK"或"109"两种格式。支持类型如下：
000 – ZMK/KEK
001 – ZPK
002 – PVK/TPK/TMK
402 – CVK;003 – TAK
008 – ZAK;009 – BDK
109 – MK-AC/MDK
209 – MK-SM
309 – MK-SMC
409 – MK-DAK
509 – MK-DN
00A – ZEK/DEK
00B – TEK
10C – HMAC
011 – KMC
zmkKey
Object
ZMK 密钥索引或密文。
importKeyCipherByZmk
String
ZMK 下加密的密钥密文。
importedKeyAlgFlag
char
密钥标识，在 LMK 下加密的密钥密文标识，Z/X/Y/U/T/P/L/R。
storeKeyIndex
int
密钥存储索引，范围：1-2048，其他值表示不存储。
storeKeyLabel
String
密钥存储标签，仅当1 <= storeKeyIndex<= 2048 时生效，用于在密钥内部存储时标记密钥的标签说明，0-16个 ASCII 字符。
传参示例
importedKeyType：001
zmkKey：R75C5203DAADCB18DF465044E4E1CE4C2
importKeyCipherByZmk：RF598258A65A3EC81FDE62E08834AC821
importedKeyAlgFlag：R
storeKeyIndex：2
storeKeyLabel：testKey
﻿

参数名称	描述
logsw	设置日志类别的开关，每类日志通过独立的关键字开启，可支持类别有 error、debug。
logPath	设置日志文件的保存路径，需确保配置的目录已经存在，且应用系统具有写入权限。

参数名称	描述
hsmModel	EVSM 类型标识，用于指定 EVSM 驱动（此接口全部使用“SRJ1303”）。
linkNum	与此设备建立长连接数量。缺省值为-10，数字前的负号‘-’表示仅使用连接池，否则为优先使用连接池，优先使用连接池时若业务并发过高则接口中可能会创建短连接以用于业务处理，可能会对系统资源造成较大影响。
host	EVSM 主机服务 IP 地址，支持以域名的形式设置。
port	EVSM 主机服务端口。
timeout	超时时间设置（默认单位为秒，缺省值为6秒）。
connTimeout	指定接口与逃生服务器建立网络连接的超时时间（不存在时使用“timeout”取值）。
readTimeout	指定接口从逃生服务器读取信息的读超时时间（不存在时使用“timeout”取值）。
socketProtocol	通讯协议，默认为 TCP，支持 TLSv1.2等。

名称	类型	描述
keyType	String	密钥类型,支持密钥类型代码和密钥类型名称两种格式，如“MDK”密钥可以传入“109”或“MDK”两种格式。支持类型如下： 000 - ZMK/KEK 001 - ZPK 002 - PVK/TPK/TMK 003 - TAK 008 - ZAK 009 - BDK 00A - ZEK/DEK 00B - TEK 011 - KMC 109 - MK-AC/MDK 10C - HMAC 209 - MK-SMI 309 - MK-SMC 402 - CVK 409 - MK-DAK 509 - MK-DN
keyFlag	char	密钥 LMK 下加密的密钥标识。支持类型如下： Z - 单倍长 DES 密钥 X - 双倍长 3DES 密钥 Y - 三倍长 3DES 密钥 U - 双倍长的 3DES 算法密钥 T - 三倍长的 3DES 算法密钥 R - 16字节 SM4 密钥 P - 16字节 SM1 密钥 L - 16字节 AES 密钥 M - AES-192 算法密钥 N - AES-256 算法密钥
ZMKKey	Object	ZMK 密钥索引或密文（管理工具合成 ZMK 返回的 LMK 加密的密文）。
storeKeyIndex	int	密钥存储索引，范围为1-2048，其他值时不存储。
storeKeyLabel	String	密钥存储标签，用于在密钥存储内部存储时标记密钥的说明标签，0-16个 ASII 字符。
LmkKeyFlag	char	LMK 密钥标识。
ZMKKeyFlag	char	ZMK下加密的密钥密文标识。

接口调用

本页目录：

操作场景

SDK 初始化

调用接口

配置文件

方式1：通过文件形式配置

格式说明

属性字段说明

示例

方式2：通过内容形式配置

函数调用

步骤1：生成工作密钥 (A0)

返回

抛出

接口定义

功能介绍

请求参数

传参示例

步骤2：导入工作密钥 (A6)

返回

抛出

接口定义

功能介绍

请求参数

传参示例