编制说明

Size: px

Start display at page:

Download "编制说明"

昀炫烘阙
4 years ago
Views:

1 广东省公共资源交易统一身份认证平台系统接入规范 V 年 9 月

2 目录概论... 3 第一部分统一身份认证服务接入流程业务场景接口协议省公共资源统一身份认证平台提供业务系统提供附录数字签名算法 DES 加解密算法说明第二部分数字签名及加解密接口范围接口列表接口协议 JavaScript 服务器端接口客户端接口时间源接口

3 概论省公共资源交易统一身份认证平台是实现全省公共资源交易一门式一网式全流程电子化交易的核心认证平台, 与省网上办事大厅统一身份认证平台省数字证书交叉认证平台对接, 以省公共资源交易统一账号作为基础账号, 一方面整合全省公共资源交易现有系统认证体系, 统一提供认证服务, 支撑全省公共资源交易所有系统之间的单点登录, 减少重复输入帐号密码及多次插入 CA 认证, 另一方面整合全省公共资源电子交易系统关键数据的数字签名及加解密工作, 提升用户使用体验, 降低用户成本, 提高用户办事效率, 推进信息验证互认和公开共享, 实现信息一地登记全省共享全网公开, 实现数字证书一地办理全省互认全程通用本规范分两部分 : 第一部分是统一身份认证服务 ; 第二部分是数字签名及加解密接口 - 3 -

4 第一部分统一身份认证服务 1. 接入流程 1. 业务系统向省公共资源交易中心申请接入省公共资源交易统一身份认证平台 ; 2. 省公共资源交易统一身份认证平台分配 ClientID 密钥加密向量; 3. 业务系统根据本规范进行系统改造开发 ; 4. 业务系统与省公共资源交易统一身份认证平台进行测试联调 ; 5. 测试联调通过后, 业务系统向省公共资源交易中心申请系统上线 ; 6. 省公共资源交易中心批复后业务系统部署上线 2. 业务场景业务系统登录流程如下 : - 4 -

5 用户 / 浏览器业务系统省公共资源交易统一身份认证平台 1 点击登陆或访问资源受限 2 业务系统检查局部会话 ( 有则直接跳到 13) 3 重定向到省公共资源交易统一身份认证平台检查全局会话 ( 重定向令牌认证接口 ) 5 导向省公共资源交易中心统一身份认证登陆页面 4 检查全局会话 ( 有则直接跳到 11) 6.1 用户输入省公共资源交易统一账号密码或者 CApin 码 6.2 用户使用省网办账号, 调用省网办统一认证, 认证成功则跳到 9 7 提交账号密码或者 CApin 码 9 携带 ticketid 回调 ticket 接收地址 (ticket 接收接口 ) 8 认证账号密码或 CA 10 根据 ticketid 查询登陆用户信息 (ticket 查询接口 ) 11 返回业务系统登陆的用户信息 13 展现登陆成功页面 12 业务系统生成局部会话 3. 接口协议 3.1 省公共资源统一身份认证平台提供重定向令牌认证接口 (1) 接口信息接口描述 TokenAuth 省公共资源交易统一身份认证平台 /TokenAuth 省公共资源交易统一身份认证平台 /TokenAuth 接口协议提供者 HTTP/HTTPS 省公共资源交易统一身份认证平台 - 5 -

6 主要使用者业务系统 (2) 1) 请求消息 TokenAuthRequestValue 为接口参数值, 包含如下信息 : 参数名称数据类型长度频次说明 ClientId String 16 1 业务系统标识 TimeStamp String 19 1 时间戳 yyyy-mm-dd HH:mm:ss, 其中 HH 取值为 00-23, 时区为东八区 ReturnURL String - 1 系统返回认证结果时需要调用的 URL Display String 登录框展示 : 1 nopage 不显示登录框, 直接返回单点失败或成功 TokenAuthRequestValue 的生成算法如下 : Digest = Base64(Hash(ClientId+ TimeStamp+ ReturnURL+Display)) 其中,Hash 算法采用 SHA-1 TokenAuthRequestValue= URLEncoding (ClientId+ $ + Base64 ( Encrypt(TimeStamp+ $ +ReturnURL + $ + Display+ $ +Digest))) 其中, 加密算法 Encrypt 采用 3DES,Key=SysKey,SysKey 是统一认证平台发给该业务系统的密钥统一认证平台在接收到重定向令牌认证请求后, 需要再做一次哈希转换 : Digest = Base64(Hash(ClientId + TimeStamp+ ReturnURL+Display)) 将 Digest 与接收到 Digest 进行比较, 若两者相同, 则传送消息没有被篡改示例 : 02%24trgDIA1KaO0kyXrT1SNhXBtqUSFFQfPp13xynPIVpQe8CRNuFxUl0RE2irGNgWg B9g6G88CUH4Rq%0ACwHaN%2F4mvU9b292IAcAaRJgtdfxZC59tKeci6%2FGmEJ7%2Fmv YqBRW46JzJah9U0do6sV2Yeb6t4EFk%0ApgchWRXp - 6 -

