DB11-T254-2-2018政务数字证书规范第2部分：应用接口

1、ICS 35.240.30L 70DB11北京市地方标准DB11/T254.22018DB11/T 254.2-20042Specification for digital certificate for government affairs Part 2: Application Programming Interface2018-04-04发布2018-07-01实施北京市质量技术监督局发布DB11/T 254.22018目次前言II引言III1范引文件1语定、略语1构2务字书用定义2附录A（范附）政务字书用口误代定和13附录B（料附）政务字书型用15IDB11/T 254.22018前言

2、本部分按照GB/T 1.12009给出的规则起草。DB11/T 254.22018政务数字证书规范分为两个部分：第1部分：格式；第2部分：应用接口。本部分为DB11/T 2542018的第2部分。DB11/T 政务数字证书规范 第GM/T 00202012第2章，引用了密码行业标准；第4章，重新命名为“结构组成”，并将接口的组成部分重新定义为设备管理接口、访问控制接口、容器管理接口、密码服务接口、证书接口和通用接口；第5章，按照第4章定义的结构重新定义接口，新的接口采用COM接口形式，在第5章的内容中，加入了符合密码行业标准的接口，接口内容参照了密码行业的相关标准；删除原附录A“政务数字证书应

3、用接口宏定义和说明”，改为“政务数字证书应用接口错误代码定义和说明（规范性附录）”，在其中给出了政务数字证书接口的错误码定义；删除了原附录B“政务证书应用接口数据结构定义和说明”，改为“政务数字证书典型调用示例（资料性附录）”；删除原附录C“政务数字证书应用接口错误代码定义和说明”；删除原附录D“政务数字证书典型应用框架图”；删除原附录E“政务数字证书典型应用示例”。本部分由北京市经济和信息化委员会提出并归口。本部分由北京市经济和信息化委员会组织实施。本部分主要起草人：潘锋、刘惠刚、刘莎、姚世全、陈淑仪、高能、荆继武、李述胜、李向锋。DB11/T 254.22018引言（PublicKeyIn

4、frastructure，PKI）核心的网络身份认证体系和信息加密技术已成为业界广泛认同的一种构造网络身份信任体制的重要方 PKIPKIIIIDB11/T 254.22018政务数字证书规范 第 2 部分：应用接口范围应用于电子商务领域的数字证书应用接口，也可参照本部分。下列文件对于本部分的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本部分。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本部分。GB/T 250692010GM/T00092012SM2GM/T00102012SM2GB/T 250692010界定的以及下列术语和定义适用于本文件。3.1.1信任 t

5、rust信任缩略语下列缩略语适用于本部分：CA书证构（Certification Authority） COM件象型（Component Object Model）CSP密务供（Cryptographic Service Provider） OID象识（Object Identifier）PKCS(thePublic-KeyCryptography Standard)1DB11/T 254.220181政务数字证书应用身份认证政务数字证书应用身份认证机密性完整性不可否认性政务数字证书应用接口设备接口密码设备.密钥密钥密钥证书接口密码服务接口容器管理接口访问控制接口设备管理接口应用程序接口层图1

6、数字书用数字证书应用接口由以下几个接口部分组成：设备管理接口：负责对所连接的密码设备进行管理、获取密码设备的信息；访问控制接口：负责确认用户是否允许连接使用密码设备，包括口令验证和修改口令等接口；容器管理接口：负责对所连接的密码设备中的容器进行管理；密码服务接口：负责具体与密码设备交互实现具体的密码运算，并将运算结果返回给应用程序；证书接口：负责数字证书的解析、证书信息的获取、有效性检查等功能；通用接口：负责提供通用类的处理功能。COMA， 使用JavaScriptBboolean：1（True）0（False）2DB11/T 254.22018LONG：BSTR：BSTROLECHAR获取设

7、备数量接口定义如下：接口型：LONGGetDeviceCount()功能述：取前在的支的备量参数：无返回：备备注：无获取有备列接定义下： 接口型：BSTRGetAllDeviceSN()功能述：获当存的支的所设的列，个设序号分(;)尾参数：无返回：有备列号组合备注：当前在有备列例个设序号使半的冒号（:）来分隔根据索引获取设备序列号接口定义如下：接口型：BSTR GetDeviceSNByIndex(LONGiIndex)功能述：据引取设的列号参数：iIndexIN引0开，能于前的设数量返回：功回备序号失返空备注：无判断设备是否存在接口定义如下：接口型：boolean IsDeviceExist

8、(BSTRsDeviceSN)功能述：断备否存在参数： sDeviceSNINTRUE，备 注 ： 无获取设备详细信息接口定义如下：接口型：BSTR GetDeviceInfo(BSTR sDeviceSN, LONGiType)功能述：取备细信息参数：sDeviceSNIN设备列号iTypeIN3DB11/T 254.22018返回：功回备信，败回空备注：前支的类参为：0 x000000010 x000000020 x000000030 x00000004RSA或SM20 x000000050 x00000007HARD或SOFT0 x000000080 x00000009CSP0 x000

