密算法庫(kù)拆解：SM2/SM3/SM4實(shí)現(xiàn)與聯(lián)調(diào)避坑)
簡(jiǎn)介面向需要在 C#/.NET 項(xiàng)目中落地國(guó)密算法的開(kāi)發(fā)者與學(xué)習(xí)者這套代碼示例圍繞 SM2、SM3、SM4 三種算法給出可運(yùn)行的 WinForm 演示幫助理解密鑰生成、簽名驗(yàn)簽、摘要計(jì)算及分組加解密的調(diào)用方式。壓縮包共 51 個(gè)文件約 5.33MB主體為 cs 源碼、resx 界面資源、dll 依賴庫(kù)與 exe 可執(zhí)行程序并附帶解決方案與項(xiàng)目配置便于在 Visual Studio 中打開(kāi)、調(diào)試和二次改造。內(nèi)容涵蓋算法工具類(lèi)、窗體交互邏輯及 BouncyCastle 加密庫(kù)引用讀者可對(duì)照界面操作觀察各算法的輸入輸出與參數(shù)配置快速梳理國(guó)密功能從界面到核心實(shí)現(xiàn)的代碼路徑。已有 1316 人學(xué)習(xí)下載適合作為 C# 國(guó)密入門(mén)、課程實(shí)驗(yàn)或業(yè)務(wù)模塊預(yù)研的參考樣例。1. 一次驗(yàn)簽失敗的聯(lián)調(diào)這套 C# 國(guó)密算法庫(kù)到底補(bǔ)的是哪個(gè)洞對(duì)接一個(gè)內(nèi)部系統(tǒng)的簽名接口對(duì)方說(shuō)只收國(guó)密算法SM2 簽名加 SM3 摘要報(bào)文用 SM4 加密。很多人第一反應(yīng)是在項(xiàng)目里搜一下有沒(méi)有現(xiàn)成的算法包結(jié)果發(fā)現(xiàn)可用的 C# 國(guó)密算法實(shí)現(xiàn)要么只覆蓋其中一兩種要么把密鑰編碼、密文排列這些細(xì)節(jié)隱藏了起來(lái)等到對(duì)方驗(yàn)簽失敗就無(wú)從查起。這套包含 SM2、SM3、SM4 的 C# 實(shí)現(xiàn)價(jià)值在于把曲線參數(shù)、補(bǔ)位規(guī)則、ZA 值計(jì)算、C1C3C2 排列這些容易被第三方庫(kù)隱藏起來(lái)的部分全部展開(kāi)成可讀代碼。適合正在做國(guó)密改造的后端開(kāi)發(fā)也適合想搞清楚算法內(nèi)部機(jī)理、準(zhǔn)備自己動(dòng)手增加支持的工程師。2. 目錄與運(yùn)行SM2/SM3/SM4 三套算法在工程里怎么分家2.1 三層拆分算法內(nèi)核、編碼適配、調(diào)用入口這類(lèi) C# 國(guó)密庫(kù)的目錄結(jié)構(gòu)通常分成三層這個(gè)劃分方式雖然簡(jiǎn)單但基本不會(huì)出錯(cuò)。算法內(nèi)核只關(guān)心數(shù)學(xué)和字節(jié)操作不接觸任何 IO編碼層負(fù)責(zé)十六進(jìn)制、Base64、ASN.1/DER、PEM 之間的轉(zhuǎn)換調(diào)用入口負(fù)責(zé)把參數(shù)整理好丟給內(nèi)核。第一次閱讀源碼時(shí)按這個(gè)順序看比從 Program.cs 往下追要快得多。SmCrypto/ ├── src/ │ ├── SmCrypto.Core/ # 純算法無(wú)外部依賴 │ │ ├── Sm2/ │ │ │ ├── Sm2Curve.cs # 曲線參數(shù)、點(diǎn)運(yùn)算、點(diǎn)乘 │ │ │ ├── Sm2.cs # 簽名驗(yàn)簽、加解密、KDF │ │ │ └── Sm2KeyPair.cs # 密鑰生成與公私鑰解析 │ │ ├── Sm3/ │ │ │ └── Sm3.cs # 常量、填充、壓縮函數(shù) │ │ ├── Sm4/ │ │ │ ├── Sm4.cs # 輪函數(shù)、單分組加解密 │ │ │ ├── Sm4Constants.cs # S 盒、FK、CK │ │ │ └── Sm4Padding.cs # PKCS7 / 無(wú)填充 │ │ ├── Encoding/ │ │ │ ├── Hex.cs # 大小寫(xiě)、帶不帶空格 │ │ │ └── Asn1.cs # DER 序列化給密鑰和簽名用 │ │ └── Utils/ │ │ ├── BigIntegerExtensions.cs# 定長(zhǎng)大端轉(zhuǎn)換、模逆 │ │ └── SecureRandom.cs # 密碼學(xué)安全隨機(jī)數(shù) │ └── SmCrypto.Console/ │ └── Program.cs # 手敲的驗(yàn)證入口 └── tests/ └── SmCrypto.Tests/ # 標(biāo)準(zhǔn)測(cè)試向量 自身往返測(cè)試看這個(gè)結(jié)構(gòu)能發(fā)現(xiàn)一個(gè)細(xì)節(jié)SM2 單獨(dú)占一個(gè)目錄還分了三個(gè)文件。原因很實(shí)在SM2 是橢圓曲線算法點(diǎn)運(yùn)算、曲線參數(shù)、業(yè)務(wù)層的簽名驗(yàn)簽是三件不同的事混在一個(gè)類(lèi)里到后面加密鑰交換或者換曲線就麻煩了。SM3 和 SM4 各自只有一個(gè)主文件是因?yàn)樗鼈兊膶?shí)現(xiàn)相對(duì)獨(dú)立沒(méi)有那么多分支。2.2 目標(biāo)框架與依賴為什么寧可手寫(xiě)也不用系統(tǒng)接口.NET 生態(tài)里做國(guó)密有個(gè)現(xiàn)實(shí)問(wèn)題系統(tǒng)自帶的加密接口在多數(shù)版本上沒(méi)有覆蓋 SM2、SM3、SM4即使新版本在部分平臺(tái)上補(bǔ)了 SM3/SM4Windows 和 Linux 的行為也不完全一致跨平臺(tái)部署很容易遇到問(wèn)題。所以這套實(shí)現(xiàn)選擇純托管代碼零外部依賴System.Numerics.BigInteger就是唯一的大數(shù)工具。目標(biāo)框架怎么選看調(diào)用方。要被老項(xiàng)目引用就多目標(biāo)輸出netstandard2.0加net8.0只做新服務(wù)直接上net8.0省事。真正影響代碼寫(xiě)法的是這三處關(guān)注點(diǎn)netstandard2.0net8.0大數(shù)System.Numerics.BigInteger同上另有TryWriteBytes定長(zhǎng)輸出高性能切片需要System.Memory包原生Spanbyte隨機(jī)數(shù)RNGCryptoServiceProviderRandomNumberGenerator.Fill我一般會(huì)統(tǒng)一寫(xiě)RandomNumberGenerator.Create()拿一個(gè)實(shí)例兩個(gè)框架都能編譯不用寫(xiě)#if。這一點(diǎn)看似無(wú)關(guān)緊要但真正到適配各個(gè)框架版本時(shí)這一點(diǎn)會(huì)節(jié)省很多時(shí)間。提示不要把System.Random用在任何密鑰、k 值、IV 上。它產(chǎn)生的序列可預(yù)測(cè)SM2 的 k 一旦可預(yù)測(cè)私鑰就等價(jià)于公開(kāi)了。2.3 第一次運(yùn)行先把 SM3 的哈希值打印出來(lái)SM2 的調(diào)試成本高因?yàn)樗鼱砍峨S機(jī)數(shù)、點(diǎn)乘、編碼三件事所以第一次運(yùn)行不要碰 SM2先驗(yàn)證 SM3。新建一個(gè)控制臺(tái)項(xiàng)目引用 Core寫(xiě)十行代碼using SmCrypto.Core.Sm3; // 標(biāo)準(zhǔn)附錄里的經(jīng)典向量SM3(abc) byte[] digest Sm3.Hash(System.Text.Encoding.ASCII.GetBytes(abc)); System.Console.WriteLine(Hex.ToHex(digest, upper: false));跑起來(lái)dotnet run --project src/SmCrypto.Console正常輸出應(yīng)該是66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0這 64 個(gè)十六進(jìn)制字符對(duì)上了說(shuō)明填充邏輯、字節(jié)序、壓縮函數(shù)這三塊沒(méi)問(wèn)題。再補(bǔ)一個(gè)長(zhǎng)度不是 3 的用例驗(yàn)證填充邊界把a(bǔ)bcd重復(fù) 16 次正好 64 字節(jié)會(huì)觸發(fā)多補(bǔ)一整個(gè)分組期望結(jié)果debe9ff92275b8a138604889c18e5a4d6fdb70e5387e5765293dcba39c0c5732這兩個(gè)值都對(duì)SM3 這塊基本可以放心了。SM4 用標(biāo)準(zhǔn)向量key 0123456789abcdeffedcba9876543210、明文與 key 相同單分組加密結(jié)果是681edf34d206965e86b3e94f536e4246同一個(gè)塊再加密一次得到595298c7c6fd271f0402f804c33d3f66加解密往返能對(duì)回去才能說(shuō)明輪密鑰沒(méi)有寫(xiě)反。SM2 不適合這么驗(yàn)證后面第 4 章講怎么用往返測(cè)試加對(duì)方的公鑰做交叉驗(yàn)證。3. SM3 與 SM4從填充到輪函數(shù)兩段能直接抄的 C# 實(shí)現(xiàn)3.1 SM3 的填充與壓縮64 輪里真正在變的是什么SM3 輸出 256 位分組 512 位結(jié)構(gòu)上和常見(jiàn)的哈希算法相近但消息擴(kuò)展和輪函數(shù)里的置換是自己的一套。先看填充這是新手最容易寫(xiě)錯(cuò)的地方private static byte[] Pad(byte[] msg) { long bitLen (long)msg.Length * 8; // 比特長(zhǎng)度用 long 防止大報(bào)文溢出 int padLen 64 - (int)((msg.Length 9) % 64); // 0x80 一字節(jié) 8 字節(jié)長(zhǎng)度 if (padLen 64) padLen 0; // 剛好對(duì)齊時(shí)不再補(bǔ)整塊 byte[] buf new byte[msg.Length 1 padLen 8]; Buffer.BlockCopy(msg, 0, buf, 0, msg.Length); buf[msg.Length] 0x80; // 先補(bǔ)一個(gè) 1后面全 0 for (int i 0; i 8; i) buf[buf.Length - 1 - i] (byte)(bitLen (8 * i)); // 大端寫(xiě)長(zhǎng)度 return buf; }bitLen必須用 64 位整型長(zhǎng)度字段是大端序這兩點(diǎn)在跨語(yǔ)言對(duì)接時(shí)最常出錯(cuò)。padLen那個(gè)if判斷也不能少當(dāng)(msg.Length 9) % 64 0時(shí)會(huì)算出 64如果不處理就會(huì)多補(bǔ)一整塊哈希值直接不同。壓縮函數(shù)的核心是消息擴(kuò)展和 64 輪迭代private static void Compress(uint[] v, byte[] block, int offset) { uint[] w new uint[68]; uint[] w1 new uint[64]; for (int i 0; i 16; i) // 前 16 個(gè)字直接讀大端 w[i] ReadBe32(block, offset i * 4); for (int j 16; j 68; j) // 擴(kuò)展到 68 個(gè)字 w[j] P1(w[j - 16] ^ w[j - 9] ^ Rol(w[j - 3], 15)) ^ Rol(w[j - 13], 7) ^ w[j - 6]; for (int j 0; j 64; j) w1[j] w[j] ^ w[j 4]; // W 只是 W 的異或組合 uint a v[0], b v[1], c v[2], d v[3]; uint e v[4], f v[5], g v[6], h v[7]; for (int j 0; j 64; j) { uint t j 16 ? 0x79cc4519u : 0x7a879d8au; // 前 16 輪與后 48 輪常量不同 uint a12 Rol(a, 12); uint ss1 Rol(a12 e Rol(t, j % 32), 7); uint ss2 ss1 ^ a12; uint ff j 16 ? (a ^ b ^ c) : ((a b) | (a c) | (b c)); uint gg j 16 ? (e ^ f ^ g) : ((e f) | (~e g)); uint tt1 ff d ss2 w1[j]; uint tt2 gg h ss1 w[j]; d c; c Rol(b, 9); b a; a tt1; h g; g Rol(f, 19); f e; e P0(tt2); } v[0] ^ a; v[1] ^ b; v[2] ^ c; v[3] ^ d; // 末態(tài)異或回初值 v[4] ^ e; v[5] ^ f; v[6] ^ g; v[7] ^ h; } private static uint P0(uint x) x ^ Rol(x, 9) ^ Rol(x, 17); private static uint P1(uint x) x ^ Rol(x, 15) ^ Rol(x, 23);這里的參數(shù)說(shuō)明一下v是 8 個(gè) 32 位的初始向量第一塊用固定常量后續(xù)塊用上一塊的輸出Rol(x, n)是 32 位循環(huán)左移n要先% 32否則 C# 的移位運(yùn)算符只取低 5 位Rol(t, j % 32)里的取模不能省。w數(shù)組 68 個(gè)字、w1數(shù)組 64 個(gè)字這兩個(gè)長(zhǎng)度是固定的用List或者動(dòng)態(tài)擴(kuò)容會(huì)讓每塊多做幾次分配壓測(cè)時(shí)差別能看出來(lái)。3.2 SM4 輪函數(shù)一個(gè) T 變換貫穿 32 輪SM4 是分組長(zhǎng)度 128 位、密鑰長(zhǎng)度 128 位的分組密碼加密和解密用同一套輪函數(shù)只是輪密鑰順序反過(guò)來(lái)。它的全部復(fù)雜度都集中在T變換上// 字節(jié)代換把 32 位字按字節(jié)逐個(gè)查 S 盒 private static uint Tau(uint a) ((uint)SBox[(a 24) 0xFF] 24) | ((uint)SBox[(a 16) 0xFF] 16) | ((uint)SBox[(a 8) 0xFF] 8) | SBox[a 0xFF]; // 線性變換加密用 L密鑰擴(kuò)展用 L1少移位一次 private static uint L(uint b) b ^ Rol(b, 2) ^ Rol(b, 10) ^ Rol(b, 18) ^ Rol(b, 24); private static uint L1(uint b) b ^ Rol(b, 13) ^ Rol(b, 23); private static uint T(uint x) L(Tau(x)); // 輪函數(shù)里的合成置換 private static uint T1(uint x) L1(Tau(x)); // 密鑰擴(kuò)展里的合成置換S 盒是 256 字節(jié)的常量表放在Sm4Constants.cs里。寫(xiě)的時(shí)候容易犯的錯(cuò)是手抄表格抄錯(cuò)一個(gè)字節(jié)結(jié)果只有某些特殊輸入才會(huì)出錯(cuò)極難排查。建議直接從標(biāo)準(zhǔn)文檔復(fù)制然后寫(xiě)一個(gè)單元測(cè)試斷言SBox[0] 0xd6、SBox[255] 0x48用首尾兩個(gè)值做初步校驗(yàn)。密鑰擴(kuò)展和單分組加解密public static uint[] ExpandKey(byte[] key) { if (key.Length ! 16) throw new ArgumentException(SM4 密鑰必須 16 字節(jié)); uint k0 ReadBe32(key, 0) ^ 0xa3b1bac6; // FK 是四個(gè)固定常量 uint k1 ReadBe32(key, 4) ^ 0x56aa3350; uint k2 ReadBe32(key, 8) ^ 0x677d9197; uint k3 ReadBe32(key, 12) ^ 0xb27022dc; uint[] rk new uint[32]; for (int i 0; i 32; i) { uint k4 k0 ^ T1(k1 ^ k2 ^ k3 ^ Ck(i)); // CK 由公式生成不必手寫(xiě)表 rk[i] k4; k0 k1; k1 k2; k2 k3; k3 k4; } return rk; } // CK[i] (ck0,ck1,ck2,ck3)其中 ck_j ((4i j) * 7) mod 256 private static uint Ck(int i) { uint v 0; for (int j 0; j 4; j) v (v 8) | (uint)(((4 * i j) * 7) 0xFF); return v; } // 加解密共用解密時(shí)把輪密鑰倒著傳進(jìn)來(lái)即可 public static void CryptBlock(uint[] rk, byte[] input, int inOff, byte[] output, int outOff) { uint x0 ReadBe32(input, inOff); uint x1 ReadBe32(input, inOff 4); uint x2 ReadBe32(input, inOff 8); uint x3 ReadBe32(input, inOff 12); for (int i 0; i 32; i) { uint x4 x0 ^ T(x1 ^ x2 ^ x3 ^ rk[i]); // 一輪只產(chǎn)出一個(gè)新字 x0 x1; x1 x2; x2 x3; x3 x4; } // 輸出要反序這一步漏了會(huì)得到完全對(duì)不上的結(jié)果 WriteBe32(output, outOff, x3); WriteBe32(output, outOff 4, x2); WriteBe32(output, outOff 8, x1); WriteBe32(output, outOff 12, x0); }參數(shù)上要注意兩件事。第一rk是 32 個(gè) 32 位輪密鑰加密時(shí)正序解密時(shí)rk.Reverse()即可不需要另寫(xiě)一個(gè)解密函數(shù)。第二最后輸出必須反序x3 x2 x1 x0這是標(biāo)準(zhǔn)里寫(xiě)死的反變換很多人在這卡一下午因?yàn)榧用芙Y(jié)果看著“像那么回事”只是每個(gè)塊都對(duì)不上。3.3 分組模式與填充ECB 之外還得有 CBC 和 PKCS7單分組函數(shù)只是零件實(shí)際報(bào)文長(zhǎng)度很少正好是 16 的倍數(shù)所以要有模式和填充。ECB 實(shí)現(xiàn)最簡(jiǎn)單但同樣的明文塊會(huì)得到同樣的密文塊圖片、表格類(lèi)數(shù)據(jù)一眼就能看出結(jié)構(gòu)業(yè)務(wù)上一般不允許用。CBC 更常見(jiàn)public static byte[] EncryptCbc(byte[] key, byte[] iv, byte[] plain) { if (iv.Length ! 16) throw new ArgumentException(CBC 的 IV 必須 16 字節(jié)); byte[] padded Sm4Padding.Pkcs7(plain, 16); // 補(bǔ)到 16 的倍數(shù) byte[] cipher new byte[padded.Length]; byte[] prev (byte[])iv.Clone(); uint[] rk ExpandKey(key); byte[] block new byte[16]; for (int i 0; i padded.Length; i 16) { for (int j 0; j 16; j) block[j] (byte)(padded[i j] ^ prev[j]); // 先和上一塊密文異或 CryptBlock(rk, block, 0, cipher, i); Buffer.BlockCopy(cipher, i, prev, 0, 16); // 本塊密文成為下一塊的 prev } return cipher; }Sm4Padding.Pkcs7的邏輯是缺 n 字節(jié)就補(bǔ) n 個(gè)值為 n 的字節(jié)正好對(duì)齊時(shí)補(bǔ)一整塊 16 個(gè)0x10。這個(gè)“正好對(duì)齊也要補(bǔ)”的規(guī)則是解密時(shí)判斷填充長(zhǎng)度的依據(jù)少補(bǔ)這一塊對(duì)方解出來(lái)的尾巴會(huì)被當(dāng)成數(shù)據(jù)。IV 每次加密都要換新的隨機(jī)值跟著密文一起發(fā)過(guò)去不需要保密但絕不能固定不變否則相同明文前綴的密文前綴也相同。注意CBC 只保證機(jī)密性不保證完整性。要防篡改還得在密文后面附加 SM3 或 SM2 的校驗(yàn)值或者干脆用 SM2 加密會(huì)話密鑰、SM4 加密數(shù)據(jù)的兩段式方案。4. SM2 關(guān)鍵鏈路曲線參數(shù)、ZA 值與密文排列4.1 曲線參數(shù)與密鑰對(duì)先把 BigInteger 的字節(jié)序捋順SM2 用的是 256 位素域上的橢圓曲線曲線方程、基點(diǎn)、階都是固定常量直接照標(biāo)準(zhǔn)抄進(jìn)Sm2Curve.cs。真正的坑不在參數(shù)在BigInteger的字節(jié)序C# 的BigInteger內(nèi)部是小端構(gòu)造函數(shù)默認(rèn)還帶符號(hào)位而國(guó)密的所有數(shù)據(jù)都是大端無(wú)符號(hào)定長(zhǎng)。// 定長(zhǎng) 32 字節(jié)大端輸出左側(cè)補(bǔ) 0 補(bǔ)齊 internal static byte[] ToFixed32(BigInteger v) { byte[] raw v.ToByteArray(isUnsigned: true, isBigEndian: true); if (raw.Length 32) return raw; byte[] result new byte[32]; Buffer.BlockCopy(raw, 0, result, 32 - raw.Length, raw.Length); return result; } // 反過(guò)來(lái)讀的時(shí)候也要聲明無(wú)符號(hào)大端否則最高位為 1 會(huì)變成負(fù)數(shù) internal static BigInteger FromFixed32(byte[] buf, int offset) new BigInteger(new ReadOnlySpanbyte(buf, offset, 32), isUnsigned: true, isBigEndian: true);ToFixed32里那個(gè)補(bǔ)零動(dòng)作不能省。橢圓曲線坐標(biāo)偶爾會(huì)出現(xiàn)高位為 0 的情況概率大約 1/256如果直接ToByteArray輸出會(huì)少一個(gè)字節(jié)長(zhǎng)度變成 31對(duì)方解析直接報(bào)錯(cuò)。這種概率性錯(cuò)誤最難排查本地跑一百次都好上線跑一萬(wàn)次報(bào)一次。密鑰對(duì)生成就是取一個(gè)[1, n-1]的隨機(jī)數(shù)當(dāng)私鑰再算d * G得到公鑰點(diǎn)public static (BigInteger d, byte[] publicKey) GenerateKeyPair() { BigInteger d; do { d Sm2Curve.RandomScalar(); } while (d.IsZero || d Sm2Curve.N); var (x, y) Sm2Curve.MultiplyG(d); // 未壓縮點(diǎn)格式04 || X(32) || Y(32)共 65 字節(jié) byte[] pub new byte[65]; pub[0] 0x04; Buffer.BlockCopy(ToFixed32(x), 0, pub, 1, 32); Buffer.BlockCopy(ToFixed32(y), 0, pub, 33, 32); return (d, pub); }公鑰點(diǎn)的序列化格式有三種未壓縮04||X||Y65 字節(jié)、壓縮02/03||X33 字節(jié)、純裸X||Y64 字節(jié)。不同系統(tǒng)默認(rèn)值不一樣聯(lián)調(diào)前先問(wèn)清對(duì)方用哪種或者干脆在庫(kù)里三種都支持讀的時(shí)候看首字節(jié)判斷。4.2 簽名與驗(yàn)簽ZA 值沒(méi)算對(duì)后面全白搭SM2 簽名和很多人熟悉的橢圓曲線簽名差別在于被簽的不是消息的哈希而是ZA || M的哈希。ZA是用戶標(biāo)識(shí)、曲線參數(shù)、公鑰點(diǎn)的哈希摘要作用是把簽名和具體身份綁定起來(lái)。這一步漏了或者用戶 ID 用了默認(rèn)值而對(duì)方用的是自己的驗(yàn)簽 100% 失敗而且失敗信息沒(méi)有任何提示。// ZA SM3(ENTL || ID || a || b || Gx || Gy || Px || Py) private static byte[] ComputeZa(byte[] userId, BigInteger px, BigInteger py) { int bitLen userId.Length * 8; // ENTL 是 ID 的比特長(zhǎng)度2 字節(jié)大端 var ms new MemoryStream(); ms.WriteByte((byte)(bitLen 8)); ms.WriteByte((byte)bitLen); ms.Write(userId); ms.Write(ToFixed32(Sm2Curve.A)); ms.Write(ToFixed32(Sm2Curve.B)); ms.Write(ToFixed32(Sm2Curve.Gx)); ms.Write(ToFixed32(Sm2Curve.Gy)); ms.Write(ToFixed32(px)); ms.Write(ToFixed32(py)); return Sm3.Hash(ms.ToArray()); } public static (BigInteger r, BigInteger s) Sign(byte[] message, BigInteger d, byte[] userId) { var (px, py) Sm2Curve.MultiplyG(d); byte[] za ComputeZa(userId, px, py); // e SM3(ZA || M)再當(dāng)作 256 位大端無(wú)符號(hào)整數(shù) byte[] digest Sm3.Hash(Concat(za, message)); BigInteger e new BigInteger(digest, isUnsigned: true, isBigEndian: true); while (true) { BigInteger k Sm2Curve.RandomScalar(); var (x1, _) Sm2Curve.MultiplyG(k); BigInteger r (e x1) % Sm2Curve.N; if (r.IsZero || (r k) % Sm2Curve.N 0) continue; // 規(guī)范要求重取 k BigInteger s BigInteger.ModPow(1 d, Sm2Curve.N - 2, Sm2Curve.N) * (k - r * d) % Sm2Curve.N; if (s.Sign 0) s Sm2Curve.N; // C# 取模會(huì)保留負(fù)號(hào)必須手動(dòng)修正 if (s.IsZero) continue; return (r, s); } }逐段說(shuō)明。ComputeZa里的所有長(zhǎng)度都必須定長(zhǎng) 32 字節(jié)少一位整體就變了所以統(tǒng)一走ToFixed32。默認(rèn)用戶 ID 是 16 字節(jié)的固定字符串很多系統(tǒng)的開(kāi)放接口就是用它但私有協(xié)議經(jīng)常換成自己的 appId這一項(xiàng)必須和對(duì)方確認(rèn)。ModPow(x, n-2, n)是在求模逆因?yàn)閚是素?cái)?shù)費(fèi)馬小定理成立比手寫(xiě)擴(kuò)展歐幾里得快也不用擔(dān)心邊界。s的負(fù)數(shù)處理是 C# 特有的一處。C# 的%運(yùn)算符對(duì)負(fù)數(shù)返回負(fù)值s.Sign 0時(shí)加一次n才能回到[0, n-1]。在 Java 或 Python 里寫(xiě)習(xí)慣的人換到 C# 上很容易忽略這一點(diǎn)結(jié)果只有極少部分簽名是負(fù)數(shù)測(cè)試樣本少的時(shí)候根本發(fā)現(xiàn)不了。驗(yàn)簽就是反過(guò)來(lái)算檢查r、s是否在[1, n-1]算t (r s) mod nt 0直接拒然后算點(diǎn)(x1, y1) s*G t*P判斷(e x1) mod n r。4.3 加解密與密文順序C1C3C2 和 C1C2C3 的互相傷害SM2 加密產(chǎn)出的三部分C1是隨機(jī)點(diǎn)kGC2是明文異或 KDF 流C3是校驗(yàn)摘要。老版本標(biāo)準(zhǔn)把順序?qū)懗蒀1C2C3新標(biāo)準(zhǔn)改成C1C3C2兩套在現(xiàn)實(shí)系統(tǒng)里都還在用所以庫(kù)里一定要留一個(gè)開(kāi)關(guān)。public static byte[] Encrypt(byte[] message, byte[] publicKey, bool c1c3c2 true) { var (x, y) Sm2Curve.DecodePoint(publicKey); // 04 || X || Y while (true) { BigInteger k Sm2Curve.RandomScalar(); var (x1, y1) Sm2Curve.MultiplyG(k); var (x2, y2) Sm2Curve.Multiply(new Point(x, y), k); byte[] t Kdf(Concat(ToFixed32(x2), ToFixed32(y2)), message.Length); if (t.All(b b 0)) continue; // 全 0 說(shuō)明 KDF 失效規(guī)范要求重來(lái) byte[] c1 Sm2Curve.EncodePoint(x1, y1); // 65 字節(jié) byte[] c2 Xor(message, t); byte[] c3 Sm3.Hash(Concat(ToFixed32(x2), message, ToFixed32(y2))); return c1c3c2 ? Concat(c1, c3, c2) : Concat(c1, c2, c3); } }KDF 是基于 SM3 的計(jì)數(shù)器派生internal static byte[] Kdf(byte[] z, int klen) { byte[] output new byte[klen]; for (int i 0, ct 1; i klen; i 32, ct) { // 計(jì)數(shù)器是 4 字節(jié)大端接在共享點(diǎn)后面一起哈希 byte[] h Sm3.Hash(Concat(z, new byte[] { (byte)(ct 24), (byte)(ct 16), (byte)(ct 8), (byte)ct })); Buffer.BlockCopy(h, 0, output, i, Math.Min(32, klen - i)); } return output; }解密的順序是先按配置把三段拆開(kāi)用C1和自己的私鑰算出共享點(diǎn)(x2, y2)用同樣的 KDF 得到t異或回C2最后重算C3比對(duì)。C3比對(duì)必須用固定時(shí)間比較逐字節(jié)異或累加不要用SequenceEqual提前返回這類(lèi)細(xì)節(jié)在安全審計(jì)時(shí)會(huì)被挑出來(lái)。5. 避坑與排查聯(lián)調(diào)現(xiàn)場(chǎng)最常見(jiàn)的五個(gè)問(wèn)題這一章是整套實(shí)現(xiàn)里最值錢(qián)的部分。算法本身照著標(biāo)準(zhǔn)寫(xiě)就行真正耗時(shí)間的是下面這些表現(xiàn)完全一樣、原因各不相同的問(wèn)題。5.1 驗(yàn)簽一直返回 false但雙方代碼看著都“對(duì)”現(xiàn)象自測(cè)簽名驗(yàn)簽往返完全正常一旦換成對(duì)方給的公鑰就失敗把對(duì)方發(fā)來(lái)的簽名拿去驗(yàn)也失敗兩邊都不報(bào)異常只是布爾值 false。原因九成是 ZA 里的用戶 ID 不一致。默認(rèn) ID 是 16 個(gè)字節(jié)的固定串而對(duì)方可能用了自己的應(yīng)用標(biāo)識(shí)另一個(gè)可能是對(duì)方把ZA || M里的M先做了 Base64 解碼再哈希而你直接對(duì)字符串字節(jié)哈希。解決讓對(duì)方明確給出 ID 的原始字節(jié)不是 Base64不是十六進(jìn)制并且約定M到底是原始報(bào)文還是某種規(guī)范化之后的字符串。確認(rèn)后先用SM3(ZA)單獨(dú)對(duì)比一次把 ZA 的哈希值發(fā)給對(duì)方核對(duì)這比反復(fù)試簽名快得多。ZA 一致了簽名再不對(duì)才是曲線參數(shù)或s負(fù)數(shù)處理的問(wèn)題。5.2 SM4 加密結(jié)果第一塊對(duì)、后面全不對(duì)現(xiàn)象16 字節(jié)以內(nèi)的短報(bào)文加密結(jié)果和對(duì)方一致一旦超過(guò) 16 字節(jié)第一塊密文相同第二塊開(kāi)始全亂。原因CBC 的鏈?zhǔn)疆惢驅(qū)戝e(cuò)了。常見(jiàn)兩種寫(xiě)法錯(cuò)誤一是用明文塊而不是密文塊作為下一輪的prev二是循環(huán)里prev更新寫(xiě)在異或之前。解決把Buffer.BlockCopy(cipher, i, prev, 0, 16)放在CryptBlock之后、下一輪異或之前中間不要有別的賦值。驗(yàn)證方法是拿 32 字節(jié)的固定輸入手工用第一塊密文異或第二塊明文看結(jié)果是不是和內(nèi)部中間值一致。5.3 SM2 加密偶發(fā)“密文長(zhǎng)度不對(duì)”重啟又好了現(xiàn)象接口大部分時(shí)間正常偶爾報(bào)密文長(zhǎng)度異常日志里能看到長(zhǎng)度是 96 或 98 而期望 97 或 112 之類(lèi)的值。原因BigInteger.ToByteArray()輸出的長(zhǎng)度不固定。坐標(biāo)高位為 0 時(shí)會(huì)少一個(gè)字節(jié)如果沒(méi)用isUnsigned: true最高位為 1 時(shí)還會(huì)多出一個(gè)0x00符號(hào)字節(jié)。兩種都會(huì)讓C1的長(zhǎng)度在 64、65、66 之間抖。解決所有點(diǎn)坐標(biāo)輸出統(tǒng)一走定長(zhǎng) 32 字節(jié)的轉(zhuǎn)換函數(shù)不要直接調(diào)ToByteArray。再在解碼側(cè)加一層防御讀到C1時(shí)按首字節(jié)判斷格式04未壓縮、02/03壓縮、其余按裸坐標(biāo)補(bǔ)齊別硬編碼固定偏移量。5.4 大量數(shù)據(jù)加密時(shí) CPU 打滿單條報(bào)文要幾十毫秒現(xiàn)象壓測(cè)時(shí) SM4 的吞吐還能接受但整個(gè)接口 RT 很高火焰圖顯示時(shí)間集中在 SM2 的標(biāo)量乘上。原因一次 SM2 加解密要做兩次點(diǎn)乘kG和kP樸素的雙倍點(diǎn)算法每次都做模逆模逆是這里面最貴的一步另外BigInteger是不可變類(lèi)型循環(huán)里頻繁產(chǎn)生中間對(duì)象GC 壓力也上來(lái)了。解決把點(diǎn)運(yùn)算改到雅可比坐標(biāo)下做只在最后一步轉(zhuǎn)回仿射坐標(biāo)一次點(diǎn)乘的模逆從幾百次降到 1 次kG因?yàn)榛c(diǎn)固定可以預(yù)計(jì)算一張表做固定窗口加速。業(yè)務(wù)側(cè)更好的做法是不用 SM2 直接加密大報(bào)文改成 SM2 加密一把隨機(jī)的 SM4 密鑰數(shù)據(jù)走 SM4性能差距是數(shù)量級(jí)的。5.5 升級(jí)框架版本后簽名結(jié)果變了現(xiàn)象從舊框架遷到新框架同樣的私鑰、同樣的報(bào)文對(duì)方突然驗(yàn)簽失敗而自測(cè)往返還是通的。原因隨機(jī)數(shù)來(lái)源換掉了或者BigInteger的行為在新運(yùn)行時(shí)上有細(xì)微差異。更隱蔽的一種是把k寫(xiě)成了固定值做“可復(fù)現(xiàn)測(cè)試”上線忘了改回去兩次簽名用了同一個(gè)k從本文還有配套的精品資源點(diǎn)擊獲取 C#國(guó)密算法庫(kù)拆解：SM2/SM3/SM4實(shí)現(xiàn)與聯(lián)調(diào)避坑
簡(jiǎn)介面向需要在 C#/.NET 項(xiàng)目中落地國(guó)密算法的開(kāi)發(fā)者與學(xué)習(xí)者這套代碼示例圍繞 SM2、SM3、SM4 三種算法給出可運(yùn)行的 WinForm 演示幫助理解密鑰生成、簽名驗(yàn)簽、摘要計(jì)算及分組加解密的調(diào)用方式。壓縮包共 51 個(gè)文件約 5.33MB主體為 cs 源碼、resx 界面資源、dll 依賴庫(kù)與 exe 可執(zhí)行程序并附帶解決方案與項(xiàng)目配置便于在 Visual Studio 中打開(kāi)、調(diào)試和二次改造。內(nèi)容涵蓋算法工具類(lèi)、窗體交互邏輯及 BouncyCastle 加密庫(kù)引用讀者可對(duì)照界面操作觀察各算法的輸入輸出與參數(shù)配置快速梳理國(guó)密功能從界面到核心實(shí)現(xiàn)的代碼路徑。已有 1316 人學(xué)習(xí)下載適合作為 C# 國(guó)密入門(mén)、課程實(shí)驗(yàn)或業(yè)務(wù)模塊預(yù)研的參考樣例。1. 一次驗(yàn)簽失敗的聯(lián)調(diào)這套 C# 國(guó)密算法庫(kù)到底補(bǔ)的是哪個(gè)洞對(duì)接一個(gè)內(nèi)部系統(tǒng)的簽名接口對(duì)方說(shuō)只收國(guó)密算法SM2 簽名加 SM3 摘要報(bào)文用 SM4 加密。很多人第一反應(yīng)是在項(xiàng)目里搜一下有沒(méi)有現(xiàn)成的算法包結(jié)果發(fā)現(xiàn)可用的 C# 國(guó)密算法實(shí)現(xiàn)要么只覆蓋其中一兩種要么把密鑰編碼、密文排列這些細(xì)節(jié)隱藏了起來(lái)等到對(duì)方驗(yàn)簽失敗就無(wú)從查起。這套包含 SM2、SM3、SM4 的 C# 實(shí)現(xiàn)價(jià)值在于把曲線參數(shù)、補(bǔ)位規(guī)則、ZA 值計(jì)算、C1C3C2 排列這些容易被第三方庫(kù)隱藏起來(lái)的部分全部展開(kāi)成可讀代碼。適合正在做國(guó)密改造的后端開(kāi)發(fā)也適合想搞清楚算法內(nèi)部機(jī)理、準(zhǔn)備自己動(dòng)手增加支持的工程師。2. 目錄與運(yùn)行SM2/SM3/SM4 三套算法在工程里怎么分家2.1 三層拆分算法內(nèi)核、編碼適配、調(diào)用入口這類(lèi) C# 國(guó)密庫(kù)的目錄結(jié)構(gòu)通常分成三層這個(gè)劃分方式雖然簡(jiǎn)單但基本不會(huì)出錯(cuò)。算法內(nèi)核只關(guān)心數(shù)學(xué)和字節(jié)操作不接觸任何 IO編碼層負(fù)責(zé)十六進(jìn)制、Base64、ASN.1/DER、PEM 之間的轉(zhuǎn)換調(diào)用入口負(fù)責(zé)把參數(shù)整理好丟給內(nèi)核。第一次閱讀源碼時(shí)按這個(gè)順序看比從 Program.cs 往下追要快得多。SmCrypto/ ├── src/ │ ├── SmCrypto.Core/ # 純算法無(wú)外部依賴 │ │ ├── Sm2/ │ │ │ ├── Sm2Curve.cs # 曲線參數(shù)、點(diǎn)運(yùn)算、點(diǎn)乘 │ │ │ ├── Sm2.cs # 簽名驗(yàn)簽、加解密、KDF │ │ │ └── Sm2KeyPair.cs # 密鑰生成與公私鑰解析 │ │ ├── Sm3/ │ │ │ └── Sm3.cs # 常量、填充、壓縮函數(shù) │ │ ├── Sm4/ │ │ │ ├── Sm4.cs # 輪函數(shù)、單分組加解密 │ │ │ ├── Sm4Constants.cs # S 盒、FK、CK │ │ │ └── Sm4Padding.cs # PKCS7 / 無(wú)填充 │ │ ├── Encoding/ │ │ │ ├── Hex.cs # 大小寫(xiě)、帶不帶空格 │ │ │ └── Asn1.cs # DER 序列化給密鑰和簽名用 │ │ └── Utils/ │ │ ├── BigIntegerExtensions.cs# 定長(zhǎng)大端轉(zhuǎn)換、模逆 │ │ └── SecureRandom.cs # 密碼學(xué)安全隨機(jī)數(shù) │ └── SmCrypto.Console/ │ └── Program.cs # 手敲的驗(yàn)證入口 └── tests/ └── SmCrypto.Tests/ # 標(biāo)準(zhǔn)測(cè)試向量 自身往返測(cè)試看這個(gè)結(jié)構(gòu)能發(fā)現(xiàn)一個(gè)細(xì)節(jié)SM2 單獨(dú)占一個(gè)目錄還分了三個(gè)文件。原因很實(shí)在SM2 是橢圓曲線算法點(diǎn)運(yùn)算、曲線參數(shù)、業(yè)務(wù)層的簽名驗(yàn)簽是三件不同的事混在一個(gè)類(lèi)里到后面加密鑰交換或者換曲線就麻煩了。SM3 和 SM4 各自只有一個(gè)主文件是因?yàn)樗鼈兊膶?shí)現(xiàn)相對(duì)獨(dú)立沒(méi)有那么多分支。2.2 目標(biāo)框架與依賴為什么寧可手寫(xiě)也不用系統(tǒng)接口.NET 生態(tài)里做國(guó)密有個(gè)現(xiàn)實(shí)問(wèn)題系統(tǒng)自帶的加密接口在多數(shù)版本上沒(méi)有覆蓋 SM2、SM3、SM4即使新版本在部分平臺(tái)上補(bǔ)了 SM3/SM4Windows 和 Linux 的行為也不完全一致跨平臺(tái)部署很容易遇到問(wèn)題。所以這套實(shí)現(xiàn)選擇純托管代碼零外部依賴System.Numerics.BigInteger就是唯一的大數(shù)工具。目標(biāo)框架怎么選看調(diào)用方。要被老項(xiàng)目引用就多目標(biāo)輸出netstandard2.0加net8.0只做新服務(wù)直接上net8.0省事。真正影響代碼寫(xiě)法的是這三處關(guān)注點(diǎn)netstandard2.0net8.0大數(shù)System.Numerics.BigInteger同上另有TryWriteBytes定長(zhǎng)輸出高性能切片需要System.Memory包原生Spanbyte隨機(jī)數(shù)RNGCryptoServiceProviderRandomNumberGenerator.Fill我一般會(huì)統(tǒng)一寫(xiě)RandomNumberGenerator.Create()拿一個(gè)實(shí)例兩個(gè)框架都能編譯不用寫(xiě)#if。這一點(diǎn)看似無(wú)關(guān)緊要但真正到適配各個(gè)框架版本時(shí)這一點(diǎn)會(huì)節(jié)省很多時(shí)間。提示不要把System.Random用在任何密鑰、k 值、IV 上。它產(chǎn)生的序列可預(yù)測(cè)SM2 的 k 一旦可預(yù)測(cè)私鑰就等價(jià)于公開(kāi)了。2.3 第一次運(yùn)行先把 SM3 的哈希值打印出來(lái)SM2 的調(diào)試成本高因?yàn)樗鼱砍峨S機(jī)數(shù)、點(diǎn)乘、編碼三件事所以第一次運(yùn)行不要碰 SM2先驗(yàn)證 SM3。新建一個(gè)控制臺(tái)項(xiàng)目引用 Core寫(xiě)十行代碼using SmCrypto.Core.Sm3; // 標(biāo)準(zhǔn)附錄里的經(jīng)典向量SM3(abc) byte[] digest Sm3.Hash(System.Text.Encoding.ASCII.GetBytes(abc)); System.Console.WriteLine(Hex.ToHex(digest, upper: false));跑起來(lái)dotnet run --project src/SmCrypto.Console正常輸出應(yīng)該是66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0這 64 個(gè)十六進(jìn)制字符對(duì)上了說(shuō)明填充邏輯、字節(jié)序、壓縮函數(shù)這三塊沒(méi)問(wèn)題。再補(bǔ)一個(gè)長(zhǎng)度不是 3 的用例驗(yàn)證填充邊界把a(bǔ)bcd重復(fù) 16 次正好 64 字節(jié)會(huì)觸發(fā)多補(bǔ)一整個(gè)分組期望結(jié)果debe9ff92275b8a138604889c18e5a4d6fdb70e5387e5765293dcba39c0c5732這兩個(gè)值都對(duì)SM3 這塊基本可以放心了。SM4 用標(biāo)準(zhǔn)向量key 0123456789abcdeffedcba9876543210、明文與 key 相同單分組加密結(jié)果是681edf34d206965e86b3e94f536e4246同一個(gè)塊再加密一次得到595298c7c6fd271f0402f804c33d3f66加解密往返能對(duì)回去才能說(shuō)明輪密鑰沒(méi)有寫(xiě)反。SM2 不適合這么驗(yàn)證后面第 4 章講怎么用往返測(cè)試加對(duì)方的公鑰做交叉驗(yàn)證。3. SM3 與 SM4從填充到輪函數(shù)兩段能直接抄的 C# 實(shí)現(xiàn)3.1 SM3 的填充與壓縮64 輪里真正在變的是什么SM3 輸出 256 位分組 512 位結(jié)構(gòu)上和常見(jiàn)的哈希算法相近但消息擴(kuò)展和輪函數(shù)里的置換是自己的一套。先看填充這是新手最容易寫(xiě)錯(cuò)的地方private static byte[] Pad(byte[] msg) { long bitLen (long)msg.Length * 8; // 比特長(zhǎng)度用 long 防止大報(bào)文溢出 int padLen 64 - (int)((msg.Length 9) % 64); // 0x80 一字節(jié) 8 字節(jié)長(zhǎng)度 if (padLen 64) padLen 0; // 剛好對(duì)齊時(shí)不再補(bǔ)整塊 byte[] buf new byte[msg.Length 1 padLen 8]; Buffer.BlockCopy(msg, 0, buf, 0, msg.Length); buf[msg.Length] 0x80; // 先補(bǔ)一個(gè) 1后面全 0 for (int i 0; i 8; i) buf[buf.Length - 1 - i] (byte)(bitLen (8 * i)); // 大端寫(xiě)長(zhǎng)度 return buf; }bitLen必須用 64 位整型長(zhǎng)度字段是大端序這兩點(diǎn)在跨語(yǔ)言對(duì)接時(shí)最常出錯(cuò)。padLen那個(gè)if判斷也不能少當(dāng)(msg.Length 9) % 64 0時(shí)會(huì)算出 64如果不處理就會(huì)多補(bǔ)一整塊哈希值直接不同。壓縮函數(shù)的核心是消息擴(kuò)展和 64 輪迭代private static void Compress(uint[] v, byte[] block, int offset) { uint[] w new uint[68]; uint[] w1 new uint[64]; for (int i 0; i 16; i) // 前 16 個(gè)字直接讀大端 w[i] ReadBe32(block, offset i * 4); for (int j 16; j 68; j) // 擴(kuò)展到 68 個(gè)字 w[j] P1(w[j - 16] ^ w[j - 9] ^ Rol(w[j - 3], 15)) ^ Rol(w[j - 13], 7) ^ w[j - 6]; for (int j 0; j 64; j) w1[j] w[j] ^ w[j 4]; // W 只是 W 的異或組合 uint a v[0], b v[1], c v[2], d v[3]; uint e v[4], f v[5], g v[6], h v[7]; for (int j 0; j 64; j) { uint t j 16 ? 0x79cc4519u : 0x7a879d8au; // 前 16 輪與后 48 輪常量不同 uint a12 Rol(a, 12); uint ss1 Rol(a12 e Rol(t, j % 32), 7); uint ss2 ss1 ^ a12; uint ff j 16 ? (a ^ b ^ c) : ((a b) | (a c) | (b c)); uint gg j 16 ? (e ^ f ^ g) : ((e f) | (~e g)); uint tt1 ff d ss2 w1[j]; uint tt2 gg h ss1 w[j]; d c; c Rol(b, 9); b a; a tt1; h g; g Rol(f, 19); f e; e P0(tt2); } v[0] ^ a; v[1] ^ b; v[2] ^ c; v[3] ^ d; // 末態(tài)異或回初值 v[4] ^ e; v[5] ^ f; v[6] ^ g; v[7] ^ h; } private static uint P0(uint x) x ^ Rol(x, 9) ^ Rol(x, 17); private static uint P1(uint x) x ^ Rol(x, 15) ^ Rol(x, 23);這里的參數(shù)說(shuō)明一下v是 8 個(gè) 32 位的初始向量第一塊用固定常量后續(xù)塊用上一塊的輸出Rol(x, n)是 32 位循環(huán)左移n要先% 32否則 C# 的移位運(yùn)算符只取低 5 位Rol(t, j % 32)里的取模不能省。w數(shù)組 68 個(gè)字、w1數(shù)組 64 個(gè)字這兩個(gè)長(zhǎng)度是固定的用List或者動(dòng)態(tài)擴(kuò)容會(huì)讓每塊多做幾次分配壓測(cè)時(shí)差別能看出來(lái)。3.2 SM4 輪函數(shù)一個(gè) T 變換貫穿 32 輪SM4 是分組長(zhǎng)度 128 位、密鑰長(zhǎng)度 128 位的分組密碼加密和解密用同一套輪函數(shù)只是輪密鑰順序反過(guò)來(lái)。它的全部復(fù)雜度都集中在T變換上// 字節(jié)代換把 32 位字按字節(jié)逐個(gè)查 S 盒 private static uint Tau(uint a) ((uint)SBox[(a 24) 0xFF] 24) | ((uint)SBox[(a 16) 0xFF] 16) | ((uint)SBox[(a 8) 0xFF] 8) | SBox[a 0xFF]; // 線性變換加密用 L密鑰擴(kuò)展用 L1少移位一次 private static uint L(uint b) b ^ Rol(b, 2) ^ Rol(b, 10) ^ Rol(b, 18) ^ Rol(b, 24); private static uint L1(uint b) b ^ Rol(b, 13) ^ Rol(b, 23); private static uint T(uint x) L(Tau(x)); // 輪函數(shù)里的合成置換 private static uint T1(uint x) L1(Tau(x)); // 密鑰擴(kuò)展里的合成置換S 盒是 256 字節(jié)的常量表放在Sm4Constants.cs里。寫(xiě)的時(shí)候容易犯的錯(cuò)是手抄表格抄錯(cuò)一個(gè)字節(jié)結(jié)果只有某些特殊輸入才會(huì)出錯(cuò)極難排查。建議直接從標(biāo)準(zhǔn)文檔復(fù)制然后寫(xiě)一個(gè)單元測(cè)試斷言SBox[0] 0xd6、SBox[255] 0x48用首尾兩個(gè)值做初步校驗(yàn)。密鑰擴(kuò)展和單分組加解密public static uint[] ExpandKey(byte[] key) { if (key.Length ! 16) throw new ArgumentException(SM4 密鑰必須 16 字節(jié)); uint k0 ReadBe32(key, 0) ^ 0xa3b1bac6; // FK 是四個(gè)固定常量 uint k1 ReadBe32(key, 4) ^ 0x56aa3350; uint k2 ReadBe32(key, 8) ^ 0x677d9197; uint k3 ReadBe32(key, 12) ^ 0xb27022dc; uint[] rk new uint[32]; for (int i 0; i 32; i) { uint k4 k0 ^ T1(k1 ^ k2 ^ k3 ^ Ck(i)); // CK 由公式生成不必手寫(xiě)表 rk[i] k4; k0 k1; k1 k2; k2 k3; k3 k4; } return rk; } // CK[i] (ck0,ck1,ck2,ck3)其中 ck_j ((4i j) * 7) mod 256 private static uint Ck(int i) { uint v 0; for (int j 0; j 4; j) v (v 8) | (uint)(((4 * i j) * 7) 0xFF); return v; } // 加解密共用解密時(shí)把輪密鑰倒著傳進(jìn)來(lái)即可 public static void CryptBlock(uint[] rk, byte[] input, int inOff, byte[] output, int outOff) { uint x0 ReadBe32(input, inOff); uint x1 ReadBe32(input, inOff 4); uint x2 ReadBe32(input, inOff 8); uint x3 ReadBe32(input, inOff 12); for (int i 0; i 32; i) { uint x4 x0 ^ T(x1 ^ x2 ^ x3 ^ rk[i]); // 一輪只產(chǎn)出一個(gè)新字 x0 x1; x1 x2; x2 x3; x3 x4; } // 輸出要反序這一步漏了會(huì)得到完全對(duì)不上的結(jié)果 WriteBe32(output, outOff, x3); WriteBe32(output, outOff 4, x2); WriteBe32(output, outOff 8, x1); WriteBe32(output, outOff 12, x0); }參數(shù)上要注意兩件事。第一rk是 32 個(gè) 32 位輪密鑰加密時(shí)正序解密時(shí)rk.Reverse()即可不需要另寫(xiě)一個(gè)解密函數(shù)。第二最后輸出必須反序x3 x2 x1 x0這是標(biāo)準(zhǔn)里寫(xiě)死的反變換很多人在這卡一下午因?yàn)榧用芙Y(jié)果看著“像那么回事”只是每個(gè)塊都對(duì)不上。3.3 分組模式與填充ECB 之外還得有 CBC 和 PKCS7單分組函數(shù)只是零件實(shí)際報(bào)文長(zhǎng)度很少正好是 16 的倍數(shù)所以要有模式和填充。ECB 實(shí)現(xiàn)最簡(jiǎn)單但同樣的明文塊會(huì)得到同樣的密文塊圖片、表格類(lèi)數(shù)據(jù)一眼就能看出結(jié)構(gòu)業(yè)務(wù)上一般不允許用。CBC 更常見(jiàn)public static byte[] EncryptCbc(byte[] key, byte[] iv, byte[] plain) { if (iv.Length ! 16) throw new ArgumentException(CBC 的 IV 必須 16 字節(jié)); byte[] padded Sm4Padding.Pkcs7(plain, 16); // 補(bǔ)到 16 的倍數(shù) byte[] cipher new byte[padded.Length]; byte[] prev (byte[])iv.Clone(); uint[] rk ExpandKey(key); byte[] block new byte[16]; for (int i 0; i padded.Length; i 16) { for (int j 0; j 16; j) block[j] (byte)(padded[i j] ^ prev[j]); // 先和上一塊密文異或 CryptBlock(rk, block, 0, cipher, i); Buffer.BlockCopy(cipher, i, prev, 0, 16); // 本塊密文成為下一塊的 prev } return cipher; }Sm4Padding.Pkcs7的邏輯是缺 n 字節(jié)就補(bǔ) n 個(gè)值為 n 的字節(jié)正好對(duì)齊時(shí)補(bǔ)一整塊 16 個(gè)0x10。這個(gè)“正好對(duì)齊也要補(bǔ)”的規(guī)則是解密時(shí)判斷填充長(zhǎng)度的依據(jù)少補(bǔ)這一塊對(duì)方解出來(lái)的尾巴會(huì)被當(dāng)成數(shù)據(jù)。IV 每次加密都要換新的隨機(jī)值跟著密文一起發(fā)過(guò)去不需要保密但絕不能固定不變否則相同明文前綴的密文前綴也相同。注意CBC 只保證機(jī)密性不保證完整性。要防篡改還得在密文后面附加 SM3 或 SM2 的校驗(yàn)值或者干脆用 SM2 加密會(huì)話密鑰、SM4 加密數(shù)據(jù)的兩段式方案。4. SM2 關(guān)鍵鏈路曲線參數(shù)、ZA 值與密文排列4.1 曲線參數(shù)與密鑰對(duì)先把 BigInteger 的字節(jié)序捋順SM2 用的是 256 位素域上的橢圓曲線曲線方程、基點(diǎn)、階都是固定常量直接照標(biāo)準(zhǔn)抄進(jìn)Sm2Curve.cs。真正的坑不在參數(shù)在BigInteger的字節(jié)序C# 的BigInteger內(nèi)部是小端構(gòu)造函數(shù)默認(rèn)還帶符號(hào)位而國(guó)密的所有數(shù)據(jù)都是大端無(wú)符號(hào)定長(zhǎng)。// 定長(zhǎng) 32 字節(jié)大端輸出左側(cè)補(bǔ) 0 補(bǔ)齊 internal static byte[] ToFixed32(BigInteger v) { byte[] raw v.ToByteArray(isUnsigned: true, isBigEndian: true); if (raw.Length 32) return raw; byte[] result new byte[32]; Buffer.BlockCopy(raw, 0, result, 32 - raw.Length, raw.Length); return result; } // 反過(guò)來(lái)讀的時(shí)候也要聲明無(wú)符號(hào)大端否則最高位為 1 會(huì)變成負(fù)數(shù) internal static BigInteger FromFixed32(byte[] buf, int offset) new BigInteger(new ReadOnlySpanbyte(buf, offset, 32), isUnsigned: true, isBigEndian: true);ToFixed32里那個(gè)補(bǔ)零動(dòng)作不能省。橢圓曲線坐標(biāo)偶爾會(huì)出現(xiàn)高位為 0 的情況概率大約 1/256如果直接ToByteArray輸出會(huì)少一個(gè)字節(jié)長(zhǎng)度變成 31對(duì)方解析直接報(bào)錯(cuò)。這種概率性錯(cuò)誤最難排查本地跑一百次都好上線跑一萬(wàn)次報(bào)一次。密鑰對(duì)生成就是取一個(gè)[1, n-1]的隨機(jī)數(shù)當(dāng)私鑰再算d * G得到公鑰點(diǎn)public static (BigInteger d, byte[] publicKey) GenerateKeyPair() { BigInteger d; do { d Sm2Curve.RandomScalar(); } while (d.IsZero || d Sm2Curve.N); var (x, y) Sm2Curve.MultiplyG(d); // 未壓縮點(diǎn)格式04 || X(32) || Y(32)共 65 字節(jié) byte[] pub new byte[65]; pub[0] 0x04; Buffer.BlockCopy(ToFixed32(x), 0, pub, 1, 32); Buffer.BlockCopy(ToFixed32(y), 0, pub, 33, 32); return (d, pub); }公鑰點(diǎn)的序列化格式有三種未壓縮04||X||Y65 字節(jié)、壓縮02/03||X33 字節(jié)、純裸X||Y64 字節(jié)。不同系統(tǒng)默認(rèn)值不一樣聯(lián)調(diào)前先問(wèn)清對(duì)方用哪種或者干脆在庫(kù)里三種都支持讀的時(shí)候看首字節(jié)判斷。4.2 簽名與驗(yàn)簽ZA 值沒(méi)算對(duì)后面全白搭SM2 簽名和很多人熟悉的橢圓曲線簽名差別在于被簽的不是消息的哈希而是ZA || M的哈希。ZA是用戶標(biāo)識(shí)、曲線參數(shù)、公鑰點(diǎn)的哈希摘要作用是把簽名和具體身份綁定起來(lái)。這一步漏了或者用戶 ID 用了默認(rèn)值而對(duì)方用的是自己的驗(yàn)簽 100% 失敗而且失敗信息沒(méi)有任何提示。// ZA SM3(ENTL || ID || a || b || Gx || Gy || Px || Py) private static byte[] ComputeZa(byte[] userId, BigInteger px, BigInteger py) { int bitLen userId.Length * 8; // ENTL 是 ID 的比特長(zhǎng)度2 字節(jié)大端 var ms new MemoryStream(); ms.WriteByte((byte)(bitLen 8)); ms.WriteByte((byte)bitLen); ms.Write(userId); ms.Write(ToFixed32(Sm2Curve.A)); ms.Write(ToFixed32(Sm2Curve.B)); ms.Write(ToFixed32(Sm2Curve.Gx)); ms.Write(ToFixed32(Sm2Curve.Gy)); ms.Write(ToFixed32(px)); ms.Write(ToFixed32(py)); return Sm3.Hash(ms.ToArray()); } public static (BigInteger r, BigInteger s) Sign(byte[] message, BigInteger d, byte[] userId) { var (px, py) Sm2Curve.MultiplyG(d); byte[] za ComputeZa(userId, px, py); // e SM3(ZA || M)再當(dāng)作 256 位大端無(wú)符號(hào)整數(shù) byte[] digest Sm3.Hash(Concat(za, message)); BigInteger e new BigInteger(digest, isUnsigned: true, isBigEndian: true); while (true) { BigInteger k Sm2Curve.RandomScalar(); var (x1, _) Sm2Curve.MultiplyG(k); BigInteger r (e x1) % Sm2Curve.N; if (r.IsZero || (r k) % Sm2Curve.N 0) continue; // 規(guī)范要求重取 k BigInteger s BigInteger.ModPow(1 d, Sm2Curve.N - 2, Sm2Curve.N) * (k - r * d) % Sm2Curve.N; if (s.Sign 0) s Sm2Curve.N; // C# 取模會(huì)保留負(fù)號(hào)必須手動(dòng)修正 if (s.IsZero) continue; return (r, s); } }逐段說(shuō)明。ComputeZa里的所有長(zhǎng)度都必須定長(zhǎng) 32 字節(jié)少一位整體就變了所以統(tǒng)一走ToFixed32。默認(rèn)用戶 ID 是 16 字節(jié)的固定字符串很多系統(tǒng)的開(kāi)放接口就是用它但私有協(xié)議經(jīng)常換成自己的 appId這一項(xiàng)必須和對(duì)方確認(rèn)。ModPow(x, n-2, n)是在求模逆因?yàn)閚是素?cái)?shù)費(fèi)馬小定理成立比手寫(xiě)擴(kuò)展歐幾里得快也不用擔(dān)心邊界。s的負(fù)數(shù)處理是 C# 特有的一處。C# 的%運(yùn)算符對(duì)負(fù)數(shù)返回負(fù)值s.Sign 0時(shí)加一次n才能回到[0, n-1]。在 Java 或 Python 里寫(xiě)習(xí)慣的人換到 C# 上很容易忽略這一點(diǎn)結(jié)果只有極少部分簽名是負(fù)數(shù)測(cè)試樣本少的時(shí)候根本發(fā)現(xiàn)不了。驗(yàn)簽就是反過(guò)來(lái)算檢查r、s是否在[1, n-1]算t (r s) mod nt 0直接拒然后算點(diǎn)(x1, y1) s*G t*P判斷(e x1) mod n r。4.3 加解密與密文順序C1C3C2 和 C1C2C3 的互相傷害SM2 加密產(chǎn)出的三部分C1是隨機(jī)點(diǎn)kGC2是明文異或 KDF 流C3是校驗(yàn)摘要。老版本標(biāo)準(zhǔn)把順序?qū)懗蒀1C2C3新標(biāo)準(zhǔn)改成C1C3C2兩套在現(xiàn)實(shí)系統(tǒng)里都還在用所以庫(kù)里一定要留一個(gè)開(kāi)關(guān)。public static byte[] Encrypt(byte[] message, byte[] publicKey, bool c1c3c2 true) { var (x, y) Sm2Curve.DecodePoint(publicKey); // 04 || X || Y while (true) { BigInteger k Sm2Curve.RandomScalar(); var (x1, y1) Sm2Curve.MultiplyG(k); var (x2, y2) Sm2Curve.Multiply(new Point(x, y), k); byte[] t Kdf(Concat(ToFixed32(x2), ToFixed32(y2)), message.Length); if (t.All(b b 0)) continue; // 全 0 說(shuō)明 KDF 失效規(guī)范要求重來(lái) byte[] c1 Sm2Curve.EncodePoint(x1, y1); // 65 字節(jié) byte[] c2 Xor(message, t); byte[] c3 Sm3.Hash(Concat(ToFixed32(x2), message, ToFixed32(y2))); return c1c3c2 ? Concat(c1, c3, c2) : Concat(c1, c2, c3); } }KDF 是基于 SM3 的計(jì)數(shù)器派生internal static byte[] Kdf(byte[] z, int klen) { byte[] output new byte[klen]; for (int i 0, ct 1; i klen; i 32, ct) { // 計(jì)數(shù)器是 4 字節(jié)大端接在共享點(diǎn)后面一起哈希 byte[] h Sm3.Hash(Concat(z, new byte[] { (byte)(ct 24), (byte)(ct 16), (byte)(ct 8), (byte)ct })); Buffer.BlockCopy(h, 0, output, i, Math.Min(32, klen - i)); } return output; }解密的順序是先按配置把三段拆開(kāi)用C1和自己的私鑰算出共享點(diǎn)(x2, y2)用同樣的 KDF 得到t異或回C2最后重算C3比對(duì)。C3比對(duì)必須用固定時(shí)間比較逐字節(jié)異或累加不要用SequenceEqual提前返回這類(lèi)細(xì)節(jié)在安全審計(jì)時(shí)會(huì)被挑出來(lái)。5. 避坑與排查聯(lián)調(diào)現(xiàn)場(chǎng)最常見(jiàn)的五個(gè)問(wèn)題這一章是整套實(shí)現(xiàn)里最值錢(qián)的部分。算法本身照著標(biāo)準(zhǔn)寫(xiě)就行真正耗時(shí)間的是下面這些表現(xiàn)完全一樣、原因各不相同的問(wèn)題。5.1 驗(yàn)簽一直返回 false但雙方代碼看著都“對(duì)”現(xiàn)象自測(cè)簽名驗(yàn)簽往返完全正常一旦換成對(duì)方給的公鑰就失敗把對(duì)方發(fā)來(lái)的簽名拿去驗(yàn)也失敗兩邊都不報(bào)異常只是布爾值 false。原因九成是 ZA 里的用戶 ID 不一致。默認(rèn) ID 是 16 個(gè)字節(jié)的固定串而對(duì)方可能用了自己的應(yīng)用標(biāo)識(shí)另一個(gè)可能是對(duì)方把ZA || M里的M先做了 Base64 解碼再哈希而你直接對(duì)字符串字節(jié)哈希。解決讓對(duì)方明確給出 ID 的原始字節(jié)不是 Base64不是十六進(jìn)制并且約定M到底是原始報(bào)文還是某種規(guī)范化之后的字符串。確認(rèn)后先用SM3(ZA)單獨(dú)對(duì)比一次把 ZA 的哈希值發(fā)給對(duì)方核對(duì)這比反復(fù)試簽名快得多。ZA 一致了簽名再不對(duì)才是曲線參數(shù)或s負(fù)數(shù)處理的問(wèn)題。5.2 SM4 加密結(jié)果第一塊對(duì)、后面全不對(duì)現(xiàn)象16 字節(jié)以內(nèi)的短報(bào)文加密結(jié)果和對(duì)方一致一旦超過(guò) 16 字節(jié)第一塊密文相同第二塊開(kāi)始全亂。原因CBC 的鏈?zhǔn)疆惢驅(qū)戝e(cuò)了。常見(jiàn)兩種寫(xiě)法錯(cuò)誤一是用明文塊而不是密文塊作為下一輪的prev二是循環(huán)里prev更新寫(xiě)在異或之前。解決把Buffer.BlockCopy(cipher, i, prev, 0, 16)放在CryptBlock之后、下一輪異或之前中間不要有別的賦值。驗(yàn)證方法是拿 32 字節(jié)的固定輸入手工用第一塊密文異或第二塊明文看結(jié)果是不是和內(nèi)部中間值一致。5.3 SM2 加密偶發(fā)“密文長(zhǎng)度不對(duì)”重啟又好了現(xiàn)象接口大部分時(shí)間正常偶爾報(bào)密文長(zhǎng)度異常日志里能看到長(zhǎng)度是 96 或 98 而期望 97 或 112 之類(lèi)的值。原因BigInteger.ToByteArray()輸出的長(zhǎng)度不固定。坐標(biāo)高位為 0 時(shí)會(huì)少一個(gè)字節(jié)如果沒(méi)用isUnsigned: true最高位為 1 時(shí)還會(huì)多出一個(gè)0x00符號(hào)字節(jié)。兩種都會(huì)讓C1的長(zhǎng)度在 64、65、66 之間抖。解決所有點(diǎn)坐標(biāo)輸出統(tǒng)一走定長(zhǎng) 32 字節(jié)的轉(zhuǎn)換函數(shù)不要直接調(diào)ToByteArray。再在解碼側(cè)加一層防御讀到C1時(shí)按首字節(jié)判斷格式04未壓縮、02/03壓縮、其余按裸坐標(biāo)補(bǔ)齊別硬編碼固定偏移量。5.4 大量數(shù)據(jù)加密時(shí) CPU 打滿單條報(bào)文要幾十毫秒現(xiàn)象壓測(cè)時(shí) SM4 的吞吐還能接受但整個(gè)接口 RT 很高火焰圖顯示時(shí)間集中在 SM2 的標(biāo)量乘上。原因一次 SM2 加解密要做兩次點(diǎn)乘kG和kP樸素的雙倍點(diǎn)算法每次都做模逆模逆是這里面最貴的一步另外BigInteger是不可變類(lèi)型循環(huán)里頻繁產(chǎn)生中間對(duì)象GC 壓力也上來(lái)了。解決把點(diǎn)運(yùn)算改到雅可比坐標(biāo)下做只在最后一步轉(zhuǎn)回仿射坐標(biāo)一次點(diǎn)乘的模逆從幾百次降到 1 次kG因?yàn)榛c(diǎn)固定可以預(yù)計(jì)算一張表做固定窗口加速。業(yè)務(wù)側(cè)更好的做法是不用 SM2 直接加密大報(bào)文改成 SM2 加密一把隨機(jī)的 SM4 密鑰數(shù)據(jù)走 SM4性能差距是數(shù)量級(jí)的。5.5 升級(jí)框架版本后簽名結(jié)果變了現(xiàn)象從舊框架遷到新框架同樣的私鑰、同樣的報(bào)文對(duì)方突然驗(yàn)簽失敗而自測(cè)往返還是通的。原因隨機(jī)數(shù)來(lái)源換掉了或者BigInteger的行為在新運(yùn)行時(shí)上有細(xì)微差異。更隱蔽的一種是把k寫(xiě)成了固定值做“可復(fù)現(xiàn)測(cè)試”上線忘了改回去兩次簽名用了同一個(gè)k從本文還有配套的精品資源點(diǎn)擊獲取