GM-T 0067-2019 清晰版 基于數(shù)字證書的身份鑒別接口規(guī)范

ICS35.040L80中華人民共和國密碼行業(yè)標(biāo)準(zhǔn)基于數(shù)字證書的身份鑒別接口規(guī)范I2019-07-12發(fā)布2019-07-12實施國家密碼管理局發(fā)布GM／T0067—2019前言 2規(guī)范性引用文件 3術(shù)語和定義 4縮略語 5實現(xiàn)方式 5.2代理身份鑒別模式 6算法標(biāo)識與數(shù)據(jù)結(jié)構(gòu) 6.1算法標(biāo)識定義 6.2數(shù)據(jù)結(jié)構(gòu)定義和說明 7接口定義及函數(shù) 7.1身份鑒別接口在公鑰密碼基礎(chǔ)設(shè)施應(yīng)用技術(shù)體系框架中的位置 7.2身份鑒別接口邏輯結(jié)構(gòu) 7.4函數(shù)接口定義 附錄A（規(guī)范性附錄）錯誤代碼定義和說明 附錄B（資料性附錄）身份鑒別應(yīng)用流程示例 參考文獻(xiàn) ⅠGM／T0067—2019本標(biāo)準(zhǔn)以GB/T15843.3—2016《信息技術(shù)安全技術(shù)實體鑒別第3部分：采用數(shù)字簽名技術(shù)的機制》為依據(jù)，規(guī)范了基于數(shù)字證書的身份鑒別密碼應(yīng)用接口。請注意本文件的某些內(nèi)容可能涉及專利。本文件的發(fā)布機構(gòu)不承擔(dān)識別這些專利的責(zé)任。本標(biāo)準(zhǔn)由密碼行業(yè)標(biāo)準(zhǔn)化技術(shù)委員會提出并歸口。本標(biāo)準(zhǔn)所使用的密碼算法遵從國家密碼管理主管部門公布的相關(guān)密碼算法。本標(biāo)準(zhǔn)主要起草單位：格爾軟件股份有限公司、上海市數(shù)字證書認(rèn)證中心有限公司、山東得安計算機技術(shù)有限公司、北京海泰方圓科技有限公司、成都衛(wèi)士通信息產(chǎn)業(yè)股份有限公司、北京數(shù)字證書認(rèn)證中心有限公司、國民技術(shù)股份有限公司、長春吉大正元信息技術(shù)股份有限公司。1GM／T0067—2019基于數(shù)字證書的身份鑒別接口規(guī)范本標(biāo)準(zhǔn)規(guī)定了公鑰密碼基礎(chǔ)設(shè)施體系上層應(yīng)用中基于數(shù)字證書的身份鑒別接口。本標(biāo)準(zhǔn)適用于公鑰密碼基礎(chǔ)設(shè)施體系上層應(yīng)用中身份鑒別服務(wù)的開發(fā)、證書應(yīng)用支撐平臺身份鑒別系統(tǒng)的研制及檢測，也可用于指導(dǎo)應(yīng)用系統(tǒng)規(guī)范化地使用證書進(jìn)行身份鑒別。2規(guī)范性引用文件下列文件對于本文件的應(yīng)用是必不可少的。凡是注日期的引用文件，僅注日期的版本適用于本文件，凡是不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T15843.1—2017信息技術(shù)安全技術(shù)實體鑒別第1部分：概述GB/T15843.3—2016信息技術(shù)安全技術(shù)實體鑒別第3部分：采用數(shù)字簽名技術(shù)的機制3術(shù)語和定義下列術(shù)語和定義適用于本文件。3.1證書認(rèn)證系統(tǒng)對數(shù)字證書的簽發(fā)、發(fā)布、更新、撤銷等數(shù)字證書全生命周期進(jìn)行管理的系統(tǒng)。3.2證書撤消列表由證書認(rèn)證機構(gòu)簽發(fā)并發(fā)布的被撤銷證書的列表。3.3證書驗證按照驗證策略確認(rèn)證書有效性和真實性的過程。3.4數(shù)字證書也稱公鑰證書，由證書認(rèn)證機構(gòu)(CA)簽名的包含公開密鑰擁有者信息、公開密鑰、簽發(fā)者信息、有效期以及擴展信息的一種數(shù)據(jù)結(jié)構(gòu)。按類別可分為個人證書、機構(gòu)證書和設(shè)備證書，按用途可分為簽名證書和加密證書。3.5用戶憑證能夠表明用戶身份的一段特定數(shù)據(jù)，用戶通過向另一方提交此數(shù)據(jù)來表明自己的身份，此數(shù)據(jù)具有不可抵賴性和可驗證性。3.6雙向驗證向雙方實體提供對方身份保證的實體鑒別。2GM／T0067—20193.7公鑰基礎(chǔ)設(shè)施基于公鑰密碼技術(shù)實施的具有普適性的基礎(chǔ)設(shè)施，可用于提供機密性、完整性、真實性及抗抵賴性等安全服務(wù)。3.8算法一種橢圓曲線公鑰密碼算法，其密鑰長度為256比特。3.9算法一種密碼雜湊算法，其輸出為256比特。4縮略語下列縮略語適用于本文件。證書認(rèn)證機構(gòu)(通用名(證書撤銷列表(可識別名(輕量級目錄訪問協(xié)議(對象標(biāo)識符(公鑰密碼基礎(chǔ)設(shè)施(5實現(xiàn)方式身份鑒別實現(xiàn)方式包括代理身份鑒別模式和調(diào)用模式，身份鑒別T與應(yīng)用B是相互信任的整體，這兩種模式下使用的身份鑒別機制遵循GB/T15843.3—2016。5.2代理身份鑒別模式在這種模式下，由代理身份鑒別服務(wù)T對用戶A的身份進(jìn)行鑒別，然后把鑒別的結(jié)果傳遞給應(yīng)用B,這種身份鑒別模式稱為代理身份模式，一般采用消息方式來實現(xiàn)。鑒別協(xié)議在用戶A和代理身份鑒別服務(wù)T間進(jìn)行，這種模式下，用戶A啟動過程并由代理身份鑒別服務(wù)T對它進(jìn)行鑒別，唯一性和時效性是通過產(chǎn)生并檢驗時間戳或序號（見GB/T15843.1—2017的附錄B)來控制的。代理模式下的單向身份鑒別機制如圖1所示。圖1代理模式下單向身份鑒別機制3GM／T0067—2019用戶A發(fā)送證書和為用戶A向代理身份鑒別服務(wù)T發(fā)的憑證，其形式參見GB/T15843.3—2016中的5.2.2)給代理身份鑒別服務(wù)T;b)代理身份鑒別服務(wù)T在接收到含有的消息時，執(zhí)行下列步驟：1)驗證A的證書有效性，包括有效期、是否可信機構(gòu)頒發(fā)、證書狀態(tài)，以及證書密鑰用法驗證等；驗證c)代理身份鑒別服務(wù)T將驗證通過的A的身份傳遞給應(yīng)用B。代理身份鑒別模式下的雙向身份鑒別機制如圖2所示。圖2代理模式下雙向身份鑒別機制用戶的形式參見中的給代理身份鑒別服務(wù)T;b)代理身份鑒別服務(wù)T在接收到含有的消息時，執(zhí)行下列步驟：1)驗證A的證書有效性，包括有效期，是否可信機構(gòu)頒發(fā)、證書狀態(tài)，以及證書密鑰用法驗證；驗證發(fā)送的證書和的形式參見在接收到含有的消息時，用戶A執(zhí)行下列步驟：1)驗證T的證書有效性，包括有效期，是否可信機構(gòu)頒發(fā)，是否在黑名單內(nèi)，以及證書密鑰用法驗證；驗證e)代理身份鑒別服務(wù)T將驗證通過的A的身份傳遞給應(yīng)用B。對于應(yīng)用獲取到用戶身份后，主動調(diào)用身份鑒別服務(wù)的對外服務(wù)接口進(jìn)行身份鑒別以獲取身份鑒別結(jié)果的模式，稱為調(diào)用模式，一般采用接口函數(shù)實現(xiàn)。GB/T15843.1—2017的附錄B)來控制鑒別協(xié)議的唯一性和時效性。驗證機制如圖3所示：4GM／T0067—2019圖3調(diào)用模式下的身份鑒別機制應(yīng)用B向A發(fā)送隨機數(shù)RB,并可選地發(fā)送一個文本字段Text;發(fā)送的證書和的形式參見的接收到A的證書和后，應(yīng)用B通過調(diào)用身份鑒別T來對A的身份進(jìn)行驗證。6算法標(biāo)識與數(shù)據(jù)結(jié)構(gòu)6.1算法標(biāo)識定義對于數(shù)據(jù)的類型定義如表1所示。表1數(shù)據(jù)類型定義數(shù)據(jù)類型描述定義示例SGD_HANDLE會話句柄（指針類型）SGD_CHAR8位字符SGD_BYTE8位無符號字符SGD_INT3232字節(jié)有符號整型SGD_UINT3232字節(jié)無符號整型對于常量的定義如表2所示。5GM／T0067—2019表2常量定義宏描述預(yù)定義值說明0x00000001布爾值為真0x00000000布爾值為假對于全局參數(shù)的定義如表3所示。表3全局參數(shù)定義非對稱算法標(biāo)識宏描述預(yù)定義值說明10x00020200SM2簽名算法20x00020400SM2密鑰交換協(xié)議30x00020800SM2加密算法n0x00080000為其他非對稱算法預(yù)留雜湊算法標(biāo)識宏描述預(yù)定義值說明0x00000001SM3密碼雜湊算法證書解析標(biāo)識宏描述預(yù)定義值說明0x00000001證書版本0x00000002證書序列號0x00000005證書頒發(fā)者信息0x00000021證書頒發(fā)者CNO0x00000022證書頒發(fā)者O0x00000023證書頒發(fā)者OU0x00000006證書有效期0x00000007證書擁有者信息0x00000031證書擁有者信息CNO0x00000032證書擁有者信息O0x00000033證書擁有者信息OU0x00000034證書擁有者信息EMAIL0x00000009證書擴展項信息驗證模式標(biāo)識宏描述預(yù)定義值說明0x00000001CRL驗證模式0x00000002OCSP驗證模式6GM／T0067—20196.2數(shù)據(jù)結(jié)構(gòu)定義和說明對于用戶憑證的驗證結(jié)果如表4所示。表4用戶憑證驗證結(jié)果字段名稱數(shù)據(jù)長度（字節(jié)）含義result4驗證結(jié)果signTime4身份鑒別時間，采用的是通用時間類型resultSign簽名信息實際數(shù)據(jù)結(jié)構(gòu)定義：{SGDINT32result;;}SIF_ITOKEN_VERIFYED;7接口定義及函數(shù)7.1身份鑒別接口在公鑰密碼基礎(chǔ)設(shè)施應(yīng)用技術(shù)體系框架中的位置本標(biāo)準(zhǔn)為公鑰密碼基礎(chǔ)設(shè)施體系上層應(yīng)用使用身份鑒別服務(wù)制定了統(tǒng)一的接口標(biāo)準(zhǔn)。身份鑒別在公鑰密碼基礎(chǔ)設(shè)施應(yīng)用技術(shù)體系框架中的位置如圖4所示。圖4身份鑒別在公鑰密碼基礎(chǔ)設(shè)施應(yīng)用技術(shù)體系框架中的位置7GM／T0067—20197.2身份鑒別接口邏輯結(jié)構(gòu)身份鑒別接口的邏輯結(jié)構(gòu)如圖5所示。圖5身份鑒別接口體系結(jié)構(gòu)身份鑒別接口規(guī)范所依托的身份鑒別服務(wù)模塊位于應(yīng)用系統(tǒng)和密碼服務(wù)接口之間，通過本接口為應(yīng)用系統(tǒng)提供身份鑒別服務(wù)。身份鑒別模塊所需要的密碼運算通過密碼服務(wù)接口規(guī)范調(diào)用密碼服務(wù)實現(xiàn)。身份鑒別接口在邏輯上分為兩部分，分別為：環(huán)境函數(shù)和身份鑒別函數(shù)。環(huán)境函數(shù)負(fù)責(zé)創(chuàng)建和管理安全程序空間，負(fù)責(zé)創(chuàng)建和管理安全程序空間中所需的各種資源、信號，并確保安全程序空間在應(yīng)用程序運行期間不會被非法訪問，造成信息泄漏。環(huán)境函數(shù)負(fù)責(zé)完成與身份鑒別服務(wù)的安全連接，確保后續(xù)的安全操作是在安全、可信的程序空間中進(jìn)行。應(yīng)用程序在使用身份鑒別接口時，要首先調(diào)用初始化環(huán)境函數(shù)(_創(chuàng)建和初始化安全的應(yīng)用程序空間，完成與身份鑒別服務(wù)的連接和初始化工作。在中止應(yīng)用程序之前，應(yīng)調(diào)用清除環(huán)境函中止與身份鑒別服務(wù)的連接，銷毀所創(chuàng)建的安全程序空間，防止由于內(nèi)存殘留所帶來的安全風(fēng)險。身份鑒別函數(shù)實現(xiàn)用戶信息的獲取以及用戶身份的驗證（主要手段通過證書驗證和分析證書撤消列表）。應(yīng)用程序通過調(diào)用身份鑒別函數(shù)來實現(xiàn)基于數(shù)字證書的身份鑒別。消息包括消息頭和消息體兩個部分，使用XML定義為：8GM／T0067—2019〉其中標(biāo)簽msg_head標(biāo)識的段落為消息頭，msg_body標(biāo)識的段落為消息體。7.3.2消息頭格式定義消息頭定義方式如下：〉〉〈version〉1〈/version〉〉其中每個字段定義如表5所示：表5消息頭字段內(nèi)容定義字段名稱字段意義字段值消息的類型0—消息請求1—正確結(jié)果返回2—錯誤結(jié)果返回消息ID0001—初始化0100—獲取用戶身份信息1000—生成用戶憑證信息1001—驗證用戶憑證信息Version消息版本號7.3.3獲取身份接口消息定義a)用戶身份獲取請求〉〉〈version〉1〈/version〉9GM／T0067—2019連接標(biāo)識b)用戶身份獲取響應(yīng)〉〉〈version〉1〈/version〉連接標(biāo)識身份信息錯誤代碼7.3.4用戶憑證生成消息a)初始化請求〉〉〈version〉1〈/version〉b)初始化響應(yīng)〉〉〈version〉1〈/version〉錯誤代碼c)用戶憑證生成請求GM／T0067—2019〉〉〈version〉1〈/version〉隨機信息(編碼〈cert〉生成用戶憑證用的證書(Base64編碼）〈/cert〉d)用戶憑證生成響應(yīng)〉〉〈version〉1〈/version〉生成的用戶憑證(編碼錯誤代碼7.3.5用戶憑證驗證消息a)用戶憑證驗證請求〉〉〈version〉1〈/version〉生成的用戶憑證(編碼生成用戶憑證所用的隨機信息(編碼〈cert〉生成用戶憑證用的證書(Base64編碼）〈/cert〉b)用戶憑證驗證響應(yīng)GM／T0067—2019〉〉〈version〉1〈/version〉驗證結(jié)果編碼錯誤代碼7.4函數(shù)接口定義接口函數(shù)包括以下具體函數(shù)，各函數(shù)返回值參見附錄A錯誤代碼定義：初始化終止獲取接口版本d)產(chǎn)生用戶憑證需要的隨機信息：SIF_GenRandom產(chǎn)生用戶憑證獲取用戶身份原型：參數(shù)：初始化身份鑒別服務(wù)，創(chuàng)建身份鑒別服務(wù)句柄pucIpAddr[in]身份鑒別服務(wù)器地址，可以為NULL,表示不連接遠(yuǎn)程服務(wù)iPort[in]身份鑒別服務(wù)器端口函數(shù)成功后返回服務(wù)句柄，失敗為NULL返回值：0成功失敗，返回錯誤代碼注：此函數(shù)在所有其他函數(shù)前調(diào)用。當(dāng)僅僅使用本地證書生成用戶憑證時，即聲稱者調(diào)用時可以不連接身份鑒別服務(wù)。描述：清除應(yīng)用程序空間，終止身份鑒別服務(wù)參數(shù)：hHandle[in]初始化得到的服務(wù)句柄返回值：0成功非0失敗，返回錯誤代碼GM／T0067—2019注：此函數(shù)在程序結(jié)束時調(diào)用。7.4.4獲取接口版本信息SGDINT32SIFGetVersion(SGDHANDLEhHandle,描述：獲取接口版本信息參數(shù)：初始化得到的服務(wù)句柄接口版本號接口提供廠商標(biāo)識返回值：0成功非0失敗，返回錯誤代碼7.4.5產(chǎn)生用戶憑證需要的隨機信息SGDINT32SIFGenRandom(SGDHANDLEhHandle,描述：產(chǎn)生指定長度的隨機信息，作為生成用戶憑證的輸入?yún)?shù)：初始化得到的服務(wù)句柄隨機數(shù)長度隨機信息返回值：0成功非0失敗，返回錯誤代碼注：為了保證隨機信息的時變性和效率，建議隨機信息長度為16~64字節(jié)。SGDINT32SIFGenUserToken(SGDHANDLEhHandle,SGDINT32uiRandMessLen,SGDINT32uiCertificateLen,描述：使用輸入數(shù)字證書對應(yīng)的私鑰對隨機信息簽名產(chǎn)生用戶憑證參數(shù)：初始化得到的服務(wù)句柄隨機信息生成也可以是時間戳信息或者其他可靠的時變數(shù)據(jù)隨機信息的長度編碼的證書編碼證書的長度產(chǎn)生的用戶憑證格式為編碼輸入時表示存放用戶憑證數(shù)據(jù)緩沖區(qū)的長度，輸出時表示用戶憑證數(shù)據(jù)的長度返回值：0成功非0失敗，返回錯誤代碼GM／T0067—2019SGDINT32uiRandMessLen,SGDINT32uiCertificateLen,,描述：驗證用戶憑證的有效性，包括驗證對應(yīng)數(shù)字證書的有效性參數(shù)：初始化得到的服務(wù)句柄隨機信息隨機信息的長度產(chǎn)生的用戶憑證數(shù)據(jù)為編碼編碼格式用戶憑證數(shù)據(jù)的長度編碼的證書編碼的證書長度驗證模式，值參見全局參數(shù)定義中的驗證模式標(biāo)識定義憑證驗證結(jié)果返回值：0成功非0失敗，返回錯誤代碼7.4.8確認(rèn)驗證結(jié)果的真實性原型：參數(shù)：返回值：SGDINT32uiCertificateLen);憑證結(jié)果的驗證，確認(rèn)是否為指定鑒別服務(wù)驗證hHandle[in]uiCertificateLen[in]0初始化得到的服務(wù)句柄憑證驗證結(jié)果編碼的證書編碼的證書長度成功失敗，返回錯誤代碼SGDINT32iPort,GM／T0067—2019描述：獲取聲稱者身份參數(shù)：iPort[in]iConnect[in]身份鑒別服務(wù)器地址身份鑒別服務(wù)器端口聲稱者連接標(biāo)識函數(shù)成功后返回聲稱者證書的DN項內(nèi)容輸入時表示存放聲稱者證書DN項內(nèi)容的緩沖區(qū)長度，輸出時表示聲稱者證書的DN項長度返回值：0成功失敗，返回錯誤代碼注：只在代理模式的實現(xiàn)中使用。GM／T0067—2019附錄A（規(guī)范性附錄）錯誤代碼定義和說明錯誤代碼定義和說明如表A.1所示。表A.1錯誤代碼定義和說明錯誤代碼標(biāo)識宏描述預(yù)定義值說明0X00000000成功0X05000001異常錯誤0X05000002未初始化0X05000003網(wǎng)絡(luò)連接未成功0X05000004內(nèi)存不足或內(nèi)存出錯0X05000005超時錯誤0X05000006版本錯誤0X05000007服務(wù)不支持0X05000100信任證書未找到0X05000101無法獲取CRL0X05000002連接