电子文档安全管理系统中间件接口文档.docx

电子文档安全管理系统中间件接口
文档
北京亿赛通科技发展有限责任公司
2016年6月22日

整型数字（单位byte）
data~fileName
压缩包名称（例：中间件接 口 HTTP调用文档及）
必填
放在http body中
把压缩包转换成二进制文件 流 byte[]放入 http body

响应返回值判断文件是否是密文接口（文件路径形式）>描述
参数名
参数说明

dala~re(urnFlag
状态标识。
必填。请参考2. 5节RS接口返回值说 明
data~rcturnTip
{”failCount”:3,”nQCQunt”:0,”s uccCount":l}
failCount表示失败个数，noCount表 示是明文不用解密个数，succCount表 示成功个数
放在http body中
把解密后的压缩包转换成二 进制文件流byte[]放入http body

在http header里传递方法名表示要调用此接口，然后中间件将在返回的http响应 的header 里返回状态（data~returnFlag）> 接口定义请求参数说明响应返回值
功能
接口类型
判断文件是否是密文的接口
RS接口
参数名参数说明
备注
method-name
checkFilelsEncryptionByPat hRest
方法参数必填此值
data-path
文件全路径（例如：
D:\Cx\SrcPath\5M.docx）,必 须是中间件服务器木地可以 访问的路径
必须要urlencode
参数名参数说明
备注
data-returnFlag
状态标识。
0：明文
1:密文
data-retumTip
如果接口返回状态不是0成 功，可以可选地在此参数里 随意写入一小段提示错误的 信息返回给调用者
非必填。
文件加密接口（文件路径形式）>描述
在http header里传递方法名表示要调用此接I I,然后中间件将在返回的http响应 的header 里返回状态（data~returnFlag）。
注：接口里在文件加密之前会对文件进行判断，如果是明文才对文件进行加密。
加密成功后原文件成为加密后的文件> 接口定义请求参数说明响应返回值
功能
接口类型
明文加密接口
RS接口
参数名
参数说明
备注
method-name
fileEncryptionByPathRest
方法参数必填此值
data~path
文件全路径（例如：
D:\Cx\SrcPath\5M.docx）,必
必须要urlencode

须是中间件服务器本地可以 访问的路径

参数名
参数说明
备注
data~rcturnFlag
状态标识。
必填。请参考2.5节RS接口返回 值说明
data〜returnTip
如果接口返回状态不是0成 功，可以可选地在此参数里 随意写入一小段提示错误的 信息返回给调用者
非必填。
226. 文件解密接口（文件路径形式）> 描述
在http header里传递方法名表示要调用此接口，然后中间件将在返同的htlp响应 的header 里返回状态（data~returnFlag）。
注：接口里在文件解密之前会对文件进行判断，如果是密文才对文件进行解密。
解密成功后原文件成为解密后的文件> 接口定义请求参数说明响应返回值
功能
接口类型
密文解密接口
RS接口
参数名
参数说明
备注
mcthod-namc
filcDccryptionByPathRest
方法参数必填此值
data 〜path
文件全路径（例如： D:\Cx\SrcPath\5M.docx）,必 须是中间件服务器本地可以 访问的路径
必须要urlencode
参数名参数说明
备注
data-rcturnFlag
状态标识。
必填。请参考2.5节RS接口返回值说 明
data-returnTip
如果接口返回状态不是0成 功，可以可选地在此参数里 随意写入一小段提示错误的 信息返回给调用者
非必填。

2.3、中间件提供给第三方业务系统的外发接口外发文件制作接口（文件流形式）＞接口输入参数• json中参数含义解释如下:
位置参数名
参数说明备注
Http header
method-name
SIPMakeEod
请求方法参数，必输项；
user 〜invoker
调用方标识
只记录日志，业务未使用
data-eodJson
EOD的配置格式，json定 义如表格尾部描述。
可能含中文做urlEncodc
data-fileName
完整的文件名称（例：电 子文档安全管理系统中间 件接口文档V2.0.docx）
必须要urlEncode
http body
明文文件流
byte[]

Type=3
TimeSpan=-l
ReadNum--l
bReadTimeLimited=1
BeginTiice-2020-06-01
EndTime=2020-06-05 bPrint=O
bNetWork-0 bRevert=O ReadOnly-0 PassWordText="123456w WatennarkTextMhahaM bShowPermissions=l IsDelete=O
类型：o-直接阅读.1-密码认证.2-机器审定认证.3-密码+机器奔定认证 阅读时长，无限，范囹1-60000 （单位：小时） 阅读次数，-1无限.范围1-500000o禁用，1启用. o禁用.1启用。
o禁用，】启用. 0非只读，1只读.

o禁用，1启用. o禁用.1启用。
o禁用，】启用. 0非只读，1只读.
是否启用阅读时限，0禁用，1启用。启用后开始时间，裁至时间才有意义，时间糟度到夭 开始时间 敏止时间 是否允许打印， 是否允许联网， 是否允许还原， 是否允许只读， 密码，靖低6位，最高16位 水印，最低1位，MS516位是否提示权限，0禁用，1启用。暂时一直有提示，无选项 失效自删除0-不自削除；1-自删除• json样例格式如下:
"Type": "1","TimeSpan": "-I","ReadNum": "2", "bReadTimeLimited": ”1”， "BeginTime": "2015-05-27", "EndTime": "2015-05-31”， "bPrint": "0","bNetWork": "0","bRevert": "0","Readonly": "0","PassWordText": ”"， "WatermarkText": ”水印内容填写哈哈”, ,,lsDelete":"0"> 接口返回参数
位置
参数名
参数说明
备注
Http header
data-returnFlag
状态标识。
必填。请参考2.5节RS接 口返回值说明
data~retumTip
如果接口返回状态不是0 成功，可以可选地在此参 数里随意写入一小段提示 错误的信息返回给调用者

http body
加密后的EOD 文件转换成二 进制文件流 byte[]放入 http body

外发文件制作接口（文件路径形式）注：外发文件制作完成后保留了原始文件，请自行删除>接口输入参数• json中参数含义解释如下:
位置
参数名参数说明
备注
Http header
method-name
SIPMakeEodByFileDirector
y
请求方法参数，必输项；
user-invoker
调用方标识
只记录日志，业务未使用
data-eodJson
EOD的配置格式，json定 义如表格尾部描述。
可能含中文做urlEncode
data~(arge(Paih
完整的文件名称或文件夹
（例：
必须要urlEncode

D:\Cx\SrcPath\5M.docx ), 必须是中间件服务器本地 可以访问的路径

Type»3
TimeSpan=-l ReadNum=-l bReadTitteLimited=l BeginTime=2020-06-01 EndTime-2020-06-0S bPrint=O bNetWork=0
bRevert-0
ReadOnly=0 PassWordText=w123456w WatermarkTextMhahaM bShowPermi5sions=l IsDelete=O
类型：o-直接阅读，1-密码认证，2-机器绑定认证,3-宅码+*几器绑定认证阅读时长，-1无限，范91-60000位：小时)阅读次数，-I无限.范围1-500000o禁用.1启用。 0禁用，1启用.
0禁用，1启用. 0非只读,1只诿。

阅读次数，-I无限.范围1-500000o禁用.1启用。 0禁用，1启用.
0禁用，1启用. 0非只读,1只诿。

o禁用.1启用。 0禁用，1启用.
0禁用，1启用. 0非只读,1只诿。
是否启用阅读时限,0禁用.1启用。启用后开始时间.敝至时间才有意义，时间精度到夭 开始时间 截止时间是否允许打印.
是否允许联网，是否允许还原，是否允许只读.
密码，最低6位，最高16位水印，最低1位，最高16位是否提示权限.0禁用,1启用。带时一直有提示，无选项失效自删除0-不自削除；1 ■自删除• json样例格式如下:
"Type": ,,1"/"TimeSpan": "-1”，"ReadNum": ”2","bReadTimeLimited": "1", "BeginTime": "2015-05-27", "EndTime": "2015-05-31",',bPrint": "0","bNetWork": "0","bRevert": "0","Readonly": "0",
"PassWordText":
-WatermarkText": ”水印内容填写哈哈","IsDelete”:" "0"
}> 接口返回参数2.3.3.判断EOD外发文件是否制作成功接口（文件路径形式）>接口输入参数> 接口返回参数2.4、其他接口
位置
参数名
参数说明
备注
Http header
data~returnFlag
状态标识。
必填。请参考2.5节RS接
口返回值说明
data~eodPa(h
制作成功后的外发文件全 路径
经过了 urlEncode
data~returnTip
如果接口返回状态不是0 成功，可以可选地在此参 数里随意写入一小段提示 错误的信息返回给调用者

位置参数名
参数说明备注
Http header
melhod~name
checkFilelsEodByPath
请求方法参数，必输项；
uscr~invokcr
调用方标识
只记录日志，业务未使用
dala-targetPath
完整的文件名称或文件夹 （例：
D:\Cx\SrcPath\5M.docx）, 必须是中间件服务器本地 可以访问的路径
必须要urlEncode
位置
参数名参数说明
备注I^H
Http header
dala~returnFlag
状态标识
0：表示制作成功
1:制作失败
2：表示正在制作
data~eodPath
制作成功后的外发文件全 路径
当 data~retumFlag 是 0 时才 返回此值
经过了 urlEncode
data~returnTip
如果接口返回状态不是0 成功，可以可选地在此参 数里随意写入一小段提示 错误的信息返回给调用者

241 .判断服务是否正常接口>接口输入参数> 接口返回参数2.5、RS接口返回值说明文档说明
位置
参数名
参数说明
备注
Http header
method-name
checkServicelsAlive
请求方法参数，必输项；
位置
参数名
参数说明
备注
Http header
data~returnFlag
状态标识
0：表示正常
其他值或者异常表示服务 不正常
参数名 参数key 参数值含义备注
返回标识
data- retumFlag
0
通用的成功

1
通用的失败

2
调用分块加密接口时表示是密 文，不用加密
调用分块解密接口时表示是明 文，不用解密
判断EOD外发文件是否制作成功 接口中表示正在制作；

9
系统密钥未获取到或者未初始化

20
加密接口异常

30
解密接口异常

31
文件流转二进制失败

32
没有获取到文件流

33
接收到的需要加密的块大小为0, 无法进行加密（data~counSize参 数值为0或空）

34
压缩包名称为空（data~fileName 参数为空）

35
文件大小为空（data^fileSize参数 为空）

36
压缩包下载失败

37
压缩包没有落地

38
文件路径为空（datapath参数为 空）

39
获取的是文件夹，无法进行判断

40
文件不存在

本文档所涉及到的文字、图表等，仅限于北京亿赛通科技发展有限责任公司和被呈送方内部使用，未经双方书面许可，请勿扩散到第三方。
文档属性文档历史
软件名称［中文］:
电子文档安全管理系统中间件接口文档
软件名称［英文］:

产品编号：

产品型号：

文档主题：
电子文档安全管理系统中间件 接口文档
文档编号：

文档作者：
李杰
编制日期：
2020-07-28
审批人：

审批日期：

批准人：

批准日期：

扩散范围：

文档版本
修订状态
修订日期
修订人
描述
V1.0
初稿
2015-5-4
桂升

V1.6
修改
2016-06-22
雷晟，李鹏鹏
给加解密接口增
加http形式
V1.7
修改
2020-02-19
李木
4^ /、、、
返回值错误码明 确定义
V2.0
修改
2020-05-11
李杰
修正错误，添加 中间件产品化项 目更新
V2.1
修改
2020-07-28
李杰
文档新版本

41
获取eodConfig出错 （data~eodJson 参数出错）

42
执行EOD文件生成命令时出错

43
EOD配置文件生成失败

44
生成EOD文件方法异常

45
目标文件或者目录不存在
（data~targetPath 参数出错）

46
eod文件制作失败或者eod文件被 删除

47
ip地址为空

48
硬件码为空

49
中间件SDK应用次数超过5次

50
文件名为空

51
非windows格式文件名

52
非合法压缩包类型

53
密钥名称为空

54
data~fileOffset 转成 Integer 失败

55
data-counSize 转成 Integer 失败

56
data~fileSize 转成 Integer 失败

57
data-fileOffset 参数为空

58
IP地址不合法

59
硬件码格式不合法

60
加解密部分成功部分失败

61
EodJson不合法

62
接1 1 Token校验失败，token为空 或者没有传入token

63
〃接口 Token校验失败，token为

空或者没有传入token

64
接口 Token校验失败，己过期

65
SDK未注册

、

4(X)
失败。请求方的请求地址或参数 不符合要求

401
失败。请求方权限不足

422
失败。请求的数据在服务端不存 在
比如请求一个文件 的权限但服务端库 里没有时，是返回0 表示没查到还是返 同422让请求方知 道数据异常，由双 方约定。

500
失败，服务端内部错误
服务端内部故障

503
服务器没有授权

504
服务不可用，中间件授权类型与 调用接口类型不一致

505
服务不可用，中间件授权失败次 数超过三次

第三部分：FAQ
3.1、查看硬件码和修改密钥中间件安装后的默认端口是：8081访问路径：http:〃ip:8081/sec-server/用户名：conf Ad min默认密码：登录，查看硬件码和秘钥
数据至配置凄件字列号ES12210004D4C3DFOE002C54420099F7撕■诳注：如果cdg服务器没有授权或者授权到期导致中间件无法启动，则要从日志中查看服务 器的硬件码
3.2、https访问中间件/调用中间件接口https访问中间件后台管理系统直接使用 https:〃ip:8443/sec-server/访问即可https调用中间件接口服务1、使用HttpCIient W.接调用中间件接口会发生.ception异常，需要使用以下代码设置 HttpCIient//设置允许所有主机名称都可以，忽略主机名称验证private static CloseableHttpClient buildSSLCloseableHttpClient () throws Exception {
SSLContext sslContext = newSSLContextBuilder().loadTrustMaterial(null, new Truststrategy() (
//信任所有
public boolean isTrusted (X509Certificate[] chain, String authType) throws CertificateException (return true;
)
}) .build();
// ALLOW ALL HOSTNAME VERIFIER:这个主机名验证器基本上是关闭主机名验证的， 实现的是一个空粮作，一并且不会抛出.ception异常。
SSLConnectionSocketFactory sslsf = newSSLConnectionSocketFactory(sslContext, new String[] ( "TLSvl" }, null, _ALL_HOSTNAME_VERIFIER);
return m().setSSLSocketFactory(sslsf).build();}2、使用以下代码获取HttpCIienthttpclient = buildSSLCloseableHttpClient();
3.3、接口调用失败，返回Http状态为500 Internal ServerError, 未返回 data〜returnFlag接11地址填写错误，请仔细检查接11地址是否正确
3.4、接口调用出错或者传参不合法导致之后生成EOD文件接口不可用（多数情况下返回42）
打开任务管理器，停止所有的CdgOut进程，重启服务后再次调用即可（如无法停止 请重启物理机）
如果仍然无法调用，清检2 CdgOut程序是否损坏（程序大小为0KB则肯定损坏）（路 径为 C:\Program Files （x86）\EsafeNet\SecServer\tomcat8.0.39\webapps\sec-server\WEB-IN F\classes\resources\eod\EODMaker＞）需要替换 CdgOut 程序。
3.5、接口 Token控制配置说明配置文件路径：
<sec 安装盘〉:'Program Files (x86)\ EsafeNet\SecServer\tomcatXXX\webapps\sec-server\WEB-INF\classes\rties86#是否开启接口鉴权开启，0关闭87est.api.auth=l88#token时效，单位小时1、开启接LI Token验证，所有的服务接LI在调用时均需要添加一个请求参数data~tokenaderC'data-token", "FMOLK川LJCKKMKJHCPKAFFJEAOOFICOCIBACBCACNCACBCMCHCL");2、data~token为请求令牌，需要请求接口http:〃中 间件服 务 IP:8081/sec-server/getToken?ssid='lk 务系统标识
获取Token,业务系统标识是双方约定保存在配置文件中的字符串，如标识错误则不能生成 令牌，令牌时效是配置文件中所配置的时间3、接口调用时如令牌错误，令牌过期均返同相应错误码
3.5、中间件日志配置说明1、SDK组件日志上传后的保存路径配置文件路径：
<sec 安装盘>:\Program Files (x86)\ EsafeNet\SecServer\tomcatXXX\webapps\sec-server\WEB-INF\classes\rties92#日志保存路径，注意愤后要/93 h=C:/sec Log/此路径即日志路地路径3.6、调用加解密接口时，中文编码说明1、如果传入的参数值是中文，如："data~fileName”:"测试文件.txt”。改值需进行UTF-8编码。
post. addHeader (■: "data-f ileName", URLEncoder. encode ( S："双(试文件°UTF-8W));
第一部分：文档概述
1.1、概述1.1.1 .方案概述.术语和缩写1.2、支持的规格1.1.1 .支持的操作系统
序号
术语
描述
1
中间件
亿赛通公司与第三方业务系统的交互接口程序。

2
第三方业务系
统
代指所有亿赛通客户的系统，如OA、业务系统等

• 支持windows系统。
1.12中间件提供的接口形式
•基于通用标准的rest接口进行与综合管理系统的交互。
第二部分：中间件提供给第三方业务系统的
接口服务
2.1、中间件提供给第三方业务系统的接口服务地址
接口的访问路径http://服务器ip地址：s/rs/uni如：
:8()81 /sec-server/s/rs/uni
:8443/sec-server/s/rs/uni
2.2、中间件提供给第三方业务系统的加解密接口2.2.1.判断文件是否是密文的接口（文件流形式）＞描述
在http header里传递方法名表示要调用此接口，在http body传二进制的文件流。然后中间件将在返回的hllp响应 的header里返回状态（data~returnFlag）＞ 接口定义请求参数说明响应返回值
功能
接口类型
判断文件是否是密文的接口
RS接口
参数名
参数说明
备注
method-name
checkFilelsEncryptionRest
方法参数必填此值
放在http body中
把文件转换成二进制文件流
byle[]放入 http body

参数名
参数说明
备注
data-returnFlag
状态标识。
0：明文
1:密文
data~re(urnTip
如果接口返回状态不是0成 功，可以可选地在此参数里 随意写入一小段提示错误的 信息返回给调用者
非必填。
2.22文件加密接口（文件流形式）＞描述
在hltp header里传递方法名表示要调用此接口，在hltp body传二进制的文件流。然后中间件将在返回的htLp响应 的header里返回状态（data~returnFlag）、在http body 里返回加密后的二进制文件流。
注：接口里在文件加密之前会对文件进行判断，如果是明文才对文件进行加密。
功能
接口类型
明文加密接口
RS接口
> 接口定义请求参数说明响应返回值文件解密接口（文件流形式）
参数名
参数说明
备注
method-name
flleEncry ption Rest
方法参数必填此值
da(a~counSize
当前文件传输的文件流的大 小
文件块的大小，实际必须为字符串形式 的整型数字（必须与实际大小相同，使 用程序获取即可）
data~fi 1 eOffset
文件截取的大小起始值
如果文件不分块传输的话fi leffet为 0,如果分块的话该值为当前块的起始 值在文件流中的位置（比如文件大小为 3072分三块，每块大小为1024；第一 块的fileoffet值为0,第二块的 fileoffet值为1024，第三块的 fileoffet值为2048）,不低于512字 节，fileOffset大于0的分块加密后调 用判断密文接口也会被识别为明文
放在http body中
把明文转换成二进制文件流 byte[]放入 http body

参数名
参数说明
备注
dala-reiurnFlag
状态标识。
必填。请参考2.5节RS接口返回值说 明
data-returnTip
如果接II返回状态不是0成 功，可以可选地在此参数里
非必填。

随意写入一小段提示错误的 信息返回给调用者

放在http body中
中间件把加密后的明文转换 成二进制文件流byte[]放入 http body

> 描述
在http header里传递方法名表示要调用此接口，在http body传二进制的文件流。然 后中间件将在返回的http响应 的header里返回状态（data'eturnFlag）、在http body 里返回解密后的二进制文件流。
注：接口里在文件解密之前会对文件进行判断，如果是密文才对文件进行解密。
功能
接口类型
密文解密接口
RS接口
> 接口定义请求参数说明响应返回值压缩包加密接口（文件流形式）
参数名
参数说明
备注
method-name
filcDccryptionRest
方法参数必填此值
data-counSize
当前文件传输的文件流的大 小
文件块的大小，实际必须为字符串形式 的整型数字（必须与实际大小相同，使 用程序获取即可）
data-fil eOffset
文件截取的大小起始值
如果文件不分块传输的话fileffet为 0,如果分块的话该值为当前块的起始 值在文件流中的位置（比如文件大小为 3072分三块，每块大小为1024：第一 块的fileoffet值为0,第二块的 fileoffet值为1024,第三块的 fileoffet 值为 2048）
blockSeq
分块解密时，从第一块解密
分块解密时，从第二块开始必填（非多

时返回的 data-returnSeq
密钥环境非分块解密时可以不填）
放在http body中
把密文转换成二进制文件流
byte[]放入 http body

参数名
参数说明
备注
data-returnFlag
状态标识。
必填。请参考2. 5节RS接口返回值说 明
data-returnTip
如果接口返回状态不是0成 功，可以可选地在此参数里 随意写入一小段提示错误的 信息返回给调用者
非必填。
放在http body中
把解密后的明文转换成二进 制文件流bytelJ放入http body

> 描述
在http header里传递方法名表示要调用此接口，在http body传二进制的文件流。然 后中间件将在返回的http响应 的header里返回状态（data~returnFlag）>在http body里返 回加密后的二进制文件流。
功能
接口类型
压缩包加密接口
RS接口
> 接口定义请求参数说明响应返回值压缩包解密接口（文件流形式）
参数名参数说明
备注
method-namc
filePackageEncrypttion
方法参数必填此值
data-fileSize
当前压缩包文件的总大小
文件的大小，实际必须为字符串形式的 整型数字（单位byte）
data-fil eName
压缩包名称（例：中间件接 口 HTTP调用文档及）
必填
放在http body中
把压缩包转换成二进制文件 流 byte[]放入 http body

参数名
参数说明

data~re(umFlag
状态标识。
必填。请参考2. 5节RS接11返回值说 明
data-rcturnTip
{"failCount”:3,"noCount":0,”s uccCount":!}
failCount表示失败个数,noCount表 示是密文不用加密个数，succCount表 示成功个数
放在http body中
把加密后的压缩包转换成二 进制文件流byle[]放入http body

>描述
在http header里传递方法名表示要调用此接口，在http body传二进制的文件流。然 后中间件将在返回的http响应 的header里返回状态（data~returnFlag）、在http body里返 回解密后的二进制文件流。
功能
接口类型
压缩包解密接口
RS接口
> 接口定义请求参数说明
参数名参数说明
备注
niethod~name
filePackageDecryption
方法参数必填此值
data-filcSize
当前压缩包文件的总大小
文件的大小，实际必须为字符串形式的