1、智能 ic 卡及智能密碼鑰匙 密碼應(yīng)用接口規(guī)范 smart card and smart token cryptography application interface specification 國家密碼管理局 2010 年 4 月 目目 次次 前 言 .iv 1范圍 .1 2規(guī)范性引用文件 .1 3術(shù)語和定義 .1 4縮略語 .2 5結(jié)構(gòu)模型 .2 5.1層次關(guān)系 .2 5.2設(shè)備的應(yīng)用結(jié)構(gòu) .3 6數(shù)據(jù)類型定義 .4 6.1算法標(biāo)識 .4 6.1.1分組密碼算法標(biāo)識.4 6.1.2非對稱密碼算法標(biāo)識.5 6.1.3密碼雜湊算法標(biāo)識.5 6.2基本數(shù)據(jù)類型 .5 6.3常量定義 .6 6

2、.4復(fù)合數(shù)據(jù)類型 .6 6.4.1版本.6 6.4.2設(shè)備信息.6 6.4.3rsa 公鑰數(shù)據(jù)結(jié)構(gòu).7 6.4.4rsa 私鑰數(shù)據(jù)結(jié)構(gòu).8 6.4.5ecc 公鑰數(shù)據(jù)結(jié)構(gòu).8 6.4.6ecc 私鑰數(shù)據(jù)結(jié)構(gòu).9 6.4.7ecc 密文數(shù)據(jù)結(jié)構(gòu).9 6.4.8ecc 簽名數(shù)據(jù)結(jié)構(gòu).9 6.4.9分組密碼參數(shù).10 6.4.10文件屬性 .10 6.4.11權(quán)限類型.11 6.4.12設(shè)備狀態(tài) .11 7接口函數(shù) .11 7.1設(shè)備管理 .11 7.1.1概述.11 7.1.2等待設(shè)備插拔事件.11 7.1.3取消等待設(shè)備插拔事件.12 7.1.4枚舉設(shè)備.12 7.1.5連接設(shè)備.12 7.1.

3、6斷開連接.12 7.1.7獲取設(shè)備狀態(tài).12 7.1.8設(shè)置設(shè)備標(biāo)簽.12 7.1.9獲取設(shè)備信息.13 7.1.10鎖定設(shè)備 .13 7.1.11解鎖設(shè)備.13 7.1.12設(shè)備命令傳輸 .13 7.2訪問控制 .13 7.2.1概述.13 7.2.2修改設(shè)備認(rèn)證密鑰.14 7.2.3設(shè)備認(rèn)證.14 7.2.4修改 pin .14 7.2.5獲取 pin 信息.14 7.2.6校驗 pin .15 7.2.7解鎖 pin .15 7.2.8清除應(yīng)用安全狀態(tài).15 7.3應(yīng)用管理 .15 7.3.1概述.15 7.3.2創(chuàng)建應(yīng)用.15 7.3.3枚舉應(yīng)用.16 7.3.4刪除應(yīng)用.16 7.

4、3.5打開應(yīng)用.16 7.3.6關(guān)閉應(yīng)用.16 7.4文件管理 .17 7.4.1概述.17 7.4.2創(chuàng)建文件.17 7.4.3刪除文件.17 7.4.4枚舉文件.17 7.4.5獲取文件屬性.18 7.4.6讀文件.18 7.4.7寫文件.18 7.5容器管理 .18 7.5.1概述.18 7.5.2創(chuàng)建容器.19 7.5.3刪除容器.19 7.5.4打開容器.19 7.5.5關(guān)閉容器.19 7.5.6枚舉容器.19 7.6密碼服務(wù) .20 7.6.1概述.20 7.6.2生成隨機數(shù).21 7.6.3生成外部 rsa 密鑰對.21 7.6.4生成 rsa 簽名密鑰對.21 7.6.5導(dǎo)入

5、rsa 加密密鑰對.21 7.6.6rsa 簽名.22 7.6.7rsa 驗簽.22 7.6.8rsa 生成并導(dǎo)出會話密鑰.22 7.6.9rsa 外來公鑰運算.23 7.6.10rsa 外來私鑰運算 .23 7.6.11生成 ecc 簽名密鑰對.23 7.6.12導(dǎo)入 ecc 加密密鑰對 .24 7.6.13ecc 簽名 .24 7.6.14ecc 驗簽 .24 7.6.15ecc 生成并導(dǎo)出會話密鑰 .24 7.6.16ecc 外來公鑰加密 .25 7.6.17ecc 外來私鑰解密 .25 7.6.18ecc 外來私鑰簽名 .25 7.6.19ecc 外來公鑰驗簽 .25 7.6.20ec

6、c 生成密鑰協(xié)商參數(shù)并輸出 .26 7.6.21ecc 產(chǎn)生協(xié)商數(shù)據(jù)并計算會話密鑰 .26 7.6.22ecc 計算會話密鑰 .26 7.6.23導(dǎo)出公鑰 .27 7.6.24導(dǎo)入會話密鑰 .27 7.6.25明文導(dǎo)入會話密鑰 .27 7.6.26加密初始化 .28 7.6.27單組數(shù)據(jù)加密 .28 7.6.28多組數(shù)據(jù)加密 .28 7.6.29結(jié)束加密 .28 7.6.30解密初始化 .29 7.6.31單組數(shù)據(jù)解密 .29 7.6.32多組數(shù)據(jù)解密 .29 7.6.33結(jié)束解密 .30 7.6.34密碼雜湊初始化 .30 7.6.35單組數(shù)據(jù)密碼雜湊 .30 7.6.36多組數(shù)據(jù)密碼雜湊

