中国工商银行银企互连系统企业开发手册.docx

《中国工商银行银企互连系统企业开发手册.docx》由会员分享，可在线阅读，更多相关《中国工商银行银企互连系统企业开发手册.docx（16页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、第 1 章 概述银企互联面对大的集团客户，供给与企业 ERP 系统直连的平台，为工行的现金治理效劳供给多渠道和客户化支持。企业 ERP 系统通过 S 协议与工行系统进展连接并向银企互联前置发送数据，数据的接口格式使用标准的xml 数据格式，但双方通讯的过程中则需要遵守下文描述的规定。银企互联前置接到企业数据后进展一系列的检查后完成交易，并将处理结果以企业便于处 理的形式返回给企业。在安全保证方面，通讯层的安全保证是 S 协议。企业如需使用银企互联系统，要办理有关注册手续，并审领证书。企业进展结算类交易时，假设涉及到授权过程，企业需要在企业网银系统中完成相关授权动作。银企互连系统将企业提交的支付

2、指令或者授权成功后的指令当作最终转账指 令，依据提交指令的证书 ID 检查收付方帐号等合法性，以保证所提交指令在权限允许范围内进展操作。第 2 章 总体方案介绍2.1 总体网络构造图/Intranet s企业ERP系统1 /Intranet s企业ERP系统2NetSafe ClientNetSafe效劳器银企互联系统上图企业ERP 系统 1 承受的是非NC 方式接入的客户；企业ERP 系统 2 承受的是NC 方式接入的客户；2.2 企业端安全效劳器简介此效劳器只对使用NC 方式接入的客户有效。企业端安全效劳器被称为NetSafe Client。它有两个可以配置的端口分别用于加密和签名验签效劳

3、，如以下图所示假设为加密端口，为签名验签端口。1. 交易恳求包2. 交易结果1. 签名验签恳求2. 签名验签结果1加密NetSafe Client2签名验签 s 交易恳求包具体使用时，企业应用向工行提交交易恳求时，可以依照 协议向 NetSafe Client 的端口发送恳求。接到恳求后，NetSafe Client 使用企业证书将 恳求包转换成 s 恳求包发往工行端效劳器；假设需要对某些交易数据进展签名，则企业应用需要与签名端口建 立 Socket 连接并将待签名数据发往端口，然后接收端口的签名结果，之后再将包含签名信息的交易恳求发往端口而完成整个交易恳求过程。对签名还是验签名恳求的区分则是

4、通过 包头来进展。 Content-Type: INFOSEC_SIGN/1.0 和 Content-Type: INFOSEC_VERIFY_SIGN/1.0 分别用于标识签名恳求和 验 签 名 请 求 ， 而 Content-Type: INFOSEC_SIGN_RESULT/1.0 和 Content-Type:INFOSEC_VERIFY_SIGN_RESULT/1.0分别用于标识签名和验签名的返回结果。为便利起见，可以将 NetSafe Client 的两个效劳端口规律地称为两台效劳器，NetSafe Client 的加密效劳器和签名效劳器。2.3 安全掌握介绍对于 NC 方式接入的

5、客户 企业向工行提交的交易数据，必需通过企业方的NetSafe Client 进展与工行效劳器的连接，接口确定需要签名的数据也必需由NetSafe Client 的签名效劳器签名后组成规定的数据包格式后，通过NetSafe Client 提交工行，这样可以保证企业数据以及相关信息不被恶意篡改。 数据全部由NetSafe Client 负责转发，使 NetSafe Client 成为架设在企业现场的工行接入效劳器。而企业与工行之间安全的连接，由NetSafe Client 和工行安全代理效劳器NetSafe 保证； 工行接收到企业提交过来的局部关键交易数据后，需要解密并验证企业的数字签名，以防止

