1. 项目概述与核心挑战最近在做一个前后端分离的项目前端用的是Vue 3后端是C#的.NET Core Web API。项目有个硬性要求所有涉及敏感数据的接口传输必须使用国密SM2算法进行非对称加密。这个需求听起来挺常规但真动起手来发现坑是一个接一个。前端我选了sm-crypto这个库因为它专为JavaScript环境设计文档也还算清晰。后端自然是用C#而BouncyCastle是.NET生态里处理加密算法的老牌瑞士军刀。本以为两边都选好库调一下API就完事了结果在密钥格式、数据编码、签名验签这些环节上两边库的“脾气”完全对不上调试过程堪称“跨服聊天”。这不仅仅是调用两个加密函数那么简单。核心挑战在于SM2算法标准本身虽然统一但不同的编程语言和密码库在实现细节上存在诸多差异。比如sm-crypto生成的密钥对是PEM格式的而BouncyCastle更习惯处理裸的字节数组或特定的密钥对象。再比如加密后的密文sm-crypto默认输出是Base64编码的十六进制字符串一种混合体而BouncyCastle处理原始字节流。如果这些“方言”不统一解密方根本看不懂对方在说什么直接报错。所以这个实战指南的重点不是简单地贴代码而是打通这两个“世界”之间的协议桥梁让你能真正实现Vue前端加密、C#后端解密或者反过来进行签名验签。这个内容非常适合正在开发需要国密合规应用的全栈或前后端协作的开发者。无论你是前端主导需要搞定加密逻辑还是后端负责确保数据安全接收都会遇到这些对接的细节问题。我会把踩过的坑、调试的思路和最终稳定的方案都摊开来讲目标就是让你看完后能直接复制关键代码块快速在自己的项目里跑通整个流程。2. 环境准备与核心库选型解析2.1 前端Vue环境与sm-crypto集成前端我使用的是Vue 3 TypeScript Vite的组合这是目前比较主流和高效的开发方式。加密库方面经过对比选择了sm-crypto。为什么不选sm2、sm-crypto-js或者其他主要基于几点考虑sm-crypto由社区维护API相对现代对TypeScript支持较好有社区类型定义types/sm-crypto而且其功能聚焦于国密算法SM2, SM3, SM4比较纯粹。它的文档虽然是中文但示例足够让你上手。安装非常简单在你的Vue项目根目录下执行npm install sm-crypto如果你使用TypeScript建议同时安装类型定义虽然它可能不是完全同步但能提供基本的智能提示npm install --save-dev types/sm-crypto接下来我通常不会在每一个组件里直接import而是创建一个通用的加密工具模块。这样做有利于统一管理密钥、处理异常和未来更换库。在src/utils目录下我创建了一个crypto.ts文件// src/utils/crypto.ts import { sm2 } from sm-crypto; // 这里先定义密钥实际项目中公钥可能来自后端接口私钥前端不应存储除非是用于签名 // sm-crypto生成的密钥对通常是PEM格式的字符串 const publicKey 你的SM2公钥PEM字符串通常以-----BEGIN PUBLIC KEY-----开头; const privateKey 你的SM2私钥PEM字符串通常以-----BEGIN PRIVATE KEY-----开头; // 警告前端不应硬编码或暴露私钥 /** * 使用SM2公钥加密文本 * param plainText 待加密的明文 * returns 加密后的密文默认是Base64字符串 */ export function encryptWithSM2(plainText: string): string { try { // sm2.doEncrypt 默认输出是16进制字符串但我们需要Base64以便于HTTP传输 const encryptedHex sm2.doEncrypt(plainText, publicKey, 1); // 输入1表示输出为16进制 // 将16进制字符串转换为Base64 const encryptedBase64 Buffer.from(encryptedHex, hex).toString(base64); return encryptedBase64; } catch (error) { console.error(SM2加密失败:, error); throw new Error(数据加密失败请重试); } } /** * 使用SM2私钥解密文本前端通常不负责解密此函数主要用于测试或特定场景 * param cipherTextBase64 Base64格式的密文 * returns 解密后的明文 */ export function decryptWithSM2(cipherTextBase64: string): string { try { // 将Base64密文转回16进制字符串 const cipherTextHex Buffer.from(cipherTextBase64, base64).toString(hex); const decrypted sm2.doDecrypt(cipherTextHex, privateKey, 1); // 输入1表示输入为16进制 return decrypted; } catch (error) { console.error(SM2解密失败:, error); throw new Error(数据解密失败); } } // 签名和验签函数定义后续展开这里有几个关键点需要注意。第一sm2.doEncrypt方法的第三个参数cipherMode它控制输出格式。传入1输出是hex十六进制字符串传入0默认输出是字节数组。为了网络传输方便我们统一先拿到十六进制字符串再手动转为Base64。第二前端绝对不应该硬编码或存储用于解密的私钥。私钥必须安全地存储在后端服务器上。前端加密公钥可以通过后端接口动态获取或者像上面一样配置一个固定的前端加密公钥与后端解密私钥配对。第三异常处理很重要加密失败不能把原始错误直接抛给用户需要转换成友好的提示但日志里要记录详细错误。2.2 后端C#环境与BouncyCastle集成后端是.NET 6的Web API项目。在C#中处理国密算法BouncyCastle库是不二之选。它强大但也相对复杂好在有稳定的NuGet包。通过Visual Studio的NuGet包管理器或者命令行安装dotnet add package BouncyCastle.Cryptography安装完成后同样地我们不建议将加密解密逻辑散落在各个Controller中。创建一个服务类Sm2CryptoService来集中处理。首先你需要准备一对SM2密钥。你可以使用OpenSSL命令行工具生成也可以使用BouncyCastle在代码中生成。为了演示一致性我这里展示如何在C#中生成一对密钥并导出为PEM格式这样你可以把公钥给前端。// Services/Crypto/Sm2CryptoService.cs using Org.BouncyCastle.Asn1.GM; using Org.BouncyCastle.Asn1.X9; using Org.BouncyCastle.Crypto; using Org.BouncyCastle.Crypto.Generators; using Org.BouncyCastle.Crypto.Parameters; using Org.BouncyCastle.Math; using Org.BouncyCastle.OpenSsl; using Org.BouncyCastle.Security; using System.Text; public class Sm2CryptoService { // 你的SM2私钥参数实际应从安全配置如AppSettings、密钥管理服务中读取 private readonly ECPrivateKeyParameters _privateKeyParameters; // 你的SM2公钥参数用于验签或提供给前端 private readonly ECPublicKeyParameters _publicKeyParameters; public Sm2CryptoService(IConfiguration configuration) { // 假设密钥PEM字符串存储在appsettings.json中 var privateKeyPem configuration[Sm2Keys:PrivateKey]; var publicKeyPem configuration[Sm2Keys:PublicKey]; // 初始化密钥参数具体解析方法在下文详述 _privateKeyParameters ParsePrivateKeyFromPem(privateKeyPem); _publicKeyParameters ParsePublicKeyFromPem(publicKeyPem); } // 密钥解析方法暂略下文会重点讲 private ECPrivateKeyParameters ParsePrivateKeyFromPem(string pem) { ... } private ECPublicKeyParameters ParsePublicKeyFromPem(string pem) { ... } }这里引出第一个大坑密钥格式的解析。sm-crypto生成的PEM和BouncyCastle默认期望的PEM格式可能不完全一样。特别是私钥sm-crypto可能生成的是PKCS#8格式的私钥而BouncyCastle需要你明确指定。如果直接使用new PemReader(new StringReader(pem)).ReadObject()很可能会读到AsymmetricCipherKeyPair对象而不是直接的私钥参数导致后续操作失败。正确的解析方式是整个对接成功的基础我们会在核心细节解析章节彻底搞定它。3. 核心细节解析密钥、编码与算法模式3.1 SM2密钥格式的“方言”统一这是跨语言通信中最容易卡住的地方。sm-crypto生成的PEM字符串看起来是这样的-----BEGIN PRIVATE KEY----- MIGTAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBHkwdwIBAQQg... -----END PRIVATE KEY----- -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE... -----END PUBLIC KEY-----这是标准的PKCS#8格式私钥和X.509格式公钥。在C#端BouncyCastle的PemReader可以读取它但读取出来的对象类型需要小心处理。C#端解析PEM密钥的正确姿势using Org.BouncyCastle.OpenSsl; using System.IO; private ECPrivateKeyParameters ParsePrivateKeyFromPem(string pem) { using var textReader new StringReader(pem.Trim()); var pemReader new PemReader(textReader); var keyPair pemReader.ReadObject() as AsymmetricCipherKeyPair; // 注意这里读出来的是KeyPair if (keyPair?.Private is ECPrivateKeyParameters ecPrivate) { return ecPrivate; } // 有些PEM可能直接包含私钥参数而非KeyPair if (pemReader.ReadObject() is ECPrivateKeyParameters directPrivate) { return directPrivate; } throw new InvalidOperationException(无法从PEM字符串解析出有效的SM2私钥参数。); } private ECPublicKeyParameters ParsePublicKeyFromPem(string pem) { using var textReader new StringReader(pem.Trim()); var pemReader new PemReader(textReader); var publicKey pemReader.ReadObject() as ECPublicKeyParameters; if (publicKey ! null) { return publicKey; } // 如果公钥是作为KeyPair的一部分存储的较少见可以这样尝试 var keyPair pemReader.ReadObject() as AsymmetricCipherKeyPair; if (keyPair?.Public is ECPublicKeyParameters ecPublic) { return ecPublic; } throw new InvalidOperationException(无法从PEM字符串解析出有效的SM2公钥参数。); }注意有时直接从某些在线工具或不同库生成的PEM其头尾标识可能略有不同如BEGIN EC PRIVATE KEY。PemReader通常能兼容但如果解析失败你需要检查PEM的实际内容。一个调试技巧是将PEM字符串Base64解码后查看其ASN.1结构但这需要一定的密码学知识。最稳妥的办法是确保前后端使用的密钥对来自同一套生成工具或流程。前端使用密钥前端sm-crypto可以直接使用上述PEM格式的公钥字符串进行加密。私钥字符串仅用于测试或前端需要签名的场景但签名私钥也应从安全渠道获取而非硬编码。3.2 数据编码的“握手”协议加密解密、签名验签本质操作的对象都是字节数组byte[]。但在网络传输和JavaScript环境中我们处理的是字符串。因此编码转换是第二个关键点。前端加密、后端解密的编码流程前端Vue输入明文字符串如Hello, SM2。sm-crypto加密sm2.doEncrypt(plainText, publicKey, 1)得到十六进制字符串Hex String。关键转换将Hex字符串转换为Base64字符串。Buffer.from(encryptedHex, hex).toString(base64)。使用Base64是因为它是HTTP传输中表示二进制数据的标准方式比Hex更紧凑。输出将Base64字符串放入JSON请求体发送给后端。后端C#输入收到Base64格式的密文字符串。关键转换将Base64字符串转换为字节数组。Convert.FromBase64String(cipherTextBase64)。BouncyCastle解密使用私钥对字节数组进行解密。输出得到明文字节数组再用UTF-8编码转换为字符串。Encoding.UTF8.GetString(decryptedBytes)。反之后端加密、前端解密的流程对称即可。核心原则前后端约定好密文的最终交换格式为Base64字符串。这样无论后端用什么库Java的BouncyCastle、Go的国密库只要大家都用Base64就能互通。3.3 SM2算法模式与参数协商SM2算法除了用于加密解密还常用于数字签名。在加密模式下它本身包含了一种特定的密钥派生函数(KDF)和消息认证码(MAC)相当于“加密完整性验证”一体。sm-crypto和BouncyCastle在实现加密时默认都遵循《SM2密码算法使用规范》中定义的流程包括使用SM3作为哈希和MAC算法。所以在算法模式上我们通常不需要额外配置使用库的默认行为即可。但在签名验签时有一个重要参数用户ID。SM2签名需要关联一个用户标识符默认是1234567812345678ASCII码。sm-crypto的sm2.doSignature函数可以接受一个userId参数。必须确保前后端签名和验签时使用的userId完全相同否则验签一定会失败。// 前端签名 import { sm2 } from sm-crypto; const msg 要签名的消息; const privateKey ...; // 签名私钥应从安全途径获取 const userId 1234567812345678; // 默认ID const signatureHex sm2.doSignature(msg, privateKey, { userId }); // 输出为16进制签名串 // 同样可以将signatureHex转为Base64传输// 后端验签 public bool VerifySignature(string message, string signatureBase64, string userId 1234567812345678) { var messageBytes Encoding.UTF8.GetBytes(message); var signatureBytes Convert.FromBase64String(signatureBase64); var signer SignerUtilities.GetSigner(SM3withSM2); signer.Init(false, _publicKeyParameters); // false表示验签模式 signer.BlockUpdate(Encoding.UTF8.GetBytes(userId), 0, userId.Length); // 更新用户ID signer.BlockUpdate(messageBytes, 0, messageBytes.Length); // 更新消息 return signer.VerifySignature(signatureBytes); }4. 完整对接实战加密、解密、签名、验签4.1 前端Vue完整加密与签名示例我们构建一个更健壮的工具类并模拟一个用户登录的场景。// src/utils/sm2Crypto.ts import { sm2, sm3 } from sm-crypto; // 从环境变量或配置中心获取公钥加密用和签名私钥谨慎 const ENCRYPT_PUBLIC_KEY import.meta.env.VITE_SM2_ENCRYPT_PUBLIC_KEY || 你的前端加密公钥; const SIGN_PRIVATE_KEY import.meta.env.VITE_SM2_SIGN_PRIVATE_KEY || ; // 生产环境应由后端在登录后下发临时签名密钥 export default class Sm2Crypto { // 默认用户ID必须与后端一致 private static readonly DEFAULT_USER_ID 1234567812345678; /** * 加密数据用于传输敏感信息如密码 * param data 明文数据对象会被转换为JSON字符串 * returns Base64格式的密文 */ static encryptData(data: any): string { try { const plainText typeof data string ? data : JSON.stringify(data); // 1. 使用公钥加密得到16进制密文 const encryptedHex sm2.doEncrypt(plainText, ENCRYPT_PUBLIC_KEY, 1); // 2. 转换为Base64以便传输 return Buffer.from(encryptedHex, hex).toString(base64); } catch (error) { console.error([SM2加密失败], error, 数据:, data); throw new Error(请求数据加密失败); } } /** * 生成请求签名用于防篡改 * param payload 需要签名的请求参数对象 * param timestamp 时间戳防止重放攻击 * returns 签名字符串Base64格式 */ static generateSignature(payload: Recordstring, any, timestamp: number): string { if (!SIGN_PRIVATE_KEY) { console.warn(签名私钥未配置跳过签名生成。); return ; } try { // 1. 构造签名字符串按特定规则排序后拼接这里简单示例为 JSON 时间戳 const signString JSON.stringify(payload) |${timestamp}; // 2. 先对字符串进行SM3哈希可选但SM2签名本身已包含哈希步骤这里演示额外哈希 const hashHex sm3(signString); // 3. 对哈希值进行SM2签名 const signatureHex sm2.doSignature(hashHex, SIGN_PRIVATE_KEY, { userId: this.DEFAULT_USER_ID, // pointPool: ..., // 可选项用于预计算加速一般不用 }); // 4. 转换为Base64 return Buffer.from(signatureHex, hex).toString(base64); } catch (error) { console.error([生成签名失败], error); throw new Error(生成请求签名失败); } } /** * 封装一个需要加密和签名的请求数据 * param requestData 原始的请求参数 * returns 处理后的、可供axios直接发送的数据对象 */ static packageRequest(requestData: any): { data: string; sign: string; timestamp: number } { const timestamp Date.now(); // 1. 加密业务数据 const encryptedData this.encryptData(requestData); // 2. 生成签名签名内容可以包含加密后的数据或其他元数据 const signPayload { encryptedData, // 对加密后的数据本身签名确保传输过程未被替换 timestamp, path: window.location.pathname, // 可加入请求路径防止复用 }; const signature this.generateSignature(signPayload, timestamp); return { data: encryptedData, // 加密后的密文 sign: signature, // 签名 timestamp, // 时间戳 }; } } // 在axios拦截器中使用示例 import axios from axios; import Sm2Crypto from /utils/sm2Crypto; const service axios.create({ baseURL: /api }); service.interceptors.request.use( (config) { if (config.method?.toUpperCase() POST config.data) { // 对POST请求的数据进行加密和签名包装 const packaged Sm2Crypto.packageRequest(config.data); config.data packaged; // 替换原始data // 可以在header中添加时间戳和签名 config.headers[X-Timestamp] packaged.timestamp; config.headers[X-Signature] packaged.sign; } return config; }, (error) Promise.reject(error) );4.2 后端C#完整解密与验签示例在后端我们需要创建对应的服务来解密和验签。// Services/Crypto/Sm2CryptoService.cs (续) using Microsoft.Extensions.Logging; using System.Text.Json; public class Sm2CryptoService : ISm2CryptoService { private readonly ECPrivateKeyParameters _decryptPrivateKey; // 用于解密前端数据的私钥 private readonly ECPublicKeyParameters _verifyPublicKey; // 用于验签的公钥 private readonly ILoggerSm2CryptoService _logger; private const string DefaultUserId 1234567812345678; public Sm2CryptoService(IConfiguration configuration, ILoggerSm2CryptoService logger) { _logger logger; var privateKeyPem configuration[Sm2Keys:DecryptPrivateKey]; var publicKeyPem configuration[Sm2Keys:VerifyPublicKey]; _decryptPrivateKey ParsePrivateKeyFromPem(privateKeyPem); _verifyPublicKey ParsePublicKeyFromPem(publicKeyPem); } /// summary /// 解密前端发送的SM2加密数据 /// /summary /// param namecipherTextBase64Base64格式的密文/param /// returns解密后的原始JSON字符串/returns public string DecryptData(string cipherTextBase64) { if (string.IsNullOrEmpty(cipherTextBase64)) throw new ArgumentNullException(nameof(cipherTextBase64)); try { // 1. Base64 - 字节数组 byte[] cipherBytes Convert.FromBase64String(cipherTextBase64); // 2. 使用BouncyCastle进行SM2解密 var sm2Engine new SM2Engine(new SM3Digest()); // SM2引擎使用SM3摘要 sm2Engine.Init(false, _decryptPrivateKey); // false 表示解密模式 byte[] decryptedBytes sm2Engine.ProcessBlock(cipherBytes, 0, cipherBytes.Length); // 3. 字节数组 - UTF8字符串 string plainText Encoding.UTF8.GetString(decryptedBytes); _logger.LogDebug(SM2解密成功明文长度: {Length}, plainText.Length); return plainText; } catch (FormatException ex) { _logger.LogError(ex, SM2解密失败密文Base64格式错误。); throw new CryptoException(密文格式无效, ex); } catch (InvalidCipherTextException ex) { _logger.LogError(ex, SM2解密失败可能是密钥不匹配或密文已损坏。); throw new CryptoException(解密失败密钥或数据错误, ex); } catch (Exception ex) { _logger.LogError(ex, SM2解密过程中发生未知错误。); throw; } } /// summary /// 验证请求签名 /// /summary /// param namedataToSign参与签名的数据字符串应与前端构造规则一致/param /// param namesignatureBase64Base64格式的签名/param /// param nameuserId用户ID默认为国密标准测试ID/param /// returns验签是否通过/returns public bool VerifySignature(string dataToSign, string signatureBase64, string userId DefaultUserId) { if (string.IsNullOrEmpty(signatureBase64)) { _logger.LogWarning(验签失败签名为空。); return false; } try { byte[] messageBytes Encoding.UTF8.GetBytes(dataToSign); byte[] signatureBytes Convert.FromBase64String(signatureBase64); // 使用SM3withSM2算法验签器 var signer SignerUtilities.GetSigner(SM3withSM2); signer.Init(false, _verifyPublicKey); // false for verification // 更新签名器数据先更新用户ID再更新消息 byte[] userIdBytes Encoding.UTF8.GetBytes(userId); signer.BlockUpdate(userIdBytes, 0, userIdBytes.Length); signer.BlockUpdate(messageBytes, 0, messageBytes.Length); bool isValid signer.VerifySignature(signatureBytes); _logger.LogDebug(SM2验签结果: {IsValid}, isValid); return isValid; } catch (Exception ex) { _logger.LogError(ex, SM2验签过程发生异常。); return false; } } /// summary /// 处理前端完整的请求包包含加密数据和签名 /// /summary /// typeparam nameT期望反序列化的数据类型/typeparam /// param nameencryptedData加密的业务数据(Base64)/param /// param namesignature签名(Base64)/param /// param nametimestamp时间戳/param /// param namerequestPath请求路径用于防重放/param /// returns解密后的业务数据对象/returns public T ProcessRequestT(string encryptedData, string signature, long timestamp, string requestPath) { // 1. 基本校验 if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - timestamp) 300000) // 5分钟有效期 { throw new CryptoException(请求已过期); } // 2. 构造验签字符串必须与前端规则完全一致 var signPayload new { encryptedData, timestamp, path requestPath }; string dataToSign JsonSerializer.Serialize(signPayload); // 使用System.Text.Json // 3. 验签 if (!VerifySignature(dataToSign, signature)) { throw new CryptoException(签名验证失败); } // 4. 解密数据 string decryptedJson DecryptData(encryptedData); // 5. 反序列化 try { return JsonSerializer.DeserializeT(decryptedJson) ?? throw new CryptoException(解密数据反序列化失败); } catch (JsonException ex) { _logger.LogError(ex, 解密后的JSON反序列化失败: {Json}, decryptedJson); throw new CryptoException(数据格式错误, ex); } } } // 自定义异常便于全局处理 public class CryptoException : Exception { public CryptoException(string message) : base(message) { } public CryptoException(string message, Exception innerException) : base(message, innerException) { } }然后在Controller中使用这个服务// Controllers/AuthController.cs [ApiController] [Route(api/[controller])] public class AuthController : ControllerBase { private readonly ISm2CryptoService _sm2Crypto; private readonly ILoggerAuthController _logger; public AuthController(ISm2CryptoService sm2Crypto, ILoggerAuthController logger) { _sm2Crypto sm2Crypto; _logger logger; } [HttpPost(login)] public async TaskIActionResult Login([FromBody] EncryptedRequest request) { try { // 1. 处理加密请求解密并验签 var loginData _sm2Crypto.ProcessRequestLoginModel( request.Data, request.Sign, request.Timestamp, HttpContext.Request.Path ); // 2. 这里loginData已经是解密后的LoginModel对象了 _logger.LogInformation(用户 {Username} 尝试登录, loginData.Username); // 3. 进行你的业务逻辑比如验证用户名密码... // var user await _userService.Authenticate(loginData.Username, loginData.Password); // 4. 返回响应响应也可以选择加密这里省略 return Ok(new { success true, message 登录成功, token generated-jwt-token }); } catch (CryptoException ex) { _logger.LogWarning(ex, 请求加解密或验签失败。); return BadRequest(new { success false, message ex.Message }); } catch (Exception ex) { _logger.LogError(ex, 登录处理过程中发生未预期错误。); return StatusCode(500, new { success false, message 服务器内部错误 }); } } } // 请求模型 public class EncryptedRequest { public string Data { get; set; } // Base64加密数据 public string Sign { get; set; } // Base64签名 public long Timestamp { get; set; } // 时间戳 } public class LoginModel { public string Username { get; set; } public string Password { get; set; } }5. 常见问题、调试技巧与避坑指南在实际对接过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理出来能帮你节省大量调试时间。5.1 密钥解析失败Invalid key format或Unknown object in GetInstance问题现象在C#端使用PemReader读取PEM字符串时抛出异常。可能原因PEM字符串头尾有空格或换行符不正确。密钥格式不符合BouncyCastle的预期例如是PKCS#1格式而非PKCS#8。公钥/私钥混淆了。解决方案清理PEM字符串确保字符串以-----BEGIN...开头以-----END...结尾中间是完整的Base64行。使用.Trim()方法。确认密钥类型用文本编辑器打开PEM文件看头部标识。BEGIN PRIVATE KEY通常是PKCS#8BEGIN EC PRIVATE KEY是PKCS#1。BouncyCastle的PemReader对PKCS#8兼容性更好。如果你的是PKCS#1可能需要先用OpenSSL转换openssl pkcs8 -topk8 -nocrypt -in private_key.pem -out private_key_pkcs8.pem。调试读取在PemReader.ReadObject()后不要直接强制转换先判断对象类型。var obj pemReader.ReadObject(); Console.WriteLine($Read object type: {obj?.GetType().FullName}); // 可能是 AsymmetricCipherKeyPair, ECPrivateKeyParameters, ECPublicKeyParameters 等5.2 解密失败Invalid ciphertext或Tag mismatch问题现象前端加密成功后端解密时抛出InvalidCipherTextException。可能原因编码不一致这是最常见的原因。前端传给后端的密文字符串编码不是纯粹的Base64或者Base64字符串在传输过程中被URL编码/解码破坏了。公钥私钥不配对用于加密的公钥和用于解密的私钥不是一对。加密模式差异虽然SM2标准统一但库的实现可能在填充或编码细节上有微小差异。sm-crypto的doEncrypt默认使用C1C3C2密文结构这是国标标准BouncyCastle的SM2Engine也默认支持此结构但需要确认。排查步骤打印和对比在前端加密后将生成的Base64密文打印到控制台console.log。在后端接收到请求后第一时间将request.Data打印到日志。对比两者是否完全一致注意换行符、空格。如果使用Postman测试确保Body是raw JSON且密文字段的值没有多余引号。检查密钥配对写一个简单的测试程序用后端的公钥加密一段文本然后用后端的私钥解密看是否成功。确保测试用的公钥就是给前端的那个。确认密文结构sm-crypto的doEncrypt默认输出顺序是C1C3C2。BouncyCastle的SM2Engine默认也期望这个顺序。一般不用改。如果怀疑是顺序问题可以尝试在创建SM2Engine时指定模式new SM2Engine(new SM3Digest(), SM2Engine.Mode.C1C3C2)虽然默认就是它。5.3 验签失败签名一直不通过问题现象前端生成的签名后端验签总是返回false。可能原因用户ID不一致这是头号杀手前端签名用的userId和后端验签时BlockUpdate的userId必须一字不差包括大小写和长度。强烈建议前后端使用同一个常量。签名数据源不一致前端用于生成签名的原始字符串和后端用于验签的字符串必须完全一样。一个空格、一个标点符号、JSON字段顺序不同都会导致哈希值不同从而验签失败。签名结果编码问题前端生成的签名是十六进制转成了Base64。后端需要先将Base64解码回字节数组再验签。确保这个转换过程无误。调试方法日志大法在前端将signString待签名的原始字符串和最终的signatureHex打印出来。在后端将dataToSign用于验签的字符串和接收到的signatureBase64解码后的字节数组长度打印出来。比对字符串将前后端打印的待签名字符串进行精确比对。可以用在线Diff工具。分步验证先在后端用代码生成一个签名使用同一个私钥和相同数据然后和前端传过来的签名比对看是否是生成环节的问题。或者用后端的公钥去验证后端自己生成的签名确保验签逻辑本身正确。5.4 性能与安全性注意事项性能SM2非对称加密比AES这样的对称加密慢得多。不要用它加密大段数据如文件、长文本。只用于加密关键信息如密码、对称加密的密钥或进行签名。对于大量数据传输应采用“SM2加密随机生成的AES密钥再用AES加密实际数据”的混合加密模式。密钥管理前端公钥用于加密的公钥可以硬编码或从接口获取暴露无妨。前端签名私钥如果前端需要签名如防篡改这个私钥绝不能硬编码在代码中。应该在用户登录后由后端动态下发一个临时的或会话级别的签名密钥对并在过期后失效。后端私钥解密私钥是核心资产必须妥善保管。推荐使用硬件安全模块HSM、云密钥管理服务KMS或至少是配置文件加密存储而不是明文写在appsettings.json里。错误处理加解密、验签失败时返回给前端的错误信息要模糊比如“处理失败”或“安全校验未通过”避免泄露系统细节如“密钥不匹配”。但后台日志一定要记录详细的错误信息方便排查。5.5 联调检查清单当你对接不成功时请按顺序检查以下清单[ ]密钥格式确认PEM密钥能被双方的库正确解析。尝试用各自库的“加载-导出”功能验证。[ ]密钥配对用后端公钥在后端加密一个字符串再用后端私钥解密确保密钥对本身有效。[ ]编码流程前端明文 -sm2.doEncrypt(hex) -Buffer.from(hex, hex).toString(base64)。后端Convert.FromBase64String-SM2Engine.Decrypt-Encoding.UTF8.GetString。确保每一步的输出都如预期。[ ]数据传输用浏览器开发者工具或Fiddler/Charles抓包确认HTTP请求体中的密文和签名字段值与前端代码生成的值完全一致没有自动转义或截断。[ ]签名数据确保前后端构造签名字符串的规则字段顺序、分隔符、是否包含时间戳/路径等百分百一致。将前后端用于签名的字符串日志拿出来逐字符对比。[ ]用户ID确认签名验签用的userId常量值完全相同。[ ]库版本检查sm-crypto和BouncyCastle的版本有时版本升级可能导致行为变化。查阅其版本更新日志。跨语言加密对接就像是在两个说不同方言的地区间架设通信协议关键在于统一“数据表示层”的约定。一旦你把密钥格式、编码方式和算法参数这三个桥梁搭稳了剩下的业务逻辑就是水到渠成。这次实战下来最大的体会就是日志要打够数据在进出每个关键函数时都打印一下十六进制或Base64很多问题就一目了然了。另外对于国密这种有明确国家标准但各库实现细节可能微调的场景优先以其中一个库比如sm-crypto的输出为基准去调整另一个库BouncyCastle的输入处理逻辑往往比两头改要高效得多。
1. 项目概述与核心挑战最近在做一个前后端分离的项目前端用的是Vue 3后端是C#的.NET Core Web API。项目有个硬性要求所有涉及敏感数据的接口传输必须使用国密SM2算法进行非对称加密。这个需求听起来挺常规但真动起手来发现坑是一个接一个。前端我选了sm-crypto这个库因为它专为JavaScript环境设计文档也还算清晰。后端自然是用C#而BouncyCastle是.NET生态里处理加密算法的老牌瑞士军刀。本以为两边都选好库调一下API就完事了结果在密钥格式、数据编码、签名验签这些环节上两边库的“脾气”完全对不上调试过程堪称“跨服聊天”。这不仅仅是调用两个加密函数那么简单。核心挑战在于SM2算法标准本身虽然统一但不同的编程语言和密码库在实现细节上存在诸多差异。比如sm-crypto生成的密钥对是PEM格式的而BouncyCastle更习惯处理裸的字节数组或特定的密钥对象。再比如加密后的密文sm-crypto默认输出是Base64编码的十六进制字符串一种混合体而BouncyCastle处理原始字节流。如果这些“方言”不统一解密方根本看不懂对方在说什么直接报错。所以这个实战指南的重点不是简单地贴代码而是打通这两个“世界”之间的协议桥梁让你能真正实现Vue前端加密、C#后端解密或者反过来进行签名验签。这个内容非常适合正在开发需要国密合规应用的全栈或前后端协作的开发者。无论你是前端主导需要搞定加密逻辑还是后端负责确保数据安全接收都会遇到这些对接的细节问题。我会把踩过的坑、调试的思路和最终稳定的方案都摊开来讲目标就是让你看完后能直接复制关键代码块快速在自己的项目里跑通整个流程。2. 环境准备与核心库选型解析2.1 前端Vue环境与sm-crypto集成前端我使用的是Vue 3 TypeScript Vite的组合这是目前比较主流和高效的开发方式。加密库方面经过对比选择了sm-crypto。为什么不选sm2、sm-crypto-js或者其他主要基于几点考虑sm-crypto由社区维护API相对现代对TypeScript支持较好有社区类型定义types/sm-crypto而且其功能聚焦于国密算法SM2, SM3, SM4比较纯粹。它的文档虽然是中文但示例足够让你上手。安装非常简单在你的Vue项目根目录下执行npm install sm-crypto如果你使用TypeScript建议同时安装类型定义虽然它可能不是完全同步但能提供基本的智能提示npm install --save-dev types/sm-crypto接下来我通常不会在每一个组件里直接import而是创建一个通用的加密工具模块。这样做有利于统一管理密钥、处理异常和未来更换库。在src/utils目录下我创建了一个crypto.ts文件// src/utils/crypto.ts import { sm2 } from sm-crypto; // 这里先定义密钥实际项目中公钥可能来自后端接口私钥前端不应存储除非是用于签名 // sm-crypto生成的密钥对通常是PEM格式的字符串 const publicKey 你的SM2公钥PEM字符串通常以-----BEGIN PUBLIC KEY-----开头; const privateKey 你的SM2私钥PEM字符串通常以-----BEGIN PRIVATE KEY-----开头; // 警告前端不应硬编码或暴露私钥 /** * 使用SM2公钥加密文本 * param plainText 待加密的明文 * returns 加密后的密文默认是Base64字符串 */ export function encryptWithSM2(plainText: string): string { try { // sm2.doEncrypt 默认输出是16进制字符串但我们需要Base64以便于HTTP传输 const encryptedHex sm2.doEncrypt(plainText, publicKey, 1); // 输入1表示输出为16进制 // 将16进制字符串转换为Base64 const encryptedBase64 Buffer.from(encryptedHex, hex).toString(base64); return encryptedBase64; } catch (error) { console.error(SM2加密失败:, error); throw new Error(数据加密失败请重试); } } /** * 使用SM2私钥解密文本前端通常不负责解密此函数主要用于测试或特定场景 * param cipherTextBase64 Base64格式的密文 * returns 解密后的明文 */ export function decryptWithSM2(cipherTextBase64: string): string { try { // 将Base64密文转回16进制字符串 const cipherTextHex Buffer.from(cipherTextBase64, base64).toString(hex); const decrypted sm2.doDecrypt(cipherTextHex, privateKey, 1); // 输入1表示输入为16进制 return decrypted; } catch (error) { console.error(SM2解密失败:, error); throw new Error(数据解密失败); } } // 签名和验签函数定义后续展开这里有几个关键点需要注意。第一sm2.doEncrypt方法的第三个参数cipherMode它控制输出格式。传入1输出是hex十六进制字符串传入0默认输出是字节数组。为了网络传输方便我们统一先拿到十六进制字符串再手动转为Base64。第二前端绝对不应该硬编码或存储用于解密的私钥。私钥必须安全地存储在后端服务器上。前端加密公钥可以通过后端接口动态获取或者像上面一样配置一个固定的前端加密公钥与后端解密私钥配对。第三异常处理很重要加密失败不能把原始错误直接抛给用户需要转换成友好的提示但日志里要记录详细错误。2.2 后端C#环境与BouncyCastle集成后端是.NET 6的Web API项目。在C#中处理国密算法BouncyCastle库是不二之选。它强大但也相对复杂好在有稳定的NuGet包。通过Visual Studio的NuGet包管理器或者命令行安装dotnet add package BouncyCastle.Cryptography安装完成后同样地我们不建议将加密解密逻辑散落在各个Controller中。创建一个服务类Sm2CryptoService来集中处理。首先你需要准备一对SM2密钥。你可以使用OpenSSL命令行工具生成也可以使用BouncyCastle在代码中生成。为了演示一致性我这里展示如何在C#中生成一对密钥并导出为PEM格式这样你可以把公钥给前端。// Services/Crypto/Sm2CryptoService.cs using Org.BouncyCastle.Asn1.GM; using Org.BouncyCastle.Asn1.X9; using Org.BouncyCastle.Crypto; using Org.BouncyCastle.Crypto.Generators; using Org.BouncyCastle.Crypto.Parameters; using Org.BouncyCastle.Math; using Org.BouncyCastle.OpenSsl; using Org.BouncyCastle.Security; using System.Text; public class Sm2CryptoService { // 你的SM2私钥参数实际应从安全配置如AppSettings、密钥管理服务中读取 private readonly ECPrivateKeyParameters _privateKeyParameters; // 你的SM2公钥参数用于验签或提供给前端 private readonly ECPublicKeyParameters _publicKeyParameters; public Sm2CryptoService(IConfiguration configuration) { // 假设密钥PEM字符串存储在appsettings.json中 var privateKeyPem configuration[Sm2Keys:PrivateKey]; var publicKeyPem configuration[Sm2Keys:PublicKey]; // 初始化密钥参数具体解析方法在下文详述 _privateKeyParameters ParsePrivateKeyFromPem(privateKeyPem); _publicKeyParameters ParsePublicKeyFromPem(publicKeyPem); } // 密钥解析方法暂略下文会重点讲 private ECPrivateKeyParameters ParsePrivateKeyFromPem(string pem) { ... } private ECPublicKeyParameters ParsePublicKeyFromPem(string pem) { ... } }这里引出第一个大坑密钥格式的解析。sm-crypto生成的PEM和BouncyCastle默认期望的PEM格式可能不完全一样。特别是私钥sm-crypto可能生成的是PKCS#8格式的私钥而BouncyCastle需要你明确指定。如果直接使用new PemReader(new StringReader(pem)).ReadObject()很可能会读到AsymmetricCipherKeyPair对象而不是直接的私钥参数导致后续操作失败。正确的解析方式是整个对接成功的基础我们会在核心细节解析章节彻底搞定它。3. 核心细节解析密钥、编码与算法模式3.1 SM2密钥格式的“方言”统一这是跨语言通信中最容易卡住的地方。sm-crypto生成的PEM字符串看起来是这样的-----BEGIN PRIVATE KEY----- MIGTAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBHkwdwIBAQQg... -----END PRIVATE KEY----- -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE... -----END PUBLIC KEY-----这是标准的PKCS#8格式私钥和X.509格式公钥。在C#端BouncyCastle的PemReader可以读取它但读取出来的对象类型需要小心处理。C#端解析PEM密钥的正确姿势using Org.BouncyCastle.OpenSsl; using System.IO; private ECPrivateKeyParameters ParsePrivateKeyFromPem(string pem) { using var textReader new StringReader(pem.Trim()); var pemReader new PemReader(textReader); var keyPair pemReader.ReadObject() as AsymmetricCipherKeyPair; // 注意这里读出来的是KeyPair if (keyPair?.Private is ECPrivateKeyParameters ecPrivate) { return ecPrivate; } // 有些PEM可能直接包含私钥参数而非KeyPair if (pemReader.ReadObject() is ECPrivateKeyParameters directPrivate) { return directPrivate; } throw new InvalidOperationException(无法从PEM字符串解析出有效的SM2私钥参数。); } private ECPublicKeyParameters ParsePublicKeyFromPem(string pem) { using var textReader new StringReader(pem.Trim()); var pemReader new PemReader(textReader); var publicKey pemReader.ReadObject() as ECPublicKeyParameters; if (publicKey ! null) { return publicKey; } // 如果公钥是作为KeyPair的一部分存储的较少见可以这样尝试 var keyPair pemReader.ReadObject() as AsymmetricCipherKeyPair; if (keyPair?.Public is ECPublicKeyParameters ecPublic) { return ecPublic; } throw new InvalidOperationException(无法从PEM字符串解析出有效的SM2公钥参数。); }注意有时直接从某些在线工具或不同库生成的PEM其头尾标识可能略有不同如BEGIN EC PRIVATE KEY。PemReader通常能兼容但如果解析失败你需要检查PEM的实际内容。一个调试技巧是将PEM字符串Base64解码后查看其ASN.1结构但这需要一定的密码学知识。最稳妥的办法是确保前后端使用的密钥对来自同一套生成工具或流程。前端使用密钥前端sm-crypto可以直接使用上述PEM格式的公钥字符串进行加密。私钥字符串仅用于测试或前端需要签名的场景但签名私钥也应从安全渠道获取而非硬编码。3.2 数据编码的“握手”协议加密解密、签名验签本质操作的对象都是字节数组byte[]。但在网络传输和JavaScript环境中我们处理的是字符串。因此编码转换是第二个关键点。前端加密、后端解密的编码流程前端Vue输入明文字符串如Hello, SM2。sm-crypto加密sm2.doEncrypt(plainText, publicKey, 1)得到十六进制字符串Hex String。关键转换将Hex字符串转换为Base64字符串。Buffer.from(encryptedHex, hex).toString(base64)。使用Base64是因为它是HTTP传输中表示二进制数据的标准方式比Hex更紧凑。输出将Base64字符串放入JSON请求体发送给后端。后端C#输入收到Base64格式的密文字符串。关键转换将Base64字符串转换为字节数组。Convert.FromBase64String(cipherTextBase64)。BouncyCastle解密使用私钥对字节数组进行解密。输出得到明文字节数组再用UTF-8编码转换为字符串。Encoding.UTF8.GetString(decryptedBytes)。反之后端加密、前端解密的流程对称即可。核心原则前后端约定好密文的最终交换格式为Base64字符串。这样无论后端用什么库Java的BouncyCastle、Go的国密库只要大家都用Base64就能互通。3.3 SM2算法模式与参数协商SM2算法除了用于加密解密还常用于数字签名。在加密模式下它本身包含了一种特定的密钥派生函数(KDF)和消息认证码(MAC)相当于“加密完整性验证”一体。sm-crypto和BouncyCastle在实现加密时默认都遵循《SM2密码算法使用规范》中定义的流程包括使用SM3作为哈希和MAC算法。所以在算法模式上我们通常不需要额外配置使用库的默认行为即可。但在签名验签时有一个重要参数用户ID。SM2签名需要关联一个用户标识符默认是1234567812345678ASCII码。sm-crypto的sm2.doSignature函数可以接受一个userId参数。必须确保前后端签名和验签时使用的userId完全相同否则验签一定会失败。// 前端签名 import { sm2 } from sm-crypto; const msg 要签名的消息; const privateKey ...; // 签名私钥应从安全途径获取 const userId 1234567812345678; // 默认ID const signatureHex sm2.doSignature(msg, privateKey, { userId }); // 输出为16进制签名串 // 同样可以将signatureHex转为Base64传输// 后端验签 public bool VerifySignature(string message, string signatureBase64, string userId 1234567812345678) { var messageBytes Encoding.UTF8.GetBytes(message); var signatureBytes Convert.FromBase64String(signatureBase64); var signer SignerUtilities.GetSigner(SM3withSM2); signer.Init(false, _publicKeyParameters); // false表示验签模式 signer.BlockUpdate(Encoding.UTF8.GetBytes(userId), 0, userId.Length); // 更新用户ID signer.BlockUpdate(messageBytes, 0, messageBytes.Length); // 更新消息 return signer.VerifySignature(signatureBytes); }4. 完整对接实战加密、解密、签名、验签4.1 前端Vue完整加密与签名示例我们构建一个更健壮的工具类并模拟一个用户登录的场景。// src/utils/sm2Crypto.ts import { sm2, sm3 } from sm-crypto; // 从环境变量或配置中心获取公钥加密用和签名私钥谨慎 const ENCRYPT_PUBLIC_KEY import.meta.env.VITE_SM2_ENCRYPT_PUBLIC_KEY || 你的前端加密公钥; const SIGN_PRIVATE_KEY import.meta.env.VITE_SM2_SIGN_PRIVATE_KEY || ; // 生产环境应由后端在登录后下发临时签名密钥 export default class Sm2Crypto { // 默认用户ID必须与后端一致 private static readonly DEFAULT_USER_ID 1234567812345678; /** * 加密数据用于传输敏感信息如密码 * param data 明文数据对象会被转换为JSON字符串 * returns Base64格式的密文 */ static encryptData(data: any): string { try { const plainText typeof data string ? data : JSON.stringify(data); // 1. 使用公钥加密得到16进制密文 const encryptedHex sm2.doEncrypt(plainText, ENCRYPT_PUBLIC_KEY, 1); // 2. 转换为Base64以便传输 return Buffer.from(encryptedHex, hex).toString(base64); } catch (error) { console.error([SM2加密失败], error, 数据:, data); throw new Error(请求数据加密失败); } } /** * 生成请求签名用于防篡改 * param payload 需要签名的请求参数对象 * param timestamp 时间戳防止重放攻击 * returns 签名字符串Base64格式 */ static generateSignature(payload: Recordstring, any, timestamp: number): string { if (!SIGN_PRIVATE_KEY) { console.warn(签名私钥未配置跳过签名生成。); return ; } try { // 1. 构造签名字符串按特定规则排序后拼接这里简单示例为 JSON 时间戳 const signString JSON.stringify(payload) |${timestamp}; // 2. 先对字符串进行SM3哈希可选但SM2签名本身已包含哈希步骤这里演示额外哈希 const hashHex sm3(signString); // 3. 对哈希值进行SM2签名 const signatureHex sm2.doSignature(hashHex, SIGN_PRIVATE_KEY, { userId: this.DEFAULT_USER_ID, // pointPool: ..., // 可选项用于预计算加速一般不用 }); // 4. 转换为Base64 return Buffer.from(signatureHex, hex).toString(base64); } catch (error) { console.error([生成签名失败], error); throw new Error(生成请求签名失败); } } /** * 封装一个需要加密和签名的请求数据 * param requestData 原始的请求参数 * returns 处理后的、可供axios直接发送的数据对象 */ static packageRequest(requestData: any): { data: string; sign: string; timestamp: number } { const timestamp Date.now(); // 1. 加密业务数据 const encryptedData this.encryptData(requestData); // 2. 生成签名签名内容可以包含加密后的数据或其他元数据 const signPayload { encryptedData, // 对加密后的数据本身签名确保传输过程未被替换 timestamp, path: window.location.pathname, // 可加入请求路径防止复用 }; const signature this.generateSignature(signPayload, timestamp); return { data: encryptedData, // 加密后的密文 sign: signature, // 签名 timestamp, // 时间戳 }; } } // 在axios拦截器中使用示例 import axios from axios; import Sm2Crypto from /utils/sm2Crypto; const service axios.create({ baseURL: /api }); service.interceptors.request.use( (config) { if (config.method?.toUpperCase() POST config.data) { // 对POST请求的数据进行加密和签名包装 const packaged Sm2Crypto.packageRequest(config.data); config.data packaged; // 替换原始data // 可以在header中添加时间戳和签名 config.headers[X-Timestamp] packaged.timestamp; config.headers[X-Signature] packaged.sign; } return config; }, (error) Promise.reject(error) );4.2 后端C#完整解密与验签示例在后端我们需要创建对应的服务来解密和验签。// Services/Crypto/Sm2CryptoService.cs (续) using Microsoft.Extensions.Logging; using System.Text.Json; public class Sm2CryptoService : ISm2CryptoService { private readonly ECPrivateKeyParameters _decryptPrivateKey; // 用于解密前端数据的私钥 private readonly ECPublicKeyParameters _verifyPublicKey; // 用于验签的公钥 private readonly ILoggerSm2CryptoService _logger; private const string DefaultUserId 1234567812345678; public Sm2CryptoService(IConfiguration configuration, ILoggerSm2CryptoService logger) { _logger logger; var privateKeyPem configuration[Sm2Keys:DecryptPrivateKey]; var publicKeyPem configuration[Sm2Keys:VerifyPublicKey]; _decryptPrivateKey ParsePrivateKeyFromPem(privateKeyPem); _verifyPublicKey ParsePublicKeyFromPem(publicKeyPem); } /// summary /// 解密前端发送的SM2加密数据 /// /summary /// param namecipherTextBase64Base64格式的密文/param /// returns解密后的原始JSON字符串/returns public string DecryptData(string cipherTextBase64) { if (string.IsNullOrEmpty(cipherTextBase64)) throw new ArgumentNullException(nameof(cipherTextBase64)); try { // 1. Base64 - 字节数组 byte[] cipherBytes Convert.FromBase64String(cipherTextBase64); // 2. 使用BouncyCastle进行SM2解密 var sm2Engine new SM2Engine(new SM3Digest()); // SM2引擎使用SM3摘要 sm2Engine.Init(false, _decryptPrivateKey); // false 表示解密模式 byte[] decryptedBytes sm2Engine.ProcessBlock(cipherBytes, 0, cipherBytes.Length); // 3. 字节数组 - UTF8字符串 string plainText Encoding.UTF8.GetString(decryptedBytes); _logger.LogDebug(SM2解密成功明文长度: {Length}, plainText.Length); return plainText; } catch (FormatException ex) { _logger.LogError(ex, SM2解密失败密文Base64格式错误。); throw new CryptoException(密文格式无效, ex); } catch (InvalidCipherTextException ex) { _logger.LogError(ex, SM2解密失败可能是密钥不匹配或密文已损坏。); throw new CryptoException(解密失败密钥或数据错误, ex); } catch (Exception ex) { _logger.LogError(ex, SM2解密过程中发生未知错误。); throw; } } /// summary /// 验证请求签名 /// /summary /// param namedataToSign参与签名的数据字符串应与前端构造规则一致/param /// param namesignatureBase64Base64格式的签名/param /// param nameuserId用户ID默认为国密标准测试ID/param /// returns验签是否通过/returns public bool VerifySignature(string dataToSign, string signatureBase64, string userId DefaultUserId) { if (string.IsNullOrEmpty(signatureBase64)) { _logger.LogWarning(验签失败签名为空。); return false; } try { byte[] messageBytes Encoding.UTF8.GetBytes(dataToSign); byte[] signatureBytes Convert.FromBase64String(signatureBase64); // 使用SM3withSM2算法验签器 var signer SignerUtilities.GetSigner(SM3withSM2); signer.Init(false, _verifyPublicKey); // false for verification // 更新签名器数据先更新用户ID再更新消息 byte[] userIdBytes Encoding.UTF8.GetBytes(userId); signer.BlockUpdate(userIdBytes, 0, userIdBytes.Length); signer.BlockUpdate(messageBytes, 0, messageBytes.Length); bool isValid signer.VerifySignature(signatureBytes); _logger.LogDebug(SM2验签结果: {IsValid}, isValid); return isValid; } catch (Exception ex) { _logger.LogError(ex, SM2验签过程发生异常。); return false; } } /// summary /// 处理前端完整的请求包包含加密数据和签名 /// /summary /// typeparam nameT期望反序列化的数据类型/typeparam /// param nameencryptedData加密的业务数据(Base64)/param /// param namesignature签名(Base64)/param /// param nametimestamp时间戳/param /// param namerequestPath请求路径用于防重放/param /// returns解密后的业务数据对象/returns public T ProcessRequestT(string encryptedData, string signature, long timestamp, string requestPath) { // 1. 基本校验 if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - timestamp) 300000) // 5分钟有效期 { throw new CryptoException(请求已过期); } // 2. 构造验签字符串必须与前端规则完全一致 var signPayload new { encryptedData, timestamp, path requestPath }; string dataToSign JsonSerializer.Serialize(signPayload); // 使用System.Text.Json // 3. 验签 if (!VerifySignature(dataToSign, signature)) { throw new CryptoException(签名验证失败); } // 4. 解密数据 string decryptedJson DecryptData(encryptedData); // 5. 反序列化 try { return JsonSerializer.DeserializeT(decryptedJson) ?? throw new CryptoException(解密数据反序列化失败); } catch (JsonException ex) { _logger.LogError(ex, 解密后的JSON反序列化失败: {Json}, decryptedJson); throw new CryptoException(数据格式错误, ex); } } } // 自定义异常便于全局处理 public class CryptoException : Exception { public CryptoException(string message) : base(message) { } public CryptoException(string message, Exception innerException) : base(message, innerException) { } }然后在Controller中使用这个服务// Controllers/AuthController.cs [ApiController] [Route(api/[controller])] public class AuthController : ControllerBase { private readonly ISm2CryptoService _sm2Crypto; private readonly ILoggerAuthController _logger; public AuthController(ISm2CryptoService sm2Crypto, ILoggerAuthController logger) { _sm2Crypto sm2Crypto; _logger logger; } [HttpPost(login)] public async TaskIActionResult Login([FromBody] EncryptedRequest request) { try { // 1. 处理加密请求解密并验签 var loginData _sm2Crypto.ProcessRequestLoginModel( request.Data, request.Sign, request.Timestamp, HttpContext.Request.Path ); // 2. 这里loginData已经是解密后的LoginModel对象了 _logger.LogInformation(用户 {Username} 尝试登录, loginData.Username); // 3. 进行你的业务逻辑比如验证用户名密码... // var user await _userService.Authenticate(loginData.Username, loginData.Password); // 4. 返回响应响应也可以选择加密这里省略 return Ok(new { success true, message 登录成功, token generated-jwt-token }); } catch (CryptoException ex) { _logger.LogWarning(ex, 请求加解密或验签失败。); return BadRequest(new { success false, message ex.Message }); } catch (Exception ex) { _logger.LogError(ex, 登录处理过程中发生未预期错误。); return StatusCode(500, new { success false, message 服务器内部错误 }); } } } // 请求模型 public class EncryptedRequest { public string Data { get; set; } // Base64加密数据 public string Sign { get; set; } // Base64签名 public long Timestamp { get; set; } // 时间戳 } public class LoginModel { public string Username { get; set; } public string Password { get; set; } }5. 常见问题、调试技巧与避坑指南在实际对接过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理出来能帮你节省大量调试时间。5.1 密钥解析失败Invalid key format或Unknown object in GetInstance问题现象在C#端使用PemReader读取PEM字符串时抛出异常。可能原因PEM字符串头尾有空格或换行符不正确。密钥格式不符合BouncyCastle的预期例如是PKCS#1格式而非PKCS#8。公钥/私钥混淆了。解决方案清理PEM字符串确保字符串以-----BEGIN...开头以-----END...结尾中间是完整的Base64行。使用.Trim()方法。确认密钥类型用文本编辑器打开PEM文件看头部标识。BEGIN PRIVATE KEY通常是PKCS#8BEGIN EC PRIVATE KEY是PKCS#1。BouncyCastle的PemReader对PKCS#8兼容性更好。如果你的是PKCS#1可能需要先用OpenSSL转换openssl pkcs8 -topk8 -nocrypt -in private_key.pem -out private_key_pkcs8.pem。调试读取在PemReader.ReadObject()后不要直接强制转换先判断对象类型。var obj pemReader.ReadObject(); Console.WriteLine($Read object type: {obj?.GetType().FullName}); // 可能是 AsymmetricCipherKeyPair, ECPrivateKeyParameters, ECPublicKeyParameters 等5.2 解密失败Invalid ciphertext或Tag mismatch问题现象前端加密成功后端解密时抛出InvalidCipherTextException。可能原因编码不一致这是最常见的原因。前端传给后端的密文字符串编码不是纯粹的Base64或者Base64字符串在传输过程中被URL编码/解码破坏了。公钥私钥不配对用于加密的公钥和用于解密的私钥不是一对。加密模式差异虽然SM2标准统一但库的实现可能在填充或编码细节上有微小差异。sm-crypto的doEncrypt默认使用C1C3C2密文结构这是国标标准BouncyCastle的SM2Engine也默认支持此结构但需要确认。排查步骤打印和对比在前端加密后将生成的Base64密文打印到控制台console.log。在后端接收到请求后第一时间将request.Data打印到日志。对比两者是否完全一致注意换行符、空格。如果使用Postman测试确保Body是raw JSON且密文字段的值没有多余引号。检查密钥配对写一个简单的测试程序用后端的公钥加密一段文本然后用后端的私钥解密看是否成功。确保测试用的公钥就是给前端的那个。确认密文结构sm-crypto的doEncrypt默认输出顺序是C1C3C2。BouncyCastle的SM2Engine默认也期望这个顺序。一般不用改。如果怀疑是顺序问题可以尝试在创建SM2Engine时指定模式new SM2Engine(new SM3Digest(), SM2Engine.Mode.C1C3C2)虽然默认就是它。5.3 验签失败签名一直不通过问题现象前端生成的签名后端验签总是返回false。可能原因用户ID不一致这是头号杀手前端签名用的userId和后端验签时BlockUpdate的userId必须一字不差包括大小写和长度。强烈建议前后端使用同一个常量。签名数据源不一致前端用于生成签名的原始字符串和后端用于验签的字符串必须完全一样。一个空格、一个标点符号、JSON字段顺序不同都会导致哈希值不同从而验签失败。签名结果编码问题前端生成的签名是十六进制转成了Base64。后端需要先将Base64解码回字节数组再验签。确保这个转换过程无误。调试方法日志大法在前端将signString待签名的原始字符串和最终的signatureHex打印出来。在后端将dataToSign用于验签的字符串和接收到的signatureBase64解码后的字节数组长度打印出来。比对字符串将前后端打印的待签名字符串进行精确比对。可以用在线Diff工具。分步验证先在后端用代码生成一个签名使用同一个私钥和相同数据然后和前端传过来的签名比对看是否是生成环节的问题。或者用后端的公钥去验证后端自己生成的签名确保验签逻辑本身正确。5.4 性能与安全性注意事项性能SM2非对称加密比AES这样的对称加密慢得多。不要用它加密大段数据如文件、长文本。只用于加密关键信息如密码、对称加密的密钥或进行签名。对于大量数据传输应采用“SM2加密随机生成的AES密钥再用AES加密实际数据”的混合加密模式。密钥管理前端公钥用于加密的公钥可以硬编码或从接口获取暴露无妨。前端签名私钥如果前端需要签名如防篡改这个私钥绝不能硬编码在代码中。应该在用户登录后由后端动态下发一个临时的或会话级别的签名密钥对并在过期后失效。后端私钥解密私钥是核心资产必须妥善保管。推荐使用硬件安全模块HSM、云密钥管理服务KMS或至少是配置文件加密存储而不是明文写在appsettings.json里。错误处理加解密、验签失败时返回给前端的错误信息要模糊比如“处理失败”或“安全校验未通过”避免泄露系统细节如“密钥不匹配”。但后台日志一定要记录详细的错误信息方便排查。5.5 联调检查清单当你对接不成功时请按顺序检查以下清单[ ]密钥格式确认PEM密钥能被双方的库正确解析。尝试用各自库的“加载-导出”功能验证。[ ]密钥配对用后端公钥在后端加密一个字符串再用后端私钥解密确保密钥对本身有效。[ ]编码流程前端明文 -sm2.doEncrypt(hex) -Buffer.from(hex, hex).toString(base64)。后端Convert.FromBase64String-SM2Engine.Decrypt-Encoding.UTF8.GetString。确保每一步的输出都如预期。[ ]数据传输用浏览器开发者工具或Fiddler/Charles抓包确认HTTP请求体中的密文和签名字段值与前端代码生成的值完全一致没有自动转义或截断。[ ]签名数据确保前后端构造签名字符串的规则字段顺序、分隔符、是否包含时间戳/路径等百分百一致。将前后端用于签名的字符串日志拿出来逐字符对比。[ ]用户ID确认签名验签用的userId常量值完全相同。[ ]库版本检查sm-crypto和BouncyCastle的版本有时版本升级可能导致行为变化。查阅其版本更新日志。跨语言加密对接就像是在两个说不同方言的地区间架设通信协议关键在于统一“数据表示层”的约定。一旦你把密钥格式、编码方式和算法参数这三个桥梁搭稳了剩下的业务逻辑就是水到渠成。这次实战下来最大的体会就是日志要打够数据在进出每个关键函数时都打印一下十六进制或Base64很多问题就一目了然了。另外对于国密这种有明确国家标准但各库实现细节可能微调的场景优先以其中一个库比如sm-crypto的输出为基准去调整另一个库BouncyCastle的输入处理逻辑往往比两头改要高效得多。
