DB11-T254-2-2018政務(wù)數(shù)字證書規(guī)范第2部分：應(yīng)用接口

1、ICS 35.240.30L 70DB11北京市地方標(biāo)準(zhǔn)DB11/T254.22018DB11/T 254.2-20042Specification for digital certificate for government affairs Part 2: Application Programming Interface2018-04-04發(fā)布2018-07-01實(shí)施北京市質(zhì)量技術(shù)監(jiān)督局發(fā)布DB11/T 254.22018目次前言II引言III1范引文件1語定、略語1構(gòu)2務(wù)字書用定義2附錄A（范附）政務(wù)字書用口誤代定和13附錄B（料附）政務(wù)字書型用15IDB11/T 254.22018前言

2、本部分按照GB/T 1.12009給出的規(guī)則起草。DB11/T 254.22018政務(wù)數(shù)字證書規(guī)范分為兩個(gè)部分：第1部分：格式；第2部分：應(yīng)用接口。本部分為DB11/T 2542018的第2部分。DB11/T 政務(wù)數(shù)字證書規(guī)范 第GM/T 00202012第2章，引用了密碼行業(yè)標(biāo)準(zhǔn)；第4章，重新命名為“結(jié)構(gòu)組成”，并將接口的組成部分重新定義為設(shè)備管理接口、訪問控制接口、容器管理接口、密碼服務(wù)接口、證書接口和通用接口；第5章，按照第4章定義的結(jié)構(gòu)重新定義接口，新的接口采用COM接口形式，在第5章的內(nèi)容中，加入了符合密碼行業(yè)標(biāo)準(zhǔn)的接口，接口內(nèi)容參照了密碼行業(yè)的相關(guān)標(biāo)準(zhǔn)；刪除原附錄A“政務(wù)數(shù)字證書應(yīng)

3、用接口宏定義和說明”，改為“政務(wù)數(shù)字證書應(yīng)用接口錯(cuò)誤代碼定義和說明（規(guī)范性附錄）”，在其中給出了政務(wù)數(shù)字證書接口的錯(cuò)誤碼定義；刪除了原附錄B“政務(wù)證書應(yīng)用接口數(shù)據(jù)結(jié)構(gòu)定義和說明”，改為“政務(wù)數(shù)字證書典型調(diào)用示例（資料性附錄）”；刪除原附錄C“政務(wù)數(shù)字證書應(yīng)用接口錯(cuò)誤代碼定義和說明”；刪除原附錄D“政務(wù)數(shù)字證書典型應(yīng)用框架圖”；刪除原附錄E“政務(wù)數(shù)字證書典型應(yīng)用示例”。本部分由北京市經(jīng)濟(jì)和信息化委員會(huì)提出并歸口。本部分由北京市經(jīng)濟(jì)和信息化委員會(huì)組織實(shí)施。本部分主要起草人：潘鋒、劉惠剛、劉莎、姚世全、陳淑儀、高能、荊繼武、李述勝、李向鋒。DB11/T 254.22018引言（PublicKeyIn

4、frastructure，PKI）核心的網(wǎng)絡(luò)身份認(rèn)證體系和信息加密技術(shù)已成為業(yè)界廣泛認(rèn)同的一種構(gòu)造網(wǎng)絡(luò)身份信任體制的重要方 PKIPKIIIIDB11/T 254.22018政務(wù)數(shù)字證書規(guī)范 第 2 部分：應(yīng)用接口范圍應(yīng)用于電子商務(wù)領(lǐng)域的數(shù)字證書應(yīng)用接口，也可參照本部分。下列文件對(duì)于本部分的應(yīng)用是必不可少的。凡是注日期的引用文件，僅注日期的版本適用于本部分。凡是不注日期的引用文件，其最新版本（包括所有的修改單）適用于本部分。GB/T 250692010GM/T00092012SM2GM/T00102012SM2GB/T 250692010界定的以及下列術(shù)語和定義適用于本文件。3.1.1信任 t