6、第三方假冒企业的行为。对于非 NC 方式接入的客户 企业向工行提交交易数据时的安全掌握企业ERP 与银企互连系统之间使用 S 协议通讯。企业可以选择是否对交易数据进展对称加密，目前系统支持的算法有 DES 与3DES。进展对称加密可以防止第三方截获交易的信息。而加密中需要用到的密钥由企业与工行共同商定。加密功能暂不支持企业需要对其发送的指令数据进展数字签名，签名中使用的证书可以是企业证 书也可以是工行证书，其中签名使用的算法是SHA1withRSA。进展数字签名可以防止第三方假冒企业的行为。 工行向企业发送结果信息时的安全掌握企业ERP 与银企互连系统之间使用 S 协议通讯。企业可选择是否对返

7、回数据进展对称加密，方法与上文一样。工行对局部关键交易返回信息进展数字签名。第 3 章 重点说明 xml 格式要支持业界公认的标准格式，例如：等同于；上送数据格式尽量简洁，避开使用CDData 等文本格式。 全部的交易恳求包中“包序列 ID”字段PackageID由企业产生，产生规章为当前日期北京时间，格式为 yyyyMMdd7 位序列号例如 202312230000001，为 2023 年 12 月 23 日发送的一个交易恳求包的包序列ID。在一个企业代码下当日包序列 ID必需唯一。工行处理完毕之后将该字段原值返回，即全部的交易返回包中“包序列 ID” 字段PackageID。 转帐交易恳求

8、包中“签名时间”字段SignTime，格式为yyyyMMddhhmmssSSS例如 20231223092710568，表示 2023 年 12 月 23 日 9 点 27 分 10 秒 568 毫秒。签名时间应为北京时间。签名时间假设与交易恳求到达工行效劳器时的北京标准时间误差过大暂定为 15 分钟，交易将无法进展。此措施将可以有效地防止黑客承受重放攻击进展干扰帐务活动的行为。同一笔交易假设由于网络不正常等因素需要重提交时， 要修改转账交易恳求包的“签名时间字段”并重签名。 全部恳求包和返回包中备用字段的使用主要是出于对今后扩展的考虑，假设以后需要增加企业上送的工程或者返回给企业的信息，不必

9、再转变交易包格式。目前对企业请求包来说这些备用字段的值可以送空；企业对银行返回包中的备用字段也不必作处理。恳求包中的备用字段标签为“ ReqReserved*”，返回包中的备用字段标签为 “RepReserved*”其中*为 1、2、3 或 4，详见接口说明文档。 查询历史明细返回数据包中交易时间 数值如为空，则说明该笔指令是银行的计息交易明细。 支付查询指令接口，便利企业对可疑、有疑问如网络中断，交易长时间没有返回等 或处理完毕的转帐指令进展查询。企业提交要查询的结算恳求的包序列ID，工行返回 该笔转帐指令的根本信息和状态。 本接口说明中全部涉及金额的字段都是以分为单位不带小数点。 如企业系

10、统需要代理汇兑功能则企业应用需同步开发网点信息下载交易，以便为代理 汇兑交易中收方为它行状况时供给工行网点名称。否则，无需开发网点信息下载交易。 在网点信息下载功能中，由于下载数据过大且数据不会常常更，所以此交易掌握了企业每日下载次数。目前暂定次数为每日2 次。 个人联名卡签权指令只支持币种是人民币的账号/卡号。 企业端传输数据时，指定xml 编码方式为GB2312。 银企互联提交包中包含“签名时间yyyyMMddhhmmssSSS” 此标签的，说明该交易需要进展签名处理。 企业端的程序需要对银行返回的数据有可扩展性，以便适应今后业务的不断进展。 银企互连系统支持两种接入方式，客户可以任何选择

11、一种。第一种：使用第三方 NC软件方式接入银企互连系统；其次种：使用非NC 方式企业直接接入银企互连系统； 一些接口中，返回包分文件级返回包和指令级返回包两种。文件级返回包是作为客户恳求的响应信息同步返回的。而指令级返回包是银行主动发起的异步返回信息，表示指令处理的结果，指令级返回包首先会返回整批指令的处理结果，然后对于其中指令状态非最终状态成功和失败的指令，银行会实时更每一条指令的状态，然后再每条分别以指令级返回包的格式返回给客户。 建议客户使用 /1.1 协议。 /1.0 及其以下协议版本可能无法正常发送指令到银行端。下面将区分两类客户分别对接入方式等相关信息进展说明。第 4 章 银企互联

