接口调用

最近更新时间：2023-09-26 14:15:25

我的收藏

本页目录：

本文主要介绍 Java 接口调用，实现集成 SDK 至业务系统中。
说明
更多接口详情请 联系我们 获取 EVSM 应用开发手册和 EVSM 接口开发文档。
SDK 初始化
hsmGeneralFinancehsm=hsmGeneralFinance.getInstance("./cacipher.ini");
调用接口
1. 生成工作密钥。
hsm.genWorkKey(keyType,algFlag,keyIndex,keyLable);
2. 数据加密。
hsm.generalDataEnc(algType,keyType,sm4SymmKey,disperFactor,sessionType,sessionFactor,padFlag,inData,IV);
3. 数据解密。
hsm.generalDataDec(algType,keyType,sm4SymmKey,disperFactor,sessionType,sessionFactor,padFlag,symmEnc,IV);
配置文件
方式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
ifHeart=yes
方式2：通过内容形式配置
可以直接将配置信息以字符串的形式传入初始化接口内。属性字段 同上述内容一致。
Stringconfig=
"{"
+"[LOGGER];"
+"logsw=error;logPath=./;"
+"[HOST1];"
+"hsmModel=SJJ1310;"
+"host=192.168.19.19;"
+"port=8018;"
+"connTimeout=5;"
+"}";
函数调用
步骤1：生成工作密钥
返回
0号索引下：密钥在 LMK 下加密的密文。
1号索引下：密钥校验值。
抛出
cn.tass.exceptions.TAException - 接口自定义异常
接口定义
  public String[] genWorkKey(String keyType,
                                     char keyFlag,
                                     int storeKeyIndex,
                                     String storeKeyLabel)
                              throws cn.tass.exceptions.TAException
请求参数
名称
类型
描述
keyType
String
密钥类型（相应密钥类型的密钥类型号），支持密钥类型代码和密钥类型名称两种格式，可以使用“00A”传入或“ZEK/DEK”传入,此密钥为用于敏感数据加密的加密密钥。支持类型如下：
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
algFlag
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算法密钥
KeyIndex
int
密钥存储索引，范围为：1-2048，其他值表示不存储。
KeyLabel
String
密钥存储标签  仅当1<=storeKeyIndex<=2048时生效，用于在密钥内部存储时标记密钥的标签说明，0-16个 ASII 字符。
传参示例
keyType：00A
algFlag：R
keyIndex：1
KeyLabel：test
步骤2：通用数据加密
返回
加密之后的密文数据。
抛出
cn.tass.exceptions.TAException - 接口自定义异常	
接口定义
    public byte[] generalDataEnc(int algType,
                             String keyType,
                             Object key,
                             String disperFactor,
                             Int sessionType,
                             String sessionFactor,
                             Int padFlag,
                             byte[] inData,
                             String IV)
                      throws cn.tass.exceptions.TAException