7 2) 应答消息接口方法为 : TokenAuthResponseValue 其中,ReturnURL 从 TokenAuthRequest 中获得 TokenAuthResponseValue 为接口参数值, 包含如下信息 : 参数名称数据类型长度频次说明 Result Integer 2 1 0: 成功 1: 失败 ClientId String 16 1 返回方系统标识省公共资源统一身份认证平台平台 Ticket String 返回给应用系统的 Ticket 信息 ; 若认证失败, 则不返回该值 TimeStamp String 19 1 时间戳 yyyy-mm-dd HH:mm:ss, 其中 HH 取值为 00-23, 时区为东八区 TokenAuthResponseValue 的生成算法如下 : Digest = Base64(Hash(Result + ClientId+ Ticket + Timestamp)) 其中,Hash 算法采用 SHA-1 TokenAuthResponseValue = URLEncoding(ClientId+ $ + Base64(Encrypt ( Result + $ + Ticket + $ + TimeStamp + $ + Digest))) 其中, 加密算法 Encrypt 采用 3DES,Key=SysKey,Syskey 是统一认证平台颁发给该系统的密钥调用方系统在接收到统一认证平台的返回结果后, 需要对重定向返回所携带的消息再做一次哈希转换 :Digest = Base64(Hash(Result + ClientId+ Ticket + TimeStamp)), 将 Digest 与接收到的 Digest 进行比较, 若两者相同, 则说明传送消息没有被篡改调用方业务系统在接收到统一认证平台成功返回的 Ticket 信息之后, 需要后台调用 Ticket 信息查询接口获取真实的用户帐号信息, 显示用户登录成功的欢迎信息示例 : 业务系统 /xxx.xxx?tokenauthresponse= %24ae8naym7wabd93bakuji3aacccr8rjy8az wha%2b9wmk%2fctpkyuvgr1jbu3bgj5uwuiolr0iowibso%0aummqpvfqvwm%2bd3kslulln SyowFojuhMrbHsxJTfTsQ%3D%3D - 7 -

8 3.1.2 Ticket 信息查询接口 (1) 接口信息 : 接口描述 ticket 省公共资源交易统一认证域名 /ticket/getticketinfo 省公共资源交易统一认证域名 /ticket/getticketinfo 接口协议 HTTP/HTTPS 提供者省公共资源交易统一身份认证平台主要使用者业务系统 (2) : 1) 请求消息参数名称数据类长频次说明型度 Sign String 参见附录 5.1 ClientId String 16 1 业务系统标识 Ticket String 64 1 中心统一认证平台通过重定向方式返回给交易系统的 Ticket TimeStamp String 19 1 时间戳 yyyy-mm-dd HH:mm:ss, 其中 HH 取值为 00-23, 时区为东八区统一认证平台接收到该请求后, 按照 Sign 参数的原始签名的处理方式, 对接收到的相应参数再做一次相同的签名处理, 得到一个 Sign 若两者结果一致, 则表示传送消息没有被篡改, 进行正常响应 2) 应答消息返回结果为 JSON 格式参数节点参数名称数据类长度频次说明型 meta code String 2 1 0: 成功 - 8 -