12、NC 方式接入客户4.1 企业端系统环境要求4.1.1 软件环境对企业的ERP 系统无要求；工行企业端证书效劳器软件NetSafe Client 需安装在一台PC 机上。4.1.2 网络环境企业财务系统通过局域网与工商银行供给的NetSafe Client 连接；企业端的 NetSafe Client 可以通过专线或 INTERNET 与中国工商银行银企互连系统互联。4.1.3 企业开发过程描述4.1.3.1 企业提交交易恳求数据过程企业提交的交易分为两大类：查询类和结算类需要进展签名处理。1、 查询类：（1） 企业依据工行供给的xml 包格式进展打包，在局域网内通过 协议以POST 方式将交

13、易包发送到NetSafe Client 的安全 协议效劳器。 恳求格式：action=” :/客户端 NetSafe Client 的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书 ID&PackageID=包序列 ID &SendTime=恳求时间”恳求数据格式post 方式：Version=版本号区分版本时间，暂定 0.0.0.1) &TransCode=交易代码区分交易类型，每个交易固定 )&BankCode= 客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID无证书客户可空)&PackageID=客户的指令包序列号由客

14、户 ERP 系统产生，不行重复)&Cert=客户的证书公钥信息进展 BASE64 编码；NC客户送空) &reqData=客户的xml 恳求数据其中：包序列 ID、证书 ID 应依据实际状况进展更改，恳求时间为企业发出该交易恳求包的当前系统时间。post 方式最终不允许有回车等其 他 乱 字 符 ， TransCode 交 易 名 称 应 与 xml 包 内 标 签 中的值全都， action 中的证书 ID 、PackageID 与恳求数据格式中的证书ID、PackageID、xml 包中的证书ID、PackageID 的值三者相全都。（2） NetSafe Client 将xml 包加密后

15、依据 s 协议，通过互联网/专线发送到银行端的NetSafe Server。本步由 NetSafe Client 完成，企业无需处理；（3） NetSafe Server 将交易恳求送银企互连系统进展处理。1NetSafeClient2NetSafeServer3企业工行2、 结算类：（1） 企业依据工行供给的 xml 包格式进展打包，在局域网内与 NetSafe Client 的签名端口建立 Socket 连接，通过此连接向签名端口发送 数据包。 包头中需包含“Content-Length”和“Content-Type”两个属性。其中“Content-Length:”后面是需要签名的二进制数

16、据包的长 度 ，“ Content-Type: ” 后 面 是 需 要 签 名 的 标 记 ， 为INFOSEC_SIGN/1.0。留意大小写 恳求格式：action=” :/客户端 NetSafe Client 的地址和签名端口号”恳求数据格式：结算类恳求提交的xml 包NetSafe Client 对 xml 包进展签名后，通过 协议将签名结果返回给企业系统。如签名成功标签与标签之间的局部为签名结果。NetSafe Client 返回的签名包如下：签名结果0MIIIXAYJKovcNAQcCo0BlLdSgw=（2） 企业依据工行供给的xml 包格式进展打包，在局域网内通过 协议以POST

17、 方式将交易包发送到NetSafe Client 的安全 协议效劳器。 恳求格式：action=” :/客户端 NetSafe Client 的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书 ID&PackageID=包序列 ID &SendTime=恳求时间”恳求数据格式post 方式：Version=版本号区分版本时间，暂定 0.0.0.1) &TransCode=交易代码区分交易类型，每个交易固定 )&BankCode= 客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID无证书客户可空)&PackageID=客户的指令包

