中国工商银行银企互连系统开发手册模板.doc

第 1 章 概述
银企互联面向大集团用户，提供和企业ERP系统直连平台，银企互联面向大集团用户，提供和企业ERP系统直连平台，为工行现金管理服务提供多渠道和用户化支持。
企业ERP系统经过HTTPS协议和工行系统进行连接并向银企互联前置发送数据，数据接口格式使用标准xml数据格式，但双方通讯过程中则需要遵守下文描述要求。银企互联前置接到企业数据后进行一系列检验后完成交易，并将处理结果以企业便于处理形式返回给企业。
在安全确保方面，通讯层安全确保是HTTPS协议。
企业如需使用银企互联络统，要办理相关注册手续，并审领证书。
企业进行结算类交易时，假如包含到授权过程，企业需要在企业网银系统中完成相关授权动作。银企互连系统将企业提交支付指令或授权成功后指令看成最终转账指令，依据提交指令证书ID检验收付方帐号等正当性，以确保所提交指令在权限许可范围内进行操作。
第 2 章 总体方案介绍
2.1 总体网络结构图

上图企业ERP系统1采取是非NC方法接入用户；企业ERP系统2采取是NC方法接入用户；
2.2 企业端安全服务器介绍
此服务器只对使用NC方法接入用户有效。企业端安全服务器被称为NetSafe Client。它有两个能够配置端口分别用于加密和署名／验签服务，以下图所表示（假设１为加密端口，２为署名／验签端口）。
1（加密）

NetSafe
Client

2（署名／验签）

1. http交易请求包
https交易请求包
1.署名／验签请求包
2.署名／验签结果
2. 交易结果

