Vue与Java前后端国密SM4加解密统一方案实践

1. 项目概述：为什么我们需要前后端统一的国密加密方案？

最近在做一个对数据安全要求比较高的项目，甲方明确要求核心数据传输必须使用国密算法。这让我不得不把之前项目中常用的AES、DES这些国际通用算法先放一放，转而研究起国密SM4。说实话，一开始觉得挺麻烦的，毕竟SM4的资料和现成的轮子远没有AES那么丰富。但真正做下来发现，只要前后端方案统一，SM4用起来其实挺顺手的。

这个方案的核心目标很简单：在Vue前端和Java后端之间，建立一套统一的、基于国密SM4算法的数据加解密流程。无论是用户密码、身份证号、交易金额还是其他敏感信息，在离开前端时就被加密，到达后端后再解密处理，全程密文传输。这不仅仅是满足合规要求，更是对用户数据安全负责。我见过不少项目，前端用CryptoJS的AES，后端用Java的Cipher，结果因为模式、填充、编码不一致，调试加解密能花掉一两天。所以，统一方案从一开始就至关重要。

2. 国密SM4算法核心原理与选型考量

2.1 SM4算法到底是什么？

SM4是一种分组对称加密算法，你可以把它理解为中国版的AES。所谓“对称”，就是加密和解密用的是同一把钥匙（密钥）。它的设计非常规整：无论是密钥长度还是每次加密的数据块大小，都是128位（也就是16个字节）。这意味着，如果你有一段更长的文本，算法会把它切成一个个16字节的“块”，然后逐个加密。

和AES有ECB、CBC等多种工作模式一样，SM4也有几种模式。在实际的网络传输场景中，ECB模式是绝对要避免的。因为它对相同的明文块总会产生相同的密文块，安全性很差。我们通常会选择CBC模式。CBC的全称是“密码分组链接”，它引入了一个叫“初始化向量”的东西。你可以把IV想象成第一块数据的“盐”，它让即使完全相同的明文，在每次加密时也会因为IV不同而产生完全不同的密文，安全性大大提升。

2.2 为什么选择SM4而不是AES？

这可能是很多开发者的第一个疑问。从纯技术角度看，AES-128同样也是128位密钥，安全性经过全球多年验证，生态极其完善。选择SM4，通常基于以下几点考量：

1. 合规性与政策要求：这是最直接的原因。在金融、政务、能源等关键领域，国家密码管理局明确推荐或要求使用国密算法。使用SM4是项目过审、满足监管要求的必要条件。
2. 自主可控：在底层核心技术领域，使用自主设计的算法有助于构建更安全、可控的技术体系，减少对国外技术的依赖。
3. 算法效率：SM4在设计上考虑了软硬件实现的效率，在通用处理器上的表现与AES相当，某些实现甚至略有优势。

对于我们开发者而言，无论选择哪种，前后端使用完全相同的算法、模式、填充和编码方式，是项目成功的第一前提。这次我们聚焦SM4，把这条技术链路彻底跑通。

3. 前端Vue实现：基于sm-crypto的加密实践

前端加密有一个基本原则：不要在网页中处理真正的密钥。在前端代码里硬编码密钥，无异于把家门钥匙挂在门上。我们的做法是，前端只负责加密操作，而加密所需的密钥（Key）和初始化向量（IV）应该通过安全的、非明文的方式从后端获取，例如在用户登录后通过HTTPS接口动态下发，或者由后端集成到某个安全模块的配置中。为了演示核心流程，我们假设密钥和IV已经通过安全途径获得了。

3.1 工具库选型：为什么是sm-crypto？

前端实现国密算法，主要有两种路径：一是寻找纯JavaScript实现的库，二是使用WebAssembly编译的C库。sm-crypto是一个纯JS实现的国密算法库，支持SM2、SM3和SM4。我选择它主要基于以下几点：

• 纯JS实现，零依赖：无需编译，直接通过npm安装引入，对Vue、React等现代框架集成非常友好。
• API简洁明了：它的加密解密接口设计得很直观，几乎一看就会。
• 社区活跃度相对较高：在国密前端库中，它的Star数和Issue处理速度算是比较好的。

当然，如果对性能有极致要求，可以考虑寻找Wasm版本，但sm-crypto对于绝大多数Web应用场景已经绰绰有余。

