【YD通讯标准】 网络电子身份标识 elD 桌面应用接口技术要求

ICS35.110
中华人民共和宝玉通信行标准
YD/T3151-2016
网络电子身份标识eID桌面应用接口技术要求
Technical requirementsfor elD personal computerapplication interface2016-07-11发布
2016-10-01实施
中华人民共和国工业和信息化部发布前
范围·
2规范性引用文件
3术语、定义和缩略语·
4eID桌面应用服务
5eID桌面应用注册要求·
6eID桌面应用接口
附录A（资料性附录）密码服务提供者（CSP）接口示例附录B（资料性附录）接口调用示例附录C（规范性附录）桌面应用接口函数交互图，参考文献
YD/T3151-2016
YD/T3151-2016
本标准属于网络电子身份标识eID相关服务与应用接口系列标准之一，该系列标准包括：《网络电子身份标识eID桌面应用接口技术要求》《网络电子身份标识eID移动应用接口技术要求》《网络电子身份标识eID验证服务接口技术要求》《网络电子身份标识eID桌面应用接口测试方法》《网络电子身份标识eID移动应用接口测试方法》《网络电子身份标识eID验证服务接口测试方法》本标准依据GB/T1.1-2009给出的规则起草。请注意本文件的某些内容可能涉及专利，本文件的发布机构不承担识别这些专利的责任本标准由中国通信标准化协会提出并归口。本标准由公安部第三研究所、中国科学院软件研究所、北京中电华大电子设计有限责任公司、国防科学技术大学计算机学院、北京邮电大学、中国科学院信息工程研究所等单位起草。本标准主要起草人：邹翔、杨明慧、汪志鹏、倪力舜、梁皓、高志刚、兰天、李树栋、落红卫、高峰、柳扬、全拥、邓璐、许晋、周薇、戴娇。Ⅱ
iiiKAoNiKAca
YD/T3151-2016
本技术要求旨在规范接口的命名；统一接口调用方式，方便eID桌面应用接入；减少多个功能库的共用接口，减小维护成本；方便在此基础上添加新的功能接口。本文件主要描述第三方应用通过桌面终端访问eID卡的接口。第三方应用后台与eID服务平台的交互参见《网络电子身份标识eID验证服务接口技术要求》。Ⅲ
HiiKAoiKAca
1范围
网络电子身份标识eID桌面应用接口技术要求本标准规范了eID应用于桌面应用的相关接口。本标准适用于eID应用于桌面应用。2规范性引用文件
YD/T3151-2016
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YDT3150-2016网络电子身份标识eID验证服务接口技术要求YD/T2592-2013身份管理(IdM)术语3术语、定义和缩略语
3.1术语和定义
YD/T2592-2013界定的术语和定义适用于本文件，3.2缩略词
下列缩略语适用于本文件。
Cryptographic ServiceProviderelectronic Identity
Personal IdentificationNumberSoftware Development Kit
4elD桌面应用服务
4.1基本功能
密码服务提供者
网络电子身份标识
个人识别码
软件开发工具包
eID桌面应用服务主要为eID桌面应用提供三个功能：实名认证、账号保护、安全登录。eID桌面应用通过接口技术方法与eID交互，使用以下三个服务功能。4.2桌面实名认证
eID桌面实名认证为eID桌面应用提供安全便捷的PC端实名认证服务。eID桌面应用将用户重定向到eID服务平台实名认证页面，用户只要插入自已的eID卡并输入eID卡的PIN码就能完成eID桌面应用的实名认证过程。
4.3桌面账号保护
4.3.1基本功能
eID的账号保护，即自建立eID第三方应用账号和eID之间的绑定关系起，一旦发生用户账号被盗或忘记口令的情况时，用户只需要插入eD卡就可以重置账号信息，让账号重新回到用户手中，eD账号保护包括账号绑定和账号找回两个过程。1
HiiKAoNiKAca
YD/T3151-2016
4.3.2账号绑定
eID桌面账号绑定为eID桌面应用提供安全便捷的PC端eID账号绑定服务当用户在eID桌面应用请求桌面账号绑定时，用户只要插入自已的eID卡并输入正确的PIN码就能完成eID桌面应用的账号绑定过程。
4.3.3账号找回
eID桌面账号找回为eID桌面应用提供安全便捷的PC端eID账号找回服务。当用户在eID桌面应用请求桌面账号找回时，用户只要插入自已的eID卡并输入PIN码就能完成eID桌面应用的账号找回业务。4.4桌面安全登录
eID桌面安全登录方式为eID桌面应用提供安全便捷的PC端eID登录服务。当用户在eID桌面应用请求插卡登录时，用户只要插入自已的eID卡就能完成eID桌面应用的登录过程。5elD桌面应用注册要求
第三方应用接入eID系统前，需联系eID服务平台进行注册。具体的规范描述见YD/T3150-2016《网络电子身份标识eID验证服务接口技术要求》。6elD桌面应用接口
6.1接口函数列表
通过调用eID桌面应用接口，eID桌面应用可以实现eID基本服务功能的接入使用与应用改造。eID桌面应用接口函数如表1所示，接口函数交互图详见附录C。表1elD桌面应用接口函数列表
函数名
eID_load
elD_getMessage
eID_getVersion
elD_detectDeviceBegin
eID_detectDeviceEnd
eID_hash
elD_sign
6.2接口方法
6.2.1接口封装方法
接口封装的方法包括：
eID桌面客户端安装检测
中文提示信息获取
版本号获取
设备插拔检测启动
设备插拔检测终止
生成eID杂凑数据
获得eID签名数据
eID桌面客户端安装检测：
中文提示信息获取：
一版本号获取：
设备插拔检测启动：
-设备插拔检测终止：
随机数获取：
签名数据。
6.2.2elD桌面客户端安装检测
对应章节
HiiKAoNiKAca
函数名：eID_load。
YD/T3151-2016
输入：回调函数类型的参数，该回调函数用于判断eID桌面客户端是否加载成功：加载失败时返回安装eID桌面客户端的URL下载标准就来标准下载网
输出：无
功能说明：用于判断是否需要提示用户下载并安装最新eID桌面客户端。6.2.3中文提示信息获取
函数名：eID_getMessage.
输入：integer类型的返回码。
输出：string类型的返回码意义。功能说明：根据返回码转义为中文提示信息。6.2.4版本号获取
函数名：eID_getVersion
输入：回调函数getVersionCallback，用于获取版本号并返回相应的返回码。输出：无。
功能说明：获取版本号便于调用接口。6.2.5设备插拔检测启动
函数名：eID_detectDeviceBegin。输入：回调函数detectDeviceCallback，用于获得最新的读卡器和银行尾号列表，并返回相应的返回码输出：无。
功能说明：在读卡器或卡片拨插时，返回最新的读卡器名列表。6.2.6设备插拨检测终止
函数名：eID_detectDeviceEnd。输入：回调函数detectDeviceEndCallback，用于终止detectDeviceBegin方法，并返回相应的返回码。输出：无。
功能说明：停止DetectDeviceBegin方法的检测。6.2.7随机数获取
函数名：eID_hash。
输入：回调函数hashCallback，用于获得杂凑结果、载体编号，并返回相应的返回码；string类型的读卡器名：string类型的待杂凑数据：string类型的杂凑类型。输出：无。
功能说明：生成eID杂凑数据，用于eID桌面客户端与应用之间的挑战应答。6.2.8签名数据
函数名：eID_sign。
输入：回调函数getVerifySignRequestCallback，用于获得签名结果、载体编号、证书颁发者等信息并返回相应的返回码；string类型的读卡器名：string类型的待签名数据：string类型的签名算法类型。输出：无。
功能说明：获得eID签名数据等，弹出验证签名PIN对话框。3
HiiKANiKAca
YD/T3151-2016
A.1概述
附录A
（资料性附录）
密码服务提供者（CSP）接口示例技术要求中所述接口的实现可以采用支持微软提供的密码服务提供者（CSP）接口，相关接口方法的实现示例如下。
A.2接口实现示例
A.2.1获取上下文
可设置场景为创建、删除、使用容器，不支持机器认证。BOOL WINAPICPAcquireContext(OUTHCRYPTPROV *phProy,INLPCSTR szContainer,INDWORDdwFlags,INPVTableProvStrucpVTable)。参数：phProv为CSP上下文句柄，szContainer为容器名，dwFlags为标识值，pVTable为功能函数列表指针。
返回值：TRUE表示成功。
说明：szContainer只能设置为个人RSA1024证书容器，例如容器名可命名为(4A7A26B1-ABA5-48ef-8B6A-24A4BA42E787)。dwFlags可设置为CRYPT_VERIFYCONTEXT或0A.2.2释放上下文
BOOLWINAPICPReleaseContext(INHCRYPTPROVhProv,INDWORDdwFlags)。参数：hProv为CSP上下文句柄，dwFlags为标识值。返回值：TRUE表示成功。
说明：CPReleaseContext函数用来释放CPAcquireContext创建的上下文句柄。A.2.3获取上下文参数
BOOL WINAPICPGetProvParam(INHCRYPTPROV hProv,INDWORD dwParam, OUTLPBYTEpbData,INOUTLPDWORDpcbDataLen,INDWORD dwFlags)。参数：hProv为CSP上下文句柄，dwParam为参数类型，pbData为参数数据，pcbDataLen为参数的长度，dwFlags为标识值。
返回值：TRUE表示成功。
说明：dwParam可设置为PP_CONTAINER、PP_UNIQUE_CONTAINER、PP_PROVTYPE、PP_IMPTYPE、PPNAME、PP_VERSION、PP_USEHARDWARE_RNG、PPKEYSPEC、PPENUMALGS、PPENUMALGSEX、PPENUMCONTAINERS、PPKEYSTORAGE。A.2.4取密钥的参数
BOOLWINAPICPGetKeyParam(INHCRYPTPROVhPro,INHCRYPTKEYhKey,INDWORDdwParam,OUTLPBYTEpbData,INOUTLPDWORDpcbDataLen,INDWORDdwFlags)。参数：hProv为CSP上下文句柄，hKey为密钥句柄，dwParam为参数类型，pbData为参数数据，pcbDataLen为参数的长度，dwFlags为标识值。4
TiiKAoNiKAca
返回值：TRUE表示成功。
YD/T3151-2016
说明：dwParam可设置为KP_ALGID、KPBLOCKLEN、KPKEYLEN、KP_PERMISSIONS、KPIV、KPPADDING、KPMODE、KP CERTIFICATEA.2.5设置Hash对象的参数
BOOLWINAPI CPSetHashParam(INHCRYPTPROVhProyIN
DWORDdwParam,INCONSTBYTE*pbData,INDWORDdwFlags)。HCRYPTHASH hHash,IN
参数：hProv为CSP上下文句柄，hHash为Hash句柄，dwParam为参数类型，pbData为参数数据，dwFlags为标识值。
返回值：TRUE表示成功。
说明：dwParam可设置为HP_HASHVAL。A.2.6获取Hash对象的参数
BOOLWINAPICPGetHashParam(INHCRYPTPROVhProV,INHCRYPTHASHhHash,IN
DWORDdwParam,OUTLPBYTEpbData,INOUTLPDWORDpcbDataLen,INDWORDdwFlags)。参数：hProv为CSP上下文句柄，hHash为Hash句柄，dwParam为参数类型，pbData为参数数据，pcbDataLen为参数的长度，dwFlags为标识值。返回值：TRUE表示成功。
说明：dwParam可设置为HP_ALGID、HP_HASHVAL、HP_HASHSIZE。A.2.7导出密钥
BOOL WINAPI CPExportKey(IN
HCRYPTPROVhProv,IN
HCRYPTKEYhKey，IN
HCRYPTKEYhPubKey,INDWORDdwBlobType,INDWORDdwFlags,OUTLPBYTEpbData,INOUT LPDWORD pcbDataLen)。
参数：hProv为CSP上下文句柄，hKey为密钥句柄，hPubKey为交换公钥句柄，dwBlobType为块类型那个，dwFlags为标识值，pbData为导出数据，pcbDataLen为导出数据长度。返回值：TRUE表示成功。
说明：dwBlobType可设置为PUBLICKEYBLOB：A.2.8创建Hash对象
BOOLWINAPICPCreateHash(IN HCRYPTPROVhProv,INALG IDAlgid,INHCRYPTKEYhKey,INDWORDdwFlags,OUTHCRYPTHASH*phHash)。参数：hProv为CSP上下文句柄，Algid为算法ID，hKey为密钥句柄，dwFlags为标识值，phHash为hash句柄。
返回值：TRUE表示成功。
说明：支持MD5和SHA1算法。
A.2.9对数据进行Hash
BOOL WINAPI CPHashData(IN HCRYPTPROVhProv,INHCRYPTHASH hHash,IN CONSTBYTE*pbData,INDWORDcbDataLen,INDWORDdwFlags)。参数：hProv为CSP上下文句柄，hHash为Hash句柄，pbData为待Hash数据，cbDataLen为待Hash数据长度，dwFlags为标识值。
HiiKAoNiKAca
YD/T3151-2016
返回值：TRUE表示成功。
说明：完成Hash操作。
A.2.10对Hash数据进行签名
BOOLWINAPICPSignHash(INHCRYPTPROVhProv,INHCRYPTHASHhHash,INDWORDdwKeySpec, IN LPCWSTR szDescription, IN DWORD dwFlags, OUT LPBYTE pbSignature, IN OUTLPDWORDpcbSigLen).
参数：hProv为CSP上下文句柄，hHash为Hash句柄，dwKeySpec为密钥对类型，szDescription为签名描述信息，dwFlags为标识值，pbSignature为签名值，pcbSigLen为签名值长度。返回值：TRUE表示成功。
说明：dwFlags支持0。
A.2.11释放Hash对象
BOOLWINAPICPDestroyHash(INHCRYPTPROVhProv,INHCRYPTHASHhHash)参数：hProv为CSP上下文句柄，hHash为Hash句柄。返回值：TRUE表示成功。
说明：CPDestroyHash函数用来释放CPCreateHash创建的上下文句柄。A.2.12获取随机数
BOOL WINAPI CPGenRandom(INHCRYPTPROVhProv,INDWORD cbLen,OUTLPBYTEpbBuffer)。
参数：hProv为CSP上下文句柄，cbLen为随机数长度，pbBuffer为随机数数据。返回值：TRUE表示成功。
说明：随机数从设备获取。
A.2.13获取用户密钥
BOOLWINAPICPGetUserKey(IN
HCRYPTPROVhProv，IN
HCRYPTKEY*phUserKey)。
DWORD dwKeySpec, OUT
参数：hProv为CSP上下文句柄，dwKeySpec为密钥对类型，phUserKey为密钥句柄。返回值：TRUE表示成功。
说明：获取个人RSA1024证书容器对应的密钥，dwKeySpec支持签名算法。附录B
（资料性附录）
接口调用示例
YD/T3151-2016
本示例中，已采用控件方式，通过实现一个JavaScript脚本，提供相应的eID桌面应用接口。完成接口脚本的加载后，即可获取实例化的eID对象。调用其方法即可方便的调用相应功能。如：var ret=eID.queryState (reader):简单设计示例如下：
var eID = functionO t
vareIDpugin = document.createElement('object)eIDpugin.id='eIDpugin'：
eIDpugin.type=application/x-eIDPluginHelper';document.body.appendChild(eIDpugin):this.detectDeviceBegin=function(onDeviceChanged)t//todo
this.detectDeviceEnd=function(onDeviceChanged)i/todo
this.queryState=function(Reader) f//todo
this.authenticate=function(Reader,Name,Number)//todo
this.verifySign=function(Reader,Data) //todo
YD/T3151-2016
附录C
（规范性附录）
桌面应用接口函数交互图
eID桌面应用调用桌面应用接口可以实现eID基本服务功能的接入使用与应用改造。对于eID桌面应用，可以通过以下桌面应用接口访问eID卡，如图C.1所示。elD_load
eID桌面客户端是否加载成功
elDgetVersion
是否成功执行elDdetectDeviceBegin是
是否成功执行eIDdetectDeviceEndeID_hash
是否成功获取杂凑结果、载体编号elID_sign
是否成功获取获得签名结果、载体编证书颁发者等信息
返回结果码
图A.1接口函数交互图
返回安装eID助手
的URL
返回错误信息
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。