国密算法 C# 实现：SM2/SM3/SM4 对接与避坑指南

简介：一套基于 C# WinForm 的国密算法演示程序，聚焦 SM2 公钥密码、SM3 摘要与 SM4 分组加密三条主线，适合正在做接口对接、数据加密改造或信创合规适配的 .NET 开发者对照学习。工程按算法拆分为独立窗体与工具类，SM2 封装密钥生成与加解密流程，SM3 提供摘要计算入口，SM4 给出上下文与工具类两层封装，便于比对调用方式与参数配置。压缩包共 51 个文件、约 5.33MB，主体为 21 个 cs 源码，配套 resx 与 resources 界面资源、dll 依赖、exe 可执行程序及 sln、csproj 工程文件，另有少量 pdb 调试符号与缓存文件，解压后可用 Visual Studio 打开解决方案直接运行调试。目前已有 1316 人学习下载。读者可获得三条国密算法的 C# 调用范式与类结构划分、基于 BouncyCastle 的依赖组织方式及可运行的窗体交互示例，便于把算法能力嵌入既有业务系统并对照验证输出。

1. 从一次对接失败说起：国密算法 C# 实现到底解决什么问题

国密算法 C# 实现这套代码包，第一次被我拿进项目时，是为了解决一个很具体的问题：对方系统只认 SM2 签名和 SM4 密文，而现有 C# 服务里只有常规哈希和 AES。那是一次跨系统数据交换，字段不多，但签名一验就失败，密文一解就乱码。后来把 SM2、SM3、SM4 的调用链拆开，才发现问题不在算法本身，而在密钥格式、密文顺序和 userId 这些边界参数上。这套实现适合正在做 C# 服务端对接、需要把国密算法嵌进业务代码的从业者；新手能按调用示例跑通，熟手可以重点看密钥编码和跨语言兼容那几节。

2. SM3 与 SM4 的落地：哈希与对称加密的 C# 调用边界

2.1 为什么先跑 SM3：数据完整性校验的最小闭环

拿到一份国密 C# 实现，我一般不会先碰 SM2。SM2 牵扯椭圆曲线点、userId、签名编码和密文顺序，变量太多，一旦结果不对，很难判断是密钥问题还是调用问题。SM3 是更干净的入口：输入一段字节，输出固定 32 字节摘要，十六进制就是 64 个字符。先用公开测试向量把 SM3 跑通，能快速确认这份实现的字节序、编码方式和 Hex 输出格式有没有问题。SM3 本身采用消息填充加迭代压缩，输出 256 位摘要，适合做完整性校验、口令派生中的中间步骤，不适合替代加密。业务里常见的用法是：对配置密文做 SM3 摘要，再用 SM2 对摘要签名；或者对上传文件分块计算 SM3，和对方给出的摘要比对。