3.2 在Vue项目中集成与基础加密

首先，在你的Vue项目中安装它：

npm install sm-crypto --save

然后，我们创建一个独立的工具文件，比如src/utils/sm4Utils.js，将加密解密逻辑封装起来。

// src/utils/sm4Utils.js import { sm4 } from 'sm-crypto'; // 注意：这里的key和iv必须是16字节的十六进制字符串。 // 在实际项目中，它们应从后端安全接口获取，而非硬编码。 // 示例：'0123456789abcdeffedcba9876543210' const defaultKey = '你的16字节Hex密钥'; // 32个十六进制字符 const defaultIv = '你的16字节Hex初始向量'; // 32个十六进制字符，CBC模式需要 /** * SM4加密 (CBC模式) * @param {string} plaintext - 待加密的明文 * @param {string} key - 16字节十六进制密钥（可选，不传则使用默认） * @param {string} iv - 16字节十六进制初始向量（可选，不传则使用默认） * @returns {string} 加密后的十六进制字符串 */ export function encryptSM4(plaintext, key = defaultKey, iv = defaultIv) { // sm-crypto的sm4.encrypt方法默认就是CBC模式 // 参数顺序：明文，密钥，填充方式，输出格式，IV // 这里我们选择pkcs#5/pkcs#7填充（参数为1），输出hex字符串 const cipherText = sm4.encrypt(plaintext, key, { mode: 'cbc', // 指定CBC模式 iv: iv, // 指定初始化向量 padding: 'pkcs#5', // 或 'pkcs#7'，两者在块加密中通常等价 output: 'hex' // 输出格式为十六进制字符串 }); return cipherText; } /** * SM4解密 (CBC模式) * @param {string} ciphertextHex - 待解密的十六进制密文 * @param {string} key - 16字节十六进制密钥（可选） * @param {string} iv - 16字节十六进制初始向量（可选） * @returns {string} 解密后的明文 */ export function decryptSM4(ciphertextHex, key = defaultKey, iv = defaultIv) { const plainText = sm4.decrypt(ciphertextHex, key, { mode: 'cbc', iv: iv, padding: 'pkcs#5', output: 'string' // 解密输出为普通字符串 }); return plainText; }

关键提示：sm-crypto的encrypt和decrypt方法在参数处理上比较灵活。上述写法使用了配置对象，清晰指定了所有参数，这是最稳妥的方式。早期版本或某些文档可能使用位置参数，容易出错，建议以当前库的官方文档为准。

3.3 在Vue组件中调用加密

封装好工具函数后，在组件中的使用就非常简单了。例如，在提交登录表单时：