18、序列号由客户 ERP 系统产生，不行重复)&Cert=客户的证书公钥信息进展 BASE64 编码；NC 客户送空) &reqData=客户的xml 恳求数据其中：包序列 ID、证书 ID 应依据实际状况进展更改，恳求时间为企业发出该交易恳求包的当前系统时间。post 方式最终不允许有回车等其 他 乱 字 符 ， TransCode 交 易 名 称 应 与 xml 包 内 标 签 中的值全都， action 中的证书 ID 、PackageID 与恳求数据格式中的证书ID、PackageID、xml 包中的证书ID、PackageID 的值三者相全都。（3） NetSafe Client 将企业

19、送来的签名包加密后依据 s 协议，通过互联网/专线发送到工行端的NetSafe Server，再发往工行网银进展处理。本步由NetSafe Client 完成，企业无需处理。1企业2NetSafeNetSafe3Client4Server4.1.3.2 企业接收交易响应数据过程企业接收到数据包的格式：reqData=交易返回包 或 errorCode=错误代码步骤：推断返回数据中是否是errorCode：（1） 假设是：依据错误代码做相应处理，完毕。错误代码的含义参见接口说明文档中的附录。（2） 假设否：企业接收到数据包的格式：reqData=交易结果包；企业依据先进展 BASE64 解码，

20、签名返回包依据格式拆分出明文和密文，验签正确后对明文按工行供给的 xml 包格式进展解包。对于单笔提交类指令即存在文件级返回包的指令，返回的 xml 包格式依据指令级返回包格式来处理，多笔则依据文件级返回包格式来处理。4.1.3.3 企业接收银行主动返回过程 恳求格式：action=” :/客户 ERP 效劳器的地址和端口号”恳求数据格式post 方式：Version=版本号区分版本时间，暂定 0.0.0.1) &TransCode=交易代码区分交易类型，每个交易固定 )&BankCode= 客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID无证书客户可空)&Package

21、ID=客户的指令包序列号由客户 ERP 系统产生，不行重复)&Cert=客户的证书公钥信息进展 BASE64 编码；NC 客户送空) &reqData=客户的xml 恳求数据reqData 数据格式：假设需要签名，格式为：数字字符串：长度 10 位，代说明文数据长度，缺乏10 位左补 0；明文：xml 明文，长度可变，需要上面的数据指明，双字节字符汉字算作 1 位长度；分隔符：ICBCCMP；密文：明文经过签名后的数据并做BASE64 编码； 假设不需要签名，则直接送xml 明文；以上数据经过拼接后，再进展 BASE64 编码仅 reqData 项、URLEncode编码全部参数项得到最终的r

22、eqData 数据。依据以上格式将恳求数据发送到企业；此格式返回的数据是不经过 NC 的，是银行直接发给企业的 ERP 系统；如有使用，企业需要在内管注册或者修改集团信息时填入企业用于接收银行反响的地址，标准格式是 :/ip:port；编解码方式查看 5.1.3.5第 5 章 银企互联非 NC 方式接入客户5.1 企业端系统环境要求5.1.1 软件环境对企业的ERP 系统无要求；5.1.2 网络环境企业财务系统可以通过专线与中国工商银行银企互连系统互联。5.1.3 企业开发过程描述5.1.3.1 企业提交交易恳求数据过程1 企业依据工行供给的xml 包格式进展打包，在局域网内通过 协议以POS

23、T 方式将交易包发送到NetSafe Client 的安全 协议效劳器。 恳求格式： action=” :/银行通讯前置的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书 ID&PackageID=包序列ID &SendTime=恳求时间”恳求数据格式post方式：Version=版本号区分版本时间，暂定 0.0.0.1) &TransCode=交易代码区分交易类型，每个交易固定 )&BankCode= 客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID无证书客户可空)&PackageID=客户的指令包序列号由客户 ERP 系统

24、产生，不行重复)&Cert=客户的证书公钥信息进展 BASE64 编码；NC 客户送空) &reqData=客户的xml 恳求数据其中：包序列 ID、证书 ID 应依据实际状况进展更改，恳求时间为企业发出该交易恳求包的当前系统时间。post 方式最终不允许有回车等其 他 乱 字 符 ， TransCode 交 易 名 称 应 与 xml 包 内 标 签 中的值全都， action 中的证书 ID 、PackageID 与恳求数据格式中的证书ID、PackageID、xml 包中的证书ID、PackageID 的值三者相全都。reqData 数据格式： 假设需要签名：数字字符串：长度 10 位，