5、rust信任縮略語下列縮略語適用于本部分：CA書證構(gòu)（Certification Authority） COM件象型（Component Object Model）CSP密務(wù)供（Cryptographic Service Provider） OID象識(shí)（Object Identifier）PKCS(thePublic-KeyCryptography Standard)1DB11/T 254.220181政務(wù)數(shù)字證書應(yīng)用身份認(rèn)證政務(wù)數(shù)字證書應(yīng)用身份認(rèn)證機(jī)密性完整性不可否認(rèn)性政務(wù)數(shù)字證書應(yīng)用接口設(shè)備接口密碼設(shè)備.密鑰密鑰密鑰證書接口密碼服務(wù)接口容器管理接口訪問控制接口設(shè)備管理接口應(yīng)用程序接口層圖1

6、數(shù)字書用數(shù)字證書應(yīng)用接口由以下幾個(gè)接口部分組成：設(shè)備管理接口：負(fù)責(zé)對(duì)所連接的密碼設(shè)備進(jìn)行管理、獲取密碼設(shè)備的信息；訪問控制接口：負(fù)責(zé)確認(rèn)用戶是否允許連接使用密碼設(shè)備，包括口令驗(yàn)證和修改口令等接口；容器管理接口：負(fù)責(zé)對(duì)所連接的密碼設(shè)備中的容器進(jìn)行管理；密碼服務(wù)接口：負(fù)責(zé)具體與密碼設(shè)備交互實(shí)現(xiàn)具體的密碼運(yùn)算，并將運(yùn)算結(jié)果返回給應(yīng)用程序；證書接口：負(fù)責(zé)數(shù)字證書的解析、證書信息的獲取、有效性檢查等功能；通用接口：負(fù)責(zé)提供通用類的處理功能。COMA， 使用JavaScriptBboolean：1（True）0（False）2DB11/T 254.22018LONG：BSTR：BSTROLECHAR獲取設(shè)

7、備數(shù)量接口定義如下：接口型：LONGGetDeviceCount()功能述：取前在的支的備量參數(shù)：無返回：備備注：無獲取有備列接定義下： 接口型：BSTRGetAllDeviceSN()功能述：獲當(dāng)存的支的所設(shè)的列，個(gè)設(shè)序號(hào)分(;)尾參數(shù)：無返回：有備列號(hào)組合備注：當(dāng)前在有備列例個(gè)設(shè)序號(hào)使半的冒號(hào)（:）來分隔根據(jù)索引獲取設(shè)備序列號(hào)接口定義如下：接口型：BSTR GetDeviceSNByIndex(LONGiIndex)功能述：據(jù)引取設(shè)的列號(hào)參數(shù)：iIndexIN引0開，能于前的設(shè)數(shù)量返回：功回備序號(hào)失返空備注：無判斷設(shè)備是否存在接口定義如下：接口型：boolean IsDeviceExist

8、(BSTRsDeviceSN)功能述：斷備否存在參數(shù)： sDeviceSNINTRUE，備 注 ： 無獲取設(shè)備詳細(xì)信息接口定義如下：接口型：BSTR GetDeviceInfo(BSTR sDeviceSN, LONGiType)功能述：取備細(xì)信息參數(shù)：sDeviceSNIN設(shè)備列號(hào)iTypeIN3DB11/T 254.22018返回：功回備信，敗回空備注：前支的類參為：0 x000000010 x000000020 x000000030 x00000004RSA或SM20 x000000050 x00000007HARD或SOFT0 x000000080 x00000009CSP0 x000

9、00073SM2200 x00000074VID_PID（16設(shè)備登錄接口定義如下：接口型:booleanSOF_Login(BSTR CertID, BSTRPassWd)功能述:錄參數(shù):CertIDIN書作一識(shí)也支只入備列。PassWdIN證口。 返回：確回TRUE，敗回備注：無設(shè)備登出接口定義如下：接口型：booleanSOF_Logout (BSTRCertID)功能述：退登錄參數(shù)：CertIDIN書作一返回：正返回TRUE 敗回FALSE 備注：無獲取口令重試次數(shù)接口定義如下：接口型：LONG SOF_GetPinRetryCount(BSTRCertID)功能述：獲證令重次數(shù)參數(shù)：

