Spring Boot集成Bouncy Castle实现SM2国密算法：前后端加密交互完整指南

1. 项目概述与核心价值

最近在做一个对数据安全要求比较高的项目，涉及到前后端敏感数据的加密传输。甲方明确要求必须使用国密算法，特别是非对称加密部分，点名要用SM2。这其实挺常见的，现在金融、政务、物联网这些领域，国密算法的落地已经是硬性标准了。我一开始想，用Java实现SM2，找个现成的国密算法库不就行了？结果一上手就发现，事情没那么简单。

JDK自带的加密体系里，并没有原生支持SM2。网上倒是有一些开源实现，比如hutool里的SmUtil，用起来确实方便，但当你需要和前端（比如Vue、React）的JavaScript加密库进行交互时，兼容性问题就冒出来了。前端常用的sm-crypto库，其内部实现和某些Java库的默认参数、编码格式可能存在微妙的差异，导致前端加密的数据后端解不开，或者反过来。这种“联调”阶段的坑，往往最耗时间。

经过一番调研和踩坑，我最终选择了Bouncy Castle这个老牌、强大的加密提供者（Provider）来在Spring Boot中实现SM2。Bouncy Castle（简称BC）是一个提供了大量加密算法实现的Java库，它对国密算法的支持相对成熟和标准。更重要的是，通过仔细配置BC的SM2实现，并规范前后端的密钥格式、加密模式、编码方式，可以确保与前端sm-crypto等JS库无缝对接。这个方案不仅解决了当前需求，其构建的加密工具类和交互规范，也成了团队后续项目的标准组件。下面，我就把从环境集成、密钥生成、加解密实现到前后端联调的完整过程，以及我踩过的那些“坑”，详细分享一下。

2. 技术选型与环境搭建

2.1 为什么是Bouncy Castle？

在Java生态里做加密，JCA（Java Cryptography Architecture）是基石。但JCA更像一个框架，具体的算法实现（如AES、RSA）由Provider提供。Oracle JDK默认的Provider不支持国密。这时候就需要引入第三方Provider，Bouncy Castle就是其中最权威、最广泛使用的一个。

选择BC的主要原因有三个：

1. 算法支持全面且标准：BC对SM2、SM3、SM4等国密算法的实现，遵循了国家密码管理局的标准规范。这对于确保与其他标准实现（如前端sm-crypto、硬件加密机）的互操作性至关重要。
2. 成熟稳定，社区活跃：BC是一个经历了长时间考验的开源项目，被广泛应用于生产环境。这意味着其代码质量、安全性和遇到问题时的解决方案都更有保障。
3. 灵活的集成方式：我们可以将BC作为JCA的一个Provider动态注册到JVM中，这样就能使用标准的KeyPairGenerator、Cipher等JCA接口来操作SM2，学习成本和代码迁移成本都更低。

相比之下，一些其他国产开源Jar包可能更“轻便”，但可能在算法实现的严格标准性、长期维护性上存在风险。对于企业级应用，尤其是涉及合规要求的场景，BC是更稳妥的选择。

2.2 Spring Boot项目集成Bouncy Castle

集成BC主要分为两步：引入依赖和注册Provider。这里我推荐使用Bouncy Castle的bcprov-jdk15on和bcpkix-jdk15on。后者包含了处理证书和CRL等公钥基础设施相关的功能，虽然SM2基础加解密不一定需要，但为了功能的完整性和未来扩展，建议一并引入。

Maven依赖配置：

<dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15on</artifactId> <version>1.70</version> <!-- 请检查并使用最新稳定版 --> </dependency> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcpkix-jdk15on</artifactId> <version>1.70</version> </dependency>

关键一步：注册Provider仅仅引入依赖，JVM并不会自动使用BC。我们需要在应用启动时，将BC的Provider注册到JCA中。一个可靠的方式是使用@PostConstruct在一个配置类里完成。