25、代说明文数据长度，缺乏10 位左补 0； 明文：xml 明文，长度可变，需要上面的数据指明，双字节字符汉字算作 1 位长度；分隔符：ICBCCMP；密文：明文经过签名后的数据并做BASE64 编码； 假设不需要签名，则直接送xml 明文；以上数据经过拼接后，再进展BASE64 编码得到最终的reqData 数据。依据以上格式将恳求数据发送到工行；5.1.3.2 企业接收交易响应数据过程企业接收到数据包的格式：reqData=交易返回包 或 errorCode=错误代码reqData=交易返回包构造：假设交易返回包进展了签名，则构造为：数字字符串：长度10位，代说明文数据长度，缺乏10位左补0；

26、步骤：明文：长度可变，需要上面的数据指明，双字节字符汉字算作1位长度； 分隔符：ICBCCMP；密文：明文经过签名后的数据；假设交易返回包没有签名，则构造为：明文；不管是否签名，交易返回包均进展了BASE64编码；推断返回数据中是否是“errorCode=”打头：（1） 假设是：依据错误代码做相应处理，完毕。错误代码的含义参见接口说明文档中的附录。（2） 假设否：企业接收到数据包的格式：reqData=交易结果包企业依据先进展 BASE64 解码，签名返回包依据格式拆分出明文和密文，验签正确后对明文按工行供给的 xml 包格式进展解包。对于单笔提交类指令即存在文件级返回包的指令，返回的 xml

27、 包格式依据指令级返回包格式来处理，多笔则依据文件级返回包格式来处理。5.1.3.3 企业接收银行主动返回过程 恳求格式：action=” :/客户 ERP 效劳器的地址和端口号”恳求数据格式post 方式：Version=版本号区分版本时间，暂定 0.0.0.1) &TransCode=交易代码区分交易类型，每个交易固定 )&BankCode= 客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID无证书客户可空)&PackageID=客户的指令包序列号由客户 ERP 系统产生，不行重复)&Cert=客户的证书公钥信息进展 BASE64 编码；NC 客户送空) &reqDat

28、a=客户的xml 恳求数据reqData 数据格式：假设需要签名，格式为：数字字符串：长度 10 位，代说明文数据长度，缺乏10 位左补 0； 明文：xml 明文，长度可变，需要上面的数据指明，双字节字符汉字算作 1 位长度；分隔符：ICBCCMP；密文：明文经过签名后的数据并做BASE64 编码； 假设不需要签名，则直接送xml 明文；以上数据经过拼接后，再进展 BASE64 编码仅 reqData 项、URLEncode编码全部参数项得到最终的reqData 数据。依据以上格式将恳求数据发送到企业；此格式返回的数据是银行直接发给企业的 ERP 系统；如有使用，企业需要在内管注册或者修改集团

29、信 息 时 填 入 企 业用 于接 收 银 行 反 馈 的 地 址 ， 标 准 格 式 是 :/ip:port；编解码方式查看 5.1.3.5企业签名验签过程在银企互联中，对于指令体的签名与验签工作由纯java 版工行签名验签接口完成的。本文档对在专业版银企互联中使用的接口作出描述。同时供给了一套纯 java 版的从企业发送指令到工行系统和从工行系统接收处理结果的例子程序。从企业发送指令到工行系统的例子中包括了两方面的内容：用企业的数据层私钥对数据进展签名，然后用工行的通讯层公钥进展通讯认证；从工行系统接收处理结果的例子中包括了两方面的内容：用企业的通讯层私钥要求通讯认证，然后用工行的数据层公

