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

ICS35.240.30L70DB11DB11/T254.2—2018代替DB11/T254.2-2004第2部分：应用接口Part2:ApplicationProgra北京市质量技术监督局发布IDB11/T254.2—2018 III 12规范性引用文件 13术语和定义、缩略语 14结构组成 25政务数字证书应用接口定义 2附录A(规范性附录)政务数字证书应用接口错误代码定义和说明 附录B(资料性附录)政务数字证书典型调用示例 15DB11/T254.2—2018例(资料性附录)”;ⅢDB11/T254.2—2018DB11/T254.2—20181政务数字证书规范第2部分：应用接口GB/T25069—2010信息安CA证书认证机构(CertificationAuthority)CSP加密服务提供者(CryptographicServiceProvider)0ID对象标识符(ObjectIdentifier)2DB11/T254.2—2018应用层接口层政务数学证书应用应用层接口层政务数学证书应用机密性完整性不可否认性应用程序政务数字证书应用接口访问控制接口容器管理接口密码服务接口证书接口设备接口密码设备密钥密钥设备管理接口密钥3LONG:BSTR:(:)来分隔功能描述：根据索引获取设备的序列号功能描述：获取设备详细信息4DB11/T254.2—2018成功返回设备信息，失败返回空目前可支持的类型参数为：0x000000020x000000030x000000040x000000730x000000745.3访问控制接口设备标签设备空余空间设备序列号设备类型返回"RSA"或"SM2"获取证书密码重试次数设备类型返回"HARD"或"SOFT"对应动态库的名称CSP名称设备类型SM2设备返回"20"设备的VID_PID(16进制数据)5.3.1设备登录设备登录接口定义如下：功能描述：登录5.3.2设备登出设备登出接口定义如下：接口原型：booleanSOF_Logout(BSTRCertID)功能描述：退出登录参数：CertID[IN]证书操作唯一标识返回值：正确返回TRUE失败返回FALSE备注：无5.3.3获取口令重试次数获取口令重试次数接口定义如下：接口原型：LONGSOF_GetPinRetryCoun功能描述：获取证书口令重试次数参数：CertID[IN]证书操作唯一标识返回值：>0表示重试次数，=0表示证书口令已被锁死，必须解锁后才能使用<0表示获取重试次数失败备注：无5.3.4修改登录口令修改登录口令接口定义如下：DB11/T254.2—20185功能描述：修改证书口令参数：CertID[IN]证书操作唯一标识OIdPassWd[IN]原始口令，646位可显示字符NewPassWd[IN]新口令，6-46位可显示字符返回值：成功返回TRUE,失败返回FALSE备注：无5.4容器管理接口5.4.1获取容器数量获取容器数量接口定义如下：功能描述：获取容器数量参数：sDeviceSN[IN]设备序列号备注：无5.4.2获取所有容器名称获取所有容器名称接口定义如下：接口原型：BSTRSOF_GetAIIContainerName(BSTRsDeviceSN)功能描述：获取所有容器名称参数：sDeviceSN[IN]设备序列号返回值：成功返回所有容器名称，失败或设备内不存在容器时返回空。返回格式为使用“&”符号分隔的容器名，即<容器名>&<容器名>&<容器名>...备注：无5.4.3删除容器删除容器接口定义如下：接口原型：booleanDeleteContainer(BSTRsDeviceSN,BSTRsContainerName)功能描述：删除容器参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称返回值：成功返回TRUE,失败返回FALSE备注：调用本接口前必须已登录5.5密码服务接口5.5.1产生密钥对产生密钥对接口定义如下：接口原型：booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContainerName,LONGiKeyType,booleanbSign)功能描述：产生密钥对参数：sDeviceSN[IN]设备序列号DB11/T254.2—20186sContainerName[IN]容器名称，应为可见字符，不能包含‘/‘字符，长度在1-32之间iKeyType[IN]密钥类型，3表示256位SM2密钥bSign[IN]签名或加密，TRUE表示签名，FALSE表示加密返回值：成功返回TRUE,失败返回FALSE备注：无5.5.2导出公钥导出公钥接口定义如下：接口原型：BSTRExportPubKey(BSTRsDeviceSN,BSTRsContainerName,booleanbSign)功能描述：导出公钥参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称bSign[IN]签名或加密，TRUE表示签名公钥，FALSE表示加密公钥返回值：成功返回Base64编码的公钥，失败返回空备注：无5.5.3导出证书请求导出证书请求接口定义如下：接口原型：BSTRExportCertificationReq(BSTRsDeviceSN,BSTRsContainerName,BSTRsDN)功能描述：导出证书请求参数：sDeviceSN设备序列号sContainerName[IN]容器名称sDN[IN]DN信息，如果DN项中有逗号(,),前边加上\进行转义返回值：成功返回Base64编码的证书请求，失败返回空备注：无5.5.4导入签名证书导入签名证书接口定义如下：接口原型：booleanImportSignCert(BSTRsDeviceSN,BSTRsContainerName,BSTRsCert)功能描述：导入签名证书参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称sCert[IN]Base64编码的签名证书返回值：成功返回TRUE,失败返回FALSE备注：无5.5.5导入加密证书和加密密钥对导入加密证书和加密密钥对接口定义如下：接口原型：booleanImportEncCert(BSTRsDeviceSN,BSTRsContainerName,BSTRsCert,BSTRsPriKeyCipher)功能描述：导入加密证书和加密密钥对参数：sDeviceSN[IN]设备序列号sContainerName[IN]容器名称78接口原型：BSTRSOF_SignMessage(shortdwFIag,BSTRCertID,BSTRInData)功能描述：对数据进行数字签名。功能描述：对数据进行验证签名。接口原型：BSTRSOF_PubKeyEncrypt(BSTRsCert,功能描述：公钥加密数据9DB11/T254.2—2018sInData[IN]原文数据返回值：正确返回Base64编码的密文数据，失败返回空无5.5.15私钥解密数据私钥解密数据接口定义如下：接口原型：BSTRSOF_PriKeyDecrypt(BSTRCertID,BSTRsInData)功能描述：私钥解密数据参数：CertID[IN]证书操作唯一标识sInData[IN]Base64编码的密文数据返回值：正确返回明文数据，失败返回空备注：无5.5.16对称加密数据对称加密数据接口定义如下：接口原型：BSTRSOF_SymEncryptData(BSTRsKey,BSTRindata)功能描述：对称加密数据参数：sKey[IN]Base64编码的对称密钥indata[IN]原文数据返回值：正确返回Base64编码的密文数据，失败返回空备注：无5.5.17对称解密数据对称解密数据接口定义如下：接口原型：BSTRSOF_SymDecryptData(BSTRsKey,BSTRindata)功能描述：对称解密数据参数：sKey[IN]Base64编码的对称密钥indata[IN]Base64编码的密文返回值：正确返回明文数据，失败返回空备注：无5.5.18数据摘要数据摘要接口定义如下：接口原型：BSTRSOF_HashData(LONGhashAlg,BSTRsInData)功能描述：对数据做摘要参数：hashAIg[IN]摘要算法，应使用0×00000001,表示SM3算法sIndata[IN]原始数据返回值：正确返回Base64编码的数据，失败返回空备注：无5.6证书接口5.6.1获取证书用户列表获取证书用户列表接口定义如下：DB11/T254.2—2018接口原型：BSTRSOF_GetUserList()功能描述：获取已安装的证书用户列表。参数：无返回值：证书用户列表备注：返回的证书用户列表格式为：用户名1||CertID1&&&用户名2||CertID2&8&用户名3||CertID3&8&...。CertID是证书操作唯一标识，格式为容器名称/设备序列号。通过CertID可以找到唯一的签名证书、加密证书，并使用对应密钥。5.6.2导出用户签名证书导出用户签名证书接口定义如下：接口原型：BSTRSOF_ExportUserCert(BSTRCertID)参数：CertID[IN]证书操作唯一标识返回值：成功返回Base64编码的签名证书，失败返回空备注：无5.6.3导出用户加密证书导出用户加密证书接口定义如下：接口原型：BSTRSOF_ExportExchangeUserCert(BSTRCertID)参数：CertID[IN]证书操作唯一标识返回值：成功返回Base64编码的加密证书，失败返回空备注：无5.6.4验证证书有效性验证证书有效性接口定义如下：接口原型：LONGSOF_ValidateCert(BSTRBase64EncodeCert)功能描述：验证证书有效性参数：Base64EncodeCert[IN]Base64编码证书返回值：正确返回0失败返回其他值如下：4证书不被信任2超过有效期范围-3证书已作废-4证书已冻结-5证书未生效备注：无5.6.5获取证书基本信息获取证书基本信息接口定义如下：接口原型：BSTRSOF_GetCertInfo(BSTRCert,shortType)功能描述：获取证书基本信息参数：Cert[IN]Base64编码的证书。Type[IN]信息类型4颁发者国家名(C)多个用逗号(,)分割11证书有效开始日期格式12证书有效结束日期格式14使用者组织名(0)多个用逗号(,)分割19使用者EMAIL(E)多个用逗号(,)分割接口原型：BSTRSOF_GetCer功能描述：获取证书的唯一实体标识DB11/T254.2—2018备注：无5.7通用接口5.7.1获取最后一次出错的错误码获取最后一次出错的错误码接口定义如下：接口原型：LONGSOF_GetLastError()功能描述：获取最后一次出错的错误码参数：无备注：无5.7.2获取最后一次出错的错误描述获取最后一次出错的错误描述接口定义如下：接口原型：BSTRSOF_GetLastErrMsg()参数：无返回值：错误描述信息备注：无错误码(十进制)1设备序列错误(索引值错误)23456789错误码(十进制)DB11/T254(资料性附录)政务数字证书典型调用示例下面的示例用JavaScript语言展示了产生随机数的功能。在示例中，首先加载了一个命名为XTXApp的厂商自定义COM控件，调用控件的相应接口，完成产生随机数的功能。其它接口也可以遵照标准调用。<scriptlanguage=JavaScript>try{if(window.ActiveXObject){document.w