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

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