9 -2: 签名失败 message String 统一帐号 -3: 无 ticket 信息 info user 0-1 用户信息 role 0-1 角色信息 resurl String caenduser String 50 1 证书号 logintype String 10 1 CA 代表 CA 证书登录,PWD 代表账号密码登录 institution 0-1 企业信息示例 : { "meta": { "code": "0", "message": " 查询票据成功!" }, "info": { "user": { "id": 200, "loginname": "test", "name": " 测试人员 ", "telephone": " ", " ": "rong@163.com", "state": 1111, "insinfoid": -1, "inspersonid": 529 }, "role": { - 9 -

10 "id": 1, "name": " 委托人 ( 招标人采购人出让人 )", "description": " 委托人 ( 招标人采购人出让人 )", "parentid": -1 }, "institutioncode": " ", "resurl": "", "logintype": "PWD", "institution": { "id": 469, "userid": 200, "name": " 广州俊业有限公司 ", "institutioncode": " ", "purchasertypeid": 231, "higherinstitution": "1", "administrativearea": , "address": " 广州市越秀区建设大马路 210 号 ", "postalcode": , "phone": " ", "faxnumber": " ", " ": "1@q.com", "economicnatureid": 11, "registeredcapital": 22, "businessscope": "222", "sidelinescope": "222", "registrationdate": "Aug 28, :00:00 AM", "chinesename": " 广州俊业有限公司 ", "scaleid": -1, "state": 2, "createtime": "Aug 28, :55:20 PM",

11 "loginflag": 0, "creator": 517, "creatorname": " 刘德华 " } } } 3.2 业务系统提供 TicketID 接收接口 (1) 接口信息接口描述接口协议提供者主要使用者 TicketID 接收接口业务系统 /xxx HTTP/HTTPS 业务系统省公共资源交易统一身份认证平台 (2) 业务系统域名 /xxx?tokenauthresponse=tokenauthresponsevalue tokenauthresponsevalue 为接口参数值, 包含如下信息 : 参数名称数据类型长度频次说明 Result Integer 2 1 0: 成功 1: 失败 ClientId String 16 1 系统标识 Ticket String 返回给应用系统的 Ticket 信息 ; 若认证失败, 则不返回该值 TimeStamp String 19 1 时间戳 yyyy-mm-dd HH:mm:ss, 其中 HH 取值为 00-23, 时区为东八区

12 tokenauthresponsevalue 的生成算法如下 :Digest = Base64(Hash(Result + ClientId+ Ticket + Timestamp)) 其中, Hash 算法采用 SHA-1 TokenAuthResponseValue = URLEncoding(ClientId+ $ + Base64(Encrypt ( Result + $ + Ticket + $ + TimeStamp + $ + Digest))) 其中, 加密算法 Encrypt 采用 3DES,Key=SysKey,Syskey 是省公共资源交易统一身份认证平台平台颁发给该系统的密钥调用方系统在接收到省公共资源交易统一身份认证平台平台的返回结果后, 需要对重定向返回所携带的消息再做一次哈希转换 :Digest = Base64(Hash(Result + ClientId+ Ticket + TimeStamp)), 将 Digest 与接收到的 Digest 进行比较, 若两者相同, 则说明传送消息没有被篡改调用方业务系统在接收到省公共资源交易统一身份认证平台平台成功返回的 Ticket 信息之后, 需要调用 Ticket 信息查询接口获取真实的用户帐号信息示例 : 业务系统 /xxx.xxx?tokenauthresponse= %24ae8naym7wabd93bakuji3aacccr8rjy8 AZwHa%2B9wMK%2FCtPkYUvgr1jbU3BgJ5UWuioLr0ioWiBSo%0AUmMqpVFqvw M%2BD3KslullnSyowFojuhMrbHsxJTfTsQ%3D%3D

13 4. 附录 4.1 数字签名算法假设参与参数签名计算的请求参数分别是 k1 k2 k3, 它们的值分别是 v1 v2 v3, 则参数签名计算方法如下 : 1. 将请求参数格式化为 key=value 格式, 即 k1=v1 k2=v2 k3=v3 ; 2. 将格式化好的参数键值对以字典序升序排列后, 拼接在一起, 即 k1=v1k2=v2k3=v3 ; 3. 在拼接好的字符串末尾追加上颁发的业务系统密钥上述字符串的 MD5 值即为签名的值注 : 计算签名时的请求参数中不要包含 sign( 签名 ) 参数, 因为 sign 参数的值此时还有待计算另外, 计算签名的时候不需要对参数进行 urlencode 处理 ( application/x-www-form-urlencoded 编码 ), 发送请求的时候需要进行 urlencode 处理 4.2 3DES 加解密算法说明对称算法运算模式 :CBC 填充模式 :PKCS7Padding 字符串编码 :utf-8 加密过程 : 使用 3DES 算法加密时, 必须将初始向量 IV 密钥及待加密明文都转换成字节数组解密过程 : 使用 3DES 算法解密时, 必须将初始向量 IV 密钥都转换成字节数组 3DES 密文的转码要求 : 在加密后, 需将密文做 Base64String 处理后, 再通过接口进行传送 ; 在解密前, 需将待解密密文通过 Base64 反解成字节数组, 再进行 3DES 解密