7、.30 7.6.37結(jié)束密碼雜湊 .31 7.6.38消息鑒別碼運算初始化 .31 7.6.39單組數(shù)據(jù)消息鑒別碼運算 .31 7.6.40多組數(shù)據(jù)消息鑒別碼運算 .32 7.6.41結(jié)束消息鑒別碼運算 .32 7.6.42關(guān)閉密碼對象句柄 .32 8設(shè)備的安全要求 .32 8.1設(shè)備使用階段 .32 8.2權(quán)限管理 .32 8.2.1權(quán)限分類.32 8.2.2權(quán)限使用.32 8.2.3設(shè)備認(rèn)證.33 8.2.4pin 碼安全要求.33 8.3密鑰安全要求 .33 8.4設(shè)備抗攻擊要求 .33 附錄 a （規(guī)范性附錄） 錯誤代碼定義和說明 .34 前前 言言 本規(guī)范涉及的密碼算法按照國家密碼管

8、理部門的要求使用。 本規(guī)范的附錄 a 為規(guī)范性附錄。 本規(guī)范由國家密碼管理局提出并歸口。 本規(guī)范起草單位：北京海泰方圓科技有限公司、北京握奇智能科技有限公司、北京大明五洲科 技有限公司、恒寶股份有限公司、深圳市明華澳漢科技股份有限公司、武漢天喻信息產(chǎn)業(yè)股份有限 公司、北京飛天誠信科技有限公司、華翔騰數(shù)碼科技有限公司。 本規(guī)范主要起草人：石玉平、柳增壽、胡俊義、管延軍、項莉、雷繼業(yè)、胡鵬、趙再興、段曉 毅、劉玉峰、劉偉豐、陳吉、何永福、李高鋒、黃東杰、王建承、汪雪林、趙李明。 本規(guī)范責(zé)任專家：劉平、郭寶安。 智能 ic 卡及智能密碼鑰匙密碼應(yīng)用接口規(guī)范 1 1范圍范圍 本規(guī)范規(guī)定了基于 pki

9、密碼體制的智能 ic 卡及智能密碼鑰匙密碼應(yīng)用接口，描述了密碼應(yīng)用 接口的函數(shù)、數(shù)據(jù)類型、參數(shù)的定義和設(shè)備的安全要求。 本規(guī)范適用于智能 ic 卡及智能密碼鑰匙產(chǎn)品的研制、使用和檢測。 2 2規(guī)范性引用文件規(guī)范性引用文件 下列文件中的條款通過本規(guī)范的引用而成為本規(guī)范的條款。凡是注日期的引用文件，其隨后所 有的修改單（不包括勘誤的內(nèi)容）或修訂版均不適用于本規(guī)范，然而，鼓勵根據(jù)本規(guī)范達(dá)成協(xié)議的 各方研究是否可使用這些的最新版本。凡是不注日期的引用文件，其最新版本適用于本規(guī)范。 gb/t aaaaa公鑰密碼基礎(chǔ)設(shè)施應(yīng)用技術(shù)體系 sm2 算法使用規(guī)范 3 3術(shù)語術(shù)語和定義和定義 以下術(shù)語和定義適用于本

10、規(guī)范。 3.13.1 應(yīng)用應(yīng)用 applicationapplication 包括容器、設(shè)備認(rèn)證密鑰和文件的一種結(jié)構(gòu)，具備獨立的權(quán)限管理。 3.23.2 容器容器 containercontainer 特指密鑰容器，是一個用于存放非對稱密鑰對和會話密鑰的邏輯對象。 3.33.3 設(shè)備設(shè)備 devicedevice 智能 ic 卡及智能密碼鑰匙的統(tǒng)稱。 3.43.4 設(shè)備認(rèn)證設(shè)備認(rèn)證 devicedevice authenticationauthentication 智能 ic 卡或智能密碼鑰匙對應(yīng)用程序的認(rèn)證。 3.53.5 設(shè)備認(rèn)證密鑰設(shè)備認(rèn)證密鑰 devicedevice authenti

11、cationauthentication keykey 用于設(shè)備認(rèn)證的密鑰。 3.63.6 設(shè)備標(biāo)簽設(shè)備標(biāo)簽 labellabel 設(shè)備的別名，可以由用戶進(jìn)行設(shè)定并存儲于設(shè)備內(nèi)部。 3.73.7 消息鑒別碼消息鑒別碼 messagemessage authenticationauthentication codecode (mac)(mac) 消息鑒別算法的輸出。 3.83.8 管理員管理員 pinpin administratoradministrator pinpin 管理員的密碼，為ascii字符串。 3.93.9 用戶用戶 pinpin useruser pinpin 用戶的個人密碼，

12、為 ascii 字符串。 3.103.10 智能智能 icic 卡卡 smartsmart cardcard 含 cpu 的 ic 卡，這里指能完成密碼功能的 ic 卡。 3.113.11 智能密碼鑰匙智能密碼鑰匙 smartsmart tokentoken 能完成密碼功能和安全存儲的終端密碼產(chǎn)品，一般采用 usb 接口。 3.123.12 sm1sm1 算法算法 sm1sm1 algorithmalgorithm 一種國家商用密碼分組加密算法，分組長度為128比特，密鑰長度為128比特。 3.133.13 sm2sm2 算法算法 sm2sm2 algorithmalgorithm 一種國家商

