Spring Boot国密算法实战：SM2/SM3/SM4集成与混合加密方案

1. 项目概述与背景

最近几年，在涉及金融、政务、能源等对数据安全有极高要求的项目中，国密算法的身影越来越常见。作为一名长期奋战在一线的Java开发者，我接手过不少需要将传统国际算法（如RSA、AES、SHA-256）替换为国密算法（SM2/SM3/SM4）的项目。说实话，第一次接触时也踩了不少坑，比如SM2的公钥格式问题、SM4的加密模式选择，以及前后端加解密结果不一致等。这些坑，文档里往往不会细说，全靠实战摸索。今天，我就结合一个完整的Spring Boot项目，手把手带你走一遍国密算法集成的全流程，从环境搭建、依赖引入，到核心代码实现、前后端联调，最后还会分享几个我趟过的“雷区”和调试技巧。无论你是初次接触国密，还是正在项目中落地，这篇近万字的实战指南都能让你少走弯路，直接复现。

简单来说，国密算法是我国自主研发的一套商用密码算法标准。SM2是非对称加密算法，对标RSA，用于数字签名和密钥交换；SM3是哈希摘要算法，对标SHA-256；SM4是对称加密算法，对标AES。在Spring Boot中集成它们，核心在于选对工具库、理清加解密流程，并处理好前后端数据交互的编码问题。接下来，我们就从零开始，构建一个具备完整国密加解密能力的后端服务。

2. 环境准备与核心依赖选型

集成任何第三方功能，第一步永远是搭建环境和引入依赖。这一步没做对，后面全是坑。

2.1 创建Spring Boot项目

我习惯使用Spring Initializr（start.spring.io）或者IDE（如IntelliJ IDEA）的内置工具来快速生成项目骨架。这里我们创建一个标准的Spring Boot 3.x项目（Spring Boot 2.7.x也完全兼容，依赖版本稍作调整即可）。

项目基本信息：

• Group:com.example
• Artifact:springboot-sm-demo
• Packaging:Jar
• Java Version:17 或 11（推荐17，长期支持版本）
• Dependencies:在生成时，我们只需要选择最基础的Spring Web依赖即可。其他的加密库依赖我们需要手动在pom.xml中添加，以便更精确地控制版本。

生成项目后，得到一个标准的Maven项目结构。关键的pom.xml文件初始内容很简单，接下来我们要往里添加国密算法所需的“弹药”。

2.2 关键依赖库深度解析

国密算法的实现，我们主要依靠两个库：Bouncy Castle和Hutool。为什么是它们？这里我详细解释一下选型逻辑。

1. Bouncy Castle (BC)这是一个功能强大的密码学提供者（Provider）库，提供了包括国密算法在内的众多密码学算法实现。在Java中，java.security包下的很多加密功能需要具体的Provider来支持。BC就是这样一个“插件”，它让JVM能够认识并执行SM2、SM3、SM4这些算法。

• 作用：提供国密算法的底层实现。
• 版本选择：务必使用较新的稳定版。我长期使用bcprov-jdk15on，版本号1.70或1.68都是经过大量项目验证的稳定版本。版本太老可能缺少某些优化或修复，太新则可能引入未知兼容性问题。
• 关键点：BC库需要被注册为JVM的安全提供者。通常Hutool在底层会自动处理，但了解这个机制对排查“NoSuchAlgorithmException”这类错误至关重要。

2. Hutool这是一个国人开发的Java工具库，其hutool-crypto模块对Bouncy Castle的国密算法进行了非常友好、易用的封装。它简化了密钥生成、加解密、签名验签等操作的API，让我们能用几行代码完成复杂操作，避免了直接调用BC原生API的繁琐和晦涩。

• 作用：提供面向国密算法的高级、易用的API封装。
• 版本选择：使用较新的5.x版本，如5.8.23。Hutool的API保持得很好，新版本功能更全，BUG更少。

最终，你的pom.xml依赖部分应该像下面这样：

<dependencies> <!-- Spring Boot 基础Web依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 国密算法底层实现 --> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15on</artifactId> <version>1.70</version> </dependency> <!-- 国密算法工具封装（强烈推荐） --> <dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-all</artifactId> <version>5.8.23</version> </dependency> <!-- 测试与文档依赖（按需添加） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.3.0</version> <!-- 用于生成API文档，可选 --> </dependency> </dependencies>

