云加密机接口调用（金融支付加密）

一、操作场景

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

八、示例

[LOGGER]logsw=errorlogPath=./[HOST1]hsmModel=SJJ1310linkNum=-5host=192.0.2.1port=8018timeout=5

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

可以直接将配置信息以字符串的形式传入初始化接口内。属性字段同上述内容一致。

Stringconfig="{"+"[LOGGER];"+"logsw=error;logPath=./;"+"[HOST1];"+"hsmModel=SJJ1310;"+"host=192.0.2.1;"+"port=8018;"+"connTimeout=5;"+"}";

十二、返回

·[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/KEK001 – ZPK002 – PVK/TPK/TMK003 – TAK008 – ZAK009 – BDK00A – ZEK/DEK00B – TEK 011 – KMC109 – MK-AC/MDK10C – HMAC209 – MK-SMI309 – MK-SMC402 – CVK409 – MK-DAK509 – 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个 ASCII 字符。
LmkKeyFlag	char	LMK 密钥标识。
ZMKKeyFlag	char	ZMK下加密的密钥密文标识。

十七、传参示例

keyType：001keyFlag：RZMKKey：R75C5203DAADCB18DF465044E4E1CE4C2storeKeyIndex：1storeKeyLabel：testKey

十九、返回

·[0]：LMK 下加密的密钥密文。

·[1]：密钥校验值。

20、抛出