<template> <div> <input v-model="username" placeholder="用户名" /> <input v-model="password" type="password" placeholder="密码" /> <button @click="handleLogin">登录</button> </div> </template> <script> import { encryptSM4 } from '@/utils/sm4Utils'; import axios from 'axios'; export default { data() { return { username: '', password: '' }; }, methods: { async handleLogin() { // 1. 对敏感字段进行加密 const encryptedPassword = encryptSM4(this.password); // 用户名如果也是敏感信息，也可以加密 // const encryptedUsername = encryptSM4(this.username); // 2. 构造请求数据 const loginData = { username: this.username, // 或 encryptedUsername password: encryptedPassword // 注意：后端拿到的是密文 }; // 3. 发送请求 try { const response = await axios.post('/api/login', loginData); // ... 处理响应 } catch (error) { // ... 处理错误 } } } }; </script>

前端实操心得：

1. 密钥管理是命门：再次强调，前端代码里不要出现真实的、固定的密钥。理想的方式是，在用户登录时，后端根据会话生成一个临时密钥（或密钥对）下发给前端，前端用这个临时密钥加密本次会话的数据。这样即使一次会话的密钥泄露，也不会影响其他用户或其他会话。
2. 统一编码格式：确保加密后的输出格式（如hex或base64）与后端约定一致。我们这里用了hex，后端解密时也要按hex处理。
3. 非对称加密混合使用：对于密钥本身的分发，可以考虑使用SM2（国密非对称算法）进行加密。即后端用SM2公钥加密SM4的对称密钥，前端用SM2私钥（妥善保管）解密得到SM4密钥，再用它加密数据。这构成了一个更安全的混合加密体系，适合更高安全要求的场景。

4. 后端Java实现：基于Bouncy Castle的SM4解密

Java标准库（JCE）在早期版本中并不直接支持国密算法。因此，我们需要引入一个强大的密码学提供者——Bouncy Castle。它是一个开源的密码学库，提供了大量标准库未包含的算法实现，包括完整的国密算法套件（SM2, SM3, SM4）。

4.1 项目依赖引入

如果你使用Maven，在pom.xml中添加以下依赖：

<dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15to18</artifactId> <version>1.74</version> <!-- 请使用最新稳定版本 --> </dependency>

如果使用Gradle：

implementation 'org.bouncycastle:bcprov-jdk15to18:1.74'

4.2 核心工具类封装

我们创建一个SM4Util工具类，封装加解密逻辑。这里的关键是正确配置Cipher实例，使其参数与前端的sm-crypto完全匹配。

import org.bouncycastle.jce.provider.BouncyCastleProvider; import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.Security; import java.util.HexFormat; public class SM4Util { // 算法名称：SM4 // 模式：CBC // 填充：PKCS5Padding (在16字节块加密中，PKCS5Padding和PKCS7Padding是等同的) private static final String ALGORITHM_NAME = "SM4"; private static final String ALGORITHM_NAME_CBC_PADDING = "SM4/CBC/PKCS5Padding"; // 密钥和IV的长度（字节） private static final int KEY_LENGTH = 16; private static final int IV_LENGTH = 16; static { // 在类加载时，将Bouncy Castle注册为安全提供者 Security.addProvider(new BouncyCastleProvider()); } /** * SM4加密 (CBC模式) * @param plaintext 明文 * @param keyHex 16字节密钥的十六进制字符串（32字符） * @param ivHex 16字节IV的十六进制字符串（32字符） * @return 加密后的十六进制字符串 */ public static String encrypt(String plaintext, String keyHex, String ivHex) throws Exception { // 1. 参数校验 validateHexParameter(keyHex, KEY_LENGTH, "Key"); validateHexParameter(ivHex, IV_LENGTH, "IV"); // 2. 将十六进制字符串转换为字节数组 byte[] keyBytes = hexStringToByteArray(keyHex); byte[] ivBytes = hexStringToByteArray(ivHex); byte[] plaintextBytes = plaintext.getBytes(StandardCharsets.UTF_8); // 3. 创建密钥和IV规范 SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, ALGORITHM_NAME); IvParameterSpec ivParameterSpec = new IvParameterSpec(ivBytes); // 4. 初始化Cipher为加密模式 Cipher cipher = Cipher.getInstance(ALGORITHM_NAME_CBC_PADDING, "BC"); // 指定BC提供者 cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivParameterSpec); // 5. 执行加密 byte[] encryptedBytes = cipher.doFinal(plaintextBytes); // 6. 将加密结果转换为十六进制字符串返回 return byteArrayToHexString(encryptedBytes); } /** * SM4解密 (CBC模式) * @param ciphertextHex 密文的十六进制字符串 * @param keyHex 16字节密钥的十六进制字符串（32字符） * @param ivHex 16字节IV的十六进制字符串（32字符） * @return 解密后的明文 */ public static String decrypt(String ciphertextHex, String keyHex, String ivHex) throws Exception { // 1. 参数校验 validateHexParameter(keyHex, KEY_LENGTH, "Key"); validateHexParameter(ivHex, IV_LENGTH, "IV"); // 2. 将十六进制字符串转换为字节数组 byte[] keyBytes = hexStringToByteArray(keyHex); byte[] ivBytes = hexStringToByteArray(ivHex); byte[] ciphertextBytes = hexStringToByteArray(ciphertextHex); // 3. 创建密钥和IV规范 SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, ALGORITHM_NAME); IvParameterSpec ivParameterSpec = new IvParameterSpec(ivBytes); // 4. 初始化Cipher为解密模式 Cipher cipher = Cipher.getInstance(ALGORITHM_NAME_CBC_PADDING, "BC"); cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, ivParameterSpec); // 5. 执行解密 byte[] decryptedBytes = cipher.doFinal(ciphertextBytes); // 6. 将解密结果转换为字符串返回 return new String(decryptedBytes, StandardCharsets.UTF_8); } // --- 以下为辅助方法 --- private static void validateHexParameter(String hexStr, int expectedBytes, String paramName) { if (hexStr == null || hexStr.isEmpty()) { throw new IllegalArgumentException(paramName + " cannot be null or empty"); } // 每个字节对应两个十六进制字符 int expectedHexLength = expectedBytes * 2; if (hexStr.length() != expectedHexLength) { throw new IllegalArgumentException(paramName + " must be " + expectedHexLength + " hex characters long"); } // 简单校验是否为合法十六进制字符串（可选，更严格时可使用正则） if (!hexStr.matches("[0-9a-fA-F]+")) { throw new IllegalArgumentException(paramName + " must be a valid hex string"); } } private static byte[] hexStringToByteArray(String hexString) { // Java 17+ 可以使用 HexFormat HexFormat hexFormat = HexFormat.of(); return hexFormat.parseHex(hexString); // 对于更早的版本，可以使用： // int len = hexString.length(); // byte[] data = new byte[len / 2]; // for (int i = 0; i < len; i += 2) { // data[i / 2] = (byte) ((Character.digit(hexString.charAt(i), 16) << 4) // + Character.digit(hexString.charAt(i+1), 16)); // } // return data; } private static String byteArrayToHexString(byte[] bytes) { HexFormat hexFormat = HexFormat.of(); return hexFormat.formatHex(bytes); // 旧版本替代方案： // StringBuilder sb = new StringBuilder(bytes.length * 2); // for (byte b : bytes) { // sb.append(String.format("%02x", b)); // } // return sb.toString(); } }

4.3 在Spring Boot控制器中使用

在Controller中，接收前端加密后的密文，调用工具类进行解密。

import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api") public class LoginController { // 这里为了演示，将密钥和IV硬编码。生产环境必须从安全的配置中心（如Apollo, Nacos）或环境变量中读取。 private static final String SM4_KEY_HEX = "0123456789abcdeffedcba9876543210"; private static final String SM4_IV_HEX = "1234567890abcdef1234567890abcdef"; @PostMapping("/login") public ResponseEntity<?> login(@RequestBody LoginRequest request) { try { // 1. 解密前端传来的密码密文 String decryptedPassword = SM4Util.decrypt(request.getPassword(), SM4_KEY_HEX, SM4_IV_HEX); // 2. 此时decryptedPassword已经是明文，可以进行后续的业务逻辑验证 // 例如：验证用户名和密码是否匹配数据库中的记录 boolean isValid = userService.validateUser(request.getUsername(), decryptedPassword); if (isValid) { // 生成Token，返回成功信息等... return ResponseEntity.ok("登录成功"); } else { return ResponseEntity.status(401).body("用户名或密码错误"); } } catch (Exception e) { // 解密失败（可能是密文格式错误、密钥不对等） // 记录日志，但返回模糊的错误信息，避免信息泄露 log.error("登录请求处理失败，解密异常", e); return ResponseEntity.status(400).body("请求参数错误"); } } // 简单的请求体封装 static class LoginRequest { private String username; private String password; // 注意：这里接收的是前端加密后的十六进制字符串 // getters and setters ... } }

后端实操心得：

1. 提供者注册：确保Bouncy Castle提供者被正确注册。Security.addProvider(new BouncyCastleProvider())这行代码只需执行一次，放在工具类的静态块中是个好选择。
2. 算法字符串必须完全匹配：Cipher.getInstance("SM4/CBC/PKCS5Padding", "BC")这里的算法字符串、模式和填充必须与前端设置完全一致。"BC"代表使用Bouncy Castle提供者。
3. 异常处理要谨慎：加解密过程可能抛出多种异常（BadPaddingException,IllegalBlockSizeException等）。在生产代码中，不要将详细的异常信息直接返回给前端，以免泄露系统信息。应该记录到日志，并返回统一的、模糊的错误响应。
4. 密钥管理升级：生产环境中，绝对不应该像示例中那样硬编码密钥。应该将密钥存储在环境变量、专用的密钥管理系统或硬件安全模块中。对于分布式系统，确保所有实例使用的密钥一致。

5. 前后端联调与核心参数对齐清单

这是整个方案中最容易出错的环节。前后端任何一个小参数对不上，都会导致解密失败。我强烈建议将以下清单作为联调Checklist。

联调步骤建议：

1. 固定测试向量：双方先使用一组已知的、标准的测试数据（明文、密钥、IV）进行加密，比对密文是否一致。可以从国密算法的官方测试向量中选取。
2. 后端加密，前端解密：先让后端用工具类加密一段已知明文，将密文、密钥、IV给前端，让前端解密看是否能得到原文。这可以验证前端解密逻辑和参数是否正确。
3. 前端加密，后端解密：再让前端用同样的密钥和IV加密一段明文，将密文发送给后端解密，验证后端解密逻辑。
4. 端到端测试：最后进行完整的API调用测试。

6. 常见问题排查与进阶优化

在实际部署中，你可能会遇到以下问题：

6.1 解密失败：BadPaddingException: pad block corrupted

这是最常见的问题，几乎可以断定是前后端参数不一致导致的。

• 排查步骤：
  1. 检查密钥和IV：确认双方使用的密钥和IV的十六进制字符串完全一致，包括大小写（建议统一使用小写）。一个字符都不能差。
  2. 检查模式：确认都是CBC模式。ECB模式不需要IV，如果后端配了CBC而前端用了ECB，或者反之，必然失败。
  3. 检查填充：确认填充方案。pkcs#5和pkcs#7在16字节块下通常可以互换，但最好明确约定为一种。如果前端是pkcs#5，后端是NoPadding，那肯定会出错。
  4. 检查数据格式：前端发送的密文是否是纯十六进制字符串？有没有被URL编码、Base64编码“二次处理”？后端接收时是否做了不必要的解码？用日志打印出前端发送的原始密文和后端接收到的密文，进行比对。
  5. 检查编码：明文在加密前，是否都统一用UTF-8编码？中文等非ASCII字符尤其要注意。

6.2 性能考虑与优化

• 密钥/IV的生成与存储：密钥和IV必须是强随机数。在Java后端，应使用SecureRandom生成。

  import java.security.SecureRandom; // 生成16字节随机密钥 byte[] key = new byte[16]; new SecureRandom().nextBytes(key); String keyHex = byteArrayToHexString(key); // 生成16字节随机IV byte[] iv = new byte[16]; new SecureRandom().nextBytes(iv); String ivHex = byteArrayToHexString(iv);

• Cipher实例复用：Cipher对象的初始化（init）开销较大。在高并发场景下，可以考虑使用ThreadLocal缓存已初始化的Cipher实例，但要注意线程安全。
• 考虑使用GMSSL：如果服务端是Linux环境，可以考虑使用GMSSL（支持国密的OpenSSL分支）通过JNI调用，性能通常优于纯Java实现，但部署复杂度会增加。

6.3 安全性增强建议

1. 动态密钥交换：不要长期使用固定的静态密钥。可以采用“一次一密”或“一次会话一密”的方式。例如，在用户登录时，后端生成一个随机的SM4会话密钥，用SM2公钥加密后下发给前端。前端用SM2私钥解密出SM4会话密钥，用于本次会话的通信加密。
2. 完整性校验：SM4只提供机密性，不提供完整性。为了防止密文在传输中被篡改，可以考虑结合国密SM3哈希算法。例如，将“明文+密钥”计算SM3摘要，将摘要和密文一起传输，后端解密后重新计算摘要进行比对。
3. HTTPS是基础：SM4加密是在应用层增加的安全保障，但它不能替代HTTPS（TLS）。HTTPS提供了传输层的加密、身份认证和完整性保护。务必在已经启用HTTPS的基础上，再实施应用层的SM4加密，形成双重保障。

6.4 关于其他国密算法

国密算法是一个体系，除了SM4（对称加密），还有：

• SM2：基于椭圆曲线的非对称加密算法，相当于RSA/ECC。用于数字签名和密钥交换。
• SM3：密码杂凑算法，相当于SHA-256。用于生成消息摘要。
• SM9：基于标识的密码算法。

在实际项目中，可以根据安全需求组合使用。例如，用SM2进行密钥交换和签名，用SM4加密业务数据，用SM3校验数据完整性。

整个方案跑通后，给我的感觉是，国密算法的集成并没有想象中那么困难。核心难点不在于算法本身，而在于前后端开发者在细节上保持高度一致，以及对密钥生命周期的安全管理。把这两点做到位，这套统一加密方案就能为你的应用数据安全提供一个坚实的合规基础。