具体使用时，企业应用向工行提交交易请求时，能够依据http协议向NetSafe Client端口１发送请求。接到请求后，NetSafe Client使用企业证书将http请求包转换成https请求包发往工行端服务器；假如需要对一些交易数据进行署名，则企业应用需要和署名端口建立Socket 连接并将待署名数据发往端口２，然后接收端口２署名结果，以后再将包含署名信息交易请求发往端口１而完成整个交易请求过程。
对署名还是验署名请求区分则是经过http包头来进行。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方法接入用户
ü 企业向工行提交交易数据，必需经过企业方NetSafe Client进行和工行服务器连接，接口确定需要署名数据也必需由NetSafe Client署名服务器署名后组成要求数据包格式后，经过NetSafe Client提交工行，这么能够确保企业数据和相关信息不被恶意篡改。
ü 数据全部由NetSafe Client负责转发，使NetSafe Client成为架设在企业现场工行接入服务器。而企业和工行之间安全连接，由NetSafe Client和工行安全代理服务器NetSafe确保；
ü 工行接收到企业提交过来部分关键交易数据后，需要解密并验证企业数字署名，以预防第三方假冒企业行为。
对于非NC方法接入用户
ü 企业向工行提交交易数据时安全控制
企业ERP和银企互连系统之间使用HTTPS协议通讯。
企业能够选择是否对交易数据进行对称加密，现在系统支持算法有DES和3DES。进行对称加密能够预防第三方截获交易信息。而加密中需要用到密钥由企业和工行共同约定。（加密功效暂不支持）
企业需要对其发送指令数据进行数字署名，署名中使用证书能够是企业证书也能够是工行证书，其中署名使用算法是SHA1withRSA。进行数字署名能够预防第三方假冒企业行为。
ü 工行向企业发送结果信息时安全控制
企业ERP和银企互连系统之间使用HTTPS协议通讯。
企业可选择是否对返回数据进行对称加密，方法和上文相同。
工行对部分关键交易返回信息进行数字署名。
第 3 章 关键说明
Ø 全部交易请求包中“包序列ID”字段（PackageID）由企业产生，产生规则为目前日期（北京时间，格式为yyyyMMdd）＋7位序列号（比如，为12月23日发送一个交易请求包包序列ID）。在一个企业代码下当日包序列ID必需唯一。工行处理完成以后将该字段原值返回，即全部交易返回包中“包序列ID”字段（PackageID）。
Ø 转帐交易请求包中“署名时间”字段（SignTime），格式为yyyyMMddhhmmssSSS（比如8，表示12月23日9点27分10秒568毫秒）。署名时间应为北京时间。署名时间假如和交易请求抵达工行服务器时北京标按时间误差过大（暂定为15分钟），交易将无法进行。此方法将能够有效地预防黑客采取重放攻击进行干扰帐务活动行为。同一笔交易假如因为网络不正常等原因需要重新提交时，要修改转账交易请求包“署名时间字段”并重新署名。
Ø 全部请求包和返回包中备用字段使用关键是出于对以后扩展考虑，假如以后需要增加企业上送项目或返回给企业信息，无须再改变交易包格式。现在对企业请求包来说这些备用字段值能够送空；企业对银行返回包中备用字段也无须作处理。请求包中备用字段标签为“ReqReserved*”，返回包中备用字段标签为“RepReserved*”（其中*为1、2、3或4，详见接口说明文档）。
Ø 查询历史明细返回数据包中交易时间（<Trans_time></Trans_time>）数值如为空，则说明该笔指令是银行计息交易明细。
Ø 支付查询指令接口，方便企业对可疑、有疑问（如网络中止，交易长时间没有返回等）或处理完成转帐指令进行查询。企业提交要查询结算请求包序列ID，工行返回该笔转帐指令基础信息和状态。
Ø 本接口说明中全部包含金额字段全部是以分为单位（不带小数点）。
Ø 如企业系统需要代理汇兑功效则企业应用需同时开发网点信息下载交易，方便为代理汇兑交易中收方为它行情况时提供工行网点名称。不然，无需开发网点信息下载交易。
Ø 在网点信息下载功效中，因为下载数据过大且数据不会常常更新，所以此交易控制了企业每日下载次数。现在暂定次数为每日2次。
Ø 个人联名卡签权指令只支持币种是人民币账号/卡号。
Ø 企业端传输数据时，指定xml编码方法为GB2312。
Ø 银企互联提交包中包含“<SignTime>署名时间（yyyyMMddhhmmssSSS）</SignTime>”此标签，说明该交易需要进行署名处理。
Ø 企业端程序需要对银行返回数据有可扩展性，方便适应以后业务不停发展。
Ø 银企互连系统支持两种接入方法，用户能够任何选择一个。第一个：使用第三方NC软件方法接入银企互连系统；第二种：使用非NC方法企业直接接入银企互连系统；
下面将区分两类用户分别对接入方法等相关信息进行说明。
第 4 章 银企互联——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包格式进行打包，在局域网内经过http协议以POST方法将交易包发送到NetSafe Client安全http协议服务器。
http请求格式：action=”http://用户端NetSafe Client地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书ID&PackageID=包序列ID &SendTime=请求时间”
请求数据格式（post方法）：Version=版本号（区分版本时间，暂定0.0.0.1) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=用户归属单位&GroupCIS=用户归属编码&ID=用户证书ID（无证书用户可空)&PackageID=用户指令包序列号（由用户ERP系统产生，不可反复)&Cert=用户证书公钥信息（进行BASE64编码；NC用户送空) &reqData=用户xml请求数据
其中：包序列ID、证书ID应依据实际情况进行更改，请求时间为企业发出该交易请求包目前系统时间。post方法最终不许可有回车等其它乱字符，TransCode交易名称应和xml包内标签<TransCode></TransCode>中值一致，action中证书ID、PackageID和请求数据格式中证书ID、PackageID、xml包中证书ID、PackageID值三者相一致。
（2） NetSafe Client将xml包加密后根据https协议，经过互联网/专线发送到银行端NetSafe Server。（本步由NetSafe Client完成，企业无需处理）；
（3） NetSafe Server将交易请求送银企互连系统进行处理。

企业
NetSafe Client
NetSafe Server
（1）
（2）

工行
（3）