14 第二部分数字签名及加解密接口 1. 范围本接口适用于电子交易系统在进行招 / 投标文件制作投标文件的解密电子交易系统关键数据的数字签名及加解密时调用接口包括 JavaScript 脚本接口交易系统的服务器端的接口, 客户端控件接口电子交易系统根据系统架构及功能模块, 选择适用的接口进行对接 2. 接口列表接口类别接口功能备注页面脚本接口 GetCert 页面端代码, 根据证书标签和证书类型读取客户端用户证书 GetCertInfo 页面端代码, 解析证书信息, 并以 XML 格式证书信息 SignData VerifySignData 服务器端接口 VerifySignData VerifySignFile DESDecryptFile 对输入数据进行数字签名对输入数据进行数字签名的验证对输入数据进行数字签名的验证对已经签名的招 / 投文件进行验签对已经加密的投文件进行解密客户端接口 GetCert 根据证书标签和证书类型读取客户端用户证书 GetCertInfo 解析证书信息, 并以 XML 格式证书信息 SignData VerifySignData SignFile 对输入数据进行数字签名对输入数据进行数字签名的验证对输入招 / 投文件进行数字签名

15 VerifySignFile EncryptFile DecryptFile 对已经签名的招 / 投标文件进行验签对投标文件进行加密对已加密投标文件进行解密 3. 接口协议 3.1 JavaScript GetCert 根据证书标签和证书类型读取客户端用户证书 GetCert(certType); certtype: 证书类型签名证书加密证书无返回编码后的证书信息 GetCertInfo 解析证书信息, 并以 XML 字符串格式返回 GetCertInfo(i_inCert); i_incert: 待解析的证书, 已编码无

16 返回采用 XML 标准结构的证书信息 [ 举例 ] <certinfo> <version>3</version> <serialnum> </serialnum> <algorithm>sha1rsa</algorithm> <issuer> <dn_c>cn</dn_c> <dn_s>shanghai</dn_s> <dn_l>zhangjiang</dn_l> <dn_o>shanghai wellhope E-Bussiness Certificate Authority</dn_o> <dn_ou>wellhope</dn_ou> <dn_cn> 自然人 CA</dn_cn> </issuer> <validity> <notbefore>2003 年 08 月 21 日 </notbefore> <notafter>2004 年 08 月 21 日 </notafter> </validity> <subject> <dn_c>cn</dn_c> <dn_s>shanghai</dn_s> <dn_l>zhangjiang</dn_l> <dn_o>wellhope</dn_o> <dn_ou>infosec</dn_ou> <dn_cn>user5</dn_cn> </subject> <publickey> f34d52b7fb481752a506905e5b8a dc 3104fc8f7d c6087dee594225d4ba1946dfad d3501e59fc9 cbd86b50c79b2ce09630fed b54c37ae c1434f9f4a15e3a1 5e9b09997b03af16c7465f816bfe2b1a49821a0090e283f82ebf2ed7daa2e a5ada469a14e78108dde58ac13b826fb </publickey> </certinfo>

17 3.1.3 SignData 对输入数据进行数字签名 SignData(i_inData); i_indata: 输入的待签名数据无输出的已编码的签名数据 VerifySignData 对输入数据进行数字签名的验证 VerifySignData(i_clearTexti_signature, i_checkcert); i_checkcert: 验证所用的证书 i_cleartext: 签名的原文 i_signature: 待验证的签名数据无 0: 成功其他 : 失败 3.2 服务器端接口 VerifySignData 对输入数据进行数字签名的验证 int VerifySignData( String i_cleartext,

18 String i_signature, String i_checkcert); i_checkcert : 验证所用的证书 i_cleartext : 签名的原文 i_signature : 待验证的签名数据无 0: 成功其他 : 失败 VerifySignFile 招投标文件文件验签 String VerifySignFile( String bstinputfilepath, String bstoutputfilepath, String bstcertdn); bstinputfilepath 签名文件路径 bstoutputfilepath 输出文件路径验证成功则返回每个证书中的证书序列号, 格式如下 : 证书序列号 1$$$ 证书序列号 2$$$ 证书序列号 : 成功其他 : 失败 DecryptFile 投标文件文件解密 longdecryptfile(string pcinfile, string puoutfile, string puckey);