13、用密碼非對稱密碼算法，密鑰長度為256比特。 3.143.14 sm3sm3 算法算法 sm3sm3 algorithmalgorithm 一種國家商用密碼密碼雜湊算法，輸出長度為256比特。 3.153.15 sms4sms4 算法算法 sms4sms4 algorithmalgorithm 一種國家商用密碼分組加密算法，分組長度為128比特，密鑰長度為128比特。 3.163.16 ssf33ssf33 算法算法 ssf33ssf33 algorithmalgorithm 一種國家商用密碼分組加密算法，分組長度為128比特，密鑰長度為128比特。 4 4縮略語縮略語 下列縮略語適用于本規(guī)范

14、： api應(yīng)用編程接口（application programming interface） pki公鑰基礎(chǔ)設(shè)施（public key infrastructure) pkcs#1公鑰密碼使用標(biāo)準(zhǔn)系列規(guī)范中的第1部分，定義rsa公開密鑰算法加密和簽名機制 (the public-key cryptography standard part 1) pkcs#5公鑰密碼使用標(biāo)準(zhǔn)系列規(guī)范中的第5部分，描述一種利用從口令派生出來的安全 密鑰加密字符串的方法(the public-key cryptography standard part 5) pin個人身份識別碼（personal identifi

15、cation number) mac消息鑒別碼（message authentication code） ecc橢圓曲線密碼算法（elliptic curve cryptography） 5 5結(jié)構(gòu)模型結(jié)構(gòu)模型 5.15.1 層次關(guān)系層次關(guān)系 智能 ic 卡及智能密碼鑰匙密碼應(yīng)用接口位于智能 ic 卡及智能密碼鑰匙應(yīng)用程序與設(shè)備之間， 如圖 1 所示。 智能ic卡及智能密碼鑰匙應(yīng)用程序 智能ic卡及智能密碼鑰匙密碼應(yīng)用接口 智能ic卡及智能密碼鑰匙設(shè)備驅(qū)動 設(shè)備1設(shè)備2設(shè)備n 圖 1 接口在應(yīng)用層次關(guān)系中的位置 5.25.2 設(shè)備的應(yīng)用結(jié)構(gòu)設(shè)備的應(yīng)用結(jié)構(gòu) 一個設(shè)備中存在設(shè)備認(rèn)證密鑰和多個應(yīng)用，

16、應(yīng)用之間相互獨立。設(shè)備的邏輯結(jié)構(gòu)如圖 2 所示。 設(shè)備認(rèn)證密鑰 應(yīng)應(yīng)用用1 1 應(yīng)應(yīng)用用n n 圖 2 設(shè)備邏輯結(jié)構(gòu) 應(yīng)用由管理員 pin、用戶 pin、文件和容器組成，可以存在多個文件和多個容器。 每個應(yīng)用維護(hù)各自的與管理員 pin 和用戶 pin 相關(guān)的權(quán)限狀態(tài)。 應(yīng)用的邏輯結(jié)構(gòu)如圖 3 所示。 管理員pin 用戶pin 文件1 文件n 加密公鑰 加密私鑰 簽名公鑰 簽名私鑰 會話密鑰1 會話密鑰n 容器1 加密公鑰 加密私鑰 簽名公鑰 簽名私鑰 會話密鑰1 會話密鑰n 容器n 應(yīng)用結(jié)構(gòu) 圖 3 應(yīng)用邏輯結(jié)構(gòu)圖 容器中存放加密密鑰對、簽名密鑰對和會話密鑰。其中加密密鑰對用于保護(hù)會話密鑰，簽

17、名密 鑰對用于數(shù)字簽名和驗證，會話密鑰用于數(shù)據(jù)加解密和 mac 運算。其中，簽名密鑰對由內(nèi)部產(chǎn)生， 加密密鑰對由外部產(chǎn)生并安全導(dǎo)入，會話密鑰可由內(nèi)部產(chǎn)生或者由外部產(chǎn)生并安全導(dǎo)入。 6 6數(shù)據(jù)類型定義數(shù)據(jù)類型定義 6.16.1 算法標(biāo)識算法標(biāo)識 6.1.16.1.1分組密碼算法標(biāo)識分組密碼算法標(biāo)識 分組密碼算法標(biāo)識包含密碼算法的類型和加密模式。 分組密碼算法標(biāo)識的編碼規(guī)則為：從低位到高位，第 0 位到第 7 位按位表示分組密碼算法工作 模式，第 8 位到第 31 位按位表示分組密碼算法類型，分組密碼算法的標(biāo)識如表 1 所示。 表 1 分組密碼算法標(biāo)識表 標(biāo)簽標(biāo)簽標(biāo)識符標(biāo)識符描述描述 sgd_sm

18、1_ecb0 x00000101 sm1 算法 ecb 加密模式 sgd_sm1_cbc0 x00000102 sm1 算法 cbc 加密模式 sgd_sm1_cfb0 x00000104 sm1 算法 cfb 加密模式 sgd_sm1_ofb0 x00000108 sm1 算法 ofb 加密模式 sgd_sm1_mac0 x00000110 sm1 算法 mac 運算 sgd_ssf33_ecb0 x00000201 ssf33 算法 ecb 加密模式 sgd_ssf33_cbc0 x00000202 ssf33 算法 cbc 加密模式 sgd_ssf33_cfb0 x00000204 ss

19、f33 算法 cfb 加密模式 sgd_ssf33_ofb0 x00000208 ssf33 算法 ofb 加密模式 sgd_ssf33_mac0 x00000210 ssf33 算法 mac 運算 sgd_sms4_ecb0 x00000401 sms4 算法 ecb 加密模式 sgd_sms4_cbc0 x00000402 sms4 算法 cbc 加密模式 sgd_sms4_cfb0 x00000404 sms4 算法 cfb 加密模式 sgd_sms4_ofb0 x00000408 sms4 算法 ofb 加密模式 sgd_sms4_mac0 x00000410 sms4 算法 mac