10、CertIDIN書作一返回：0示次數(shù)，=0表示證書口令已被鎖死，必須解鎖后才能使用&.備注：無刪除容器接口定義如下：接口型：boolean DeleteContainer(BSTR sDeviceSN, BSTRsContainerName)功能述：除器參數(shù)：sDeviceSNIN設(shè)序號(hào)sContainerNameIN容器返回：功回TRUE，敗回FALSE 備注：用接前必已錄產(chǎn)Th產(chǎn)生密鑰對(duì)接口定義如下：接口型:booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContainerName,LONGiKeyType, boolean bSign)功能述:生鑰對(duì)參

11、數(shù):sDeviceSNIN設(shè)序號(hào)5DB11/T 254.22018sContainerNameIN/1-32之間iKeyTypeIN3256位SM2密鑰bSignIN名加，TRUE示名，F(xiàn)ALSE加返回：功回TRUE，敗回FALSE備注：無導(dǎo)出公鑰接口定義如下：接口型:BSTR ExportPubKey(BSTR sDeviceSN, BSTR sContainerName, booleanbSign)功能述:出鑰參數(shù):sDeviceSNIN設(shè)序號(hào)sContainerNameINbSignIN示名鑰,FALSE示加公鑰返回:功回Base64碼公，敗空備注：無導(dǎo)出證書請(qǐng)求接口定義如下：接口型：B

12、STRExportCertificationReq(BSTRsDeviceSN,BSTRsContainerName,BSTRsDN)功能述：出書參數(shù)：sDeviceSN設(shè)序號(hào)sContainerNameINsDNINDNDN返回：功回Base64碼證請(qǐng)，返回空備注：無導(dǎo)入簽名證書接口定義如下：接口型:boolean ImportSignCert(BSTR sDeviceSN, BSTR sContainerName, BSTRsCert)功能述:入名參數(shù):sDeviceSNIN設(shè)序號(hào)sContainerNameINsCertINBase64返回:功回TRUE，敗回FALSE備注：無導(dǎo)入加密證

13、書和加密密鑰對(duì)接口定義如下：接口型:booleanImportEncCert(BSTRsDeviceSN,BSTRsContainerName,BSTRsCert,BSTR sPriKeyCipher)功能述:入密書和密鑰對(duì)參數(shù):sDeviceSNIN設(shè)序號(hào)sContainerNameIN6DB11/T 254.22018sCertINBase64編加密sPriKeyCipherINBase64編的密密返回:功回TRUE，敗回FALSE備注：無數(shù)據(jù)簽名接口定義如下：接口型:BSTR SOF_SignData(BSTR CertID, BSTRInData)功能述:數(shù)進(jìn)數(shù)字名。參數(shù):CertID

14、IN證操唯識(shí)InDataIN返回:功回Base64碼簽值失回空備注:名果符合GM/T 00092012中7.3的求數(shù)據(jù)驗(yàn)簽接口定義如下：接口型:boolean SOF_VerifySignedData(BSTR Cert, BSTR InData， BSTRSignValue)功能述:證據(jù)名。參數(shù):CertINBase64碼證InDataIN簽原文SignValueINBase64編的名返回:功回TRUE，敗回FALSE備注：無數(shù)字信封加密數(shù)據(jù)接口定義如下：接口型:BSTR SOF_EncryptData(BSTR Cert, BSTRIndata)功能述:生字封參數(shù):CertINBase64

15、編的證IndataIN原數(shù)據(jù)返回:功回Base64碼密數(shù)，返回空備注:使用時(shí)產(chǎn)的對(duì)密加密據(jù),然使數(shù)字書加對(duì)稱鑰(字信)。格式應(yīng)合GM/T 00102012中第章要求數(shù)字信封解密數(shù)據(jù)接口定義如下：接口型:BSTR SOF_DecryptData(BSTR CertID, BSTRIndata)功能述:數(shù)信密參數(shù):CertIDIN證操唯標(biāo)識(shí)IndataINBase64返回:功回文數(shù)，敗回空備注：無7DB11/T 254.22018消息簽名接口定義如下：接口型：BSTR SOF_SignMessage(short dwFlag，BSTR CertID, BSTRInData)功能述：數(shù)進(jìn)數(shù)字名。參數(shù)

