T/HBDIA 001-2024 黑龙江省社会保障卡应用服务接口规范

前 言
本文件按照GB/T 1.1-2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起
草。
请注意本文件的某些内容可能涉及专利，本文件的发布机构不承担识别专利的责任。
本标准由黑龙江省人力资源和社会保障信息中心提出。
本标准由黑龙江省大数据产业协归口。
本标准起草单位：黑龙江省大数据产业协会、黑龙江省人力资源和社会保障信息中心、哈尔滨卓瑞
世纪科技发展有限责任公司。
本标准主要起草人：闫瑞、王鑫、朱巍、李璐昆、李宇环、回春阳、刘宇新、李文才、刘婷婷。
T/HBDIA 001-2024
1
黑龙江省社会保障卡应用服务接口规范
1 范围
本文件规定了黑龙江省社会保障卡读写终端与业务系统及其客户端的接口的交互流程、接口服务、
关键问题说明。
本文件适用于黑龙江省社会保障卡读写终端与业务系统及其客户端在信息化系统开发、应用的标准
化工作。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的应用文件，
仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本
文件。
GB/T 11456 信息技术软件工程术语
LB 002 社会保障（个人）卡规范
LD/T 32.6 社会保障卡规范第6部分应用数据结构
3 术语和定义
下列术语和定义适用于本文件。
3.1
社会保障卡
中华人民共和国社会保障卡由国务院人力资源社会保障行政部门统一规划，各级人力资源社会保障
部门联合合作商业银行面向社会公众发行，是持卡人享受人力资源社会保障权益及政府其他公共服务权
益的服务载体。
3.2
电子社会保障卡
社会保障卡的线上形态，是社会保障卡电子证照的具体表现形式，与实体社会保障卡一一对应、功
能相通。
4 接口交互流程
接口交互流程如图1所示：
T/HBDIA 001-2024
2
图1 接口交互流程图
5 接口服务
5.1 读写卡配置
5.1.1 功能说明
功能包括：
a) 功能描述：适配读卡器，在列表中选定读卡器品牌；
b) 功能细节：在选定读卡器品牌后，会根据选定品牌提供相应适配读卡器的动态库文件。
5.1.2 操作流程
操作包括：
a) 登陆读卡器配置管理器，选定读卡器设备，保存配置，后登陆读卡器测试工具进行测试；
b) 经适配调试，目前满足黑龙江省读卡器应用设备含：华大、德卡、德生、明泰、天梦者、首云、
华旭多版本。
5.2 读卡模块
5.2.1 功能说明
功能包括：
a) 功能描述：读卡，读基本信息函数；
b) 功能细节：读卡功能可以实现读取社会保障卡的基本信息项，并将正确内容进行返回。
T/HBDIA 001-2024
3
5.2.2 操作流程
操作包括：
a) 读取人员基本信息函数(类型，网点编号)；
b) 正确时返回：0，发卡地区行政区划代码（卡识别码前6位）|社会保障号码|卡号|卡识别码|
姓名|卡复位信息（仅取历史字节）|规范版本|发卡日期|卡有效期|终端机编号|终端设备号|。
5.3 写卡模块
5.3.1 功能说明
功能包括：
a) 功能描述：写卡，写卡函数；
b) 功能细节：写卡功能可以实现将参保人的基本信息项写入到社会保障卡内并进行读取。
5.3.2 操作流程
写卡(图片路径或Base64码)网点编号，卡号，社会保障号码(身份证号)，姓名，性别，民族，出生
日期，个人编号，发卡日期，卡有效期，图片路径或Base64码。
5.4 密码修改、重置、校验、解锁
5.4.1 功能说明
功能包括：
a) 功能描述：修改、重置、校验、解锁社会保障卡密码；
b) 功能细节：调用相应函数对社会保障卡进行密码操作、修改密码、校验密码、解锁密码为同级、
重置密码需要更高级别权限、此过程均与社会保障卡芯片进行交互，全程密码不落地，保证密码安全。
5.4.2 操作流程
操作包括：
a) 修改卡内PIN码(类型，原密码|新密码，网点编号)，正确时返回：0；
b) 重置卡内PIN码(类型，密码|密码，网点编号)，正确时返回：0；
c) 校验卡内PIN码(类型，密码|密码，网点编号)，正确时返回：0；
d) 解锁卡内PIN码(类型，网点编号)，正确时返回：0。
5.5 密码键盘
5.5.1 功能说明
功能包括：
a) 功能描述：操作密码键盘；
b) 功能细节：输入密码、显示按键、加密传输、验证密码、错误重试、安全擦除。
5.5.2 操作流程
操作包括：
a) 将密码键盘通过USB接口连接至电脑或移动设备；
b) 在密码键盘上输入密码，使用数字键进行输入；
c) 在输入完成后，按下密码键盘上的确认键或提交键，以提交输入的密码；
T/HBDIA 001-2024
4
d) 输入密码正确，系统将进入下一级操作界面或完成操作。输入密码不正确，系统提示重新输入
密码或进行其他操作。
5.6 高拍仪模块
5.6.1 功能说明
功能包括：
a) 功能描述：拍人像，拍凹槽；
b) 功能细节：利用高拍仪上置摄像头、下置摄像头，完成拍摄工作。
5.6.2 操作流程
操作包括：
a) 全景拍摄相片，返回拍摄到的全景相片Base64格式，正确0表示成功；非0表示失败；
b) 凹槽区域拍摄相片，返回拍摄到的全景相片Base64格式，正确0表示成功；非0表示失败；
c) 人像拍摄相片（针对具有人像拍摄功能高拍仪），返回拍摄到的全景相片Base64格式，正确0
表示成功；非0表示失败。
5.7 复位信息和卡版本读取
5.7.1 功能说明
功能包括：
a) 功能描述：读取社会保障卡复位信息；
b) 功能细节：读取社会保障卡复位信息(26位)及社会保障卡的规划版本号。
5.7.2 操作流程
操作包括：
a) 读取复位信息函数；
b) 正确返回：复位信息|识别码|卡规范版本|。
5.8 终端唯一识别码获取
5.8.1 功能说明
功能包括：
a) 功能描述：终端唯一识别码；
b) 功能细节：可以获取到当前连接读卡器的终端设备号(20位)+PSAM卡终端机编号(12位)。
5.8.2 操作流程
操作包括：
a) 读取终端唯一识别码函数；
b) 正确返回：终端设备号|PSAM卡终端机编号|。
5.9 卡识别码与卡号的获取
5.9.1 卡识别码与卡号的获取
功能包括：
T/HBDIA 001-2024
5
a) 功能描述：读卡识别码与卡号；
b) 功能细节：可以获取到社会保障卡的卡识别码（32位）与卡号（9位）。
5.9.2 操作流程
操作包括：
a) 读卡识别码和卡号函数；
b) 正确返回：识别码|卡号|。
5.10 身份证模块
5.10.1 功能说明
功能包括：
a) 功能描述：读取身份证信息；
b) 功能细节：可以读取持卡人的姓名、出生日期、性别、国籍、公民身份号码等基本信息。
5.10.2 操作流程
操作包括：
a) 读取身份证信息函数；
b) 正确返回数据格式为：身份证号码|姓名|性别（格式：代码#中文）|民族（格式：代码#中文）
|出生日期|户籍地址|有效期起始日期|有效期截止日期|签发机关|照片（BASE64编码）|；
c) 输出参数：函数执行失败时，该输出参数为错误信息描述。
6 关键问题说明
6.1 算法环境选择
使用“查询”命令通过文件名方式选择社会保障卡社会保障系统环境，同时根据卡片返回的应答信
息确定算法环境，由“9F0C”带出的“86”模板代表算法，“01”为DES算法，“02”为SSF33算法，“03”
为SM4算法；如无此模板，需根据发卡地区行政区划代码（卡识别码前6位）的前2位编码的不同数值进
行选择，如是“11”，则为SSF33算法，否则为DES算法；之后再根据算法环境标识选择相应算法密钥文
件。
6.2 规范版本判断方法
规范版本判断方法包括：
a) 卡内规范版本数据项共4位，格式如1.0x、2.0x、3.0x等。用卡时，只根据前3位进行规范版本
判断。规范版本为“1.0x”、“2.0x”、“3.0x”的社会保障卡，分别简称为1.0卡、2.0卡、3.0卡；
b) 1.0卡的卡内数据文件结构参见《社会保障（个人）卡规范》（LB 002—2000）；
c) 2.0卡的卡内数据文件结构参见《社会保障卡规范第6部分应用数据结构》（LD/T 32.6—2015）；
d) 2.0卡或3.0卡读个人基本信息时需读出“姓名扩展”，与“姓名”拼接后返回完整姓名。3.0
卡的个人基本信息文件增加了读控制密钥“RKSSSE”，读取该文件信息前需进行外部认证。
6.3 密钥分散因子提取方法
提取密钥分散因子的方法如下：根据发卡地区行政区划代码（卡识别码前6位）的前2位编码的不同
数值进行选择，如果是“33”，则将卡识别码的前2个字节展开为4字节的ASCII码（如：3301展开为“33
T/HBDIA 001-2024
6
33 30 31”）后补“30 30 73 78”，形成8个字节的二级分散因子；否则，将卡识别码的前3个字节展
开为6字节的ASCII码（如：650100展开为“36 35 30 31 30 30”），后补“73 78”，形成8个字节的
二级分散因子。
6.4 卡号读取长度
“卡号”标准长度应为9位，读取“卡号”时只读前9位。
6.5 PSAM 卡认证和加密机认证选择
PSAM卡认证是首选模式。当业务系统判断以下五种错误代码后，调用基于加密机的函数接口继续进
行相应操作：
a) 无PSAM卡；
b) PSAM卡算法不支持（即PSAM卡内没有SSF33算法或SM4算法）；
c) PSAM卡内没有RKSSSE密钥（3.0卡读个人基本信息需要RKSSSE密钥外部认证）；
d) PSAM卡内未找到引用数据、未找到密钥；
e) PSAM卡密钥级别不够；
f) 分别返回特定错误代码“-2201”、“-2202”、“-2203”、“-27272”、“-24”（具体参见
附录A）。
6.6 动态库命名
读写终端动态库DLL统一命名为：SSCardDriver.DLL，对应的ActiveX控件版本为：SSCARD，
CLSID=D9532F10-603B-4BF7-87AE-F4130EF43553。
T/HBDIA 001-2024
7
附录A
（资料性）
错误代码
错误代码见表A.1。
表A.1 错误代码
常见错误信息
返回值错误信息描述
-1 卡类型不对
-2 无卡
-3 有卡未上电
-4 卡无应答
-5 加载动态库错
-11 读卡器连接错
-12 未建立连接
-13 （动态库）不支持该命令
-14 （发给动态库的）命令参数错
-15 信息校验和出错
-20 卡识别码或规范版本格式错
-21 内部认证失败（用户卡不合法）
-22 传入数据与卡内不符
-23 传入数据不合法
-24 密钥权限不够
-25 此卡文件结构中无传入的文件名或数据项
-31 用户取消密码输入
-32 密码输入操作超时
-33 输入密码长度错
-34 两次输入密码不一致
-35（预留） 初始密码不能交易
-36（预留） 不能改为初始密码
-41 运算数据含非法字符
-42 运算数据长度错
-51 PIN 校验剩余次数N 次（根据卡返回信息）
-52 PIN 锁定
-2201 无PSAM 卡
-2202 PSAM 卡算法不支持
-2203 PSAM 卡内没有RKSSSE 密钥
T/HBDIA 001-2024
8
表A.1 错误代码（续）
常见错误信息
返回值错误信息描述
-25536、-25537、-25538 外部认证失败（剩余可尝试次数N 次）
-26368 Lc/Le 不正确
-26881 命令不接受（无效状态）
-27009 命令与文件结构不相符、当前文件非所需文件
-27010 不满足安全条件
-27011 密钥锁定（算法锁定）鉴别方法锁定
-27012 引用数据无效、随机数无效
-27013 不满足使用条件、应用被锁定、应用未选择、余额上溢
-27016 安全报文数据项不正确、MAC 不正确
-27264 数据域参数不正确
-27265 不支持该功能、卡中无MF、卡被锁定、应用锁定
-27266 未找到文件、文件标识相重、SFI 不正确
-27267 未找到记录
-27272 未找到引用数据、未找到密钥
-37634 MAC 无效
-37635 应用已被永久锁定、卡片锁定
-37891 PSAM 卡不支持消费交易
-37894 所需MAC（或/和TAC）不可用
-70001 卡片为省外社会保障卡，请调用加密机函数
-70002 网络异常
-70003 密服系统内部错误
-70004 加密机内部错误
-70005 扫码失败
-70006 终端不合法
其他未知错误