20、運算 6.1.26.1.2非對稱密碼算法標(biāo)識非對稱密碼算法標(biāo)識 非對稱密碼算法標(biāo)識僅定義了密碼算法的類型，在使用非對稱算法進(jìn)行數(shù)字簽名運算時，可將 非對稱密碼算法標(biāo)識符與密碼雜湊算法標(biāo)識符進(jìn)行“或”運算后使用，如“rsa with sha1”可表 示為 sgd_rsa | sgd_sha1，即 0 x00010002， “|”表示“或”運算。 非對稱密碼算法標(biāo)識的編碼規(guī)則為：從低位到高位，第 0 位到第 7 位為 0，第 8 位到第 15 位 按位表示非對稱密碼算法的算法協(xié)議，如果所表示的非對稱算法沒有相應(yīng)的算法協(xié)議則為 0，第 16 位到第 31 位按位表示非對稱密碼算法類型，非對稱密碼算法

21、的標(biāo)識如表 2 所示。 表 2 非對稱密碼算法標(biāo)識表 標(biāo)簽標(biāo)簽標(biāo)識符標(biāo)識符描述描述 sgd_rsa0 x00010000 rsa 算法 sgd_sm2_10 x00020100 橢圓曲線簽名算法 sgd_sm2_20 x00020200 橢圓曲線密鑰交換協(xié)議 sgd_sm2_30 x00020400 橢圓曲線加密算法 6.1.36.1.3密碼雜湊算法標(biāo)識密碼雜湊算法標(biāo)識 密碼雜湊算法標(biāo)識符可以在進(jìn)行密碼雜湊運算或計算 mac 時應(yīng)用，也可以與非對稱密碼算法標(biāo) 識符進(jìn)行“或”運算后使用，表示簽名運算前對數(shù)據(jù)進(jìn)行密碼雜湊運算的算法類型。 密碼雜湊算法標(biāo)識的編碼規(guī)則為：從低位到高位，第 0 位到第

22、7 位表示密碼雜湊算法，第 8 位 到第 31 位為 0，密碼雜湊算法的標(biāo)識如表 3 所示。 表 3 密碼雜湊算法標(biāo)識表 標(biāo)簽標(biāo)簽標(biāo)識符標(biāo)識符描述描述 sgd_sm30 x00000001 sm3 密碼雜湊算法 sgd_sha10 x00000002 sha1 密碼雜湊算法 sgd_sha2560 x00000004 sha256 密碼雜湊算法 6.26.2 基本數(shù)據(jù)類型基本數(shù)據(jù)類型 本規(guī)范中的字節(jié)數(shù)組均為高位字節(jié)在前（big-endian）方式存儲和交換?；緮?shù)據(jù)類型定義如 表 4 所示： 表 4 基本數(shù)據(jù)類型 類型名稱類型名稱描述描述定義定義 int8 有符號 8 位整數(shù) int16 有符

23、號 16 位整數(shù) int32 有符號 32 位整數(shù) uint8 無符號 8 位整數(shù) uint16 無符號 16 位整數(shù) uint32 無符號 32 位整數(shù) bool 布爾類型，取值為 true 或 false byte 字節(jié)類型，無符號 8 位整數(shù) typedef uint8 byte char 字符類型，無符號 8 位整數(shù) typedef uint8 char short 短整數(shù)，有符號 16 位 typedef int16 short ushort 無符號 16 位整數(shù) typedef uint16 ushort long 長整數(shù)，有符號 32 位整數(shù) typedef int32 long

24、 ulong 長整數(shù)，無符號 32 位整數(shù) typedef uint32 ulong uint 無符號 32 位整數(shù) typedef uint32 uint word 字類型，無符號 16 位整數(shù) typedef uint16 word dword 雙字類型，無符號 32 位整 數(shù) typedef uint32 dword flags 標(biāo)志類型，無符號 32 位整 數(shù) typedef uint32 flags lpstr 8 位字符串指針，按照 utf8 格式存儲及交換 typedef char * lpstr handle 句柄，指向任意數(shù)據(jù)對象的 起始地址 typedef void * h

25、andle devhandle 設(shè)備句柄 typedef handle devhandle happlication 應(yīng)用句柄 typedef handle happlication hcontainer 容器句柄 typedef handle hcontainer 6.36.3 常量定義常量定義 數(shù)據(jù)常量標(biāo)識定義了在規(guī)范中用到的常量的取值。 數(shù)據(jù)常量標(biāo)識的定義如表 5 所示。 表 5 常量定義 常量名常量名取值取值描述描述 true0 x00000001 布爾值為真 false0 x00000000 布爾值為假 devapi_stdcall _stdcall 函數(shù)調(diào)用方式 admin_typ

26、e0 管理員 pin 類型 user_type1 用戶 pin 類型 6.46.4 復(fù)合數(shù)據(jù)類型復(fù)合數(shù)據(jù)類型 6.4.16.4.1版本版本 （1）類型定義 typedef struct struct_version byte major; byte minor; version; （2）數(shù)據(jù)項描述參見表 6： 表 6版本定義 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 majorbyte 主版本號 minorbyte 次版本號 主版本號和次版本號以“.”分隔，例如 version 1.0，主版本號為 1，次版本號為 0；version 2.10，主 版本號為 2，次版本號為 10。 6.4.26.4

27、.2設(shè)備信息設(shè)備信息 （1）類型定義 typedef struct struct_devinfo versionversion; charmanufacturer64; charissuer64; charlabel32; charserialnumber32; versionhwversion; versionfirmwareversion; ulongalgsymcap; ulongalgasymcap; ulongalghashcap; ulongdevauthalgid; ulongtotalspace; ulongfreespace; byte reserved64; devinfo