16、：dwFlagIN標(biāo)識(shí)否Detached0帶原，1表不原CertIDINInDataIN返回：碼簽值失回空備注：字串據(jù)進(jìn)數(shù)簽，式符合GM/T001220128章要求驗(yàn)證消息簽名接口定義如下：接口型:boolean SOF_VerifySignedMessage(BSTR MessageData，BSTRInData)功能述:數(shù)進(jìn)驗(yàn)證名。參數(shù):MessageDataINBase64編的名值InDataIN原數(shù)據(jù)返回:功回TRUE，敗回FALSE備注：無解析消息簽名接口定義如下：接口型：BSTR SOF_GetInfoFromSignedMessage(BSTR SignedMessage，sho

17、rttype)功能述：解析息名內(nèi)信，包：文簽值簽名書信。參數(shù)：SignedMessageINBase64碼簽值typeIN型值范如1：原文2：簽名者證書3：名返回：功回析的息失返空 備注：無產(chǎn)Th產(chǎn)生隨機(jī)數(shù)接口定義如下：接口型:BSTR SOF_GenRandom(LONGRandomLen)功能述:生機(jī)參數(shù):RandomLenIN隨數(shù)長。返回:功回Base64編的機(jī)，敗回備注：無公鑰加密數(shù)據(jù)接口定義如下：接口型：BSTR SOF_PubKeyEncrypt(BSTR sCert, BSTRsInData)功能述：鑰密參數(shù)：sCertINBase64碼8DB11/T 254.22018sInD

18、ataIN返回：確回Base64碼密數(shù)，返回空備注：無私鑰解密數(shù)據(jù)接口定義如下：接口型:BSTR SOF_PriKeyDecrypt(BSTR CertID, BSTRsInData)功能述:鑰密參數(shù):CertIDIN書作一標(biāo)識(shí)sInDataINBase64返回:確回文數(shù)，敗回空備注：無對(duì)稱加密數(shù)據(jù)接口定義如下：接口型：BSTR SOF_SymEncryptData(BSTR sKey, BSTRindata)功能述：稱密參數(shù)：sKeyINBase64碼的稱indataIN文返回：確回Base64碼密數(shù)，返回空備注：無對(duì)稱解密數(shù)據(jù)接口定義如下：接口型：BSTR SOF_SymDecryptDa

19、ta(BSTR sKey, BSTRindata)功能述：稱密參數(shù)：sKeyINBase64碼的稱indataINBase64編的密文返回：確回文數(shù)，敗回空備注：無數(shù)據(jù)摘要接口定義如下：接口型：BSTR SOF_HashData(LONG hashAlg, BSTRsInData)功能述：數(shù)做要參數(shù)：hashAlgIN要法使用0 x00000001,示SM3算法sIndataIN返回：確回Base64碼數(shù)，敗空備注：無獲取證書用戶列表接口定義如下：9DB11/T 254.22018接口型：BSTRSOF_GetUserList()功能述：取安的證用列。參數(shù)：無返回：書戶備注： 返回的證書用戶列

20、表格式為：用戶名1|CertID1&用戶名2|CertID2&用戶名3|CertID3&CertID導(dǎo)出用戶簽名證書接口定義如下：接口型：BSTR SOF_ExportUserCert(BSTRCertID)功能述：根證操唯標(biāo)獲取Base64編格的名證參數(shù)：CertIDIN書作標(biāo)識(shí) 返回：功回Base64碼簽證，返回備注：無導(dǎo)出用戶加密證書接口定義如下：接口型：BSTR SOF_ExportExchangeUserCert(BSTR CertID) 功能述：據(jù)書作唯標(biāo)獲Base64碼格的書參數(shù)：CertIDIN書作標(biāo)識(shí)返回：功回Base64碼加證，返回空備注：無驗(yàn)證證書有效性接口定義如下：接口