19 pcinfile 密文路径 puoutfile 输出路径 bstenckey 对称密钥无 0: 成功其他 : 失败 3.3 客户端接口 GetCert 根据证书标签和证书类型读取客户端用户证书 STRING GetCert(int certtype); certtype: 证书类型签名证书加密证书无返回编码后的证书信息 3.3.2GetCertInfo 解析证书信息, 并以 XML 字符串格式返回 STRING GetCertInfo(STRING i_incert); i_incert: 待解析的证书, 已编码无

20 返回采用 XML 标准结构的证书信息 [ 举例 ] <certinfo> <version>3</version> <serialnum> </serialnum> <algorithm>sha1rsa</algorithm> <issuer> <dn_c>cn</dn_c> <dn_s>shanghai</dn_s> <dn_l>zhangjiang</dn_l> <dn_o>shanghai wellhope E-Bussiness Certificate Authority</dn_o> <dn_ou>wellhope</dn_ou> <dn_cn> 自然人 CA</dn_cn> </issuer> <validity> <notbefore>2003 年 08 月 21 日 </notbefore> <notafter>2004 年 08 月 21 日 </notafter> </validity> <subject> <dn_c>cn</dn_c> <dn_s>shanghai</dn_s> <dn_l>zhangjiang</dn_l> <dn_o>wellhope</dn_o> <dn_ou>infosec</dn_ou> <dn_cn>user5</dn_cn> </subject> <publickey> f34d52b7fb481752a506905e5b8a dc 3104fc8f7d c6087dee594225d4ba1946dfad d3501e59fc9 cbd86b50c79b2ce09630fed b54c37ae c1434f9f4a15e3a1 5e9b09997b03af16c7465f816bfe2b1a49821a0090e283f82ebf2ed7daa2e a5ada469a14e78108dde58ac13b826fb </publickey> </certinfo>

21 3.3.3 SignData 对输入数据进行数字签名 STRING SignData(STRING i_indata); i_indata: 输入的待签名数据无输出的已编码的签名数据 VerifySignData 对输入数据进行数字签名的验证 int VerifySignData( STRING i_cleartext, STRING i_signature, STRING i_checkcert); i_checkcert : 验证所用的证书 i_cleartext : 签名的原文 i_signature : 待验证的签名数据无 0: 成功其他 : 失败 SignFile 对招投标文件进行数字签名 Int SignFile ( STRING bstinputfilepath, STRING bstoutputfilepath);

22 bstinputfilepath 待签名原文路径 bstoutputfilepath 签名文件输出路径无 0: 成功其他 : 失败 VerifySignFile 招投标文件验签 STRING VerifySignFile ( STRING bstinputfilepath, STRING bstoutputfilepath, STRING bstcertdn); bstinputfilepath 签名文件路径 bstoutputfilepath 输出文件路径验证成功则返回每个证书中的证书序列号, 格式如下 : 证书序列号 1$$$ 证书序列号 2$$$ 证书序列号 : 成功其他 : 失败 EncryptFile 投标文件加密 int EncryptFile ( STRING bstinputfilepath, STRING bstoutputfilepath, STRING bstenckey); bstinputfilepath 待加密原文路径

23 bstoutputfilepath 加密后输出路径 bstenckey 已加密的加密密钥,(RSA 或 SM2) 0: 成功其他 : 失败 DecryptFile 投标文件解密 int DecryptFile( STRING bstinputfilepath, STRING bstoutputfilepath, STRING bstenckey, long ret); bstinputfilepath 待解密原文路径 bstoutputfilepath 解密后输出路径 bstenckey 对称密钥 ret=0 成功, 其他失败 0: 成功其他 : 失败 3.4 时间源接口时间源支持标准 NTP/SNTP 网络时间传输协议和 ARP ICMP 协议电子交易系统的服务器 ( 操作系统 ) 选择上述协议进行时间服务配置

获取 Access Token access_token 是接口的全局唯一票据, 接入方调用各接口时都需使用 access_token 开发者需要进行妥善保存 access_token 的存储至少要保留 512 个字符空间 access_token 的有效期目前为 2 个小时, 需定时刷新, 重复

获取 Access Token access_token 是接口的全局唯一票据, 接入方调用各接口时都需使用 access_token 开发者需要进行妥善保存 access_token 的存储至少要保留 512 个字符空间 access_token 的有效期目前为 2 个小时, 需定时刷新, 重复获取将导致上次获取的 access_token 失效接入方可以使用 AppID 和 AppSecret