28、,*pdevinfo; （2）數(shù)據(jù)項描述參見表 7： 表 7設(shè)備信息描述 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 versionversion 版本號數(shù)據(jù)結(jié)構(gòu)版本號，本結(jié)構(gòu)的版本號 為 1.0 manufacturer char 數(shù)組設(shè)備廠商信息以 0為結(jié)束符的 ascii 字符 串 issuer char 數(shù)組發(fā)行廠商信息以 0為結(jié)束符的 ascii 字符 串 label char 數(shù)組設(shè)備標(biāo)簽以 0為結(jié)束符的 ascii 字符 串 serialnumber char 數(shù)組序列號以 0為結(jié)束符的 ascii 字符 串 hwversionversion 設(shè)備硬件版本 firmwareversio

29、nversion 設(shè)備本身固件版本 algsymcapulong 分組密碼算法標(biāo)識 algasymcapulong 非對稱密碼算法標(biāo)識 alghashcapulong 密碼雜湊算法標(biāo)識 devauthalgidulong 設(shè)備認(rèn)證使用的分組 密碼算法標(biāo)識 totalspaceulong 設(shè)備總空間大小 freespaceulong 用戶可用空間大小 reservedbyte 保留擴展 6.4.36.4.3rsarsa 公鑰數(shù)據(jù)結(jié)構(gòu)公鑰數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_rsapublickeyblob ulongalgid; ulongbitlen; byte

30、modulusmax_rsa_modulus_len; bytepublicexponentmax_rsa_exponent_len; rsapublickeyblob, *prsapublickeyblob; max_rsa_modulus_len 為算法模數(shù)的最大長度； max_rsa_exponent_len 為算法指數(shù)的最大長度。 （2）數(shù)據(jù)項描述參見表 8： 表 8rsa 公鑰數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 algidulong 算法標(biāo)識號 bitlenulong 模數(shù)的實際位長度必須是 8 的倍數(shù) modulus byte 數(shù)組模數(shù) n = p * q實際長度為 b

31、itlen/8 字節(jié) #define max_rsa_modulus_len 256 #define max_rsa_exponent_len 4 publicexponent byte 數(shù)組公開密鑰 e一般為 00010001 6.4.46.4.4rsarsa 私鑰數(shù)據(jù)結(jié)構(gòu)私鑰數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_rsaprivatekeyblob ulongalgid; ulongbitlen; bytemodulusmax_rsa_modulus_len; bytepublicexponentmax_rsa_exponent_len; byteprivat

32、eexponentmax_rsa_modulus_len; byteprime1max_rsa_modulus_len/2; byteprime2max_rsa_modulus_len/2; byteprime1exponentmax_rsa_modulus_len/2; byteprime2exponentmax_rsa_modulus_len/2; bytecoefficientmax_rsa_modulus_len/2; rsaprivatekeyblob, *prsaprivatekeyblob; max_rsa_modulus_len 為 rsa 算法模數(shù)的最大長度； （2）數(shù)據(jù)項描

33、述參見表 9： 表 9rsa 私鑰數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 algidulong 算法標(biāo)識號 bitlenulong 模數(shù)的實際位長度必須是 8 的倍數(shù) modulus byte 數(shù)組模數(shù) n = p * q實際長度為 bitlen/8 字節(jié) publicexponent byte 數(shù)組公開密鑰 e一般為 00010001 privateexponent byte 數(shù)組私有密鑰 d實際長度為 bitlen/8 字節(jié) prime1 byte 數(shù)組素數(shù) p實際長度為 bitlen/16 字節(jié) prime2 byte 數(shù)組素數(shù) q實際長度為 bitlen/16 字節(jié) prime

34、1exponent byte 數(shù)組d mod (p-1)的值實際長度為 bitlen/16 字節(jié) prime2exponent byte 數(shù)組d mod (q -1)的值實際長度為 bitlen/16 字節(jié) coefficient byte 數(shù)組q 模 p 的乘法逆元實際長度為 bitlen/16 字節(jié) 6.4.56.4.5eccecc 公鑰數(shù)據(jù)結(jié)構(gòu)公鑰數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_eccpublickeyblob ulongbitlen; bytexcoordinateecc_max_xcoordinate_bits_len/8; byteycoord

35、inateecc_max_ycoordinate_bits_len/8; eccpublickeyblob, *peccpublickeyblob; ecc_max_xcoordinate_len 為 ecc 算法 x 坐標(biāo)的最大長度； ecc_max_ycoordinate_len 為 ecc 算法 y 坐標(biāo)的最大長度。 （2）數(shù)據(jù)項描述參見表 10： 表 10 ecc 公鑰數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 bitlenulong 模數(shù)的實際 位長度 必須是 8 的倍數(shù) xcoordinate byte 數(shù)組曲線上點的 x 坐標(biāo) 有限域上的整數(shù) #define ecc_max_

36、xcoordinate_bits_len 512 ycoordinate byte 數(shù)組曲線上點的 y 坐標(biāo) 有限域上的整數(shù) #define ecc_max_ycoordinate_bits_len 512 6.4.66.4.6eccecc 私鑰數(shù)據(jù)結(jié)構(gòu)私鑰數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_eccprivatekeyblob ulongbitlen; byteprivatekeyecc_max_modulus_bits_len/8; eccprivatekeyblob, *peccprivatekeyblob; ecc_max_modulus_bits_le