21、型：LONG SOF_ValidateCert(BSTRBase64EncodeCert)功能述：證書效性參數(shù)：Base64EncodeCertINBase64碼返回：確回0失敗回他如：-1證書不被信任-2超過有效期范圍-3證書已作廢-4證書已凍結(jié)-5證書未生效-6其他錯(cuò)誤備注：無獲取證書基本信息接口定義如下：接口型:BSTR SOF_GetCertInfo(BSTR Cert, shortType)功能述:取書信息參數(shù):CertINBase64編證書TypeIN息型10DB11/T 254.22018返回:功回的基信，敗回空備注:前支證書息型數(shù)下：V1V2或 V3RSASM2(C)(O)(O

22、U(ST(CN(L) 多個(gè)用逗號(hào)(,)分割10 EMAIL(E) 多個(gè)用逗號(hào)(,)分割11YYYYMMDDHHMMSS 12 YYYYMMDDHHMMSS 13 (C)14 使(O)15 使用(OU16 使用(ST17 使用(CN18 使用(L)19 使用者EMAIL(E) 多個(gè)用逗號(hào)(,)分割20鑰 Base642”3 33DN34 頒發(fā)者獲取證書擴(kuò)展信息接口定義如下：接口型:BSTR SOF_GetCertInfoByOid(BSTR Cert, BSTROid)功能述:據(jù)OID獲證書私擴(kuò)信息參數(shù):CertINBase64編證OidINOID串返回:功回的擴(kuò)信，敗回空備注：無獲取證書唯一實(shí)

23、體標(biāo)識(shí)接口定義如下：接口型：BSTR SOF_GetCertEntity(BSTRCert)功能述：取書唯一體識(shí)參數(shù)：CertINBase64編的證書11DB11/T 254.22018返回：功回書唯實(shí)標(biāo)，敗回空備注：無獲取后次錯(cuò)錯(cuò)碼接定如接口型：LONGSOF_GetLastError()功能述：取后次出的誤碼參數(shù)：無返回：誤。中0示常其表誤。誤定和明附錄A備注：無獲取后次錯(cuò)錯(cuò)描述口義下接口型：BSTRSOF_GetLastErrMsg()功能述：取后次出的誤述參數(shù)：無返回：誤述備注：無12DB11/T 254.22018附錄A（規(guī)范性附錄）政務(wù)數(shù)字證書應(yīng)用接口錯(cuò)誤代碼定義和說明A.1政務(wù)數(shù)

24、字證書應(yīng)用接口錯(cuò)誤代碼定義和說明見表A.1。表A.1務(wù)字書用接錯(cuò)代定和錯(cuò)誤碼(十進(jìn)制）描述1設(shè)備序列錯(cuò)誤（索引值錯(cuò)誤）2設(shè)備序列號(hào)長度錯(cuò)誤3打開設(shè)備錯(cuò)誤4打開應(yīng)用錯(cuò)誤5沒有打開設(shè)備6Pin碼長度錯(cuò)誤7校驗(yàn)口令失敗8獲取Pin碼重試次數(shù)錯(cuò)誤9修改管理員口令失敗10修改用戶口令失敗11解鎖用戶口令失敗12容器名稱長度錯(cuò)誤13創(chuàng)建容器失敗14產(chǎn)生密鑰對(duì)失敗15打開容器失敗16導(dǎo)出公鑰失敗17尚未登錄18導(dǎo)入證書失敗19容器類型錯(cuò)誤20ENVSN為空21寫入ENVSN失敗22讀取ENVSN失敗23獲取容器數(shù)量失敗24刪除容器失敗25判斷容器是否存在失敗26獲取設(shè)備序列號(hào)失敗27導(dǎo)入證書時(shí)，證書中的公鑰和設(shè)備容器中的公鑰不匹配28Base64編碼失敗29Base64解碼失敗30解析字符串失敗13DB11/T 254.22018表 A.1 政務(wù)數(shù)字證書應(yīng)用接口錯(cuò)誤代碼定義和說明（續(xù)）錯(cuò)誤碼(十進(jìn)制）描述31產(chǎn)生隨機(jī)數(shù)失敗32設(shè)置明文對(duì)稱密鑰失敗33加密或解密初始化失敗34對(duì)稱加密失敗35認(rèn)證設(shè)備密鑰失敗36刪除應(yīng)用失敗37創(chuàng)建應(yīng)用失敗38創(chuàng)