请求参数
名称
类型
描述
algType
int
加密算法模式，详情请参见 EVSM 应用开发手册4.2对称加解密运算模式。支持类型如下：
0-ECB 模式加密
1-CBC 模式加密
2-CFB 模式加密
3-OFB 模式加密
4-CRT 模式加密(16字节分组长度处理）
keyType
String
用于加密数据的源密钥类型，支持密钥类型名称和密钥类型编码两种格式。例如 ZEK/DEK 可以传00A和ZEK/DEK两种格式。密钥类型为用于敏感数据加密的加密密钥。ZEK/DEK 密钥也可通过管理工具产生，详见 EVSM 应用开发手册3.2.1章节。支持类型如下：
000–KEK
109–MDK
309–MK-SMC
00A–ZEK/DEK
00B–TEK
011–KMC
key
Object
用户加密数据的密钥的索引或密文，详情请参见 EVSM 应用开发手册3.2.1章节产生随机对称密钥部分。
传入参数数据类型为 int 型时，通过密钥索引调用密钥（取值需为1-2048之间）。
传入参数类型为 String 时，按 LMK 加密的密钥密文处理。
disperFactor
String
密钥分散因子 n 级分散因子进行串联，且每级分散因子必须为16个字节。  
敏感数据加密一般传空字符串或 NULL。
sessionType
int
密钥分散因子 n 级分散因子进行串联，且每级分散因子必须为16个字节。
敏感数据加密一般传空字符串或 NULL 。
sessionFactor
String
会话密钥因子。
sessionType 为1时，该域为8字节（16H）
sessionType 为2时，该域为16字节（32H）
sessionType 为5时，该域为16字节（32H）
敏感数据加密一般传空字符串或 NULL。
padFlag
int
PAD 填充标识，取值范围：00–05或10–11。
0-PBOC2.0 填充模式
1-ISO/IEC9797-1的 PADDING 模式2
2-ISO/IEC9797-1的 PADDING 模式1
3-ANSIX9.23
4-PKCS#5
5-NoPadding 模式
10-PBOC3.0
11-左填充+ISO/IEC9797-1
针对敏感数据加密一般选择1，详情请参见 EVSM 接口开发文档。
inData
byte[]
输入的明文数据。
IV
String
初始向量，仅当 algType 取值为01/02/03/4时需存在该域。
若密钥算法为128分组，该域为16字节（32H）
若密钥算法为64分组，该域为8字节（16H）
选择时根据加密算法模式是否使用初始向量，从而决定是否传入 IV，ECB 模式不需要 IV，传空字符串或 NULL 即可。
传参示例
algType：1
keyType："00A"
key:symmKey[0]//加密的对称密钥密文，使用EVSM内部的索引密钥，使用内部密钥时为int类型。
disperFactor：null
sessionType：0
sessionFactor：null
padFlag：1
inData：根据用户业务自行输入数据内容。
IV："00000000000000000000000000000000"
步骤3：通用数据解密
返回
解密后的数据。
抛出
cn.tass.exceptions.TAException - 程序运行异常		
接口定义
public byte[] generalDataDec(int algType,
                             String keyType,
                             Object key,
                             String disperFactor,
                             int sessionType,
                             String sessionFactor,
                             int padFlag,
                             byte[] inData,
                             String IV)
                      throws cn.tass.exceptions.TAException
﻿
请求参数
名称
类型
描述
algType
int
算法标识，详情请参见 EVSM 应用开发手册4.2对称加解密运算模式。支持类型如下：
0-ECB 模式加密  
1-CBC 模式加密
2-CFB 模式加密
3-OFB 模式加密
 4-CTR 模式加密数据长度必须为16的整数倍
keyType
String
密钥类型，支持类型包括：MK-SMC、ZEK、DEK、TEK 。
key
Object
用于加密数据的密钥索引或密文 。
disperFactor
String
密钥分散因子：n*32H（n 取值为0-8，每级分散因子长度为32H 即是16字节）。
 敏感数据加密一般传空字符串或 NULL。
sessionType
int
会话密钥产生模式。
0-不产生会话密钥 
1-ECB 模式加密8字节会话密钥因子，得8字节会话密钥
2-ECB 模式加密16字节会话密钥因子，得16字节会话密钥 
3-密钥的左右8字节异或，得8字节会话密钥 
 4-取密钥的左8字节作为会话密钥 
5-CBC 模式加密16字节会话密钥因子，得16字节会话密钥
敏感数据加密一般传空字符串或 NULL。
sessionFactor
String
会话密钥因子（仅当 sessionType 取值为01/02/05时生效）。
会话密钥模式为1时，该域为8字节（16H）
会话密钥模式为2时，该域为16字节（32H）
会话密钥模式为5时，该域为16字节（32H）
敏感数据加密一般传空字符串或 NULL。
padFlag
int
填充模式，取值范围：00–05或10–11。
0-PBOC2.0 填充模式
1-ISO/IEC9797-1的 PADDING 模式2
 2-ISO/IEC9797-1的 PADDING 模式 1
3-ANSIX9.23
4-PKCS#5
5-NoPadding 模式
10-PBOC3.0
11-左填充+ISO/IEC9797-1
针对敏感数据加密一般选择1，详情请 联系我们 获取 EVSM 接口开发文档。
inData
byte[]
待解密的数据。
IV
String
初始化向量，仅当 algType 为01/02/03该域存在。
若密钥算法为128分组，该域为16字节（32H）
若密钥算法为64分组，该域为8字节（16H）
传参示例
algType：1
keyType："00A"
key:symmKey[0]//加密的对称密钥密文，使用EVSM内部的索引密钥，使用内部密钥时为int类型。
disperFactor：null
sessionType：0
sessionFactor：null
padFlag：1
inData：自行输入加密后的数据。
IV："00000000000000000000000000000000"
﻿

参数名称	描述
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	密钥类型（相应密钥类型的密钥类型号），支持密钥类型代码和密钥类型名称两种格式，可以使用“00A”传入或“ZEK/DEK”传入,此密钥为用于敏感数据加密的加密密钥。支持类型如下： 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
algFlag	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算法密钥
KeyIndex	int	密钥存储索引，范围为：1-2048，其他值表示不存储。
KeyLabel	String	密钥存储标签仅当`1<=storeKeyIndex<=2048时生效，用于在密钥内部存储时标记密钥的标签说明，0-16个 ASII 字符。`