37、n 為 ecc 算法模數(shù)的最大長度。 （2）數(shù)據(jù)項描述參見表 11： 表 11 ecc 私鑰數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 bitlenulong 模數(shù)的實際位長度必須是 8 的倍數(shù) privatekey byte 數(shù)組私有密鑰有限域上的整數(shù) #define ecc_max_modulus_bits_len 512 6.4.76.4.7eccecc 密文數(shù)據(jù)結(jié)構(gòu)密文數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_ecccipherblob byte xcoordinateecc_max_xcoordinate_bits_len/8; byte ycoord

38、inateecc_max_xcoordinate_bits_len/8; byte hash32; ulongcipherlen; byte cipher1; ecccipherblob, *pecccipherblob; （2）數(shù)據(jù)項描述參見表 12： 表 12 ecc 密文數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 xcoordinate byte 數(shù)組與 y 組成橢圓曲線上的點（x，y） ycoordinate byte 數(shù)組與 x 組成橢圓曲線上的點（x，y） hash byte 數(shù)組明文的雜湊值 cipherlenulong 密文數(shù)據(jù)長度 cipher byte 數(shù)組密文數(shù)據(jù)實際

39、長度為 cipherlen 6.4.86.4.8eccecc 簽名數(shù)據(jù)結(jié)構(gòu)簽名數(shù)據(jù)結(jié)構(gòu) （1）類型定義 typedef struct struct_eccsignatureblob byte recc_max_xcoordinate_bits_len/8; byte secc_max_xcoordinate_bits_len/8; eccsignatureblob, *peccsignatureblob; ecc_max_modulus_bits_len 為 ecc 算法模數(shù)的最大長度； （2）數(shù)據(jù)項描述參見表 13： 表 13 ecc 簽名數(shù)據(jù)結(jié)構(gòu) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 r

40、byte 數(shù)組簽名結(jié)果的 r 部分 s byte 數(shù)組簽名結(jié)果的 s 部分 6.4.96.4.9分組密碼參數(shù)分組密碼參數(shù) （1）類型定義 typedef struct struct_blockcipherparam byteivmax_iv_len; ulongivlen; ulongpaddingtype; ulongfeedbitlen; blockcipherparam, *pblockcipherparam; （2）數(shù)據(jù)項描述參見表 14： 表 14 分組密碼參數(shù) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 iv byte 數(shù)組初始向量，max_iv_len 為初始化向量的 最大長度 #de

41、fine max_iv_len 32 ivlenulong 初始向量實際長度（按字節(jié)計算） paddingtypeulong 填充方式，0 表示不填充，1 表示按照 pkcs#5 方式進(jìn)行填充 feedbitlenulong 反饋值的位長度（按位計算）只針對 ofb、cfb 模 式 6.4.106.4.10eccecc 加密密鑰對保護(hù)結(jié)構(gòu)加密密鑰對保護(hù)結(jié)構(gòu) （1）類型定義 typedef struct skf_envelopedkeyblob ulong version; / 當(dāng)前版本為 1 ulong ulsymmalgid; / 對稱算法標(biāo)識，限定 ecb 模式 ulong ulbits;

42、/ 加密密鑰對的密鑰位長度 byte cbencryptedprikey64; / 加密密鑰對私鑰的密文 eccpublickeyblob pubkey; / 加密密鑰對的公鑰 ecccipherblob ecccipherblob; / 用保護(hù)公鑰加密的對稱密鑰密文。 envelopedkeyblob, *penvelopedkeyblob; （2）數(shù)據(jù)項描述參見表 15： 表 15 分組密碼參數(shù) 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 versionulong 版本號，本版本為 1 ulsymmalgidulong 對稱算法標(biāo)識必須為 ecb 模式 ulbitsulong 加密密鑰對的密鑰位

43、長 cbencryptedpri vkey byte 數(shù)組對稱算法加密的加密私鑰, 加密私鑰的原文為 eccprivatekeyblob 結(jié)構(gòu) 中的 privatekey。 其有效長度為原文的 （ulbits + 7）/8 pubkeyeccpublickeyblob 加密密鑰對的公鑰 ecccipherblobecccipherblob 用保護(hù)公鑰加密過的對稱 密鑰密文 6.4.116.4.11文件屬性文件屬性 （1）類型定義 typedef struct struct_fileattribute charfilename32; ulongfilesize; ulongreadrights;

44、 ulongwriterights; fileattribute, *pfileattribute; （2）數(shù)據(jù)項描述參見表 16： 表 16 文件屬性 數(shù)據(jù)項數(shù)據(jù)項類型類型意義意義備注備注 filename char 數(shù)組文件名以0結(jié)束的 ascii 字符串，最大 長度為 32 filesizeulong 文件大小創(chuàng)建文件時定義的文件大小 readrightsulong 讀取權(quán)限讀取文件需要的權(quán)限 writerightsulong 寫入權(quán)限寫入文件需要的權(quán)限 6.4.126.4.12權(quán)限類型權(quán)限類型 權(quán)限類型的定義參見表 17： 表 17 權(quán)限類型 權(quán)限類型權(quán)限類型值值說明說明 secure

45、_never_account0 x00000000 不允許 secure_adm_account0 x00000001 管理員權(quán)限 secure_user_account0 x00000010 用戶權(quán)限 secure_anyone_account0 x000000ff 任何人 6.4.136.4.13設(shè)備狀態(tài)設(shè)備狀態(tài) 設(shè)備狀態(tài)的定義參見表 18： 表 18 設(shè)備狀態(tài) 設(shè)備狀態(tài)設(shè)備狀態(tài)值值說明說明 dev_absent_state0 x00000000 設(shè)備不存在 dev_present_state0 x00000001 設(shè)備存在 dev_unknow_state0 x00000002 設(shè)備狀態(tài)