using System; using System.Text; using NationalCrypto.Sm; namespace SmCryptoDemo { class Sm3Demo { static void Main() { // 待校验的原始字节，不要先转成十六进制字符串再哈希 byte[] data = Encoding.UTF8.GetBytes("abc"); // 资源里的 SM3 封装：输入 byte[]，输出小写十六进制字符串 string digestHex = Sm3Hash.ComputeHex(data); Console.WriteLine(digestHex); // 预期输出：66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 // 如果业务需要原始 32 字节，用 Compute 而不是 ComputeHex byte[] digestBytes = Sm3Hash.Compute(data); Console.WriteLine(digestBytes.Length); // 32 } } }

这段代码的关键在输入类型。Sm3Hash.ComputeHex接收byte[]，返回 64 字符小写十六进制；Sm3Hash.Compute返回原始 32 字节。参数上最容易翻车的是编码：调用方用 UTF-8，验签方用 GBK，摘要一定对不上。另一个常见误用是把十六进制字符串再当成普通字符串哈希一遍，结果长度还是 64，但值完全不对。测试向量abc的 SM3 值是公开的，拿它做第一道校验最省事；如果输出只有 32 个字符，通常是拿byte[].ToString()直接输出了类型名，不是真正的十六进制。文件摘要不要一次性ReadAllBytes，大文件用流式分块，每块更新同一个 SM3 上下文，最后再取摘要。

2.2 SM4 的四种模式与填充：CBC、ECB、GCM 怎么选

SM4 是分组密码，分组长度 128 位，密钥长度 128 位，也就是 16 字节。它和 AES 一样需要模式与填充配合，C# 里没有内置 SM4，所以这份实现自己封装了Sm4Cryptor。选型时先看对方系统用什么：老系统经常用 ECB，因为不需要 IV，但 ECB 会把相同明文块加密成相同密文块，敏感配置不要用；CBC 需要 16 字节 IV，能接受随机 IV 随密文传输，兼容性最好；CTR 把分组密码当流密码用，不需要填充，但计数器管理要小心；GCM 带认证标签，能同时做加密和完整性校验，不过不是所有国密对接方都支持。我一般会先确认资源里的Sm4Mode枚举到底暴露了哪几种，不要假设它支持 GCM。

using System; using System.Text; using NationalCrypto.Sm; namespace SmCryptoDemo { class Sm4Demo { static void Main() { // 16 字节密钥，十六进制字符串长度必须是 32 byte[] key = Convert.FromHexString("0123456789abcdeffedcba9876543210"); // CBC 模式需要 16 字节 IV，实际项目里每次加密随机生成 byte[] iv = Convert.FromHexString("000102030405060708090a0b0c0d0e0f"); byte[] plain = Encoding.UTF8.GetBytes("{\"db\":\"mysql\",\"user\":\"app\"}"); var sm4 = new Sm4Cryptor(key, iv, Sm4Mode.Cbc, Sm4Padding.Pkcs7); byte[] cipher = sm4.Encrypt(plain); byte[] back = sm4.Decrypt(cipher); Console.WriteLine(Convert.ToHexString(cipher)); Console.WriteLine(Encoding.UTF8.GetString(back)); } } }

Sm4Cryptor的构造参数是密钥、IV、模式和填充。密钥必须是 16 字节，IV 在 CBC 模式下也必须是 16 字节，长度不对会在构造或加密时直接抛异常。填充用Sm4Padding.Pkcs7时，解密端必须用同样的填充；如果对方用 NoPadding，明文长度必须自己补齐到 16 字节的整数倍。密文传输格式也要提前约定：Hex 字符串长度是偶数字符，Base64 带+、/、=，两种格式混用会在解码阶段就失败。IV 可以公开，但不要固定成常量，更不要所有报文复用同一个 IV；CBC 下 IV 复用会让相同前缀的明文产生相同密文前缀，安全性会打折扣。

2.3 用 C# 封装一层：统一入口与参数校验

直接在业务代码里到处new Sm4Cryptor不是不行，但对接方一多，Hex 大小写、Base64 去空格、密钥长度校验会散落在各个服务里。我一般会加一层很薄的 Facade，只做参数收敛和异常包装，不重新实现算法。这样后面换实现、加日志、做密钥轮换，都只改一个地方。下面这段代码把 SM3 和 SM4 的常用入口收在一起，重点看ParseHex的长度校验：SM4 密钥和 IV 都固定 16 字节，提前拦住比等到解密报填充错误要省时间。

using System; using NationalCrypto.Sm; namespace SmCryptoDemo { public static class SmCryptoFacade { public static string Sm3Hex(string text) { if (text == null) throw new ArgumentNullException(nameof(text)); return Sm3Hash.ComputeHex(System.Text.Encoding.UTF8.GetBytes(text)); } public static string Sm4EncryptHex(string plainText, string keyHex, string ivHex) { byte[] key = ParseHex(keyHex, 16, nameof(keyHex)); byte[] iv = ParseHex(ivHex, 16, nameof(ivHex)); var sm4 = new Sm4Cryptor(key, iv, Sm4Mode.Cbc, Sm4Padding.Pkcs7); byte[] cipher = sm4.Encrypt(System.Text.Encoding.UTF8.GetBytes(plainText)); return Convert.ToHexString(cipher); } private static byte[] ParseHex(string hex, int expectedBytes, string paramName) { if (string.IsNullOrWhiteSpace(hex)) throw new ArgumentException("十六进制字符串不能为空", paramName); byte[] bytes = Convert.FromHexString(hex); if (bytes.Length != expectedBytes) throw new ArgumentException($"{paramName} 需要 {expectedBytes} 字节，实际 {bytes.Length} 字节", paramName); return bytes; } } }

expectedBytes是这层封装的核心参数：SM4 密钥传 16，IV 传 16，后面 SM2 私钥可以传 32。异常信息里带参数名和实际长度，联调时能直接定位是密钥给错还是 IV 给错。Convert.FromHexString在较新的 .NET 里可用，老框架换成自定义 Hex 工具即可，注意不要用BitConverter.ToString反向拼接时留下连字符。这层 Facade 不隐藏算法细节，只收敛边界；真正排查问题时，还是要把Sm4Cryptor单独拿出来跑一组测试向量。

3. SM2 的落地：密钥对、签名验签与加解密的分工

3.1 SM2 密钥格式：04 开头公钥与 PKCS#8 私钥的转换

SM2 基于椭圆曲线，公钥是一个曲线点。未压缩公钥的十六进制通常是04 + X(32字节) + Y(32字节)，总长 130 个字符；去掉04就是 128 个字符。私钥是 32 字节，十六进制 64 个字符。跨语言对接时，第一件事就是确认公钥带不带04：有的系统给 130 字符，有的给 128 字符，有的给压缩公钥 66 字符（02或03开头）。这份 C# 实现的Sm2KeyPair.PublicKeyHex我一般按带04处理，如果对方只给 128 字符，验签前补04；如果对方给的是压缩公钥，需要先解压成未压缩点再验签。私钥不要补00，也不要截断，长度不对直接抛异常比后面签名失败更好查。

using NationalCrypto.Sm; var keyPair = Sm2KeyPair.Generate(); // 未压缩公钥：04 + X(32字节) + Y(32字节)，十六进制长度 130 string publicKeyHex = keyPair.PublicKeyHex; // 私钥：32 字节，十六进制长度 64 string privateKeyHex = keyPair.PrivateKeyHex; Console.WriteLine(publicKeyHex.Length); // 130 Console.WriteLine(privateKeyHex.Length); // 64 // 从已有十六进制字符串恢复密钥对，用于配置注入 var restored = Sm2KeyPair.FromHex(publicKeyHex, privateKeyHex);

Generate用于测试环境生成密钥对，FromHex用于把配置中心里的密钥字符串还原成对象。参数上要注意：PublicKeyHex是否带04由这份实现决定，不要凭感觉截断；PrivateKeyHex是 64 字符，不要当 Base64 解码。生产环境私钥不要明文写进配置文件，至少用环境变量或密钥管理服务注入；测试密钥和正式密钥要分开，避免把测试私钥带到联调环境。如果对方要求 PKCS#8 或 X.509 封装，这份实现里的裸 Hex 需要再做一层编码转换，转换时保留好原始 32 字节私钥和 65 字节公钥点。

3.2 签名与验签：userId 和随机数 k 的坑

SM2 签名不是直接对消息做哈希，而是先算ZA，再把ZA和消息一起做 SM3，最后用私钥和随机数k做椭圆曲线运算。ZA里包含 userId，默认值是 16 字节 ASCII 的1234567812345678。很多验签失败不是密钥错，而是双方 userId 不一致：一端用默认值，另一端传了业务号，摘要输入变了，验签自然不过。另一个坑是随机数k，签名内部必须每次生成新的k，不能复用，也不能自己传固定值。复用k会直接暴露私钥，这不是玄学，是椭圆曲线签名的数学性质决定的。

using System.Text; using NationalCrypto.Sm; byte[] data = Encoding.UTF8.GetBytes("orderId=1001&amount=99.00"); string userId = "1234567812345678"; // SM2 默认 userId，16 字节 ASCII string sign = Sm2Signer.SignData(data, privateKeyHex, userId); bool ok = Sm2Signer.VerifyData(data, sign, publicKeyHex, userId); Console.WriteLine(ok); // True

SignData的入参是原始字节、私钥 Hex 和 userId，返回签名串；VerifyData用公钥 Hex 和同一个 userId 验签。参数说明：data不要先 Base64 再签名，签名对象必须和验签对象逐字节一致；sign的编码格式要确认，常见有 DER 和 RS 拼接两种，跨语言时先拿一组固定数据比对签名长度和结构。签名串传输时注意大小写和换行，Hex 里混入空格会让解码失败。如果验签返回 false，先查 userId，再查公钥是否带04，最后查签名编码格式，不要一上来就怀疑算法实现。

3.3 加密与解密：C1C3C2 与 C1C2C3 的顺序问题

SM2 加密的输出由三部分组成：C1是椭圆曲线点，未压缩时 65 字节；C3是 SM3 摘要，32 字节；C2是密文数据，长度和明文一致。国密标准里常见顺序是C1C3C2，但一些老系统或跨语言库用C1C2C3。这两种顺序密文总长度一样，解密时如果顺序搞错，可能不报错但解出来是乱码，或者报点格式错误。我一般会在联调前先问清楚三件事：C1 带不带04、顺序是 C1C3C2 还是 C1C2C3、密文是 Hex 还是 Base64。这三个参数对齐了，SM2 加解密基本不会出问题。

using System.Text; using NationalCrypto.Sm; byte[] plain = Encoding.UTF8.GetBytes("{\"token\":\"abc\"}"); // C1C3C2：C1 为椭圆曲线点，C3 为 SM3 摘要，C2 为密文数据 string cipherHex = Sm2Cryptor.Encrypt(plain, publicKeyHex, Sm2CipherFormat.C1C3C2); byte[] back = Sm2Cryptor.Decrypt(cipherHex, privateKeyHex, Sm2CipherFormat.C1C3C2); Console.WriteLine(Encoding.UTF8.GetString(back));

Sm2CipherFormat是加解密的关键参数，必须和对方一致。Encrypt接收明文字节、公钥 Hex 和格式枚举；Decrypt接收密文 Hex、私钥 Hex 和同一个格式枚举。SM2 加密适合小数据，比如加密一个 SM4 密钥、一个 token 或一段短配置；长数据不要直接 SM2，性能不合适，常见做法是用 SM4 加密业务数据，再用 SM2 加密 SM4 密钥。密文 Hex 长度可以用公式粗算：C165 字节 +C332 字节 + 明文长度，再乘 2 得到十六进制字符数；长度明显不对，先查 C1 是否被截掉04。

4. 把三种算法串起来：一个配置中心加解密的完整示例

4.1 场景建模：配置项加密与签名校验

单独跑通 SM3、SM4、SM2 只是第一步，真正落地时它们通常串在一条链上。假设一个模拟项目里，配置中心要下发一段数据库连接配置，链路要求是：配置明文用 SM4 加密，密文用 SM3 做摘要，摘要用 SM2 私钥签名；接收方先用 SM2 公钥验签，确认摘要没被改，再用 SM4 解密。这个场景里 SM4 负责机密性，SM3 负责完整性，SM2 负责身份认证和不可否认。选型理由很直接：SM4 比 SM2 适合加密长数据，SM3 比直接签名密文更省性能，SM2 签名比 HMAC 更适合跨系统互信。下面用一份简化代码把链路串起来，重点看每一步的输入输出类型。

4.2 代码实现：SM4 加密配置、SM3 摘要、SM2 签名

using System; using System.Text; using NationalCrypto.Sm; namespace SmCryptoDemo { class ConfigFlow { static void Main() { // 模拟配置明文 string configJson = "{\"db\":\"mysql\",\"timeout\":30}"; byte[] configBytes = Encoding.UTF8.GetBytes(configJson); // 1. 生成一次性 SM4 密钥和 IV byte[] sm4Key = Sm4KeyGenerator.RandomKey(); // 16 字节 byte[] sm4Iv = Sm4KeyGenerator.RandomIv(); // 16 字节 // 2. SM4 加密配置 var sm4 = new Sm4Cryptor(sm4Key, sm4Iv, Sm4Mode.Cbc, Sm4Padding.Pkcs7); byte[] configCipher = sm4.Encrypt(configBytes); // 3. 对密文做 SM3 摘要，用于完整性校验 string cipherDigest = Sm3Hash.ComputeHex(configCipher); // 4. 用 SM2 私钥对摘要签名 string sign = Sm2Signer.SignData( Encoding.UTF8.GetBytes(cipherDigest), privateKeyHex, "1234567812345678"); // 5. 接收方验签、解密 bool ok = Sm2Signer.VerifyData( Encoding.UTF8.GetBytes(cipherDigest), sign, publicKeyHex, "1234567812345678"); if (!ok) throw new InvalidOperationException("配置密文签名校验失败"); byte[] plain = sm4.Decrypt(configCipher); Console.WriteLine(Encoding.UTF8.GetString(plain)); } } }

这段代码里，Sm4KeyGenerator.RandomKey()和RandomIv()是资源里的辅助方法，分别生成 16 字节密钥和 IV；如果手头版本没有这两个方法，用RandomNumberGenerator生成 16 字节也行。Sm3Hash.ComputeHex(configCipher)的输出是 64 字符十六进制，签名时把它转成 UTF-8 字节，而不是直接对configCipher签名；验签方必须用同样的转换方式，否则摘要字符串一样、字节不一样，验签照样失败。SM4 密钥和 IV 不能只放在内存里，实际链路里要随密文一起传给接收方，可以用 SM2 公钥再加密一次 SM4 密钥，形成数字信封。参数上，Sm4Mode.Cbc和Sm4Padding.Pkcs7要跟解密端一致，Sm2CipherFormat在这个示例里没出现，但数字信封那一步会用到。

4.3 验证与回归：测试向量和边界数据

链路跑通后不要只测一条正常数据。我一般会准备一组边界输入：空字符串、纯中文、超长 JSON、包含换行和引号的配置、二进制字节。SM3 先用公开测试向量卡住实现，SM4 用固定密钥和 IV 做一次已知密文比对，SM2 用同一组密钥做签名验签回归。下面这张表是我常用的最小验证集，第三列不是让读者死记，而是提醒每个输入都要有明确预期，不然联调时只能靠猜。

回归时重点看三个位置：SM3 输入是不是原始字节、SM4 的 key/IV 长度是不是 16、SM2 的 userId 和密文顺序是不是和对方一致。任何一个位置变了，整条链的结果都会变。测试数据里最好保留一组“错误样例”，比如故意把 C1C3C2 改成 C1C2C3，确认解密会报错而不是静默返回乱码；再比如故意把 userId 改一位，确认验签返回 false。这些负向用例在联调阶段比正向用例更能省时间。

5. 避坑与排查：国密 C# 实现里最容易翻车的五件事

5.1 现象：验签总失败，换一把密钥就正常

现象是同一段数据、同一个签名串，A 公钥验签失败，换 B 公钥就通过。原因通常不是密钥本身，而是公钥格式不一致：一端给的是 130 字符带04的未压缩公钥，另一端按 128 字符解析，或者把04当成了数据的一部分。还有一种情况是 userId 不一致，签名端用默认1234567812345678，验签端传了业务号，ZA变了，验签自然失败。解决时先打印公钥长度和前缀，确认是不是04开头；再确认双方 userId 是否逐字节一致；最后确认签名串是 DER 还是 RS 拼接。不要一上来就重新生成密钥，换密钥能“好”往往只是碰巧绕开了格式问题。

5.2 现象：SM4 解密报填充无效

现象是加密正常，解密抛填充无效或解密结果尾部多出乱码。原因常见有三类：密钥或 IV 长度不对，比如把 32 字符 Hex 当成了 32 字节密钥；模式和填充不一致，加密用 CBC/PKCS7，解密用 ECB/NoPadding；密文编码混用，加密端输出 Base64，解密端按 Hex 解码。解决时先把 key、IV、密文长度打印出来，SM4 的 key 和 IV 都应该是 16 字节，密文长度应该是 16 的整数倍；再核对双方的模式和填充枚举；最后统一密文传输格式，Hex 就全程 Hex，Base64 就全程 Base64，不要在中途转来转去。

5.3 现象：SM2 密文跨语言解不开

现象是 C# 端加密的 SM2 密文，Java 端或别的语言解出来是乱码，或者报点格式错误。原因大多是密文顺序和 C1 格式：C# 端用C1C3C2，对方按C1C2C3解析；或者 C# 端 C1 带04，对方期望不带；还有的库默认输出 Base64，而 C# 端按 Hex 传。解决时先确认三件事：C1 是否带04、顺序是 C1C3C2 还是 C1C2C3、密文编码是 Hex 还是 Base64。用一段固定明文和固定密钥做交叉测试，把密文按字节拆开看长度：C1 未压缩 65 字节，C3 固定 32 字节，剩下的就是 C2。长度对不上，先查 C1 有没有被截断。

5.4 现象：SM3 摘要长度对不上

现象是对方给 64 字符摘要，自己算出来 32 字符，或者反过来。原因是把原始字节和十六进制字符串混着哈希：Sm3Hash.Compute返回 32 字节，直接ToString()得到的是类型名，不是十六进制；ComputeHex返回 64 字符，如果又对它做了一次 UTF-8 编码再哈希，结果还是 64 字符但值变了。解决时统一入口：业务层只传byte[]，需要展示时用Convert.ToHexString转十六进制，需要比对时比对小写十六进制字符串。文件摘要要按字节流分块，不要先转 Base64 再哈希；空字符串和空字节数组的摘要不一样，测试时分开覆盖。

5.5 现象：多线程下加密结果不稳定

现象是单线程测试正常，压测时偶尔解密失败或密文长度异常。原因通常是共享了非线程安全的加密对象，比如把同一个Sm4Cryptor实例注册成单例，多个线程同时调用Encrypt；或者 IV 被静态复用，导致相同明文在不同请求里产生相同密文前缀。解决时把Sm4Cryptor设计成每次加密新建，或者至少保证每个线程独立实例；IV 每次随机生成，随密文一起传输；SM2 签名内部随机数k不要自己维护，交给实现生成。压测时重点看解密失败率，不要只看吞吐量。

6. 进阶用法：把国密算法封装成可替换的加解密组件

6.1 接口设计与依赖注入

业务代码稳定后，我一般会把国密调用收成一个接口，方便测试时替换成固定密钥的假实现，也方便后面换底层库。接口只暴露业务需要的动作，不把Sm4Cryptor、Sm2Signer这些类型泄漏到业务层。下面这个接口是简化版，参数用 Hex 字符串，适合配置中心和报文加解密场景；如果业务里二进制多，可以再加一组byte[]重载。

public interface ISmCryptoService { string Sm3Hex(byte[] data); string Sm4EncryptHex(byte[] plain, string keyHex, string ivHex); byte[] Sm4DecryptHex(string cipherHex, string keyHex, string ivHex); string Sm2Sign(byte[] data, string privateKeyHex, string userId = "1234567812345678"); bool Sm2Verify(byte[] data, string sign, string publicKeyHex, string userId = "1234567812345678"); }

实现类里做参数校验和异常包装，注册到依赖注入容器时用单例还是瞬时，要看内部有没有共享状态。我的习惯是：只持有配置和只读密钥的组件可以单例，持有加密上下文或随机数状态的对象不要单例。测试时用固定密钥实现替换，联调时再用真实实现，接口不变，业务代码不用改。

6.2 性能与线程安全的一个小技巧

SM4 加密长报文时，不要一次性把几百 MB 数据读进byte[]，用流式分块，每块 8KB 到 64KB，加密后直接写输出流；SM3 同理，用增量更新。这样内存占用稳定，压测时不容易被大报文打爆。另一个技巧是密钥和 IV 的生成与使用分离：生成一次 16 字节随机密钥，加密时用，加密完立即从内存里清掉临时数组；IV 随密文走，不要缓存成静态字段。线程安全上，我吃过一次亏：把Sm4Cryptor当单例，结果高并发下偶发解密失败，后来改成每次加密新建实例，问题才消失。从那以后我每次接入新系统，都先拿一组公开测试向量跑通，再压测多线程，最后才联调。希望帮到你。

本文还有配套的精品资源，点击获取