2、 结算类：
（1） 企业根据工行提供xml包格式进行打包，在局域网内和NetSafe Client署名端口建立Socket连接，经过此连接向署名端口发送http数据包。http包头中需包含“Content-Length”和“Content-Type”两个属性。其中“Content-Length:”后面是需要署名二进制数据包长度，“Content-Type:”后面是需要署名标识，为INFOSEC_SIGN/1.0。（注意大小写）
http请求格式：action=”http://用户端NetSafe Client地址和署名端口号”
请求数据格式：结算类请求提交xml包
NetSafe Client对xml包进行署名后，经过http协议将署名结果返回给企业系统。如署名成功<sign>标签和</sign>标签之间部分为署名结果。
NetSafe Client返回署名包以下：
<html>
<head>
<title>署名结果</title>
<result>0</result>
</head>
<body>
<sign>MIIIXAYJKovcNAQcCo…………. 0BlLdSgw=</sign>
</body>
</html>
（2） 企业根据工行提供xml包格式进行打包，在局域网内经过http协议以POST方法将交易包发送到NetSafe Client安全http协议服务器。
http请求格式：action=”http://用户端NetSafe Client地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书ID&PackageID=包序列ID &SendTime=请求时间”
请求数据格式（post方法）：Version=版本号（区分版本时间，暂定0.0.0.1) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=用户归属单位&GroupCIS=用户归属编码&ID=用户证书ID（无证书用户可空)&PackageID=用户指令包序列号（由用户ERP系统产生，不可反复)&Cert=用户证书公钥信息（进行BASE64编码；NC用户送空) &reqData=用户xml请求数据
其中：包序列ID、证书ID应依据实际情况进行更改，请求时间为企业发出该交易请求包目前系统时间。post方法最终不许可有回车等其它乱字符，TransCode交易名称应和xml包内标签<TransCode></TransCode>中值一致，action中证书ID、PackageID和请求数据格式中证书ID、PackageID、xml包中证书ID、PackageID值三者相一致。
（3） NetSafe Client将企业送来署名包加密后根据https协议，经过互联网/专线发送到工行端NetSafe Server，再发往工行网银进行处理。（本步由NetSafe Client完成，企业无需处理）。

企业

NetSafe Client

NetSafe Server
（1）
（2）
（3）
（4）