30、钥进展数据的验签。使用这种接入方式的客户只能使用磁盘证书；该磁盘证书需要拆分，拆分为一对数据层证书，用于签名验签；一对通讯层证书，用于建立与银行的 s 连接。拆分方法见第 7 章企业签名验签方法总体介绍接口包含 icbc.jar、InfosecCrypto_Java1_02_JDK14.jar、org.mortbay.jetty.jar、tools.jar 四个文件，使用时需要把这四个文件放置到java 的 classpath 名目中。该接口建议的JDK 版本为 1.4.2。不要使用 JDK1.5 版本或者比 1.4 更低版本接口使用的具体说明Sign对原始数据进展数字签名的函数public

31、static byte sign(byte src,int len,byte privateKey, char keyPass)Description 用 rsa 算法对一段消息签名Parameters:privateKey - 为口令保护的私钥src - 为待签名消息len - 为待签名消息的长度keyPass - 为私钥保护口令Returns:假设成功返回签名结果,假设失败返回null Throws:NoSuchProviderException - NoSuchAlgorithmException - InvalidKeyException - SignatureException -v

32、erifySign对数字签名进展验签的函数public static int verifySign(byte src,int len, byte cert, byte sign)Description 用 rsa 算法对一段签名进展验证Parameters:cert - 为证书src - 为被签名的消息len - 为被签名消息的长度sign - 为签名的结果Returns:假设成功返回 0,假设其它则失败Throws:SignatureException - NoSuchAlgorithmException - InvalidKeyException -附件说明1. ceshizhang.ce

33、r ，ceshizhang.key 是一套客户证书的公钥与私钥，保护口令是 12345678。2. Test.java 是一个演示各个接口使用方式的测试程序。3. APIforZHEJIANG 文件夹指导企业开发的例子程序；使用说明例子的使用说明。4. 附件如下5.1.3.4 s 效劳器建立开发支持请参考上面附件中APIforZHEJIANGAPIforZHEJIANGicbcapiserver.java开发。使用说明文档介绍了开发方法。5.1.3.5 Base64 编解码方法参考建议使用sun 供给的BASE64 编解码方法实现。/* base64解码* param s:需要解码的数据* r

34、eturn 解码后的数据*/public static String getstrFromBASE64(String s) if (s = null)return null;sun.misc.BASE64Decoder decoder = new sun.misc.BASE64Decoder; try byte b = decoder.decodeBuffer(s); return new String(b); catch (Exception e) return null;/* base64解码* param s:需要解码的数据* return 解码后的数据*/public static b

35、yte getbyteFromBASE64(String s) if (s = null)return null;sun.misc.BASE64Decoder decoder = new sun.misc.BASE64Decoder;try return decoder.decodeBuffer(s); catch (Exception e) return null;/* base64编码* param s:需要编码的数据* return 编码后的数据*/public static String getrevFromBASE64(byte s) if (s = null)return null

36、;sun.misc.BASE64Encoder encoder = new sun.misc.BASE64Encoder; try return encoder.encode(s); catch (Exception e) return null;第 6 章 关于通讯证书和银行证书的说明假设企业客户需要接收银行的主动反响信息，请留意以下内容：1、 对于申请 IC 卡或者 USBKey 的硬方式数据证书的客户，需要在电子银行内部治理系统的“企业客户治理-客户通讯证书 ID 治理”下载一个通讯证书。此证书为磁盘证书，用于银行与客户建立 s 通讯使用；签名证书请客户连续使用硬证书；此磁盘证书需要拆分

37、，拆分方法请见第7 章。2、 全部客户需要从银行端猎取两张证书，一张是：银行端将对应的数据层公钥 trust 文件发给客户，以便银行与客户主动建立 s 链接认证使用；另一张是：银行端还要将客户验签使用的公钥证书在客户注册时也要发给客户，以便客户对银行返回的局部交易的数据进展验签使用。第 7 章 磁盘证书拆分7.1 证书拆分方法见以下附件中的证书制作流程.doc，拆分工具也在其中。7.2 证书拆分后流程企业将证书拆分后，需要进展以下步骤1、 将 trust 文件通讯层公钥发给银行，由银行布置在相关效劳器上，以便建立 s 认证；2、 其他.cer、.key 和 store 文件由客户保存，分别是数据层公钥、数据层私钥和通讯层私钥；