SS628(100)+用户需求+中国电信100型控件-V1.0.0.3.doc

中国电信CRM系统身份证阅读器接入规范版本：V2.2日期: 2016-05-191 综述1.1 适用范围本方案用于规范身份证阅读器接入中国电信CRM系统。1.2 解释权本方案的解释权属于中国电信集团公司。1.3 版权本方案的版权属于中国电信集团公司。1.4 修订历史日期修订号描述著者2015-03-240.1新建谢基锋2015-03-250.2修改增加蓝牙技术要求和开发包规范谢基锋2015-04-020.3修改增加蓝牙加密传输流程谢基锋2015-04-150.4修改浏览器控件方法属性定义谢基锋2015-04-220.5修改删除了设备配置要求史萌2015-04-240.6修改蓝牙传输加密流程，删除密钥在APP和设备间传输的流程，改为批量导入后台数据库谢基锋2015-04-290.7修改蓝牙开发包提供的API规范谢基锋2015-05-040.8修改蓝牙传输加密密钥长度16字节谢基锋2015-05-051.0修改增加蓝牙设备名和SDK包名规范谢基锋2015-05-061.1修改增加要求支持Firefox浏览器谢基锋2015-05-071.2完善蓝牙传输的加密技术规范谢基锋2015-05-121.3增加统一字符编码方式谢基锋2015-06-251.4修改Firefox命名要求，去除扫描蓝牙接口要求，修改iOS蓝牙连接参数CBPeripheral谢基锋2015-06-271.5修改iOS蓝牙调用类名称定义确保厂家类名称唯一性，修改蓝牙连接方法定义谢基锋2015-11-201.6修改读取身份证内容，增加照片字段陈华荣2015-12-011.7修改蓝牙证件图片格式为JPG谢基锋2015-12-031.8增加USB证件图片建议值，明确蓝牙图片转码陈华荣2016-02-261.9为兼容云实名制认证增加读取身份证的时候传入业务参数，包含USB和蓝牙接入的身份证读取协议的变更谢基锋2016-03-042.0调整了身份证阅读器分体机的规范，增加：2.3.5、3.5、3.6.2、4、3.2.1-云识别身份证、3.2.2-云识别身份证等篇幅，修改：2.3.1-回参增加isCloud谢基锋2016-05-172.1增加了对USB读取的身份证内容做签名和获取浏览器控件版本号的接口谢基锋2016-05-192.2修改了获取浏览器控件版本号的接口，支持对不同厂家的一体机控件版本更新；支持给厂家分配不同密钥对USB读取的身份证内容做签名；新增了2.6厂商信息分配表谢基锋2 USB接入2.1 浏览器要求操作系统：Windows XP、Windows7（32位和64位）支持浏览器：IE浏览器IE7、IE8、IE9、IE10、IE11Firefox浏览器2.2 控件规范要求IE浏览器采用OCX控件，命名规范：CertReader.ocxFirefox浏览器采用DLL控件，命名规范：npCertReader.dll浏览器网页中能统一使用下面代码来访问控件：2.3 控件方法属性2.3.1 连接身份证阅读器方法名称connect提供者设备提供方描述连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否返回数据类型字符串，要求JSON格式方法使用例子var jsonStr = CertCtl.connect();1、 方法入参无2、 返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回设备连接的结果标识0：连接成功-1：发生错误isCloud?数值1返回是否云读卡0：是1：否errorMsg?字符100错误信息错误的信息描述3、 示例“resultFlag”:-1,“errorMsg”:”XXXX”2.3.2 获取控件版本号方法名称getVersion提供者设备提供方描述获取身份证阅读器的控件版本号返回数据类型字符串，要求JSON格式方法使用例子var jsonStr = CertCtl.getVersion();1、方法入参无2、返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回接口调用的结果标识0：连接成功-1：发生错误versionSerial1字符10返回控件版本号控件版本号，例如1.0venderId1数值5厂商标识厂商标识（见2.6厂商信息分配表）errorMsg?字符100错误信息错误的信息描述3、示例“resultFlag”:0,“versionSerial”:”1.0”2.3.3 断开设备连接方法名称disconnect提供者设备提供方描述断开连接身份证阅读器，由CRM客户端发起连接，设备端返回连接断开成功与否返回数据类型字符串，要求JSON格式方法使用例子var jsonStr = CertCtl.disconnect();1、 方法入参无2、 返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回结果标识0：成功断开连接-1：发生错误errorMsg?字符100错误信息错误的信息描述3、 示例“resultFlag”:-1,“errorMsg”:”XXXX”2.3.4 获取设备的连接状态方法名称getStatus提供者设备提供方描述连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否返回数据类型字符串，要求JSON格式方法使用例子var jsonStr = CertCtl.getStatus();1、 方法入参无2、 返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回结果标识0：成功获得连接状态-1：发生错误errorMsg?字符100错误信息错误的信息描述status?数值2连接状态0：正常连接1：无连接3、 示例“resultFlag”:-1,“errorMsg”:”XXXX”2.3.5 读取身份证内容方法名称readCert提供者设备提供方描述由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端返回数据类型字符串，要求JSON格式方法使用例子var jsonStr = CertCtl.readCert();1、 方法入参无2、 返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回成功或失败的结果标识0：成功-1：发生错误errorMsg?字符100错误信息错误的信息描述venderId1数值5厂商标识厂商标识（见2.6厂商信息分配表）signature?16进制字符20字节对resultContent实体对象属性做数字签名resultContent实体对象的属性值按照下列表格的顺序拼接成字符串，并在字符串末尾拼接约定的appSecret字段，对最终的字符串做数字签名，签名采用SHA-1算法。（不同厂商appSecret不同，见2.6厂商信息分配表）resultContent?实体身份证内容实体对象身份证内容实体对象，具体参考示例resultContent实体对象属性描述：属性名称约束类型长度限制描述取值说明partyName1字符20姓名要求中间无空格gender1数值1性别性别，取值为“1”（表示“男”）或“0”（表示“女”）nation1字符20民族民族，汉字即可bornDay1字符8出生日期出生日期，要求格式为: yyyyMMdd，长度为8certAddress1字符100地址certNumber1字符18身份证号码居民身份号码，长度18位certOrg1字符20签发机关签发机关effDate1字符8起始有效期要求格式为: yyyyMMdd，长度为8expDate1字符8终止有效期要求格式为:yyyyMMdd，长度为8，如果是长期有效则返回：长期，中文汉字。identityPic1字符照片要求为JPG进行BASE64编码得到的字符串，建议JPG大小不要超过4K3、 示例“resultFlag”:0,“signature”:“6d5cf40f8353a0b7dd03861a3fdabf69af5ddaeb”，“resultContent”:“partyName”:”XXX”,“gender”:0,“nation”:”汉”,2.3.6 云识别身份证内容方法名称cloudReadCert提供者设备提供方描述由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端返回数据类型字符串，要求JSON格式方法使用例子var jsonStr =CertCtl.cloudReadCert(appId,timestamp,nonce,businessExt,signature);1、方法入参属性名称约束类型长度限制描述取值说明appId1字符32应用ID应用ID对应唯一加密密钥timestamp1字符32时间戳时间戳nonce1字符32随机字符串随机字符串businessExt?字符300业务属性，busiSerial：业务流水号；staffCode：受理人工号；channelCode：渠道编码；areaCode：地区编码；teminalType：终端类型；srcSystem：发起方系统编码；osType：操作系统类型；browserModel：浏览器型号；clientIP：客户端IP地址；deviceModel：设备型号；deviceSerial：设备序列号可扩展字段，以JSON（key:value）格式表达，例如：“busiSerial”:”12345”,“staffCode”:”110011”,”channelCode”:”2001”。终端类型取值：PC，IOS，Android。signature116进制字符20字节签名将上述参数值按如上顺序排列拼接成字符串最后拼接上appId对应的密钥appSecret得到的字符串，使用SHA-1算法进行签名，appId对应的密钥由云服务端来分配。2、 返回的JSON字符串的属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回读取成功或失败的标识0：读取成功-1：发生错误errorMsg?字符100错误信息错误的信息描述resultContent?字符2000二代身份证内容密文返回XML格式的字符串（内容不允许包含单引号、双引号、&、等特殊字符）使用3DES加密算法和appId对应的密钥进行加密resultContent字段内容描述：XML根节点名称certificate字段名称约束类型长度限制描述取值说明partyName1字符20姓名要求中间无空格gender1数值1性别性别，取值为“1”（表示“男”）或“0”（表示“女”）nation1字符20民族民族，例如：汉族返回“汉”bornDay1字符8出生日期出生日期，要求格式为: yyyyMMdd，长度为8certAddress1字符100地址certNumber1字符18身份证号码居民身份号码，长度18位certOrg1字符20签发机关签发机关effDate1字符8起始有效期要求格式为: yyyyMMdd，长度为8expDate1字符8终止有效期要求格式为:yyyyMMdd，长度为8，如果是长期有效则返回：长期，中文汉字。identityPic1字符2048照片要求为JPG进行BASE64编码得到的字符串，建议JPG大小不要超过4K2.2 resultContent字段明文样例代码2.4 3DES加密技术规范身份证内容采用3des算法加密。以appId作为密钥标识，要求工作模式采用CBC/NoPadding模式，设置 CBC模式的byte keyiv=0,1,2,3,4,5,6,7,NoPadding模式对需要加密的数据返回的byte数组如果长度不足8字节的整数倍，则需要在数组末尾补零。字符编码统一采用UTF-8编码。2.5 驱动安装要求要求身份证阅读器厂商提供安装驱动软件，该安装驱动具备如下功能：1. 所有驱动和控件等安装所需文件需打包在一个安装程序中，免驱动的设备需提供控件的安装程序。2. Windows操作系统的驱动默认安装目录：C:CertReader。3. 安装浏览器的控件及相关所依赖的文件，需符合本文档对各浏览器控件的要求。4. 驱动程序需支持Windows XP，Windows 7（包括32位和64位）操作系统。浏览器控件需支持IE7、IE8、IE9、IE10、IE11版本浏览器以及Firefox浏览器。5. 安装程序启动运行后能实现自动识别操作系统版本和浏览器版本而进行相应的安装，安装过程信息明确，尽量减少人工交互，并自动注册控件。 6. 对于已经安装过时版本控件的系统，要能保证身份证阅读器软件安装后，新控件可以覆盖原控件并生效。2.6 厂商信息分配表附件身份证阅读器厂商信息分配表.xlsx，接入集团规范的身份证阅读器厂商，后续需要维护此表。3 蓝牙接入3.1 蓝牙技术要求部件项目关键指标要求和描述蓝牙射频天线工作频率：2.4GHz（fc）蓝牙版本应同时符合BluetoothV2.1+EDR,BT3.0,BT4.0(BLE)Beacon支持苹果IBeacon和安卓4.3 Beacon通信距离不低于10m移动系统苹果系统、安卓系统设备名规则要求同个厂商的设备名前缀应统一，且与其他厂商的不同，即确保厂商所有的设备名前缀的唯一性。双模要求既支持传统蓝牙SPP协议又要支持蓝牙4.0 BLE协议，能自动判断上端蓝牙是传统蓝牙还是BLE蓝牙，以便按不同模式进行连接并向上端应用提供服务接口3.1.1 传统蓝牙要求通过系统设置绑定蓝牙设备，输入pin绑定编码，实现绑定。设备方需提供demo开发样例能实现设备绑定的功能，SDK需提供绑定设备，查询绑定设备，检查绑定状态的接口。3.1.2 蓝牙4.0要求蓝牙连接时上层应用根据uuid判断是否是可信的设备，需要保证设备到上层应用的安全，方案将采用为每个连接上的设备设置数据传输使用的对称加密密钥，防止身份证阅读器设备冒名充当。数据传输加密传统蓝牙和4.0都需要支持。3.2 开发包技术要求3.2.1移动系统开发包-安卓包名规范定义：com.公司名.XXX蓝牙调用类名称定义：BtReaderClient初始化: BtReaderClient mClient = new BtReaderClient(this); mClient.setCallBack(mCallback);/设置蓝牙连接状态回调，在回调接口onBtState 中显示蓝牙连接的状态回调接口名定义：IClientCallBack要求接口必须提供onBtState方法：void onBtState(finalbooleanis_connect);BtReaderClient类提供的方法定义： 连接蓝牙Boolean connectBt(String bt_mac); 设置蓝牙连接状态回调的接口void setCallBack(IClientCallBack mCallback); 断开蓝牙Boolean disconnectBt(); 加密传输身份证内容传入参数和返回结果详见章节。1、读取身份证Map readCert();2、 云识别身份证Map cloudReadCert(String appId,String timestamp,String nonce,String businessExt,String signature);3.2.2移动系统开发包-iOS文件名规范定义：以公司名为前缀，确保唯一性蓝牙调用类名称定义：公司名+BleTool，确保类名称唯一，各厂家不产生冲突初始化调用: BleTool bletool=BleTool allocinit:(id)myself;/ 初始化并设置回调委托委托名定义：BR_Callback，委托需定义如下方法：-(void)BR_connectResult:(BOOL)isconnected;/调用方需实现委托定义的如上方法（用于蓝牙设备连接状态变更的通知，注意，先返回监听再返回connectBt函数）BleTool类提供的方法和属性定义： 连接蓝牙-(bool)connectBt:(CBPeripheral*)btusingCBManager:(CBCentralManager*)cbmanager;/连接蓝牙设备对象 断开蓝牙-(bool)disconnectBt; 加密传输身份证内容传入参数和返回结果详见章节1、读取身份证-(NSDictionary*)readCert;2、云识别身份证-(NSDictionary*)cloudReadCert:(NSString*)appId (NSString*)timestamp (NSString*)nonce (NSString*)businessExt (NSString*)signature;注意：SDK不要包含CoreBluetooth.framework包3.3 蓝牙传输流程图图一、APP-身份证阅读器数据加密传输流程图3.4 蓝牙传输加密技术规范根据上面流程图的描述采用3des算法加密，预先批量导入设备的出厂密钥到后台数据库，一体机以设备厂商名作为密钥标识，分体机以appId作为密钥标识。要求工作模式采用CBC/NoPadding模式，设置 CBC模式的byte keyiv=0,1,2,3,4,5,6,7,NoPadding模式对需要加密的数据返回的byte数组如果长度不足8字节的整数倍，则需要在数组末尾补零。字符编码统一采用UTF-8编码。3.5 蓝牙扫描设备命名规范一体机命名规范：以厂家名称字母缩写作为前缀+设备型号；例如，SS8000。分体机命名规范：以“X-”作为前缀+厂家名称字母缩写+设备型号；例如，X-SS8000。3.6 接口协议3.6.1 读取身份证内容名称readCert提供者设备提供方描述读取身份证接口，由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端。参数格式要求SDK提供的方法返回的对象由键值对组成，例如JAVA的Map对象加密说明3DES加密算法，密钥长度为16字节，以十六进制字符组成，密钥模式采用K1K2K1方式。要求阅读器出厂内置加密密钥，CRM预先导入批次设备的密钥到后台数据库，以设备mac（字母大写）作为标识关联。要求设备厂商提供的密钥数据的字段统一定义为：mac、key。设备需支持出厂密钥的手动更改，更改后提供新的密钥数据给CRM更新到后台库。样例如下：mac=BC:14:EF:28:28:D3key=12ab34cdabcd1234abcd123456efabcd字符编码统一采用UTF-8编码1、 接口入参空2、返回的对象属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回读取成功或失败的标识0：读取成功-1：发生错误errorMsg?字符100错误信息错误的信息描述mac?字符48设备mac地址resultContent?字符2000二代身份证内容密文返回XML格式的字符串（内容不允许包含单引号、双引号、&、等特殊字符）经规范要求的加密算法进行加密后的字符串resultContent字段描述：XML根节点名称certificate字段名称约束类型长度限制描述取值说明partyName1字符20姓名要求中间无空格gender1数值1性别性别，取值为“1”（表示“男”）或“0”（表示“女”）nation1字符20民族民族，例如：汉族返回“汉”bornDay1字符8出生日期出生日期，要求格式为: yyyyMMdd，长度为8certAddress1字符100地址certNumber1字符18身份证号码居民身份号码，长度18位certOrg1字符20签发机关签发机关effDate1字符8起始有效期要求格式为: yyyyMMdd，长度为8expDate1字符8终止有效期要求格式为:yyyyMMdd，长度为8，如果是长期有效则返回：长期，中文汉字。identityPic1字符2048照片要求为wlt进行BASE64编码得到的字符2.2 明文样例代码3.6.2 云识别身份证内容名称cloudReadCert提供者设备提供方描述读取身份证接口，由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端。参数格式要求SDK提供的方法返回的对象由键值对组成，例如JAVA的Map对象身份证内容加密说明3DES加密算法，密钥长度为16字节，以十六进制字符组成，密钥模式采用K1K2K1方式。实名制云平台和CRM系统双方以约定好的密钥对身份证内容进行加解密，实名制云平台加密，CRM解密。并且支持密钥的同步更新。样例如下：appId=10001key=12ab34cdabcd1234abcd123456efabcd字符编码统一采用UTF-8编码1、接口入参属性名称约束类型长度限制描述取值说明appId1字符32应用ID应用ID对应唯一加密密钥timestamp1字符32时间戳时间戳nonce1字符32随机字符串随机字符串businessExt?字符300业务属性，busiSerial：业务流水号；staffCode：受理人工号；channelCode：渠道编码；areaCode：地区编码；teminalType：终端类型；srcSystem：发起方系统编码；osType：操作系统类型；browserModel：浏览器型号；clientIP：客户端IP地址；deviceModel：设备型号；deviceSerial：设备序列号可扩展字段，以JSON（key:value）格式表达，例如：“busiSerial”:”12345”,“staffCode”:”110011”,”channelCode”:”2001”。终端类型取值：PC，IOS，Android。signature1字符160签名将上述参数按字典排序后生成字符串，使用SHA-1加密算法和appId对应的加密密钥（appSecret）进行加密签名2、返回的对象属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回读取成功或失败的标识0：读取成功-1：发生错误errorMsg?字符100错误信息错误的信息描述resultContent?字符2000二代身份证内容密文返回XML格式的字符串（内容不允许包含单引号、双引号、&、等特殊字符）使用3DES加密算法和appId对应的密钥进行加密resultContent字段内容描述：XML根节点名称certificate字段名称约束类型长度限制描述取值说明partyName1字符20姓名要求中间无空格gender1数值1性别性别，取值为“1”（表示“男”）或“0”（表示“女”）nation1字符20民族民族，例如：汉族返回“汉”bornDay1字符8出生日期出生日期，要求格式为: yyyyMMdd，长度为8certAddress1字符100地址certNumber1字符18身份证号码居民身份号码，长度18位certOrg1字符20签发机关签发机关effDate1字符8起始有效期要求格式为: yyyyMMdd，长度为8expDate1字符8终止有效期要求格式为:yyyyMMdd，长度为8，如果是长期有效则返回：长期，中文汉字。identityPic1字符2048照片要求为JPG进行BASE64编码得到的字符串，建议JPG大小不要超过4K2.2 resultContent字段明文样例代码4 移动端OTG/NFC接入-分体机4.1 接口协议4.1.1 连接身份证阅读器方法名称connect提供者设备提供方描述连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否1、方法入参属性名称约束类型长度限制描述取值说明connectWay1数值1连接方式1：OTG连接2：NFC读卡2、返回的对象属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回设备连接的结果标识0：连接成功-1：发生错误errorMsg?字符100错误信息错误的信息描述3、示例“resultFlag”:-1,“errorMsg”:”XXXX”4.1.2 断开设备连接方法名称disconnect提供者设备提供方描述断开连接身份证阅读器，由CRM客户端发起连接，设备端返回连接断开成功与否1、方法入参无2、返回的对象属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回结果标识0：成功断开连接-1：发生错误errorMsg?字符100错误信息错误的信息描述3、示例“resultFlag”:-1,“errorMsg”:”XXXX”4.1.3 获取设备的连接状态方法名称getStatus提供者设备提供方描述连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否1、方法入参无2、返回的对象属性定义属性名称约束类型长度限制描述取值说明resultFlag1数值1返回结果标识0：成功获得连接状态-1：发生错误errorMsg?字符100错误信息错误的信息描述status?数值2连接状态0：正常连接1：无连接3、示例“resultFlag”:-1,“errorMsg”:”XXXX”4.1.4 云识别身份证内容方法名称cloudReadCert提供者设备提供方描述由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端1、接口入参属性名称约束类型长度限制描述取值说明appId1字符32应用ID应用ID对应唯一加密密钥timestamp1字符32时间戳时间戳nonce1字符32随机字符串随机字符串businessExt?字符300业务属性，busiSerial：业务流水号；staffCode：受理人工号；channelCode：渠道编码；areaCode：地区编码；teminalType：终端类型；sr