import org.bouncycastle.jce.provider.BouncyCastleProvider; import org.springframework.context.annotation.Configuration; import javax.annotation.PostConstruct; import java.security.Security; @Configuration public class CryptoConfig { @PostConstruct public void init() { // 防止重复注册 if (Security.getProvider(BouncyCastleProvider.PROVIDER_NAME) == null) { Security.addProvider(new BouncyCastleProvider()); System.out.println("BouncyCastle Provider 注册成功。"); } } }

注意：注册Provider的代码要确保在任何加密操作之前执行。将其放在@PostConstruct中，由Spring容器在Bean初始化后调用，是一个简单有效的方法。另外，一定要检查是否已注册，避免重复注册导致意外问题。

验证注册是否成功：你可以写一个简单的测试接口或单元测试，打印当前所有Provider：

@Test public void testProvider() { Provider[] providers = Security.getProviders(); for (Provider p : providers) { System.out.println(p.getName()); } }

如果输出中包含BC或BouncyCastle，就说明注册成功了。

3. SM2密钥对生成与管理

3.1 使用BC生成SM2密钥对

SM2算法基于椭圆曲线密码学（ECC），其密钥对包括一个私钥（PrivateKey）和一个公钥（PublicKey）。生成密钥对时，需要指定一条标准的椭圆曲线参数。国密SM2标准推荐使用sm2p256v1这条曲线（其OID为1.2.156.10197.1.301）。

以下是生成SM2密钥对的工具方法：

import lombok.extern.slf4j.Slf4j; import org.bouncycastle.asn1.gm.GMNamedCurves; import org.bouncycastle.asn1.x9.X9ECParameters; import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPrivateKey; import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPublicKey; import org.bouncycastle.jce.spec.ECParameterSpec; import org.springframework.stereotype.Component; import java.security.*; import java.security.spec.ECGenParameterSpec; import java.util.Base64; @Slf4j @Component public class Sm2KeyGenerator { /** * 生成SM2密钥对 * @return 包含公钥和私钥的KeyPair对象 * @throws NoSuchAlgorithmException * @throws InvalidAlgorithmParameterException */ public KeyPair generateSm2KeyPair() throws NoSuchAlgorithmException, InvalidAlgorithmParameterException { // 1. 获取SM2椭圆曲线参数 final X9ECParameters sm2EcParameters = GMNamedCurves.getByName("sm2p256v1"); final ECParameterSpec sm2Spec = new ECParameterSpec( sm2EcParameters.getCurve(), sm2EcParameters.getG(), sm2EcParameters.getN(), sm2EcParameters.getH() ); // 2. 使用标准JCA接口，指定算法为"EC"，并设置Provider为BC KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC", BouncyCastleProvider.PROVIDER_NAME); keyPairGenerator.initialize(sm2Spec, new SecureRandom()); // 使用强随机数种子 // 3. 生成密钥对 KeyPair keyPair = keyPairGenerator.generateKeyPair(); log.info("SM2密钥对生成成功。"); return keyPair; } /** * 将公钥对象转换为Base64编码的字符串（便于存储或传输） * @param publicKey 公钥对象 * @return Base64字符串 */ public String getPublicKeyBase64(PublicKey publicKey) { BCECPublicKey bcecPublicKey = (BCECPublicKey) publicKey; // 获取Q值（椭圆曲线上的点）的编码形式 byte[] encoded = bcecPublicKey.getQ().getEncoded(false); // false表示不压缩 return Base64.getEncoder().encodeToString(encoded); } /** * 将私钥对象转换为Base64编码的字符串（需妥善保管！） * @param privateKey 私钥对象 * @return Base64字符串 */ public String getPrivateKeyBase64(PrivateKey privateKey) { BCECPrivateKey bcecPrivateKey = (BCECPrivateKey) privateKey; // 获取私钥大整数D的字节数组 byte[] encoded = bcecPrivateKey.getD().toByteArray(); // 注意：私钥D的字节数组长度可能不固定，可能需要处理前导零 return Base64.getEncoder().encodeToString(encoded); } }

关键点解析：

1. 曲线参数：GMNamedCurves.getByName("sm2p256v1")是BC库中定义的国密标准曲线，这是与前端sm-crypto互操作的基础。切勿使用其他非标曲线。
2. 算法名称：KeyPairGenerator.getInstance("EC", BouncyCastleProvider.PROVIDER_NAME)。这里算法名是"EC"（椭圆曲线通用名），但通过BC Provider和指定的sm2Spec参数，实际生成的就是SM2密钥。直接使用"SM2"可能在某些版本中不被识别。
3. 公钥格式：SM2公钥本质是椭圆曲线上的一个点(Q)。getEncoded(false)获取的是非压缩格式的字节表示（04 || X || Y），这是最通用、兼容性最好的格式。前端sm-crypto通常也接受这种格式的Base64或Hex字符串。
4. 私钥格式：私钥是一个大整数(D)。直接将其转换为字节数组并Base64编码。这里需要注意，BigInteger.toByteArray()可能包含符号位，导致数组长度不定，但在SM2上下文下，通常直接使用即可。更严谨的做法是将其填充或转换为固定长度的字节数组（如32字节）。

3.2 密钥的存储与安全实践

生成的密钥对需要妥善管理：

• 公钥：可以公开发布，用于加密或验签。可以存储在配置文件、数据库或通过接口动态下发。
• 私钥：必须绝对保密。绝不能硬编码在代码中或提交到版本库。
  • 推荐方案：将私钥的Base64字符串存储在环境变量、云厂商的密钥管理服务（如AWS KMS,阿里云KMS）或专用的硬件安全模块（HSM）中。应用启动时从这些安全位置读取。
  • 次选方案：对于安全性要求稍低的内部系统，可以使用经过加密的配置文件，并在启动时注入密码解密。

示例：从环境变量读取私钥并还原为PrivateKey对象

public PrivateKey loadPrivateKeyFromEnv() throws Exception { String base64PrivateKey = System.getenv("SM2_PRIVATE_KEY"); byte[] privateKeyBytes = Base64.getDecoder().decode(base64PrivateKey); BigInteger d = new BigInteger(1, privateKeyBytes); // 使用1确保正数 // 获取曲线参数 X9ECParameters sm2EcParameters = GMNamedCurves.getByName("sm2p256v1"); ECParameterSpec sm2Spec = new ECParameterSpec(...); // 同生成代码 // 构建私钥规格 ECPrivateKeySpec privateKeySpec = new ECPrivateKeySpec(d, sm2Spec); // 使用BC的KeyFactory生成私钥对象 KeyFactory keyFactory = KeyFactory.getInstance("EC", BouncyCastleProvider.PROVIDER_NAME); return keyFactory.generatePrivate(privateKeySpec); }

4. 后端SM2加解密核心实现

4.1 加密实现详解

SM2加密不是简单的“公钥加密明文”，它本质上是一种“集成加密方案”，内部包含了密钥派生和对称加密等步骤。BC的Cipher类封装了这些细节，我们只需要按标准方式调用。

import org.bouncycastle.jce.provider.BouncyCastleProvider; import javax.crypto.Cipher; import java.security.*; import java.util.Base64; @Component public class Sm2CryptoService { private static final String ALGORITHM = "SM2"; private static final String PROVIDER = BouncyCastleProvider.PROVIDER_NAME; /** * SM2公钥加密 * @param publicKeyBase64 Base64编码的公钥字符串 * @param plainText 明文 * @return Base64编码的密文 */ public String encrypt(String publicKeyBase64, String plainText) throws Exception { // 1. 将Base64公钥字符串还原为PublicKey对象 PublicKey publicKey = restorePublicKey(publicKeyBase64); // 2. 获取Cipher实例，指定算法和Provider Cipher cipher = Cipher.getInstance(ALGORITHM, PROVIDER); // 3. 初始化为加密模式 cipher.init(Cipher.ENCRYPT_MODE, publicKey); // 4. 执行加密（明文需先转为字节） byte[] cipherTextBytes = cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8)); // 5. 将密文字节数组转换为Base64字符串返回 return Base64.getEncoder().encodeToString(cipherTextBytes); } /** * 从Base64字符串还原SM2公钥对象 * 这是与前端交互的关键，格式必须匹配 */ private PublicKey restorePublicKey(String publicKeyBase64) throws Exception { byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyBase64); // 假设公钥格式为未压缩的04||X||Y，共65字节 if (publicKeyBytes.length != 65 || publicKeyBytes[0] != 0x04) { throw new IllegalArgumentException("无效的SM2公钥格式，预期为65字节未压缩格式(04开头)"); } X9ECParameters sm2EcParameters = GMNamedCurves.getByName("sm2p256v1"); ECCurve curve = sm2EcParameters.getCurve(); // 从字节数组中解析出X, Y坐标 BigInteger x = new BigInteger(1, Arrays.copyOfRange(publicKeyBytes, 1, 33)); // 第1-32字节是X BigInteger y = new BigInteger(1, Arrays.copyOfRange(publicKeyBytes, 33, 65)); // 第33-64字节是Y ECPoint ecPoint = curve.createPoint(x, y); ECParameterSpec sm2Spec = new ECParameterSpec(...); // 同前 ECPublicKeySpec pubKeySpec = new ECPublicKeySpec(ecPoint, sm2Spec); KeyFactory keyFactory = KeyFactory.getInstance("EC", PROVIDER); return keyFactory.generatePublic(pubKeySpec); } }

加密过程注意事项：

1. 公钥格式：restorePublicKey方法假设前端传过来的公钥是65字节、以0x04开头的未压缩格式。这是sm-crypto库getPublicKey('hex')或getPublicKey('base64')默认输出的格式。务必与前端同学确认公钥格式，这是联调成功的第一道关卡。
2. 字符编码：明文getBytes()必须指定字符集，如UTF-8，避免在不同环境下因默认编码不同导致加密结果不一致。
3. 异常处理：加密操作可能抛出BadPaddingException、IllegalBlockSizeException等，在生产代码中需要进行妥善的异常处理和日志记录，但不应将具体的加密错误细节暴露给前端。

4.2 解密实现详解

解密是加密的逆过程，使用私钥进行。

public class Sm2CryptoService { // ... 承接上文 /** * SM2私钥解密 * @param privateKeyBase64 Base64编码的私钥字符串（从安全处获取） * @param cipherTextBase64 Base64编码的密文 * @return 解密后的明文 */ public String decrypt(String privateKeyBase64, String cipherTextBase64) throws Exception { // 1. 还原私钥对象 PrivateKey privateKey = restorePrivateKey(privateKeyBase64); // 2. 获取Cipher实例 Cipher cipher = Cipher.getInstance(ALGORITHM, PROVIDER); // 3. 初始化为解密模式 cipher.init(Cipher.DECRYPT_MODE, privateKey); // 4. 执行解密 byte[] cipherTextBytes = Base64.getDecoder().decode(cipherTextBase64); byte[] plainTextBytes = cipher.doFinal(cipherTextBytes); // 5. 将明文字节数组按UTF-8编码转为字符串 return new String(plainTextBytes, StandardCharsets.UTF_8); } /** * 从Base64字符串还原SM2私钥对象 */ private PrivateKey restorePrivateKey(String privateKeyBase64) throws Exception { byte[] privateKeyBytes = Base64.getDecoder().decode(privateKeyBase64); BigInteger d = new BigInteger(1, privateKeyBytes); // 使用1确保为正数 X9ECParameters sm2EcParameters = GMNamedCurves.getByName("sm2p256v1"); ECParameterSpec sm2Spec = new ECParameterSpec(...); // 同前 ECPrivateKeySpec privateKeySpec = new ECPrivateKeySpec(d, sm2Spec); KeyFactory keyFactory = KeyFactory.getInstance("EC", PROVIDER); return keyFactory.generatePrivate(privateKeySpec); } }

解密过程关键点：

1. 私钥安全：privateKeyBase64参数应从安全存储（如环境变量）中获取，而不是由前端传递。后端解密接口通常需要严格的权限控制。
2. 密文格式：确保接收到的cipherTextBase64是后端encrypt方法生成的标准Base64字符串，或与前端约定好的格式。SM2加密后的密文是ASN.1 DER编码的复杂结构，BC的Cipher类会处理这个结构的解析。
3. 错误处理：解密失败最常见的原因是密钥不匹配（用错了公钥/私钥对）或密文被篡改。返回给前端的错误信息应足够模糊（如“解密失败”），避免信息泄露。

5. 前端JS加密与交互规范

5.1 前端库选型与初始化

前端我们选择sm-crypto，这是一个纯JavaScript实现的国密算法库，支持SM2、SM3、SM4，在Node.js和浏览器环境都能运行，且API设计友好。

安装：

npm install sm-crypto --save # 或 yarn add sm-crypto

初始化与密钥生成：在前端，我们通常不会生成密钥对，而是使用后端下发的公钥进行加密。但为了测试和演示，这里也展示一下前端的密钥生成。

import { sm2 } from 'sm-crypto'; // 1. 生成密钥对（通常由后端生成，前端仅用于测试） const keypair = sm2.generateKeyPairHex(); const publicKey = keypair.publicKey; // 04开头的16进制公钥字符串 const privateKey = keypair.privateKey; // 16进制私钥字符串 console.log('公钥:', publicKey); console.log('私钥:', privateKey); // 注意：前端不应保存或使用私钥！ // 2. 后端下发的公钥（假设是Base64格式，需要转换） // 假设从接口获取的公钥Base64字符串为 backendPublicKeyBase64 import { Base64 } from 'js-base64'; // 可能需要引入Base64库 const backendPublicKeyBase64 = 'MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAEL...'; // 示例 // 将Base64解码为字节，再转为16进制（sm-crypto的encrypt方法通常接受16进制公钥） const backendPublicKeyHex = Buffer.from(backendPublicKeyBase64, 'base64').toString('hex'); // 或者，如果后端直接提供16进制公钥字符串则更简单

重要提示：在实际生产环境中，前端绝对不应该生成或持有私钥。私钥的生成、保管和使用必须完全在后端（或硬件设备）的安全环境中进行。前端只负责用公钥加密数据。

5.2 前端加密与数据发送

前端加密的核心是使用sm-crypto的sm2.doEncrypt方法。这里有一个至关重要的细节：加密模式。sm-crypto默认使用C1C3C2的ASN.1编码格式，而BC库默认可能使用C1C2C3或其他格式。如果格式不匹配，后端解密必定失败。

经过实测，确保前后端一致的配置如下：

// 前端加密函数 function encryptData(plainText, publicKeyHex) { // 关键参数：cipherMode = 0， 表示输出为C1C3C2顺序的ASN.1 DER编码密文 // 这个模式与后端Bouncy Castle的默认解密期望格式兼容 const cipherMode = 0; const encryptedDataHex = sm2.doEncrypt(plainText, publicKeyHex, cipherMode); // 将16进制密文转换为Base64，便于在JSON中传输 const encryptedDataBase64 = Buffer.from(encryptedDataHex, 'hex').toString('base64'); return encryptedDataBase64; } // 使用示例 const dataToEncrypt = JSON.stringify({ userId: '12345', timestamp: Date.now() }); const encryptedBase64 = encryptData(dataToEncrypt, backendPublicKeyHex); // 将加密后的数据作为请求体发送 fetch('/api/secure-endpoint', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cipherText: encryptedBase64 }) }) .then(response => response.json()) .then(data => console.log('响应:', data));

核心要点：

1. cipherMode = 0：这是与Java BC库兼容的关键。sm-crypto的doEncrypt方法第二个参数是公钥，第三个参数是模式。模式0代表C1C3C2的ASN.1 DER编码，这是目前与BC默认解密器兼容性最好的选择。务必与后端确认并使用此模式。
2. 编码转换：sm-crypto加密输出的是16进制字符串，而网络传输中Base64更常用（体积更小）。使用Buffer或js-base64库进行转换。
3. 明文格式：通常我们会将需要加密的数据（如一个JSON对象）先序列化成字符串，再加密。确保前后端对明文字符串的编码（UTF-8）有共识。

5.3 后端接收与解密处理

后端提供一个RESTful接口来接收前端加密的数据。

import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api") @Slf4j public class CryptoController { @Autowired private Sm2CryptoService sm2CryptoService; // 假设私钥已从安全位置加载到这个变量中 @Value("${sm2.private-key-base64}") private String serverPrivateKeyBase64; @PostMapping("/secure-endpoint") public ResponseEntity<Map<String, Object>> handleEncryptedRequest(@RequestBody EncryptedRequest request) { Map<String, Object> response = new HashMap<>(); try { // 1. 获取前端传来的Base64密文 String cipherTextBase64 = request.getCipherText(); // 2. 使用服务端私钥解密 String decryptedText = sm2CryptoService.decrypt(serverPrivateKeyBase64, cipherTextBase64); // 3. 将解密后的字符串解析为业务对象 MyBusinessDTO businessData = objectMapper.readValue(decryptedText, MyBusinessDTO.class); log.info("解密成功，业务数据: {}", businessData); // 4. 处理业务逻辑... // ... // 5. 构造响应（如需返回加密数据，则用前端公钥加密） response.put("success", true); response.put("data", "处理成功"); return ResponseEntity.ok(response); } catch (Exception e) { log.error("请求处理失败，解密或业务逻辑错误", e); // 注意：不要将具体的异常信息（如解密失败详情）返回给前端，以防信息泄露 response.put("success", false); response.put("message", "请求处理失败"); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response); } } // 用于接收加密请求的DTO @Data public static class EncryptedRequest { private String cipherText; } }

6. 联调实战、常见问题与排查技巧

6.1 联调核对清单

前后端联调SM2加密时，请按以下清单逐一核对，可以解决90%的问题：

6.2 典型错误与解决方案

问题1：后端解密失败，抛出InvalidCipherTextException或类似异常。

• 可能原因A：公钥不匹配。前端用于加密的公钥，与后端解密使用的私钥不是一对。
  • 排查：让后端打印用于解密的私钥对应的公钥（Base64），与前端用于加密的公钥进行比对。确保完全一致。
• 可能原因B：加密模式不匹配。前端sm-crypto加密时未指定模式或模式错误。
  • 解决：前端加密必须使用sm2.doEncrypt(plainText, publicKeyHex, 0)。第三个参数0是联调成功的黄金法则。
• 可能原因C：密文在传输过程中被篡改或编码错误。
  • 排查：后端收到密文Base64字符串后，先尝试Base64解码，看是否能正常解码为字节数组。同时，对比前端发送的Base64字符串和后端接收到的字符串是否完全相同（注意URL编码问题，如果放在URL中可能需要encode/decode）。

问题2：后端能解密，但解密出的明文是乱码。

• 可能原因：前后端字符编码不一致。
  • 解决：后端在加密时将字符串转为字节数组时，显式指定plainText.getBytes(StandardCharsets.UTF_8)。解密后，用new String(plainBytes, StandardCharsets.UTF_8)。前端确保加密前的字符串是UTF-8编码。

问题3：前端加密时，公钥格式错误。

• 现象：sm-crypto报错，提示无效的公钥。
• 排查：检查后端提供给前端的公钥字符串。如果是Base64，前端需要先将其解码为16进制。确保公钥字符串以04开头（如果是16进制），且长度正确（130个16进制字符，对应65字节）。

问题4：性能问题，加密大量数据慢。

• 原因：SM2作为非对称加密，不适合加密大数据量。通常用于加密对称加密的密钥（如AES密钥），或者加密非常短的数据（如票据、签名）。
• 最佳实践：采用“混合加密”体系。
  1. 前端随机生成一个AES密钥（key）。
  2. 使用这个AES密钥，通过SM4或AES算法加密实际的大数据（data）。
  3. 使用后端的SM2公钥，加密上一步生成的AES密钥（encryptedKey）。
  4. 将{ cipherData: encryptedData, encryptedKey: encryptedKey }发送给后端。
  5. 后端先用SM2私钥解密出AES密钥，再用该密钥解密数据。

6.3 进阶技巧：签名与验签

除了加密，SM2还用于数字签名。流程类似，但目的不同：签名是为了验证数据的完整性和来源真实性。

后端签名：

public String sign(PrivateKey privateKey, String data) throws Exception { Signature signature = Signature.getInstance("SM3withSM2", BouncyCastleProvider.PROVIDER_NAME); signature.initSign(privateKey); signature.update(data.getBytes(StandardCharsets.UTF_8)); byte[] signBytes = signature.sign(); return Base64.getEncoder().encodeToString(signBytes); }

前端验签：

import { sm2 } from 'sm-crypto'; const publicKeyHex = '...'; // 后端公钥 const originalData = '待验签数据'; const signBase64 = '...'; // 后端传来的签名 const signHex = Buffer.from(signBase64, 'base64').toString('hex'); const verifyResult = sm2.doVerifySignature(originalData, signHex, publicKeyHex); console.log('验签结果:', verifyResult); // true or false

签名验签注意事项：

1. 签名算法名是SM3withSM2，表示使用SM3做摘要，SM2做签名。
2. 签名的结果也是ASN.1 DER编码的，直接Base64传输即可。
3. 前端sm-crypto的doVerifySignature方法默认支持这种格式的签名。

7. 项目集成与生产级考量

7.1 配置化与Bean管理

在实际Spring Boot项目中，我们不应在每次加解密时都去读取环境变量或重建密钥对象。最佳实践是使用@ConfigurationProperties或@Value将密钥注入，并在应用启动时初始化好Sm2CryptoServiceBean。

@Configuration @Slf4j public class Sm2AutoConfiguration { @Bean @ConditionalOnMissingBean public Sm2CryptoService sm2CryptoService( @Value("${sm2.private-key-base64:#{null}}") String privateKeyBase64, @Value("${sm2.public-key-base64:#{null}}") String publicKeyBase64) throws Exception { Sm2CryptoService service = new Sm2CryptoService(); if (privateKeyBase64 != null && !privateKeyBase64.trim().isEmpty()) { // 初始化服务端私钥（用于解密和签名） PrivateKey privateKey = service.restorePrivateKey(privateKeyBase64); service.setServerPrivateKey(privateKey); log.info("SM2服务端私钥已加载。"); } if (publicKeyBase64 != null && !publicKeyBase64.trim().isEmpty()) { // 初始化服务端公钥（用于验签，如果前端需要验签的话） PublicKey publicKey = service.restorePublicKey(publicKeyBase64); service.setServerPublicKey(publicKey); log.info("SM2服务端公钥已加载。"); } else { // 或者，可以在这里生成一对新的密钥对 // KeyPair keyPair = new Sm2KeyGenerator().generateSm2KeyPair(); // service.setServerKeyPair(keyPair); // log.warn("未配置SM2公钥，已自动生成新密钥对。请妥善保管私钥。"); } return service; } }

然后在application.yml中配置：

sm2: # 从安全环境变量中读取，不要明文写在配置文件中 private-key-base64: ${SM2_SERVER_PRIVATE_KEY} # 公钥可以配置，也可以由私钥推导或动态生成 public-key-base64: ${SM2_SERVER_PUBLIC_KEY}

7.2 封装为Starter或通用模块

如果公司内有多个项目需要使用SM2，强烈建议将上述Sm2CryptoService、Sm2KeyGenerator、配置类以及相关的工具类（如密钥格式转换）打包成一个独立的Spring Boot Starter或者一个通用的Jar包。这样可以：

1. 统一实现：确保所有项目使用相同、正确的BC配置和交互规范。
2. 降低接入成本：其他项目只需引入依赖，简单配置即可使用。
3. 便于升级和维护：算法库版本升级、安全补丁应用只需修改一个地方。

7.3 监控与日志

在生产环境中，加解密操作应该被妥善监控和记录。

• 日志：记录加解密操作的摘要信息（如操作类型、数据ID），但绝对不要记录明文、密文、密钥等敏感信息到日志文件。
• 监控：监控加解密接口的调用频率、耗时和错误率。异常的解密失败请求突然增多，可能是遭受攻击的迹象。
• 性能：非对称加密是CPU密集型操作。在高并发场景下，需要关注服务器的CPU使用率，必要时考虑使用连接池化技术或硬件加速卡。

7.4 密钥轮换与多版本支持

为了安全，密钥需要定期轮换。在设计中需要考虑：

1. 密钥版本化：每个密钥对有一个版本号（如v1,v2）。加密时，可以在密文或请求头中附带使用的公钥版本号。
2. 后端多密钥支持：后端根据版本号，从密钥库中加载对应的私钥进行解密。这样，旧版本密钥在轮换后仍能解密历史数据，新数据则用新密钥加密。
3. 前端动态获取公钥：前端不应硬编码公钥，而应该从一个安全的接口动态获取当前活跃的公钥及其版本号。这为密钥轮换提供了可能。

实现这套方案后，你的Spring Boot应用就具备了符合国密标准、且能与前端安全交互的SM2加解密能力。整个过程的核心在于对Bouncy Castle库的正确使用，以及对前后端数据格式、编码、模式的严格约定。联调阶段耐心按照核对清单排查，就能顺利打通。这套方案已经在我们多个对数据安全有严格要求的项目中稳定运行，希望能为你提供可靠的参考。