注意：如果你所在公司的Maven私服无法下载这些依赖，可能需要配置正确的仓库地址，或者联系运维人员。依赖下载失败是新手遇到的第一个高频问题。

添加完依赖，执行mvn clean compile，确保所有依赖都能正常下载和编译。至此，我们的“武器库”就准备齐全了。

3. SM3：消息摘要算法实战

SM3算法用于生成数据的“数字指纹”，特点是不可逆（无法从摘要反推原始数据）和抗碰撞（极难找到两份不同数据产生相同摘要）。常用在数据完整性校验、数字签名场景中。Hutool将其封装得极其简单。

3.1 基础字符串与文件摘要计算

我们先创建一个测试类Sm3DemoService来感受一下：

import cn.hutool.crypto.SmUtil; import cn.hutool.core.util.HexUtil; import java.io.File; import java.io.FileInputStream; import java.io.IOException; @Service public class Sm3DemoService { /** * 对普通字符串进行SM3哈希 */ public String hashString(String data) { // 一行代码搞定。digestHex 返回16进制字符串形式的摘要 return SmUtil.sm3().digestHex(data); // 输出示例：66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 } /** * 对文件进行SM3哈希（无密钥） * 用于验证文件传输后是否被篡改 */ public String hashFile(String filePath) throws IOException { File file = new File(filePath); try (FileInputStream fis = new FileInputStream(file)) { // 直接对输入流进行摘要计算，适合大文件 return SmUtil.sm3().digestHex(fis); } } }

调用hashString("Hello, 国密!")，你会得到一个固定的64位十六进制字符串。这就是该字符串唯一的“指纹”。文件摘要同理，文件内容哪怕只改变一个比特，生成的摘要也会截然不同。

3.2 带密钥的HMAC-SM3

SM3本身不需要密钥，但HMAC（基于哈希的消息认证码）机制可以为其引入一个密钥，用于在验证数据完整性的同时验证消息来源的真实性（即知道密钥的人生成的摘要）。

public class Sm3DemoService { // ... 其他方法 /** * 使用HMAC-SM3计算带密钥的摘要 * @param data 原始数据 * @param key 密钥（字符串形式） * @return 摘要 */ public String hmacSm3(String data, String key) { // 将密钥转换为字节数组。注意，密钥本身也需要妥善保管。 byte[] keyBytes = key.getBytes(StandardCharsets.UTF_8); // 使用Hutool的SmUtil.hmacSm3方法 return SmUtil.hmacSm3(keyBytes).digestHex(data); } /** * 对文件流进行HMAC-SM3计算 */ public String hmacSm3File(String filePath, String key) throws IOException { byte[] keyBytes = key.getBytes(StandardCharsets.UTF_8); File file = new File(filePath); try (FileInputStream fis = new FileInputStream(file)) { return SmUtil.hmacSm3(keyBytes).digestHex(fis); } } }

实操心得：

1. 摘要比较：比较两个摘要是否相等时，一定要使用安全的比较方法，如MessageDigest.isEqual(byte[], byte[])或比较其十六进制字符串，以避免时序攻击。
2. 密钥管理：HMAC的密钥需要像密码一样保密。在实际项目中，不应硬编码在代码里，而应从安全的配置中心或密钥管理服务（KMS）中获取。
3. 性能考量：对于超大文件，直接使用digestHex(InputStream)是流式处理，不会将整个文件加载到内存，避免内存溢出（OOM）。

SM3的集成相对直接，难点在于理解其应用场景。接下来，我们进入更复杂的非对称加密世界——SM2。

4. SM2：非对称加密与签名实战

SM2是基于椭圆曲线密码学（ECC）的非对称算法。它包含加密解密和数字签名两大功能。非对称意味着有一对密钥：公钥（公开）和私钥（保密）。公钥用于加密或验证签名，私钥用于解密或进行签名。

4.1 生成SM2密钥对

一切始于密钥对。我们用Hutool可以轻松生成。

import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.asymmetric.SM2; import cn.hutool.core.util.HexUtil; import cn.hutool.crypto.BCUtil; import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPublicKey; import java.util.HashMap; import java.util.Map; @Service public class Sm2KeyService { /** * 生成SM2密钥对，并以16进制字符串形式返回 * @return Map包含公钥(publicKey)和私钥(privateKey) */ public Map<String, String> generateKeyPairHex() { // 1. 使用Hutool生成SM2对象，内部会自动创建密钥对 SM2 sm2 = SmUtil.sm2(); // 2. 提取公钥字节并转换为16进制（不压缩格式，通常以'04'开头） // BCUtil.encodeECPublicKey 用于提取ECC公钥的Q点编码 byte[] publicKeyBytes = BCUtil.encodeECPublicKey(sm2.getPublicKey()); String publicKeyHex = HexUtil.encodeHexStr(publicKeyBytes).toUpperCase(); // 3. 提取私钥字节并转换为16进制 byte[] privateKeyBytes = BCUtil.encodeECPrivateKey(sm2.getPrivateKey()); String privateKeyHex = HexUtil.encodeHexStr(privateKeyBytes).toUpperCase(); Map<String, String> keyPair = new HashMap<>(2); keyPair.put("publicKey", publicKeyHex); keyPair.put("privateKey", privateKeyHex); return keyPair; } }

生成的公钥通常是一个130字符（65字节）的十六进制字符串，以04开头。私钥是一个64字符的十六进制字符串。务必妥善保存私钥！公钥可以分发给任何需要向你发送加密数据或验证你签名的人。

4.2 SM2加密与解密

假设前端获得了你的公钥，他可以用公钥加密一段敏感数据（如一个对称加密的密钥），只有持有对应私钥的你才能解密。

@Service public class Sm2CryptoService { // 假设这是从数据库或配置中读取的密钥对 private String publicKeyHex = "04F8BA2A9DFDE5977DFDE3C87A3D0298809FF3396BD908B01DE7057EE4951CF4F193EB0841DA05D7612D13A13E23C0ACB8A00902C0D409236A92C4EF3AA2C72823"; private String privateKeyHex = "3AEAE64C481550DF7D50B6A693378D0C3722947DFFBD55B43880912497126620"; /** * 使用公钥加密 * @param plainText 明文 * @return 16进制密文 */ public String encrypt(String plainText) { // 1. 使用公钥创建SM2对象（私钥为null） SM2 sm2 = SmUtil.sm2(null, publicKeyHex); // 2. 设置加密模式为 C1C3C2 (这是SM2标准格式) sm2.setMode(SM2Engine.Mode.C1C3C2); // 3. 执行加密，返回16进制密文 // Hutool的encryptHex方法默认会在密文前加04，这是未压缩公钥的标识 return sm2.encryptHex(plainText, KeyType.PublicKey); } /** * 使用私钥解密 * @param cipherTextHex 16进制密文 * @return 明文 */ public String decrypt(String cipherTextHex) { // **关键坑点处理：前后端密文格式统一** // 前端SM2加密库（如sm-crypto）生成的密文可能不带04前缀。 // 但Hutool的decryptStr方法默认期望密文带04前缀。 // 解决方案：如果前端传来不带04的密文，我们手动加上。 if (!cipherTextHex.startsWith("04")) { cipherTextHex = "04" + cipherTextHex; } // 1. 使用私钥创建SM2对象（公钥为null） SM2 sm2 = SmUtil.sm2(privateKeyHex, null); // 2. 设置解密模式，必须与加密时一致 sm2.setMode(SM2Engine.Mode.C1C3C2); // 3. 执行解密 return sm2.decryptStr(cipherTextHex, KeyType.PrivateKey); } }

注意事项：

1. 加密模式（Mode）：SM2加密后的数据由C1, C2, C3三部分组成，排列顺序有C1C2C3和C1C3C2两种标准。前后端必须统一！国内通常使用C1C3C2，这也是Hutool的默认模式。务必在代码中显式声明setMode，并在文档中告知前端同学。
2. 密文格式（04前缀）：这是集成时最容易出错的点。不同库对公钥和密文的表示习惯不同。上述代码中的判断和补全操作，是我经过多次联调试错后总结的稳健做法。最可靠的方式是前后端约定好密文的传输格式（带或不带04），或者在后端提供一个测试接口，让前端加密一段固定文本，看后端是否能成功解密。
3. 加密长度限制：SM2作为非对称加密，不适合直接加密很长的数据（性能差）。通常用于加密“会话密钥”或“关键数据”。长数据加密应使用SM4。

4.3 SM2签名与验签

数字签名用于证明“这段数据是我发的，且中途没有被篡改”。发送方用私钥签名，接收方用公钥验签。

@Service public class Sm2SignatureService { private String privateKeyHex = "你的私钥"; private String publicKeyHex = "你的公钥"; /** * 使用私钥对数据进行签名 * @param data 待签名数据 * @return 16进制签名结果 */ public String sign(String data) { SM2 sm2 = SmUtil.sm2(privateKeyHex, null); // 使用DER编码格式的签名 return sm2.signHex(data.getBytes(StandardCharsets.UTF_8)); } /** * 使用公钥验证签名 * @param data 原始数据 * @param signHex 16进制签名 * @return 验签是否通过 */ public boolean verify(String data, String signHex) { SM2 sm2 = SmUtil.sm2(null, publicKeyHex); return sm2.verify(data.getBytes(StandardCharsets.UTF_8), HexUtil.decodeHex(signHex)); } }

签名验签流程在接口调用、合同电子化等场景中至关重要，确保了数据的不可否认性和完整性。

5. SM4：对称加密算法实战

SM4是一种分组对称加密算法，密钥长度固定为128位（16字节）。它速度快，适合加密大量数据。常用的工作模式有ECB和CBC。

5.1 ECB模式与CBC模式

• ECB (Electronic Codebook):最简单的模式，将数据分成块，每块独立加密。缺点：相同的明文块会加密成相同的密文块，不能很好地隐藏数据模式，安全性相对较低。一般不推荐用于加密有规律的数据。
• CBC (Cipher Block Chaining):每个明文块先与前一个密文块进行异或操作，然后再加密。需要一个初始化向量（IV）来启动这个过程。优点：相同的明文块在不同位置会加密成不同的密文块，安全性更好。这是推荐使用的模式。

5.2 使用Hutool进行SM4加解密

import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.symmetric.SM4; import cn.hutool.core.util.CharsetUtil; import java.nio.charset.StandardCharsets; @Service public class Sm4CryptoService { /** * SM4 ECB模式加密 (Base64输出) * @param key 16字节的密钥（16个字符的字符串或32位16进制字符串） * @param plainText 明文 * @return Base64编码的密文 */ public String encryptEcb(String key, String plainText) { // 将密钥字符串转换为字节数组。确保密钥是16字节。 byte[] keyBytes = ensureKeyLength(key); SM4 sm4 = SmUtil.sm4(keyBytes); // 设置模式为ECB，无需IV sm4.setMode(SM4.Mode.ECB); // 加密并转为Base64，方便网络传输 return sm4.encryptBase64(plainText); } public String decryptEcb(String key, String cipherTextBase64) { byte[] keyBytes = ensureKeyLength(key); SM4 sm4 = SmUtil.sm4(keyBytes); sm4.setMode(SM4.Mode.ECB); return sm4.decryptStr(cipherTextBase64); } /** * SM4 CBC模式加密 (推荐) * @param key 16字节密钥 * @param iv 16字节初始化向量 * @param plainText 明文 * @return Base64编码的密文 */ public String encryptCbc(String key, String iv, String plainText) { byte[] keyBytes = ensureKeyLength(key); byte[] ivBytes = ensureIVLength(iv); SM4 sm4 = SmUtil.sm4(keyBytes); // 设置模式为CBC，并传入IV sm4.setMode(SM4.Mode.CBC); sm4.setIv(ivBytes); return sm4.encryptBase64(plainText); } public String decryptCbc(String key, String iv, String cipherTextBase64) { byte[] keyBytes = ensureKeyLength(key); byte[] ivBytes = ensureIVLength(iv); SM4 sm4 = SmUtil.sm4(keyBytes); sm4.setMode(SM4.Mode.CBC); sm4.setIv(ivBytes); return sm4.decryptStr(cipherTextBase64); } /** * 确保密钥长度为16字节（128位） * 简单示例：如果传入的是16字符的字符串，直接取字节。 * 更健壮的做法：支持16进制字符串或进行密钥派生（KDF）。 */ private byte[] ensureKeyLength(String key) { // 这里假设key是长度为16的ASCII字符串 // 实际项目应从安全渠道获取二进制密钥，或使用安全的KDF生成 if (key.length() != 16) { throw new IllegalArgumentException("SM4 key must be 16 bytes (128 bits) long."); } return key.getBytes(StandardCharsets.UTF_8); } private byte[] ensureIVLength(String iv) { if (iv.length() != 16) { throw new IllegalArgumentException("SM4 IV must be 16 bytes long."); } return iv.getBytes(StandardCharsets.UTF_8); } }

核心要点：

1. 密钥与IV管理：密钥（Key）和初始化向量（IV）是对称加密的命门。绝对不要硬编码在代码中！应该从安全的配置源（如Vault, KMS）获取，或者通过安全的密钥交换协议（如SM2）动态生成。
2. 编码问题：加密后得到的是字节数组，为了在网络中传输或存储，通常需要编码。encryptBase64和decryptStr（内部处理Base64）是Hutool提供的便捷方法。确保前后端使用相同的编码（通常都是Base64）。
3. 填充模式：Hutool的SM4默认使用PKCS7Padding（也叫PKCS5Padding），这是一种标准的填充方式。前后端库需要确认填充模式一致，否则解密会失败。

6. 混合加密实战：SM2+SM4构建安全信道

在实际系统中，单纯使用一种加密方式往往不够。一个经典的、兼顾安全与性能的混合加密方案是：使用SM2加密传输SM4的会话密钥，再用该SM4密钥加密实际业务数据。这结合了非对称加密的安全性和对称加密的高效性。

6.1 完整流程与代码实现

我们来构建一个完整的Controller，模拟一次安全的数据提交过程。

import cn.hutool.core.util.HexUtil; import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.asymmetric.KeyType; import cn.hutool.crypto.asymmetric.SM2; import cn.hutool.crypto.symmetric.SM4; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import lombok.Data; import org.bouncycastle.crypto.engines.SM2Engine; import org.springframework.web.bind.annotation.*; import java.nio.charset.StandardCharsets; import java.util.HashMap; import java.util.Map; import java.util.UUID; @Tag(name = "安全数据接口") @RestController @RequestMapping("/api/secure") public class SecureDataController { // 后端持有的固定SM2密钥对（实际项目中，私钥应存储在更安全的地方，如HSM） private static final String SERVER_SM2_PRIVATE_KEY = "3AEAE64C481550DF7D50B6A693378D0C3722947DFFBD55B43880912497126620"; private static final String SERVER_SM2_PUBLIC_KEY = "04F8BA2A9DFDE5977DFDE3C87A3D0298809FF3396BD908B01DE7057EE4951CF4F193EB0841DA05D7612D13A13E23C0ACB8A00902C0D409236A92C4EF3AA2C72823"; /** * 接口1：获取后端SM2公钥 * 前端调用此接口获取公钥，用于加密它生成的SM4会话密钥。 */ @Operation(summary = "获取服务器SM2公钥") @GetMapping("/publicKey") public Map<String, String> getServerPublicKey() { Map<String, String> result = new HashMap<>(); result.put("publicKey", SERVER_SM2_PUBLIC_KEY); // 也可以告知前端使用的加密模式，避免混淆 result.put("encryptMode", "C1C3C2"); return result; } @Data public static class EncryptedRequest { // 前端用SM2公钥加密后的SM4密钥（16进制字符串） private String encryptedSm4Key; // 前端用上述SM4密钥加密后的业务数据（Base64字符串） private String encryptedData; // 可选的：SM4加密使用的IV（如果是CBC模式，需要传递） private String iv; } /** * 接口2：接收前端加密数据并解密处理 * 这是核心接口，处理混合加密逻辑。 */ @Operation(summary = "提交加密数据") @PostMapping("/submit") public Map<String, Object> submitEncryptedData(@RequestBody EncryptedRequest request) { Map<String, Object> response = new HashMap<>(); try { // 步骤1：后端使用SM2私钥解密，得到SM4会话密钥明文 String sm4KeyPlain = decryptSm2Key(request.getEncryptedSm4Key()); response.put("decryptedSm4Key", sm4KeyPlain); // 调试用，生产环境不应返回 // 步骤2：使用解密得到的SM4密钥，解密业务数据 // 这里假设前端使用CBC模式，并传递了IV。如果是ECB，则不需要IV。 String iv = request.getIv() != null ? request.getIv() : "1234567890123456"; // 默认IV，应与前端约定 String businessDataPlain = decryptSm4Data(sm4KeyPlain, iv, request.getEncryptedData()); response.put("status", "success"); response.put("decryptedData", businessDataPlain); // 这里可以处理businessDataPlain，例如反序列化为JSON对象，进行业务逻辑处理... response.put("message", "数据接收并解密成功"); } catch (Exception e) { response.put("status", "error"); response.put("message", "解密失败: " + e.getMessage()); } return response; } /** * 使用SM2私钥解密被加密的SM4密钥 */ private String decryptSm2Key(String encryptedKeyHex) { // 处理可能的04前缀问题 String cipherText = encryptedKeyHex.startsWith("04") ? encryptedKeyHex : "04" + encryptedKeyHex; SM2 sm2 = SmUtil.sm2(SERVER_SM2_PRIVATE_KEY, null); sm2.setMode(SM2Engine.Mode.C1C3C2); // 解密后得到的是SM4密钥的明文（字符串形式） return sm2.decryptStr(cipherText, KeyType.PrivateKey); } /** * 使用SM4密钥和IV解密业务数据 */ private String decryptSm4Data(String sm4Key, String iv, String encryptedDataBase64) { // 确保密钥和IV长度 byte[] keyBytes = sm4Key.getBytes(StandardCharsets.UTF_8); if (keyBytes.length != 16) { // 更健壮的做法：如果密钥不是16字节，进行密钥派生或报错 throw new IllegalArgumentException("Invalid SM4 key length."); } byte[] ivBytes = iv.getBytes(StandardCharsets.UTF_8); SM4 sm4 = SmUtil.sm4(keyBytes); sm4.setMode(SM4.Mode.CBC); sm4.setIv(ivBytes); // decryptStr 默认处理Base64输入 return sm4.decryptStr(encryptedDataBase64); } /** * 接口3：模拟生成一个随机的SM4密钥（仅供前端演示用） * 实际应由前端在每次会话时动态生成。 */ @Operation(summary = "生成随机SM4密钥（示例）") @GetMapping("/demo/sm4Key") public Map<String, String> generateDemoSm4Key() { // 生成一个16字节的随机字符串作为SM4密钥 String randomKey = UUID.randomUUID().toString().replace("-", "").substring(0, 16); Map<String, String> result = new HashMap<>(); result.put("sm4Key", randomKey); result.put("iv", "1234567890123456"); // 示例IV，应与前端约定生成规则 return result; } }

6.2 前端配合要点（Vue示例）

为了让整个流程更清晰，这里给出前端（以Vue +sm-crypto+gm-crypt为例）的关键步骤伪代码：

1. 初始化：调用后端/api/secure/publicKey接口，获取服务器SM2公钥。
2. 生成会话密钥：在浏览器端，使用crypto.getRandomValues或库函数生成一个16字节的随机数作为本次会话的SM4密钥 (sm4SessionKey)。
3. 加密SM4密钥：使用sm-crypto库的sm2.doEncrypt(sm4SessionKey, serverPublicKey)，得到encryptedSm4Key。
4. 加密业务数据：使用gm-crypt库，用sm4SessionKey和约定的IV（如全零或随机生成并传递）对业务JSON字符串进行CBC模式加密，得到encryptedData。
5. 发送请求：将{ encryptedSm4Key, encryptedData, iv }作为请求体，发送给后端的/api/secure/submit。

这样，即使网络请求被截获，攻击者没有服务器的SM2私钥，就无法解密encryptedSm4Key，从而也无法解密真正的业务数据encryptedData。

7. 常见问题排查与性能优化

集成过程中，你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格，方便你快速排查。

问题现象	可能原因	排查步骤与解决方案
SM2解密失败，报错：Invalid point coordinates或Invalid ciphertext	1. 密文格式不匹配（缺少或多余04前缀）。 2. 加密/解密模式（C1C2C3/C1C3C2）前后端不统一。 3. 公钥私钥不配对。	1.统一格式：前后端约定好密文是否带04。可在后端加判断逻辑自动补全。 2.统一模式：在代码中显式设置sm2.setMode(SM2Engine.Mode.C1C3C2)，并确保前端库使用相同模式。 3.验证密钥对：编写一个测试用例，用一对密钥加密后立即解密，验证基础功能是否正常。
SM4解密失败，报错：Given final block not properly padded	1. 密钥（Key）或初始化向量（IV）前后端不一致。 2. 加密模式（ECB/CBC）不匹配。 3. 填充模式（Padding）不匹配。 4. 密文在传输过程中编码出错（如Base64解码失败）。	1.检查密钥和IV：确保前端用于加密的密钥和IV与后端解密时使用的完全一致（字节对字节）。打印日志对比。 2.检查模式：确认两端都使用CBC（推荐）或ECB。 3.检查填充：Hutool默认PKCS7Padding，前端库需配置相同填充。 4.检查编码：确保密文以Base64传输，且解码正确。可先用一个固定明文测试。
SM3摘要结果与在线工具或前端不一致	1. 数据编码不一致（如UTF-8 vs GBK）。 2. 处理的是字符串还是字节数组（换行符、BOM头影响）。 3. 在线工具可能计算的是文件的摘要，而你计算的是文件内容的字符串摘要。	1.统一编码：在计算摘要前，明确指定字符串的编码，如data.getBytes(StandardCharsets.UTF_8)。 2.处理原始字节：对于文件，尽量使用digestHex(InputStream)直接处理流，避免引入字符串转换的歧义。 3.区分数据源：明确你计算的是“字符串”的摘要还是“文件二进制流”的摘要。
性能问题，加密大量数据时慢	1. 错误地使用SM2加密大量数据。 2. 频繁创建加密对象（如SM2、SM4实例）。	1.使用混合加密：绝对不要用SM2直接加密超过几十KB的数据。务必采用SM2加密SM4密钥，SM4加密业务数据的模式。 2.对象复用：对于使用相同密钥的SM4加密器，可以创建单例复用，避免重复初始化开销。SM2对象如果公钥私钥固定，也可以复用。
内存溢出（OOM）处理大文件	一次性将整个文件读入内存进行加密或摘要。	使用流式处理：Hutool的SmUtil.sm3().digestHex(InputStream)和SmUtil.sm4().encrypt(InputStream, OutputStream)支持流式操作。对于大文件，务必采用流式读写，分块处理。

性能优化建议：

• 密钥缓存：对于频繁使用的固定密钥（如服务器SM2密钥对），将其对应的SM2或SM4对象缓存起来，避免每次加解密都重新解析密钥字符串。
• 连接池与异步：在高并发场景下，加解密是CPU密集型操作。考虑使用异步处理或增加应用实例，避免阻塞业务线程。对于REST API，确保你的Web服务器（如Tomcat）有足够的线程池大小。
• 硬件加速：在极端性能要求的场景下，可以调研是否支持国密算法的硬件加密卡或CPU指令集加速。

8. 项目结构规划与安全建议

一个健壮的、集成了国密算法的Spring Boot项目，代码结构应该清晰，安全措施要到位。

推荐的包结构：

src/main/java/com/yourcompany/ ├── config/ │ └── CryptoConfig.java // 密码学相关Bean配置（如注册BC Provider） ├── constant/ │ └── CryptoConstant.java // 定义常量，如加密模式、密钥长度 ├── service/ │ ├── Sm2Service.java // SM2相关业务逻辑 │ ├── Sm3Service.java // SM3相关业务逻辑 │ └── Sm4Service.java // SM4相关业务逻辑 ├── controller/ │ ├── KeyExchangeController.java // 密钥交换、获取公钥等接口 │ └── DataSecureController.java // 数据加密提交、解密处理接口 ├── utils/ │ └── CryptoUtil.java // 加密解密工具类，封装底层调用 └── exception/ └── CryptoException.java // 自定义加密相关异常

至关重要的安全建议：

1. 私钥永不落地（理想情况）：服务器的SM2私钥是最高机密。不应放在代码、配置文件甚至普通的数据库里。应使用**硬件安全模块（HSM）或云厂商的密钥管理服务（KMS）**来存储和进行解密/签名操作。代码中只保留一个密钥标识符或访问凭证。
2. 密钥轮转：定期更换SM2密钥对和SM4的会话密钥。为密钥设置版本号，实现平滑过渡。
3. 防御重放攻击：在加密数据包中加入时间戳和随机数（Nonce），并在服务端校验，防止请求被恶意重复发送。
4. 完整的审计日志：记录关键操作，如密钥生成、解密失败、签名验证失败等，但不记录明文密钥或敏感数据。
5. 依赖安全：定期更新Bouncy Castle和Hutool到安全版本，避免使用存在已知漏洞的旧版本。

国密算法的集成，技术实现只是第一步，将其融入一套安全、可维护的工程实践和架构设计中，才是真正发挥其价值的开始。希望这篇从实战出发的长文，能帮你扫清集成路上的障碍。如果在实际操作中遇到新的问题，不妨从编码、格式、模式匹配这几个最常见的方向先做排查，祝你好运。