4.1.3.2 企业接收交易响应数据过程
企业接收到数据包格式：reqData=交易返回包 或 errorCode=错误代码
步骤：
判定返回数据中是否是errorCode：
（1）假如是：依据错误代码做对应处理，结束。错误代码含义参见接口说明文档中附录。
（2）假如否：
企业接收到数据包格式：reqData=交易结果包；企业依据优异行BASE64解码，署名返回包根据格式拆分出明文和密文，验签正确后对明文按工行提供xml包格式进行解包。对于单笔提交类指令（即存在文件级返回包指令），返回xml包格式根据指令级返回包格式来处理，多笔则根据文件级返回包格式来处理。
4.1.3.3 企业接收银行主动返回过程
http请求格式：action=”http://用户ERP服务器地址和端口号”
请求数据格式（post方法）：Version=版本号（区分版本时间，暂定0.0.0.1) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=用户归属单位&GroupCIS=用户归属编码&ID=用户证书ID（无证书用户可空)&PackageID=用户指令包序列号（由用户ERP系统产生，不可反复)&Cert=用户证书公钥信息（进行BASE64编码；NC用户送空) &reqData=用户xml请求数据
reqData数据格式：
假如需要署名，格式为：
数字字符串：长度10位，代表明文数据长度，不足10位左补0；
明文：xml明文，长度可变，需要上面数据指明，双字节字符（汉字）算作1位长度；
分隔符：ICBCCMP；
密文：明文经过署名后数据并做BASE64编码；
假如不需要署名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode编码（全部参数项）得到最终reqData数据。
根据以上格式将请求数据发送到企业；
第 5 章 银企互联——非NC方法接入用户
5.1 企业端系统环境要求
5.1.1 软件环境
对企业ERP系统无要求；
5.1.2 网络环境
企业财务系统能够经过专线和中国工商银行银企互连系统互联。
5.1.3 企业开发过程描述
5.1.3.1 企业提交交易请求数据过程
（1） 企业根据工行提供xml包格式进行打包，在局域网内经过http协议以POST方法将交易包发送到NetSafe Client安全http协议服务器。
http请求格式：action=”http://用户端NetSafe Client地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID=证书ID&PackageID=包序列ID &SendTime=请求时间”
请求数据格式（post方法）：Version=版本号（区分版本时间，暂定0.0.0.1) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=用户归属单位&GroupCIS=用户归属编码&ID=用户证书ID（无证书用户可空)&PackageID=用户指令包序列号（由用户ERP系统产生，不可反复)&Cert=用户证书公钥信息（进行BASE64编码；NC用户送空) &reqData=用户xml请求数据
其中：包序列ID、证书ID应依据实际情况进行更改，请求时间为企业发出该交易请求包目前系统时间。post方法最终不许可有回车等其它乱字符，TransCode交易名称应和xml包内标签<TransCode></TransCode>中值一致，action中证书ID、PackageID和请求数据格式中证书ID、PackageID、xml包中证书ID、PackageID值三者相一致。
reqData数据格式：
假如需要署名：
数字字符串：长度10位，代表明文数据长度，不足10位左补0；
明文：xml明文，长度可变，需要上面数据指明，双字节字符（汉字）算作1位长度；
分隔符：ICBCCMP；
密文：明文经过署名后数据并做BASE64编码；
假如不需要署名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码得到最终reqData数据。
根据以上格式将请求数据发送到工行；
5.1.3.2 企业接收交易响应数据过程
企业接收到数据包格式：reqData=交易返回包 或 errorCode=错误代码
reqData=交易返回包结构：
假如交易返回包进行了署名，则结构为：
数字字符串：长度10位，代表明文数据长度，不足10位左补0；
明文：长度可变，需要上面数据指明，双字节字符（汉字）算作1位长度；
分隔符：ICBCCMP；
密文：明文经过署名后数据；
假如交易返回包没有署名，则结构为：明文；
不管是否署名，交易返回包均进行了BASE64编码；
步骤：
判定返回数据中是否是“errorCode=”打头：
（1）假如是：依据错误代码做对应处理，结束。错误代码含义参见接口说明文档中附录。
（2）假如否：
企业接收到数据包格式：reqData=交易结果包
企业依据优异行BASE64解码，署名返回包根据格式拆分出明文和密文，验签正确后对明文按工行提供xml包格式进行解包。对于单笔提交类指令（即存在文件级返回包指令），返回xml包格式根据指令级返回包格式来处理，多笔则根据文件级返回包格式来处理。
5.1.3.3 企业接收银行主动返回过程
http请求格式：action=”http://用户ERP服务器地址和端口号”
请求数据格式（post方法）：Version=版本号（区分版本时间，暂定0.0.0.1) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=用户归属单位&GroupCIS=用户归属编码&ID=用户证书ID（无证书用户可空)&PackageID=用户指令包序列号（由用户ERP系统产生，不可反复)&Cert=用户证书公钥信息（进行BASE64编码；NC用户送空) &reqData=用户xml请求数据
reqData数据格式：
假如需要署名，格式为：
数字字符串：长度10位，代表明文数据长度，不足10位左补0；
明文：xml明文，长度可变，需要上面数据指明，双字节字符（汉字）算作1位长度；
分隔符：ICBCCMP；
密文：明文经过署名后数据并做BASE64编码；
假如不需要署名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode编码（全部参数项）得到最终reqData数据。
根据以上格式将请求数据发送到企业；
企业署名验签过程
在银企互联中，对于指令体署名和验签工作由纯java版工行署名验签接口完成。
本文档对在专业版银企互联中使用接口作出描述。
同时提供了一套纯java版从企业发送指令到工行系统和从工行系统接收处理结果例子程序。从企业发送指令到工行系统例子中包含了两方面内容：用企业数据层私钥对数据进行署名，然后用工行通讯层公钥进行通讯认证；从工行系统接收处理结果例子中包含了两方面内容：用企业通讯层私钥要求通讯认证，然后用工行数据层公钥进行数据验签。
企业署名验签方法总体介绍
接口包含icbc.jar、InfosecCrypto_Java1_02_JDK14.jar、org.mortbay.jetty.jar、tools.jar四个文件，使用时需要把这四个文件放置到javaclasspath目录中。
该接口提议JDK 版本为1.4.2。（不要使用JDK1.5版本或比1.4更低版本）
接口使用具体说明
Sign （对原始数据进行数字署名函数）
public 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 -
verifySign （对数字署名进行验签函数）
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.cer ，ceshizhang.key是一套用户证书公钥和私钥，保护口令是12345678。
2． Test.java是一个演示各个接口使用方法测试程序。
3． APIforZHEJIANG.rar指导企业开发例子程序；《使用说明》例子使用说明。
4． 附件以下

5.1.3.4 https服务器建立开发支持
请参考上面附件中APIforZHEJIANG.rar\APIforZHEJIANG\icbc\api\server.java开发。《使用说明》文档介绍了开发方法。
5.1.3.5 Base64编解码方法参考
/**
* base64解码
* @param s
* @return
*/
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 byte[] 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(String s) {
if (s == null)
return null;
sun.misc.BASE64Encoder encoder = new sun.misc.BASE64Encoder();
try {
return encoder.encode(s.getBytes());
} catch (Exception e) {
return null;
}
}