9、00073SM2200 x00000074VID_PID（16设备登录接口定义如下：接口型:booleanSOF_Login(BSTR CertID, BSTRPassWd)功能述:录参数:CertIDIN书作一识也支只入备列。PassWdIN证口。 返回：确回TRUE，败回备注：无设备登出接口定义如下：接口型：booleanSOF_Logout (BSTRCertID)功能述：退登录参数：CertIDIN书作一返回：正返回TRUE 败回FALSE 备注：无获取口令重试次数接口定义如下：接口型：LONG SOF_GetPinRetryCount(BSTRCertID)功能述：获证令重次数参数：

10、CertIDIN书作一返回：0示次数，=0表示证书口令已被锁死，必须解锁后才能使用&.备注：无删除容器接口定义如下：接口型：boolean DeleteContainer(BSTR sDeviceSN, BSTRsContainerName)功能述：除器参数：sDeviceSNIN设序号sContainerNameIN容器返回：功回TRUE，败回FALSE 备注：用接前必已录产Th产生密钥对接口定义如下：接口型:booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContainerName,LONGiKeyType, boolean bSign)功能述:生钥对参

11、数:sDeviceSNIN设序号5DB11/T 254.22018sContainerNameIN/1-32之间iKeyTypeIN3256位SM2密钥bSignIN名加，TRUE示名，FALSE加返回：功回TRUE，败回FALSE备注：无导出公钥接口定义如下：接口型:BSTR ExportPubKey(BSTR sDeviceSN, BSTR sContainerName, booleanbSign)功能述:出钥参数:sDeviceSNIN设序号sContainerNameINbSignIN示名钥,FALSE示加公钥返回:功回Base64码公，败空备注：无导出证书请求接口定义如下：接口型：B

12、STRExportCertificationReq(BSTRsDeviceSN,BSTRsContainerName,BSTRsDN)功能述：出书参数：sDeviceSN设序号sContainerNameINsDNINDNDN返回：功回Base64码证请，返回空备注：无导入签名证书接口定义如下：接口型:boolean ImportSignCert(BSTR sDeviceSN, BSTR sContainerName, BSTRsCert)功能述:入名参数:sDeviceSNIN设序号sContainerNameINsCertINBase64返回:功回TRUE，败回FALSE备注：无导入加密证

13、书和加密密钥对接口定义如下：接口型:booleanImportEncCert(BSTRsDeviceSN,BSTRsContainerName,BSTRsCert,BSTR sPriKeyCipher)功能述:入密书和密钥对参数:sDeviceSNIN设序号sContainerNameIN6DB11/T 254.22018sCertINBase64编加密sPriKeyCipherINBase64编的密密返回:功回TRUE，败回FALSE备注：无数据签名接口定义如下：接口型:BSTR SOF_SignData(BSTR CertID, BSTRInData)功能述:数进数字名。参数:CertID

14、IN证操唯识InDataIN返回:功回Base64码签值失回空备注:名果符合GM/T 00092012中7.3的求数据验签接口定义如下：接口型:boolean SOF_VerifySignedData(BSTR Cert, BSTR InData， BSTRSignValue)功能述:证据名。参数:CertINBase64码证InDataIN签原文SignValueINBase64编的名返回:功回TRUE，败回FALSE备注：无数字信封加密数据接口定义如下：接口型:BSTR SOF_EncryptData(BSTR Cert, BSTRIndata)功能述:生字封参数:CertINBase64

15、编的证IndataIN原数据返回:功回Base64码密数，返回空备注:使用时产的对密加密据,然使数字书加对称钥(字信)。格式应合GM/T 00102012中第章要求数字信封解密数据接口定义如下：接口型:BSTR SOF_DecryptData(BSTR CertID, BSTRIndata)功能述:数信密参数:CertIDIN证操唯标识IndataINBase64返回:功回文数，败回空备注：无7DB11/T 254.22018消息签名接口定义如下：接口型：BSTR SOF_SignMessage(short dwFlag，BSTR CertID, BSTRInData)功能述：数进数字名。参数

16、：dwFlagIN标识否Detached0带原，1表不原CertIDINInDataIN返回：码签值失回空备注：字串据进数签，式符合GM/T001220128章要求验证消息签名接口定义如下：接口型:boolean SOF_VerifySignedMessage(BSTR MessageData，BSTRInData)功能述:数进验证名。参数:MessageDataINBase64编的名值InDataIN原数据返回:功回TRUE，败回FALSE备注：无解析消息签名接口定义如下：接口型：BSTR SOF_GetInfoFromSignedMessage(BSTR SignedMessage，sho

17、rttype)功能述：解析息名内信，包：文签值签名书信。参数：SignedMessageINBase64码签值typeIN型值范如1：原文2：签名者证书3：名返回：功回析的息失返空 备注：无产Th产生随机数接口定义如下：接口型:BSTR SOF_GenRandom(LONGRandomLen)功能述:生机参数:RandomLenIN随数长。返回:功回Base64编的机，败回备注：无公钥加密数据接口定义如下：接口型：BSTR SOF_PubKeyEncrypt(BSTR sCert, BSTRsInData)功能述：钥密参数：sCertINBase64码8DB11/T 254.22018sInD

