SS628100+用户需求+中国电信100型控件V1003.docx
《SS628100+用户需求+中国电信100型控件V1003.docx》由会员分享，可在线阅读，更多相关《SS628100+用户需求+中国电信100型控件V1003.docx（35页珍藏版）》请在冰豆网上搜索。
SS628100+用户需求+中国电信100型控件V1003
中国电信CRM系统
身份证阅读器接入规范
版本：
V2.2
日期:
2016-05-19
综述
适用范围
本方案用于规范身份证阅读器接入中国电信CRM系统。
解释权
本方案的解释权属于中国电信集团公司。
版权
本方案的版权属于中国电信集团公司。
修订历史
日期
修订号
描述
著者
2015-03-24
0.1
新建
谢基锋
2015-03-25
0.2
修改增加蓝牙技术要求和开发包规范
谢基锋
2015-04-02
0.3
修改增加蓝牙加密传输流程
谢基锋
2015-04-15
0.4
修改浏览器控件方法属性定义
谢基锋
2015-04-22
0.5
修改删除了设备配置要求
史萌
2015-04-24
0.6
修改蓝牙传输加密流程，删除密钥在APP和设备间传输的流程，改为批量导入后台数据库
谢基锋
2015-04-29
0.7
修改蓝牙开发包提供的API规范
谢基锋
2015-05-04
0.8
修改蓝牙传输加密密钥长度16字节
谢基锋
2015-05-05
1.0
修改增加蓝牙设备名和SDK包名规范
谢基锋
2015-05-06
1.1
修改增加要求支持Firefox浏览器
谢基锋
2015-05-07
1.2
完善蓝牙传输的加密技术规范
谢基锋
2015-05-12
1.3
增加统一字符编码方式
谢基锋
2015-06-25
1.4
修改Firefox命名要求，去除扫描蓝牙接口要求，修改iOS蓝牙连接参数CBPeripheral
谢基锋
2015-06-27
1.5
修改iOS蓝牙调用类名称定义确保厂家类名称唯一性，修改蓝牙连接方法定义
谢基锋
2015-11-20
1.6
修改读取身份证内容，增加照片字段
陈华荣
2015-12-01
1.7
修改蓝牙证件图片格式为JPG
谢基锋
2015-12-03
1.8
增加USB证件图片建议值，明确蓝牙图片转码
陈华荣
2016-02-26
1.9
为兼容云实名制认证增加读取身份证的时候传入业务参数，包含USB和蓝牙接入的身份证读取协议的变更
谢基锋
2016-03-04
2.0
调整了身份证阅读器分体机的规范，增加：
2.3.5、3.5、3.6.2、4、3.2.1-云识别身份证、3.2.2-云识别身份证等篇幅，修改：
2.3.1-回参增加isCloud
谢基锋
2016-05-17
2.1
增加了对USB读取的身份证内容做签名和获取浏览器控件版本号的接口
谢基锋
2016-05-19
2.2
修改了获取浏览器控件版本号的接口，支持对不同厂家的一体机控件版本更新；支持给厂家分配不同密钥对USB读取的身份证内容做签名；新增了2.6厂商信息分配表
谢基锋
USB接入
浏览器要求
操作系统：
WindowsXP、Windows7（32位和64位）
支持浏览器：
IE浏览器IE7、IE8、IE9、IE10、IE11
Firefox浏览器
控件规范要求
IE浏览器采用OCX控件，命名规范：
CertReader.ocx
Firefox浏览器采用DLL控件，命名规范：
npCertReader.dll
浏览器网页中能统一使用下面代码来访问控件：
控件方法属性
1.1.1连接身份证阅读器
方法名称
connect
提供者
设备提供方
描述
连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=CertCtl.connect（）;
1、方法入参
无
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回设备连接的结果标识
0：
连接成功
-1：
发生错误
isCloud
?
数值
1
返回是否云读卡
0：
是
1：
否
errorMsg
?
字符
100
错误信息
错误的信息描述
3、示例
{
“resultFlag”:
-1,
“errorMsg”:
”XXXX”
}
1.1.2获取控件版本号
方法名称
getVersion
提供者
设备提供方
描述
获取身份证阅读器的控件版本号
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=CertCtl.getVersion（）;
1、方法入参
无
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回接口调用的结果标识
0：
连接成功
-1：
发生错误
versionSerial
1
字符
10
返回控件版本号
控件版本号，例如1.0
venderId
1
数值
5
厂商标识
厂商标识（见2.6厂商信息分配表）
errorMsg
?
字符
100
错误信息
错误的信息描述
3、示例
{
“resultFlag”:
0,
“versionSerial”:
”1.0”
}
1.1.3断开设备连接
方法名称
disconnect
提供者
设备提供方
描述
断开连接身份证阅读器，由CRM客户端发起连接，设备端返回连接断开成功与否
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=CertCtl.disconnect（）;
1、方法入参
无
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回结果标识
0：
成功断开连接
-1：
发生错误
errorMsg
?
字符
100
错误信息
错误的信息描述
3、示例
{
“resultFlag”:
-1,
“errorMsg”:
”XXXX”
}
1.1.4获取设备的连接状态
方法名称
getStatus
提供者
设备提供方
描述
连接身份证阅读器，由CRM客户端发起连接，设备端返回连接成功与否
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=CertCtl.getStatus（）;
1、方法入参
无
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回结果标识
0：
成功获得连接状态
-1：
发生错误
errorMsg
?
字符
100
错误信息
错误的信息描述
status
?
数值
2
连接状态
0：
正常连接
1：
无连接
3、示例
{
“resultFlag”:
-1,
“errorMsg”:
”XXXX”
}
1.1.5读取身份证内容
方法名称
readCert
提供者
设备提供方
描述
由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=CertCtl.readCert（）;
1、方法入参
无
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回成功或失败的结果标识
0：
成功
-1：
发生错误
errorMsg
?
字符
100
错误信息
错误的信息描述
venderId
1
数值
5
厂商标识
厂商标识（见2.6厂商信息分配表）
signature
?
16进制字符
20字节
对resultContent实体对象属性做数字签名
resultContent实体对象的属性值按照下列表格的顺序拼接成字符串，并在字符串末尾拼接约定的appSecret字段，对最终的字符串做数字签名，签名采用SHA-1算法。
（不同厂商appSecret不同，见2.6厂商信息分配表）
resultContent
?
实体
身份证内容实体对象
身份证内容实体对象，具体参考示例
resultContent实体对象属性描述：
属性名称
约束
类型
长度限制
描述
取值说明
partyName
1
字符
20
姓名
要求中间无空格
gender
1
数值
1
性别
性别，取值为“1”（表示“男”）或“0”（表示“女”）
nation
1
字符
20
民族
民族，汉字即可
bornDay
1
字符
8
出生日期
出生日期，要求格式为:
yyyyMMdd，长度为8
certAddress
1
字符
100
地址
certNumber
1
字符
18
身份证号码
居民身份号码，长度18位
certOrg
1
字符
20
签发机关
签发机关
effDate
1
字符
8
起始有效期
要求格式为:
yyyyMMdd，长度为8
expDate
1
字符
8
终止有效期
要求格式为:
yyyyMMdd，长度为8，如果是长期有效则返回：
长期，中文汉字。
identityPic
1
字符
照片
要求为JPG进行BASE64编码得到的字符串，建议JPG大小不要超过4K
3、示例
{
“resultFlag”:
0,
“signature”:
“6d5cf40f8353a0b7dd03861a3fdabf69af5ddaeb”，
“resultContent”:
{
“partyName”:
”XXX”,
“gender”:
0,
“nation”:
”汉”,
……
}
}
1.1.6云识别身份证内容
方法名称
cloudReadCert
提供者
设备提供方
描述
由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端
返回数据类型
字符串，要求JSON格式
方法使用例子
varjsonStr=
CertCtl.cloudReadCert（appId,timestamp,nonce,businessExt,signature）;
1、方法入参
属性名称
约束
类型
长度限制
描述
取值说明
appId
1
字符
32
应用ID
应用ID对应唯一加密密钥
timestamp
1
字符
32
时间戳
时间戳
nonce
1
字符
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。
signature
1
16进制字符
20字节
签名
将上述参数值按如上顺序排列拼接成字符串最后拼接上appId对应的密钥appSecret得到的字符串，使用SHA-1算法进行签名，appId对应的密钥由云服务端来分配。
2、返回的JSON字符串的属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回读取成功或失败的标识
0：
读取成功
-1：
发生错误
errorMsg
?
字符
100
错误信息
错误的信息描述
resultContent
?
字符
2000
二代身份证内容密文返回
XML格式的字符串（内容不允许包含单引号、双引号、&、<、>等特殊字符）使用3DES加密算法和appId对应的密钥进行加密
resultContent字段内容描述：
XML根节点名称certificate
字段名称
约束
类型
长度限制
描述
取值说明
partyName
1
字符
20
姓名
要求中间无空格
gender
1
数值
1
性别
性别，取值为“1”（表示“男”）或“0”（表示“女”）
nation
1
字符
20
民族
民族，例如：
汉族返回“汉”
bornDay
1
字符
8
出生日期
出生日期，要求格式为:
yyyyMMdd，长度为8
certAddress
1
字符
100
地址
certNumber
1
字符
18
身份证号码
居民身份号码，长度18位
certOrg
1
字符
20
签发机关
签发机关
effDate
1
字符
8
起始有效期
要求格式为:
yyyyMMdd，长度为8
expDate
1
字符
8
终止有效期
要求格式为:
yyyyMMdd，长度为8，如果是长期有效则返回：
长期，中文汉字。
identityPic
1
字符
2048
照片
要求为JPG进行BASE64编码得到的字符串，建议JPG大小不要超过4K
2.2resultContent字段明文样例代码
……
3DES加密技术规范
身份证内容采用3des算法加密。
以appId作为密钥标识，要求工作模式采用CBC/NoPadding模式，设置CBC模式的byte[]keyiv = { 0, 1, 2, 3, 4, 5, 6, 7 },NoPadding模式对需要加密的数据返回的byte[]数组如果长度不足8字节的整数倍，则需要在数组末尾补零。
字符编码统一采用UTF-8编码。
驱动安装要求
要求身份证阅读器厂商提供安装驱动软件，该安装驱动具备如下功能：
1.所有驱动和控件等安装所需文件需打包在一个安装程序中，免驱动的设备需提供控件的安装程序。
2.Windows操作系统的驱动默认安装目录：
C:
\CertReader。
3.安装浏览器的控件及相关所依赖的文件，需符合本文档对各浏览器控件的要求。
4.驱动程序需支持WindowsXP，Windows7（包括32位和64位）操作系统。
浏览器控件需支持IE7、IE8、IE9、IE10、IE11版本浏览器以及Firefox浏览器。
5.安装程序启动运行后能实现自动识别操作系统版本和浏览器版本而进行相应的安装，安装过程信息明确，尽量减少人工交互，并自动注册控件。
6.对于已经安装过时版本控件的系统，要能保证身份证阅读器软件安装后，新控件可以覆盖原控件并生效。
厂商信息分配表
附件《身份证阅读器厂商信息分配表.xlsx》，
接入集团规范的身份证阅读器厂商，后续需要维护此表。
蓝牙接入
蓝牙技术要求
部件
项目
关键指标要求和描述
蓝牙
射频天线
工作频率：
2.4GHz（fc）
蓝牙版本
应同时符合BluetoothV2.1+EDR,BT3.0,BT4.0（BLE）
Beacon
支持苹果IBeacon和安卓4.3Beacon
通信距离
不低于10m
移动系统
苹果系统、安卓系统
设备名规则
要求同个厂商的设备名前缀应统一，且与其他厂商的不同，即确保厂商所有的设备名前缀的唯一性。
双模要求
既支持传统蓝牙SPP协议又要支持蓝牙4.0BLE协议，能自动判断上端蓝牙是传统蓝牙还是BLE蓝牙，以便按不同模式进行连接并向上端应用提供服务接口
3.1.1传统蓝牙要求
通过系统设置绑定蓝牙设备，输入pin绑定编码，实现绑定。
设备方需提供demo开发样例能实现设备绑定的功能，SDK需提供绑定设备，查询绑定设备，检查绑定状态的接口。
3.1.2蓝牙4.0要求
蓝牙连接时上层应用根据uuid判断是否是可信的设备，需要保证设备到上层应用的安全，方案将采用为每个连接上的设备设置数据传输使用的对称加密密钥，防止身份证阅读器设备冒名充当。
数据传输加密传统蓝牙和4.0都需要支持。
开发包技术要求
3.2.1移动系统开发包--安卓
包名规范定义：
com.公司名.XXX
蓝牙调用类名称定义：
BtReaderClient
初始化:
BtReaderClientmClient=newBtReaderClient（this）;
mClient.setCallBack（mCallback）;
//设置蓝牙连接状态回调，在回调接口onBtState中显示蓝牙连接的状态
回调接口名定义：
IClientCallBack
要求接口必须提供onBtState方法：
voidonBtState（final boolean is_connect）;
BtReaderClient类提供的方法定义：
Ø连接蓝牙
BooleanconnectBt（Stringbt_mac）;
Ø设置蓝牙连接状态回调的接口
voidsetCallBack（IClientCallBackmCallback）;
Ø断开蓝牙
BooleandisconnectBt（）;
Ø加密传输身份证内容
传入参数和返回结果详见<<接口协议>>章节。
1、读取身份证
MapreadCert（）;
2、云识别身份证
MapcloudReadCert（StringappId,Stringtimestamp,Stringnonce,StringbusinessExt,Stringsignature）;
3.2.2移动系统开发包--iOS
文件名规范定义：
以公司名为前缀，确保唯一性
蓝牙调用类名称定义：
公司名+BleTool，确保类名称唯一，各厂家不产生冲突
初始化调用:
BleToolbletool=[[BleToolalloc]init:
（id）myself];
//初始化并设置回调委托
委托名定义：
BR_Callback，委托需定义如下方法：
-（void）BR_connectResult:
（BOOL）isconnected;
//调用方需实现委托定义的如上方法（用于蓝牙设备连接状态变更的通知，注意，先返回监听再返回connectBt函数）
BleTool类提供的方法和属性定义：
Ø连接蓝牙
-（bool）connectBt:
（CBPeripheral*）bt usingCBManager:
（CBCentralManager*）cbmanager;
//连接蓝牙设备对象
Ø断开蓝牙
-（bool）disconnectBt;
Ø加密传输身份证内容
传入参数和返回结果详见<<接口协议>>章节
1、读取身份证
-（NSDictionary*）readCert;
2、云识别身份证
-（NSDictionary*）cloudReadCert:
（NSString*）appId（NSString*）timestamp（NSString*）nonce（NSString*）businessExt（NSString*）signature;
注意：
SDK不要包含CoreBluetooth.framework包
蓝牙传输流程图
图一、APP-身份证阅读器数据加密传输流程图
蓝牙传输加密技术规范
根据上面流程图的描述采用3des算法加密，预先批量导入设备的出厂密钥到后台数据库，一体机以设备厂商名作为密钥标识，分体机以appId作为密钥标识。
要求工作模式采用CBC/NoPadding模式，设置CBC模式的byte[]keyiv = { 0, 1, 2, 3, 4, 5, 6, 7 },NoPadding模式对需要加密的数据返回的byte[]数组如果长度不足8字节的整数倍，则需要在数组末尾补零。
字符编码统一采用UTF-8编码。
蓝牙扫描设备命名规范
一体机命名规范：
以厂家名称字母缩写作为前缀+设备型号；
例如，SS8000。
分体机命名规范：
以“X-”作为前缀+厂家名称字母缩写+设备型号；
例如，X-SS8000。
接口协议
1.1.7读取身份证内容
名称
readCert
提供者
设备提供方
描述
读取身份证接口，由CRM客户端调用，阅读器读取身份证内容返回给CRM客户端。
参数格式
要求SDK提供的方法返回的对象由键值对组成，例如JAVA的Map对象
加密说明
3DES加密算法，密钥长度为16字节，以十六进制字符组成，密钥模式采用K1K2K1方式。
要求阅读器出厂内置加密密钥，CRM预先导入批次设备的密钥到后台数据库，以设备mac（字母大写）作为标识关联。
要求设备厂商提供的密钥数据的字段统一定义为：
mac、key。
设备需支持出厂密钥的手动更改，更改后提供新的密钥数据给CRM更新到后台库。
样例如下：
mac=BC:
14:
EF:
28:
28:
D3
key=12ab34cdabcd1234abcd123456efabcd
字符编码
统一采用UTF-8编码
1、接口入参
空
2、返回的对象属性定义
属性名称
约束
类型
长度限制
描述
取值说明
resultFlag
1
数值
1
返回读取成功或失败的标识
0：
读取成功
-1：
发生错误
errorMsg
?
字符
100
错误信息
错误的信息描述
mac
?
字符
48
设备mac地址
resultContent
?
字符
2000
二代身份证内容密文返回
XML格式的字符串（内容不允许包含单引号、双引号、&、<、>等特殊字符）经规范要求的加密算法进行加密后的字符串
resultContent字段描述：
XML根节点名称certificate
字段名称
约束
类型
长度限制
描述
取值说明
partyName
1
字符
20
姓名
要求中间无空格
gender
1
数值
1
性别
性别，取值为“1”（表示“男”）或“0”（表示“女”）
nation
1
字符
20
民族
民族，例如：
汉族返回“汉”
bornDay
1
字符
8
出生日期
出生日期，要求格式为:
yyyyMMdd，长度为8
certAddress
1
字符
100
地址
certN
升级会员 