46、未知 7 7接口函數(shù)接口函數(shù) 7.17.1 設(shè)備管理設(shè)備管理 7.1.17.1.1概述概述 設(shè)備管理主要完成設(shè)備的插拔事件處理、枚舉設(shè)備、連接設(shè)備、斷開連接、獲取設(shè)備狀態(tài)、設(shè) 置設(shè)備標(biāo)簽、獲取設(shè)備信息、鎖定設(shè)備、解鎖設(shè)備和設(shè)備命令傳輸?shù)炔僮鳌ＴO(shè)備管理系列函數(shù)如表 19 所示： 表 19 設(shè)備管理系列函數(shù) 函數(shù)名稱功能 skf_waitfordevevent 等待設(shè)備插拔事件 skf_cancelwaitfordevevent 取消等待設(shè)備插拔事件 skf_enumdev 枚舉設(shè)備 skf_connectdev 連接設(shè)備 skf_disconnectdev 斷開連接 skf_getdevstat

47、e 獲取設(shè)備狀態(tài) skf_setlabel 設(shè)置設(shè)備標(biāo)簽 skf_getdevinfo 獲取設(shè)備信息 skf_lockdev 鎖定設(shè)備 skf_unlockdev 解鎖設(shè)備 skf_transmit 設(shè)備命令傳輸 7.1.27.1.2等待設(shè)備插拔事件等待設(shè)備插拔事件 函數(shù)原型 ulong devapi skf_waitfordevevent(lpstr szdevname,ulong *puldevnamelen, ulong *pulevent) 功能描述該函數(shù)等待設(shè)備插入或者拔除事件。szdevname 返回發(fā)生事件的設(shè)備名稱。 szdevname out 發(fā)生事件的設(shè)備名稱。 pulde

48、vnamelen in/out 輸入/輸出參數(shù)，當(dāng)輸入時表示緩沖區(qū)長度，輸出時表 示設(shè)備名稱的有效長度,長度包含字符串結(jié)束符。 參數(shù) pulevent out事件類型。1 表示插入，2 表示拔出。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.37.1.3取消等待設(shè)備插拔事件取消等待設(shè)備插拔事件 函數(shù)原型 ulong devapi skf_cancelwaitfordevevent() 功能描述該函數(shù)取消等待設(shè)備插入或者拔除事件。 參數(shù) 返回值sar_ok：成功。 其他：錯誤碼。 備注使本進(jìn)程正在執(zhí)行的 skf_waitfordevevent 函數(shù)立即返回。 7.1.47.1.4枚舉設(shè)備

49、枚舉設(shè)備 函數(shù)原型 ulong devapi skf_enumdev(bool bpresent, lpstr sznamelist, ulong *pulsize) 功能描述獲得當(dāng)前系統(tǒng)中的設(shè)備列表。 參數(shù) bpresent in 為 true 表示取當(dāng)前設(shè)備狀態(tài)為存在的設(shè)備列表。為 false 表示取當(dāng)前驅(qū)動支持的設(shè)備列表。 sznamelist out 設(shè)備名稱列表。如果該參數(shù)為 null，將由 pulsize 返回所 需要的內(nèi)存空間大小。每個設(shè)備的名稱以單個0結(jié)束，以雙 0表示列表的結(jié)束。 pulsize in，out 輸入時表示設(shè)備名稱列表的緩沖區(qū)長度，輸出時表示 sznamelis

50、t 所占用的空間大小。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.57.1.5連接設(shè)備連接設(shè)備 函數(shù)原型 ulong devapi skf_connectdev (lpstr szname, devhandle *phdev) 功能描述通過設(shè)備名稱連接設(shè)備，返回設(shè)備的句柄。 szname in 設(shè)備名稱。參數(shù) phdev out 返回設(shè)備操作句柄。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.67.1.6斷開連接斷開連接 函數(shù)原型 ulong devapi skf_disconnectdev (devhandle hdev) 功能描述斷開一個已經(jīng)連接的設(shè)備，并釋放句柄。 參數(shù)

51、 hdev in 連接設(shè)備時返回的設(shè)備句柄。 返回值sar_ok：成功。 其他：錯誤碼。 備注如果該設(shè)備已被鎖定，函數(shù)應(yīng)首先解鎖該設(shè)備。斷開連接操作并不影響設(shè)備的權(quán)限 狀態(tài)。 7.1.77.1.7獲取設(shè)備狀態(tài)獲取設(shè)備狀態(tài) 函數(shù)原型 ulong devapi skf_getdevstate(lpstr szdevname, ulong *puldevstate) 功能描述獲取設(shè)備是否存在的狀態(tài)。 szdevname in 設(shè)備名稱。參數(shù) puldevstate out 返回設(shè)備狀態(tài)。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.87.1.8設(shè)置設(shè)備標(biāo)簽設(shè)置設(shè)備標(biāo)簽 函數(shù)原型 ulong

52、devapi skf_setlabel (devhandle hdev, lpstr szlabel) 功能描述設(shè)置設(shè)備標(biāo)簽。 hdev in 連接設(shè)備時返回的設(shè)備句柄。參數(shù) szlabel in 設(shè)備標(biāo)簽字符串。該字符串應(yīng)小于 32 字節(jié)。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.97.1.9獲取設(shè)備信息獲取設(shè)備信息 函數(shù)原型 ulong devapi skf_getdevinfo (devhandle hdev, devinfo *pdevinfo) 功能描述獲取設(shè)備的一些特征信息，包括設(shè)備標(biāo)簽、廠商信息、支持的算法等。 hdev in 連接設(shè)備時返回的設(shè)備句柄。參數(shù) pdev

