DB11/T254.2第2部分：應(yīng)用接口SpecificationfordigitalPart2:ApplicationProgrammingInterface北京市質(zhì)量技術(shù)監(jiān)督局發(fā)布I I1 12規(guī)范性引用文件 13術(shù)語和定義、縮略語 14結(jié)構(gòu)組成 25政務(wù)數(shù)字證書應(yīng)用接口定義 2附錄A(規(guī)范性附錄)政務(wù)數(shù)字證書應(yīng)用接口錯誤代碼定義和說明 附錄B(資料性附錄)政務(wù)數(shù)字證書典型調(diào)用示例 本部分按照GB/T1.1-2009給出的規(guī)則起草。DB11/T254.2—2018《政務(wù)數(shù)字證書規(guī)范》分為兩個部分：——第1部分：格式；——第2部分：應(yīng)用接口。本部分為DB11/T254—2018的第2部分。本部分代替DB11/T254.2—2004《政務(wù)數(shù)字證書規(guī)范第2部分：應(yīng)用接口》。本部分根據(jù)電子政務(wù)中數(shù)字證書接口的使用情況，對原有標(biāo)準(zhǔn)的內(nèi)容進(jìn)行了結(jié)構(gòu)上的調(diào)整，重新定義了接口的架構(gòu)和接口的形式。新的接口以GM/T0020—2012《證書應(yīng)用綜合服務(wù)接口規(guī)范》中的定義為主，并加入法人一證通項目實施所需的擴展接口。詳細(xì)修訂包括：——第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)用接口宏定義和說明”,改為“政務(wù)數(shù)字證書應(yīng)用接口錯誤代碼定義和說明(規(guī)范性附錄)",在其中給出了政務(wù)數(shù)字證書接口的錯誤碼定義；——刪除了原附錄B“政務(wù)證書應(yīng)用接口數(shù)據(jù)結(jié)構(gòu)定義和說明”,改為“政務(wù)數(shù)字證書典型調(diào)用示例(資料性附錄)";——刪除原附錄C“政務(wù)數(shù)字證書應(yīng)用接口錯誤代碼定義和說明”;——刪除原附錄D“政務(wù)數(shù)字證書典型應(yīng)用框架圖”;——刪除原附錄E“政務(wù)數(shù)字證書典型應(yīng)用示例”。本部分由北京市經(jīng)濟(jì)和信息化委員會提出并歸口。本部分由北京市經(jīng)濟(jì)和信息化委員會組織實施。本部分主要起草單位：北京市經(jīng)濟(jì)和信息化委員會、北京數(shù)字認(rèn)證股份有限公司、中國科學(xué)院信息工程研究所、北京市國家保密局、北京市密碼管理局。本部分主要起草人：潘鋒、劉惠剛、劉莎、姚世全、陳淑儀、高能、荊繼武、李述勝、李向鋒。ⅢDB11/T254.2—2018信息技術(shù)和網(wǎng)絡(luò)技術(shù)在極大地促進(jìn)了社會的經(jīng)濟(jì)、科技、文化、教育和管理等各個方面發(fā)展的同時，也帶來了巨大的信息安全風(fēng)險。隨著北京市電子政務(wù)工程的不斷深入和發(fā)展，迫切需要在開放的網(wǎng)絡(luò)環(huán)境下建立一個真實、有效的身份信任體制，確認(rèn)電子政務(wù)參與方的各自身份，建立彼此間的信任關(guān)系以及保證信息的保密性、完整性和可用性。以公開密鑰基礎(chǔ)設(shè)施(PublicKeyInfrastructure,PKI)為核心的網(wǎng)絡(luò)身份認(rèn)證體系和信息加密技術(shù)已成為業(yè)界廣泛認(rèn)同的一種構(gòu)造網(wǎng)絡(luò)身份信任體制的重要方式，并成為信息安全保障體系中極其重要的組成部分之一。數(shù)字證書應(yīng)用接口是PKI技術(shù)應(yīng)用的關(guān)鍵和核心，是電子政務(wù)應(yīng)用系統(tǒng)使用和應(yīng)用PKI技術(shù)的橋梁。為了確保政務(wù)數(shù)字證書在電子政務(wù)信息的應(yīng)用中能夠通用，實現(xiàn)信息系統(tǒng)互聯(lián)互通，統(tǒng)一數(shù)字證書應(yīng)用接口規(guī)范，能夠有效降低數(shù)字證書應(yīng)用集成的復(fù)雜度，有助于更好形成統(tǒng)一的網(wǎng)絡(luò)信任體系。本部分定義了政務(wù)數(shù)字證書應(yīng)用的系統(tǒng)架構(gòu)，并定義了政務(wù)數(shù)字證書應(yīng)用的各種接口。1政務(wù)數(shù)字證書規(guī)范第2部分：應(yīng)用接口1范圍凡是不注日期的引用文件，其最新版本(包括所有的修改單)適用于本部分。GB/T25069—2010信息安全技術(shù)術(shù)語COM組件對象模型(ComponentObjectCSP加密服務(wù)提供者(CryptographicS0ID對象標(biāo)識符(ObjectIdentifier)4結(jié)構(gòu)組成24.1.1政務(wù)證書數(shù)字證書應(yīng)用的一般體系結(jié)構(gòu)，如圖1所示：政務(wù)數(shù)字證書應(yīng)用政務(wù)數(shù)字證書應(yīng)用工4.1.2政務(wù)數(shù)字證書應(yīng)用接口位于應(yīng)用層和密碼設(shè)備之間，應(yīng)用程序通過調(diào)用政務(wù)數(shù)字證書應(yīng)用接口數(shù)字證書應(yīng)用接口由以下幾個接口部分組成：——訪問控制接口：負(fù)責(zé)確認(rèn)用戶是否允許連接使用密碼設(shè)備，包括口令驗證和修——密碼服務(wù)接口：負(fù)責(zé)具體與密碼設(shè)備交互實現(xiàn)具體的密碼運算，并將運算結(jié)果返回給應(yīng)用程序；5.1類型說明3表示一個有符號長整數(shù)，其位數(shù)與取值范圍與特定的平臺有關(guān)。獲取設(shè)備數(shù)量接口定義如下：功能描述：獲取當(dāng)前存在的可支持的設(shè)備數(shù)量參數(shù)：無返回值：設(shè)備數(shù)量備注：無獲取所有設(shè)備序列號接口定義如下：功能描述：獲取當(dāng)前存在的可支持的所有設(shè)備的序列號，每個設(shè)備序列號以分號(;)結(jié)尾參數(shù)：無返回值：所有設(shè)備序列號的組合備注：當(dāng)前存在所有設(shè)備序列號，例如"11111;22222;",各個設(shè)備序列號間使用半角的冒號(:)來分隔根據(jù)索引獲取設(shè)備序列號接口定義如下：接口原型：BSTRGetDeviceSNByIn功能描述：根據(jù)索引獲取設(shè)備的序列號參數(shù)：ilndex[IN]索引，從0開始，不能大于當(dāng)前存在的設(shè)備數(shù)量返回值：成功返回設(shè)備序列號，失敗返回空備注：無判斷設(shè)備是否存在接口定義如下：功能描述：判斷設(shè)備是否存在參數(shù)：sDeviceSN[IN]設(shè)備序列號備注：無獲取設(shè)備詳細(xì)信息接口定義如下：功能描述：獲取設(shè)備詳細(xì)信息參數(shù)：sDeviceSN[IN]設(shè)備序列號iType[IN]信息類型4成功返回設(shè)備信息，失敗返回空目前可支持的類型參數(shù)為：5.3訪問控制接口5.3.1設(shè)備登錄設(shè)備標(biāo)簽設(shè)備空余空間設(shè)備序列號設(shè)備類型返回"RSA"或"SM2"獲取證書密碼重試次數(shù)設(shè)備類型返回"HARD"或"SOFT"對應(yīng)動態(tài)庫的名稱CSP名稱設(shè)備類型SM2設(shè)備返回"20"設(shè)備的VID_PID(16進(jìn)制數(shù)據(jù))設(shè)備登錄接口定義如下：接口原型：booleanSOF_Login(BSTRC功能描述：登錄參數(shù)：CertID[IN]證書操作唯一標(biāo)識，也支持只輸入設(shè)備序列號。PassWd[IN]證書口令。返回值：正確返回TRUE,失敗返回FALSE備注：無5.3.2設(shè)備登出設(shè)備登出接口定義如下：功能描述：退出登錄參數(shù)：CertID[IN]證書操作唯一標(biāo)識返回值：正確返回TRUE失敗返回FALSE備注：無5.3.3獲取口令重試次數(shù)獲取口令重試次數(shù)接口定義如下：功能描述：獲取證書口令重試次數(shù)參數(shù)：CertID[IN]證書操作唯一標(biāo)識返回值：>0表示重試次數(shù)，=0表示證書口令已被鎖死，必須解鎖后才能使用<0表示獲取重試次數(shù)失敗備注：無5.3.4修改登錄口令修改登錄口令接口定義如下：5功能描述：修改證書口令參數(shù)：CertID[IN]證書操作唯一標(biāo)識0ldPassWd[IN]原始口令，6-46位可顯示字符NewPassWd[IN]新口令，6-46位可顯示字符返回值：成功返回TRUE,失敗返回FALSE備注：無5.4容器管理接口5.4.1獲取容器數(shù)量獲取容器數(shù)量接口定義如下：接口原型：LONGGetContainerCount(BSTRsDeviceSN)功能描述：獲取容器數(shù)量參數(shù)：sDeviceSN[IN]設(shè)備序列號返回值：成功返回容器數(shù)量，失敗返回負(fù)數(shù)備注：無5.4.2獲取所有容器名稱獲取所有容器名稱接口定義如下：功能描述：獲取所有容器名稱參數(shù)：sDeviceSN[IN]設(shè)備序列號返回值：成功返回所有容器名稱，失敗或設(shè)備內(nèi)不存在容器時返回空。返回格式為使用“&”符號分隔的容器名，即<容器名>&<容器名>&<容器名>...備注：無5.4.3刪除容器刪除容器接口定義如下：接口原型：booleanDeleteCo功能描述：刪除容器參數(shù)：sDeviceSN[IN]設(shè)備序列號sContainerName[IN]容器名稱返回值：成功返回TRUE,失敗返回FALSE備注：調(diào)用本接口前必須已登錄5.5密碼服務(wù)接口5.5.1產(chǎn)生密鑰對產(chǎn)生密鑰對接口定義如下：接口原型：booleanGenerateKeyPair(BSTRsDeviceSN,BSTRsContain功能描述：產(chǎn)生密鑰對參數(shù)：sDeviceSN[IN]設(shè)備序列號6sContainerName[IN]容器名稱，應(yīng)為可見字符，不能包含‘/‘字符，長度在1-32iKeyType[IN]密鑰類型，3表示256位SM2密鑰bSign[IN]簽名或加密，TRUE表示簽名，F(xiàn)ALSE表示加密返回值：成功返回TRUE,失敗返回FALSE備注：無5.5.2導(dǎo)出公鑰導(dǎo)出公鑰接口定義如下：功能描述：導(dǎo)出公鑰參數(shù)：sDeviceSN[IN]設(shè)備序列號sContainerName[IN]容器名稱返回值：成功返回Base64編碼的公鑰，失敗返回空備注：無5.5.3導(dǎo)出證書請求導(dǎo)出證書請求接口定義如下：接口原型：BSTRExportCertificationReq(BSTRsDeviceSN,BSTRsConta功能描述：導(dǎo)出證書請求參數(shù)：sDeviceSN設(shè)備序列號sContainerName[IN]容器名稱SDN[IN]DN信息，如果DN項中有逗號(,),前邊加上\進(jìn)行轉(zhuǎn)義返回值：成功返回Base64編碼的證書請求，失敗返回空備注：無5.5.4導(dǎo)入簽名證書導(dǎo)入簽名證書接口定義如下：功能描述：導(dǎo)入簽名證書參數(shù)：sDeviceSN[IN]設(shè)備序列號sContainerName[IN]容器名稱sCert[IN]Base64編碼的簽名證書返回值：成功返回TRUE,失敗返回FALSE備注：無5.5.5導(dǎo)入加密證書和加密密鑰對導(dǎo)入加密證書和加密密鑰對接口定義如下：接口原型：booleanImportEncCert(BSTR功能描述：導(dǎo)入加密證書和加密密鑰對參數(shù)：sDeviceSN[IN]設(shè)備序列號sContainerName[IN]容器名稱7DB11/T254.2—2018sCert[IN]Base64編碼的加密證書sPriKeyCipher[IN]Base64編碼的加密密鑰密文返回值：成功返回TRUE,失敗返回FALSE備注：無5.5.6數(shù)據(jù)簽名數(shù)據(jù)簽名接口定義如下：接口原型：BSTRSOF_SignData(BSTRCertID,BSTR功能描述：對數(shù)據(jù)進(jìn)行數(shù)字簽名。參數(shù)：CertID[IN]證書操作唯一標(biāo)識InData[IN]簽名原文返回值：成功返回Base64編碼的簽名值，失敗返回空備注：簽名結(jié)果應(yīng)符合GM/T0009—2012中7.3的要求5.5.7數(shù)據(jù)驗簽數(shù)據(jù)驗簽接口定義如下：接口原型：booleanSOF_VerifySignedData(BSTRCert,BSTRInData,BSTRSignVal功能描述：驗證數(shù)據(jù)簽名。參數(shù)：Cert[IN]Base64編碼的證書InData[IN]簽名原文SignValue[IN]Base64編碼的簽名值返回值：成功返回TRUE,失敗返回FALSE備注：無5.5.8數(shù)字信封加密數(shù)據(jù)數(shù)字信封加密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_EncryptData(BSTRCert,BSTRIndata)功能描述：產(chǎn)生數(shù)字信封Indata[IN]原始數(shù)據(jù)返回值：成功返回Base64編碼的密文數(shù)據(jù)，失敗返回空備注：使用臨時產(chǎn)生的對稱密鑰加密數(shù)據(jù)，然后使用數(shù)字證書加密對稱密鑰(數(shù)字信封)。格式應(yīng)符合GM/T0010—2012中第9章的要求5.5.9數(shù)字信封解密數(shù)據(jù)數(shù)字信封解密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_DecryptData(BSTRCertID,BSTRIndata)功能描述：解數(shù)字信封密參數(shù)：CertID[IN]證書操作唯一標(biāo)識Indata[IN]Base64編碼的密文數(shù)據(jù)返回值：成功返回明文數(shù)據(jù)，失敗返回空備注：無5.5.10消息簽名8消息簽名接口定義如下：接口原型：BSTRSOF_SignMessage(shortdwFlag,BSTRCertID,BSTRInData)功能描述：對數(shù)據(jù)進(jìn)行數(shù)字簽名。參數(shù)：dwFlag[IN]標(biāo)識是否Detached。0表示帶原文，1表示不帶原文。CertID[IN]證書操作唯一標(biāo)識InData[IN]待簽名的原始數(shù)據(jù)返回值：成功返回Base64編碼的簽名值，失敗返回空備注：對字符串?dāng)?shù)據(jù)進(jìn)行數(shù)字簽名，格式應(yīng)符合GM/T0012—2012中第8章的要求5.5.11驗證消息簽名驗證消息簽名接口定義如下：接口原型：booleanSOF_VerifySigned功能描述：對數(shù)據(jù)進(jìn)行驗證簽名。參數(shù)：MessageData[IN]Base64編碼的簽名值。InData[IN]原始數(shù)據(jù)返回值：成功返回TRUE,失敗返回FALSE備注：無5.5.12解析消息簽名解析消息簽名接口定義如下：接口原型：BSTRSOF_GetInfoFromSignedMessage(BSTRSignedMessage功能描述：解析消息簽名包內(nèi)的信息，包括：原文、簽名值、簽名證書等信息。參數(shù)：SignedMessage[IN]Base64編碼的簽名值。type[IN]類型，取值范圍如下：1:原文2:簽名者證書3:簽名值返回值：成功返回解析的信息，失敗返回空備注：無5.5.13產(chǎn)生隨機數(shù)產(chǎn)生隨機數(shù)接口定義如下：接口原型：BSTRSOF_GenRandom(LONGRandomLen)功能描述：產(chǎn)生隨機數(shù)。參數(shù)：RandomLen[IN]隨機數(shù)的長度。返回值：成功返回Base64編碼的隨機數(shù)，失敗返回空備注：無5.5.14公鑰加密數(shù)據(jù)公鑰加密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_PubKeyEncrypt(BSTRsCert,功能描述：公鑰加密數(shù)據(jù)9sInData[IN]原文數(shù)據(jù)正確返回Base64編碼的密文數(shù)據(jù)，失敗返回空無5.5.15私鑰解密數(shù)據(jù)私鑰解密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_PriKeyDecrypt(BSTRCert功能描述：私鑰解密數(shù)據(jù)參數(shù)：CertID[IN]證書操作唯一標(biāo)識sInData[IN]Base64編碼的密文數(shù)據(jù)返回值：正確返回明文數(shù)據(jù)，失敗返回空備注：無5.5.16對稱加密數(shù)據(jù)對稱加密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_SymEncryptData(功能描述：對稱加密數(shù)據(jù)參數(shù)：sKey[IN]Base64編碼的對稱密鑰返回值：正確返回Base64編碼的密文數(shù)據(jù)，失敗返回空備注：無5.5.17對稱解密數(shù)據(jù)對稱解密數(shù)據(jù)接口定義如下：接口原型：BSTRSOF_SymDecryptData(BSTRsKe功能描述：對稱解密數(shù)據(jù)參數(shù)：sKey[IN]Base64編碼的對稱密鑰返回值：正確返回明文數(shù)據(jù)，失敗返回空備注：無5.5.18數(shù)據(jù)摘要數(shù)據(jù)摘要接口定義如下：接口原型：BSTRSOF_HashData(LONGhashAlg,BSTRsInData)功能描述：對數(shù)據(jù)做摘要參數(shù)：hashAlg[IN]摘要算法，應(yīng)使用0x00000001,表示SM3算法sIndata[IN]原始數(shù)據(jù)返回值：正確返回Base64編碼的數(shù)據(jù)，失敗返回空備注：無5.6證書接口5.6.1獲取證書用戶列表獲取證書用戶列表接口定義如下：功能描述：獲取已安裝的證書用戶列表。參數(shù)：無返回值：證書用戶列表備注：返回的證書用戶列表格式為：用戶名1||CertID1&&&用戶名2||CertID2&&&用戶名3||CertID3&&&...。CertID是證書操作唯一標(biāo)識，格式為容器名稱/設(shè)備序列號。通過CertID可以找到唯一的簽名證書、加密證書，并使用對應(yīng)密鑰。5.6.2導(dǎo)出用戶簽名證書導(dǎo)出用戶簽名證書接口定義如下：接口原型：BSTRSOF_ExportUserCert(BSTRCertID)功能描述：根據(jù)證書操作唯一標(biāo)識獲取Base64編碼格式的簽名證書。參數(shù)：CertID[IN]證書操作唯一標(biāo)識返回值：成功返回Base64編碼的簽名證書，失敗返回空備注：無5.6.3導(dǎo)出用戶加密證書導(dǎo)出用戶加密證書接口定義如下：接口原型：BSTRSOF_ExportExchangeUserCert(BSTRCertID)功能描述：根據(jù)證書操作唯一標(biāo)識獲取Base64編碼格式的證書。參數(shù)：CertID[IN]證書操作唯一標(biāo)識返回值：成功返回Base64編碼的加密證書，失敗返回空備注：無5.6.4驗證證書有效性驗證證書有效性接口定義如下：接口原型：LONGSOF_ValidateCert(BSTRBase64EncodeCert)功能描述：驗證證書有效性參數(shù)：Base64EncodeCert[IN]Base64編碼證書返回值：正確返回0失敗返回其他值如下：4證書不被信任2超過有效期范圍-3證書已作廢-4證書已凍結(jié)備注：無5.6.5獲取證書基本信息獲取證書基本信息接口定義如下：功能描述：獲取證書基本信息參數(shù)：Cert[IN]Base64編碼的證書。Type[IN]信息類型返回值：成功返回證書的基本信息，失敗返回空1證書版本號返回"V1"或"V2"或"V3"2證書序列號3證書類型返回"RSA"或"SM2"4頒發(fā)者國家名(C)多個用逗號(,)分割5頒發(fā)者組織名(0)多個用逗號(,)分割6頒發(fā)者部門名(OU)多個用逗號(,)分割9頒發(fā)者城市名(L)多個用逗號(,)分割11證書有效開始日期格式12證書有效結(jié)束日期格式13使用者國家名(C)多個用逗號(,)分割14使用者組織名(0)多個用逗號(,)分割15使用者部門名(OU)多個用逗號(,)分割16使用者省州名(ST)多個用逗號(,)分割18使用者城市名(L)多個用逗號(,)分割20證書公鑰Base64編碼格式23密鑰用法證書中如果沒有密鑰用法擴展項返回"0",密鑰用法為加密返回"1",密鑰用法為簽名返回"2”,密鑰用法既有加密也有簽名返回"334頒發(fā)者DN功能描述：根據(jù)OID獲取證書的私有擴展信息返回值：成功返回對應(yīng)的擴展信息，失敗返回空備注：無接口原型：BSTRSOF_GetCertEntity(BSTRCert)功能描述：獲取證書的唯一實體標(biāo)識參數(shù)：Cert[IN]Base64編碼的成功返回證書唯一實體標(biāo)識，失敗返回空無5.7通用接口5.7.1獲