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

DB11/T254.2第2部分：应用接口SpecificationfordigitalPart2:ApplicationProgrammingInterface北京市质量技术监督局发布I I1 12规范性引用文件 13术语和定义、缩略语 14结构组成 25政务数字证书应用接口定义 2附录A(规范性附录)政务数字证书应用接口错误代码定义和说明 附录B(资料性附录)政务数字证书典型调用示例 本部分按照GB/T1.1-2009给出的规则起草。DB11/T254.2—2018《政务数字证书规范》分为两个部分：——第1部分：格式；——第2部分：应用接口。本部分为DB11/T254—2018的第2部分。本部分代替DB11/T254.2—2004《政务数字证书规范第2部分：应用接口》。本部分根据电子政务中数字证书接口的使用情况，对原有标准的内容进行了结构上的调整，重新定义了接口的架构和接口的形式。新的接口以GM/T0020—2012《证书应用综合服务接口规范》中的定义为主，并加入法人一证通项目实施所需的扩展接口。详细修订包括：——第2章，引用了密码行业标准；——第4章，重新命名为“结构组成”,并将接口的组成部分重新定义为设备管理接口、访问控制接口、容器管理接口、密码服务接口、证书接口和通用接口；——第5章，按照第4章定义的结构重新定义接口，新的接口采用COM接口形式，在第5章的内容中，加入了符合密码行业标准的接口，接口内容参照了密码行业的相关标准；——删除原附录A“政务数字证书应用接口宏定义和说明”,改为“政务数字证书应用接口错误代码定义和说明(规范性附录)",在其中给出了政务数字证书接口的错误码定义；——删除了原附录B“政务证书应用接口数据结构定义和说明”,改为“政务数字证书典型调用示例(资料性附录)";——删除原附录C“政务数字证书应用接口错误代码定义和说明”;——删除原附录D“政务数字证书典型应用框架图”;——删除原附录E“政务数字证书典型应用示例”。本部分由北京市经济和信息化委员会提出并归口。本部分由北京市经济和信息化委员会组织实施。本部分主要起草单位：北京市经济和信息化委员会、北京数字认证股份有限公司、中国科学院信息工程研究所、北京市国家保密局、北京市密码管理局。本部分主要起草人：潘锋、刘惠刚、刘莎、姚世全、陈淑仪、高能、荆继武、李述胜、李向锋。ⅢDB11/T254.2—2018信息技术和网络技术在极大地促进了社会的经济、科技、文化、教育和管理等各个方面发展的同时，也带来了巨大的信息安全风险。随着北京市电子政务工程的不断深入和发展，迫切需要在开放的网络环境下建立一个真实、有效的身份信任体制，确认电子政务参与方的各自身份，建立彼此间的信任关系以及保证信息的保密性、完整性和可用性。以公开密钥基础设施(PublicKeyInfrastructure,PKI)为核心的网络身份认证体系和信息加密技术已成为业界广泛认同的一种构造网络身份信任体制的重要方式，并成为信息安全保障体系中极其重要的组成部分之一。数字证书应用接口是PKI技术应用的关键和核心，是电子政务应用系统使用和应用PKI技术的桥梁。为了确保政务数字证书在电子政务信息的应用中能够通用，实现信息系统互联互通，统一数字证书应用接口规范，能够有效降低数字证书应用集成的复杂度，有助于更好形成统一的网络信任体系。本部分定义了政务数字证书应用的系统架构，并定义了政务数字证书应用的各种接口。1政务数字证书规范第2部分：应用接口1范围凡是不注日期的引用文件，其最新版本(包括所有的修改单)适用于本部分。GB/T25069—2010信息安全技术术语COM组件对象模型(ComponentObjectCSP加密服务提供者(CryptographicS0ID对象标识符(ObjectIdentifier)4结构组成24.1.1政务证书数字证书应用的一般体系结构，如图1所示：政务数字证书应用政务数字证书应用工4.1.2政务数字证书应用接口位于应用层和密码设备之间，应用程序通过调用政务数字证书应用接口数字证书应用接口由以下几个接口部分组成：——访问控制接口：负责确认用户是否允许连接使用密码设备，包括口令验证和修——密码服务接口：负责具体与密码设备交互实现具体的密码运算，并将运算结果返回给应用程序；5.1类型说明3表示一个有符号长整数，其位数与取值范围与特定的平台有关。获取设备数量接口定义如下：功能描述：获取当前存在的可支持的设备数量参数：无返回值：设备数量备注：无获取所有设备序列号接口定义如下：功能描述：获取当前存在的可支持的所有设备的序列号，每个设备序列号以分号(;)结尾参数：无返回值：所有设备序列号的组合备注：当前存在所有设备序列号，例如"11111;22222;",各个设备序列号间使用半角的冒号(:)来分隔根据索引获取设备序列号接口定义如下：接口原型：BSTRGetDeviceSNByIn功能描述：根据索引获取设备的序列号参数：ilndex[IN]索引，从0开始，不能大于当前存在的设备数量返回值：成功返回设备序列号，失败返回空备注：无判断设备是否存在接口定义如下：功能描述：判断设备是否存在参数：sDeviceSN[IN]设备序列号备注：无获取设备详细信息接口定义如下：功能描述：获取设备详细信息参数：sDeviceSN[IN]设备序列号iType[IN]信息类型4成功返回设备信息，失败返回空目前可支持的类型参数为：5.3访问控制接口5.3.1设备登录设备标签设备空余空间设备序列号设备类型返回"RSA"或"SM2"获取证书密码重试次数设备类型返回"HARD"或"SOFT"对应动态库的名称CSP名称设备类型SM2设备返回"20"设备的VID_PID(16进制数据)设备登录接口定义如下：接口原型：booleanSOF_Login(BSTRC功能描述：登录参数：CertID[IN]证书操作唯一标识，也支持只输入设备序列号。PassWd[IN]证书口令。返回值：正确返回TRUE,失败返回FALSE备注：无5.3.2设备登出设备登出接口定义如下：功能描述：退出登录参数：CertID[IN]证书操作唯一标识返回值：正确返回TRUE失败返回FALSE备注：无5.3.3获取口令重试次数获取口令重试次数接口定义如下：功能描述：获取证书口令重试次数参数：CertID[IN]证书操作唯一标识返回值：>0表示重试次数，=0表示证书口令已被锁死，必须解锁后才能使用<0表示获取重试次数失败备注：无5.3.4修改登录口令修改登录口令接口定义如下：5功能描述：修改证书口令参数：CertID[IN]证书操作唯一标识0ldPassWd[IN]原始口令，6-46位可显示字符NewPassWd[IN]新口令，6-46位可显示字符返回值：成功返回TRUE,失败返回FALSE备注：无5.4容器管理接口5.4.1获取容器数量获取容器数量接口定义如下：接口原型：LONGGetContainerCount(BSTRsDeviceSN)功能描述：获取容器数量参数：sDeviceSN[IN]设备序列号返回值：成功返回容器数量，失败返回负数备注：无5.4.2获取所有容器名称获取所有容器名称接口定义如下：功能描述：获取所有容器名称参数：sDeviceSN[IN]设备序列号返回值：成功返回所有容器名称，失败或设备内不存在容器时返回空。返回格式为使用“&”符号分隔的容器名，即<容器名>&<容器名>&<容器名>...备注：无5.4.3删除容器删除容器接口定义如下：接口原型：booleanDeleteCo功能描述：删除容器参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称返回值：成功返回TRUE,失败返回FALSE备注：调用本接口前必须已登录5.5密码服务接口5.5.1产生密钥对产生密钥对接口定义如下：接口原型：booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContain功能描述：产生密钥对参数：sDeviceSN[IN]设备序列号6sContainerName[IN]容器名称，应为可见字符，不能包含‘/‘字符，长度在1-32iKeyType[IN]密钥类型，3表示256位SM2密钥bSign[IN]签名或加密，TRUE表示签名，FALSE表示加密返回值：成功返回TRUE,失败返回FALSE备注：无5.5.2导出公钥导出公钥接口定义如下：功能描述：导出公钥参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称返回值：成功返回Base64编码的公钥，失败返回空备注：无5.5.3导出证书请求导出证书请求接口定义如下：接口原型：BSTRExportCertificationReq(BSTRsDeviceSN,BSTRsConta功能描述：导出证书请求参数：sDeviceSN设备序列号sContainerName[IN]容器名称SDN[IN]DN信息，如果DN项中有逗号(,),前边加上\进行转义返回值：成功返回Base64编码的证书请求，失败返回空备注：无5.5.4导入签名证书导入签名证书接口定义如下：功能描述：导入签名证书参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称sCert[IN]Base64编码的签名证书返回值：成功返回TRUE,失败返回FALSE备注：无5.5.5导入加密证书和加密密钥对导入加密证书和加密密钥对接口定义如下：接口原型：booleanImportEncCert(BSTR功能描述：导入加密证书和加密密钥对参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称7DB11/T254.2—2018sCert[IN]Base64编码的加密证书sPriKeyCipher[IN]Base64编码的加密密钥密文返回值：成功返回TRUE,失败返回FALSE备注：无5.5.6数据签名数据签名接口定义如下：接口原型：BSTRSOF_SignData(BSTRCertID,BSTR功能描述：对数据进行数字签名。参数：CertID[IN]证书操作唯一标识InData[IN]签名原文返回值：成功返回Base64编码的签名值，失败返回空备注：签名结果应符合GM/T0009—2012中7.3的要求5.5.7数据验签数据验签接口定义如下：接口原型：booleanSOF_VerifySignedData(BSTRCert,BSTRInData,BSTRSignVal功能描述：验证数据签名。参数：Cert[IN]Base64编码的证书InData[IN]签名原文SignValue[IN]Base64编码的签名值返回值：成功返回TRUE,失败返回FALSE备注：无5.5.8数字信封加密数据数字信封加密数据接口定义如下：接口原型：BSTRSOF_EncryptData(BSTRCert,BSTRIndata)功能描述：产生数字信封Indata[IN]原始数据返回值：成功返回Base64编码的密文数据，失败返回空备注：使用临时产生的对称密钥加密数据，然后使用数字证书加密对称密钥(数字信封)。格式应符合GM/T0010—2012中第9章的要求5.5.9数字信封解密数据数字信封解密数据接口定义如下：接口原型：BSTRSOF_DecryptData(BSTRCertID,BSTRIndata)功能描述：解数字信封密参数：CertID[IN]证书操作唯一标识Indata[IN]Base64编码的密文数据返回值：成功返回明文数据，失败返回空备注：无5.5.10消息签名8消息签名接口定义如下：接口原型：BSTRSOF_SignMessage(shortdwFlag,BSTRCertID,BSTRInData)功能描述：对数据进行数字签名。参数：dwFlag[IN]标识是否Detached。0表示带原文，1表示不带原文。CertID[IN]证书操作唯一标识InData[IN]待签名的原始数据返回值：成功返回Base64编码的签名值，失败返回空备注：对字符串数据进行数字签名，格式应符合GM/T0012—2012中第8章的要求5.5.11验证消息签名验证消息签名接口定义如下：接口原型：booleanSOF_VerifySigned功能描述：对数据进行验证签名。参数：MessageData[IN]Base64编码的签名值。InData[IN]原始数据返回值：成功返回TRUE,失败返回FALSE备注：无5.5.12解析消息签名解析消息签名接口定义如下：接口原型：BSTRSOF_GetInfoFromSignedMessage(BSTRSignedMessage功能描述：解析消息签名包内的信息，包括：原文、签名值、签名证书等信息。参数：SignedMessage[IN]Base64编码的签名值。type[IN]类型，取值范围如下：1:原文2:签名者证书3:签名值返回值：成功返回解析的信息，失败返回空备注：无5.5.13产生随机数产生随机数接口定义如下：接口原型：BSTRSOF_GenRandom(LONGRandomLen)功能描述：产生随机数。参数：RandomLen[IN]随机数的长度。返回值：成功返回Base64编码的随机数，失败返回空备注：无5.5.14公钥加密数据公钥加密数据接口定义如下：接口原型：BSTRSOF_PubKeyEncrypt(BSTRsCert,功能描述：公钥加密数据9sInData[IN]原文数据正确返回Base64编码的密文数据，失败返回空无5.5.15私钥解密数据私钥解密数据接口定义如下：接口原型：BSTRSOF_PriKeyDecrypt(BSTRCert功能描述：私钥解密数据参数：CertID[IN]证书操作唯一标识sInData[IN]Base64编码的密文数据返回值：正确返回明文数据，失败返回空备注：无5.5.16对称加密数据对称加密数据接口定义如下：接口原型：BSTRSOF_SymEncryptData(功能描述：对称加密数据参数：sKey[IN]Base64编码的对称密钥返回值：正确返回Base64编码的密文数据，失败返回空备注：无5.5.17对称解密数据对称解密数据接口定义如下：接口原型：BSTRSOF_SymDecryptData(BSTRsKe功能描述：对称解密数据参数：sKey[IN]Base64编码的对称密钥返回值：正确返回明文数据，失败返回空备注：无5.5.18数据摘要数据摘要接口定义如下：接口原型：BSTRSOF_HashData(LONGhashAlg,BSTRsInData)功能描述：对数据做摘要参数：hashAlg[IN]摘要算法，应使用0x00000001,表示SM3算法sIndata[IN]原始数据返回值：正确返回Base64编码的数据，失败返回空备注：无5.6证书接口5.6.1获取证书用户列表获取证书用户列表接口定义如下：功能描述：获取已安装的证书用户列表。参数：无返回值：证书用户列表备注：返回的证书用户列表格式为：用户名1||CertID1&&&用户名2||CertID2&&&用户名3||CertID3&&&...。CertID是证书操作唯一标识，格式为容器名称/设备序列号。通过CertID可以找到唯一的签名证书、加密证书，并使用对应密钥。5.6.2导出用户签名证书导出用户签名证书接口定义如下：接口原型：BSTRSOF_ExportUserCert(BSTRCertID)功能描述：根据证书操作唯一标识获取Base64编码格式的签名证书。参数：CertID[IN]证书操作唯一标识返回值：成功返回Base64编码的签名证书，失败返回空备注：无5.6.3导出用户加密证书导出用户加密证书接口定义如下：接口原型：BSTRSOF_ExportExchangeUserCert(BSTRCertID)功能描述：根据证书操作唯一标识获取Base64编码格式的证书。参数：CertID[IN]证书操作唯一标识返回值：成功返回Base64编码的加密证书，失败返回空备注：无5.6.4验证证书有效性验证证书有效性接口定义如下：接口原型：LONGSOF_ValidateCert(BSTRBase64EncodeCert)功能描述：验证证书有效性参数：Base64EncodeCert[IN]Base64编码证书返回值：正确返回0失败返回其他值如下：4证书不被信任2超过有效期范围-3证书已作废-4证书已冻结备注：无5.6.5获取证书基本信息获取证书基本信息接口定义如下：功能描述：获取证书基本信息参数：Cert[IN]Base64编码的证书。Type[IN]信息类型返回值：成功返回证书的基本信息，失败返回空1证书版本号返回"V1"或"V2"或"V3"2证书序列号3证书类型返回"RSA"或"SM2"4颁发者国家名(C)多个用逗号(,)分割5颁发者组织名(0)多个用逗号(,)分割6颁发者部门名(OU)多个用逗号(,)分割9颁发者城市名(L)多个用逗号(,)分割11证书有效开始日期格式12证书有效结束日期格式13使用者国家名(C)多个用逗号(,)分割14使用者组织名(0)多个用逗号(,)分割15使用者部门名(OU)多个用逗号(,)分割16使用者省州名(ST)多个用逗号(,)分割18使用者城市名(L)多个用逗号(,)分割20证书公钥Base64编码格式23密钥用法证书中如果没有密钥用法扩展项返回"0",密钥用法为加密返回"1",密钥用法为签名返回"2”,密钥用法既有加密也有签名返回"334颁发者DN功能描述：根据OID获取证书的私有扩展信息返回值：成功返回对应的扩展信息，失败返回空备注：无接口原型：BSTRSOF_GetCertEntity(BSTRCert)功能描述：获取证书的唯一实体标识参数：Cert[IN]Base64编码的成功返回证书唯一实体标识，失败返回空无5.7通用接口5.7.1获