53、info out 返回設(shè)備信息。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.107.1.10鎖定設(shè)備鎖定設(shè)備 函數(shù)原型 ulong devapi skf_lockdev (devhandle hdev, ulong ultimeout) 功能描述獲得設(shè)備的獨占使用權(quán)。 hdev in 連接設(shè)備時返回的設(shè)備句柄。參數(shù) ultimeout in 超時時間，單位為毫秒。如果為 0 xffffffff 表示無限等待。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.117.1.11解鎖設(shè)備解鎖設(shè)備 函數(shù)原型 ulong devapi skf_unlockdev (devhandle hd

54、ev) 功能描述釋放對設(shè)備的獨占使用權(quán)。 參數(shù) hdev in 連接設(shè)備時返回的設(shè)備句柄。 返回值sar_ok：成功。 其他：錯誤碼。 7.1.127.1.12設(shè)備命令傳輸設(shè)備命令傳輸 函數(shù)原型 ulong devapi skf_transmit(devhandle hdev, byte* pbcommand, ulong ulcommandlen,byte* pbdata, ulong* puldatalen) 功能描述將命令直接發(fā)送給設(shè)備，并返回結(jié)果。 參數(shù) hdev in 設(shè)備句柄。 pbcommand in 設(shè)備命令。 ulcommandlen in 命令長度。 pbdata out

55、返回結(jié)果數(shù)據(jù)。 puldatalen in，out 輸入時表示結(jié)果數(shù)據(jù)緩沖區(qū)長度，輸出時表示結(jié)果數(shù)據(jù) 實際長度。 返回值sar_ok：成功。 其他：錯誤碼。 7.27.2 訪問控制訪問控制 7.2.17.2.1概述概述 訪問控制主要完成設(shè)備認(rèn)證、pin 碼管理和安全狀態(tài)管理等操作。訪問控制系列函數(shù)如表 20 所示： 表 20 訪問控制系列函數(shù) 函數(shù)名稱功能 skf_changedevauthkey 修改設(shè)備認(rèn)證密鑰 skf_devauth 設(shè)備認(rèn)證 skf_changepin 修改 pin skf_getpininfo 獲得 pin 碼信息 skf_verifypin 校驗 pin skf_u

56、nblockpin 解鎖 pin skf_clearsecuestate 清除應(yīng)用安全狀態(tài) 7.2.27.2.2修改設(shè)備認(rèn)證密鑰修改設(shè)備認(rèn)證密鑰 函數(shù)原型ulong devapi skf_changedevauthkey (devhandle hdev, byte *pbkeyvalue， ulong ulkeylen) 功能描述更改設(shè)備認(rèn)證密鑰。 hdev in 連接時返回的設(shè)備句柄。 pbkeyvalue in 密鑰值。 參數(shù) ulkeylen in 密鑰長度。 返回值sar_ok：成功。 其他：錯誤碼。 備注權(quán)限要求：設(shè)備認(rèn)證成功后才能使用。 7.2.37.2.3設(shè)備認(rèn)證設(shè)備認(rèn)證 函數(shù)原

57、型ulong devapi skf_devauth (devhandle hdev, byte *pbauthdata，ulong ullen) 功能描述設(shè)備認(rèn)證是設(shè)備對應(yīng)用程序的認(rèn)證。認(rèn)證過程參見 8.2.3。 hdev in 連接時返回的設(shè)備句柄。 pbauthdata in 認(rèn)證數(shù)據(jù)。 參數(shù) ullen in 認(rèn)證數(shù)據(jù)的長度。 返回值sar_ok：成功。 其他：錯誤碼。 7.2.47.2.4修改修改 pinpin 函數(shù)原型 ulong devapi skf_changepin (happlication happlication, ulong ulpintype, lpstr szold

58、pin, lpstr sznewpin, ulong *pulretrycount) 功能描述調(diào)用該函數(shù)可以修改 administrator pin 和 user pin 的值。 如果原 pin 碼錯誤導(dǎo)致驗證失敗，該函數(shù)會返回相應(yīng) pin 碼的剩余重試次數(shù)，當(dāng)剩 余次數(shù)為 0 時，表示 pin 已經(jīng)被鎖死。 happlication in 應(yīng)用句柄。 ulpintype in pin 類型，可為 admin_type 或 user_type。 szoldpin in 原 pin 值。 sznewpin in 新 pin 值。 參數(shù) pulretrycount out 出錯后重試次數(shù)。 返回值

59、sar_ok：成功。 其他：錯誤碼。 7.2.57.2.5獲取獲取 pinpin 信息信息 函數(shù)原型 ulong devapi skf_getpininfo(happlication happlication, ulong ulpintype, ulong *pulmaxretrycount, ulong *pulremainretrycount, bool *pbdefaultpin) 功能描述獲取 pin 碼信息，包括最大重試次數(shù)、當(dāng)前剩余重試次數(shù)，以及當(dāng)前 pin 碼是否為 出廠默認(rèn) pin 碼。 happlication in 應(yīng)用句柄。 ulpintype in pin 類型。 pulmaxretrycount out 最大重試次數(shù)。 pulremainretrycount out 當(dāng)前剩余重試次數(shù)，當(dāng)為 0 時表示已鎖死。 參數(shù) pbdefaultpin out 是否為出廠默認(rèn) pin 碼。 返回值sar_ok：成功。 其他：錯誤碼。 7.2.67.2.6校驗校驗 pinpin 函數(shù)原型 ulong devapi skf_verifypin (happlication happlication, ulong ulpintype, lpstr szpin, ulong *pulretrycount) 功能描述校驗 pin 碼。校驗成功后，會獲得相應(yīng)的權(quán)限，如果 pin