DB11-T254-2-2018政務數(shù)字證書規(guī)范第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發(fā)布2018-07-01實施北京市質量技術監(jiān)督局發(fā)布DB11/T 254.22018目次前言II引言III1范引文件1語定、略語1構2務字書用定義2附錄A（范附）政務字書用口誤代定和13附錄B（料附）政務字書型用15IDB11/T 254.22018前言

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

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

4、frastructure，PKI）核心的網(wǎng)絡身份認證體系和信息加密技術已成為業(yè)界廣泛認同的一種構造網(wǎng)絡身份信任體制的重要方 PKIPKIIIIDB11/T 254.22018政務數(shù)字證書規(guī)范 第 2 部分：應用接口范圍應用于電子商務領域的數(shù)字證書應用接口，也可參照本部分。下列文件對于本部分的應用是必不可少的。凡是注日期的引用文件，僅注日期的版本適用于本部分。凡是不注日期的引用文件，其最新版本（包括所有的修改單）適用于本部分。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政務數(shù)字證書應用身份認證政務數(shù)字證書應用身份認證機密性完整性不可否認性政務數(shù)字證書應用接口設備接口密碼設備.密鑰密鑰密鑰證書接口密碼服務接口容器管理接口訪問控制接口設備管理接口應用程序接口層圖1

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

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

8、(BSTRsDeviceSN)功能述：斷備否存在參數(shù)： sDeviceSNINTRUE，備 注 ： 無獲取設備詳細信息接口定義如下：接口型：BSTR GetDeviceInfo(BSTR sDeviceSN, LONGiType)功能述：取備細信息參數(shù)：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)功能述:錄參數(shù):CertIDIN書作一識也支只入備列。PassWdIN證口。 返回：確回TRUE，敗回備注：無設備登出接口定義如下：接口型：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設序號sContainerNameIN容器返回：功回TRUE，敗回FALSE 備注：用接前必已錄產Th產生密鑰對接口定義如下：接口型:booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContainerName,LONGiKeyType, boolean bSign)功能述:生鑰對參

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

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

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

14、IN證操唯識InDataIN返回:功回Base64碼簽值失回空備注:名果符合GM/T 00092012中7.3的求數(shù)據(jù)驗簽接口定義如下：接口型: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ù)，返回空備注:使用時產的對密加密據(jù),然使數(shù)字書加對稱鑰(字信)。格式應合GM/T 00102012中第章要求數(shù)字信封解密數(shù)據(jù)接口定義如下：接口型:BSTR SOF_DecryptData(BSTR CertID, BSTRIndata)功能述:數(shù)信密參數(shù):CertIDIN證操唯標識IndataINBase64返回:功回文數(shù)，敗回空備注：無7DB11/T 254.22018消息簽名接口定義如下：接口型：BSTR SOF_SignMessage(short dwFlag，BSTR CertID, BSTRInData)功能述：數(shù)進數(shù)字名。參數(shù)

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

17、rttype)功能述：解析息名內信，包：文簽值簽名書信。參數(shù)：SignedMessageINBase64碼簽值typeIN型值范如1：原文2：簽名者證書3：名返回：功回析的息失返空 備注：無產Th產生隨機數(shù)接口定義如下：接口型:BSTR SOF_GenRandom(LONGRandomLen)功能述:生機參數(shù):RandomLenIN隨數(shù)長。返回:功回Base64編的機，敗回備注：無公鑰加密數(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書作一標識sInDataINBase64返回:確回文數(shù)，敗回空備注：無對稱加密數(shù)據(jù)接口定義如下：接口型：BSTR SOF_SymEncryptData(BSTR sKey, BSTRindata)功能述：稱密參數(shù)：sKeyINBase64碼的稱indataIN文返回：確回Base64碼密數(shù)，返回空備注：無對稱解密數(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導出用戶簽名證書接口定義如下：接口型：BSTR SOF_ExportUserCert(BSTRCertID)功能述：根證操唯標獲取Base64編格的名證參數(shù)：CertIDIN書作標識 返回：功回Base64碼簽證，返回備注：無導出用戶加密證書接口定義如下：接口型：BSTR SOF_ExportExchangeUserCert(BSTR CertID) 功能述：據(jù)書作唯標獲Base64碼格的書參數(shù)：CertIDIN書作標識返回：功回Base64碼加證，返回空備注：無驗證證書有效性接口定義如下：接口

21、型：LONG SOF_ValidateCert(BSTRBase64EncodeCert)功能述：證書效性參數(shù)：Base64EncodeCertINBase64碼返回：確回0失敗回他如：-1證書不被信任-2超過有效期范圍-3證書已作廢-4證書已凍結-5證書未生效-6其他錯誤備注：無獲取證書基本信息接口定義如下：接口型:BSTR SOF_GetCertInfo(BSTR Cert, shortType)功能述:取書信息參數(shù):CertINBase64編證書TypeIN息型10DB11/T 254.22018返回:功回的基信，敗回空備注:前支證書息型數(shù)下：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 頒發(fā)者獲取證書擴展信息接口定義如下：接口型:BSTR SOF_GetCertInfoByOid(BSTR Cert, BSTROid)功能述:據(jù)OID獲證書私擴信息參數(shù):CertINBase64編證OidINOID串返回:功回的擴信，敗回空備注：無獲取證書唯一實

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

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