18、ataIN返回：确回Base64码密数，返回空备注：无私钥解密数据接口定义如下：接口型:BSTR SOF_PriKeyDecrypt(BSTR CertID, BSTRsInData)功能述:钥密参数:CertIDIN书作一标识sInDataINBase64返回:确回文数，败回空备注：无对称加密数据接口定义如下：接口型：BSTR SOF_SymEncryptData(BSTR sKey, BSTRindata)功能述：称密参数：sKeyINBase64码的称indataIN文返回：确回Base64码密数，返回空备注：无对称解密数据接口定义如下：接口型：BSTR SOF_SymDecryptDa

19、ta(BSTR sKey, BSTRindata)功能述：称密参数：sKeyINBase64码的称indataINBase64编的密文返回：确回文数，败回空备注：无数据摘要接口定义如下：接口型：BSTR SOF_HashData(LONG hashAlg, BSTRsInData)功能述：数做要参数：hashAlgIN要法使用0 x00000001,示SM3算法sIndataIN返回：确回Base64码数，败空备注：无获取证书用户列表接口定义如下：9DB11/T 254.22018接口型：BSTRSOF_GetUserList()功能述：取安的证用列。参数：无返回：书户备注： 返回的证书用户列

20、表格式为：用户名1|CertID1&用户名2|CertID2&用户名3|CertID3&CertID导出用户签名证书接口定义如下：接口型：BSTR SOF_ExportUserCert(BSTRCertID)功能述：根证操唯标获取Base64编格的名证参数：CertIDIN书作标识 返回：功回Base64码签证，返回备注：无导出用户加密证书接口定义如下：接口型：BSTR SOF_ExportExchangeUserCert(BSTR CertID) 功能述：据书作唯标获Base64码格的书参数：CertIDIN书作标识返回：功回Base64码加证，返回空备注：无验证证书有效性接口定义如下：接口

21、型：LONG SOF_ValidateCert(BSTRBase64EncodeCert)功能述：证书效性参数：Base64EncodeCertINBase64码返回：确回0失败回他如：-1证书不被信任-2超过有效期范围-3证书已作废-4证书已冻结-5证书未生效-6其他错误备注：无获取证书基本信息接口定义如下：接口型:BSTR SOF_GetCertInfo(BSTR Cert, shortType)功能述:取书信息参数:CertINBase64编证书TypeIN息型10DB11/T 254.22018返回:功回的基信，败回空备注:前支证书息型数下：V1V2或 V3RSASM2(C)(O)(O

22、U(ST(CN(L) 多个用逗号(,)分割10 EMAIL(E) 多个用逗号(,)分割11YYYYMMDDHHMMSS 12 YYYYMMDDHHMMSS 13 (C)14 使(O)15 使用(OU16 使用(ST17 使用(CN18 使用(L)19 使用者EMAIL(E) 多个用逗号(,)分割20钥 Base642”3 33DN34 颁发者获取证书扩展信息接口定义如下：接口型:BSTR SOF_GetCertInfoByOid(BSTR Cert, BSTROid)功能述:据OID获证书私扩信息参数:CertINBase64编证OidINOID串返回:功回的扩信，败回空备注：无获取证书唯一实

23、体标识接口定义如下：接口型：BSTR SOF_GetCertEntity(BSTRCert)功能述：取书唯一体识参数：CertINBase64编的证书11DB11/T 254.22018返回：功回书唯实标，败回空备注：无获取后次错错码接定如接口型：LONGSOF_GetLastError()功能述：取后次出的误码参数：无返回：误。中0示常其表误。误定和明附录A备注：无获取后次错错描述口义下接口型：BSTRSOF_GetLastErrMsg()功能述：取后次出的误述参数：无返回：误述备注：无12DB11/T 254.22018附录A（规范性附录）政务数字证书应用接口错误代码定义和说明A.1政务数

24、字证书应用接口错误代码定义和说明见表A.1。表A.1务字书用接错代定和错误码(十进制）描述1设备序列错误（索引值错误）2设备序列号长度错误3打开设备错误4打开应用错误5没有打开设备6Pin码长度错误7校验口令失败8获取Pin码重试次数错误9修改管理员口令失败10修改用户口令失败11解锁用户口令失败12容器名称长度错误13创建容器失败14产生密钥对失败15打开容器失败16导出公钥失败17尚未登录18导入证书失败19容器类型错误20ENVSN为空21写入ENVSN失败22读取ENVSN失败23获取容器数量失败24删除容器失败25判断容器是否存在失败26获取设备序列号失败27导入证书时，证书中的公钥和设备容器中的公钥不匹配28Base64编码失败29Base64解码失败30解析字符串失败13DB11/T 254.22018表 A.1 政务数字证书应用接口错误代码定义和说明（续）错误码(十进制）描述31产生随机数失败32设置明文对称密钥失败33加密或解密初始化失败34对称加密失败35认证设备密钥失败36删除应用失败37创建应用失败38创