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通常基于以下几点考量合规性与政策要求这是最直接的原因。在金融、政务、能源等关键领域国家密码管理局明确推荐或要求使用国密算法。使用SM4是项目过审、满足监管要求的必要条件。自主可控在底层核心技术领域使用自主设计的算法有助于构建更安全、可控的技术体系减少对国外技术的依赖。算法效率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-modelusername placeholder用户名 / input v-modelpassword typepassword placeholder密码 / button clickhandleLogin登录/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前端实操心得密钥管理是命门再次强调前端代码里不要出现真实的、固定的密钥。理想的方式是在用户登录时后端根据会话生成一个临时密钥或密钥对下发给前端前端用这个临时密钥加密本次会话的数据。这样即使一次会话的密钥泄露也不会影响其他用户或其他会话。统一编码格式确保加密后的输出格式如hex或base64与后端约定一致。我们这里用了hex后端解密时也要按hex处理。非对称加密混合使用对于密钥本身的分发可以考虑使用SM2国密非对称算法进行加密。即后端用SM2公钥加密SM4的对称密钥前端用SM2私钥妥善保管解密得到SM4密钥再用它加密数据。这构成了一个更安全的混合加密体系适合更高安全要求的场景。4. 后端Java实现基于Bouncy Castle的SM4解密Java标准库JCE在早期版本中并不直接支持国密算法。因此我们需要引入一个强大的密码学提供者——Bouncy Castle。它是一个开源的密码学库提供了大量标准库未包含的算法实现包括完整的国密算法套件SM2, SM3, SM4。4.1 项目依赖引入如果你使用Maven在pom.xml中添加以下依赖dependency groupIdorg.bouncycastle/groupId artifactIdbcprov-jdk15to18/artifactId version1.74/version !-- 请使用最新稳定版本 -- /dependency如果使用Gradleimplementation org.bouncycastle:bcprov-jdk15to18:1.744.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(i1), 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 ... } }后端实操心得提供者注册确保Bouncy Castle提供者被正确注册。Security.addProvider(new BouncyCastleProvider())这行代码只需执行一次放在工具类的静态块中是个好选择。算法字符串必须完全匹配Cipher.getInstance(SM4/CBC/PKCS5Padding, BC)这里的算法字符串、模式和填充必须与前端设置完全一致。BC代表使用Bouncy Castle提供者。异常处理要谨慎加解密过程可能抛出多种异常BadPaddingException,IllegalBlockSizeException等。在生产代码中不要将详细的异常信息直接返回给前端以免泄露系统信息。应该记录到日志并返回统一的、模糊的错误响应。密钥管理升级生产环境中绝对不应该像示例中那样硬编码密钥。应该将密钥存储在环境变量、专用的密钥管理系统或硬件安全模块中。对于分布式系统确保所有实例使用的密钥一致。5. 前后端联调与核心参数对齐清单这是整个方案中最容易出错的环节。前后端任何一个小参数对不上都会导致解密失败。我强烈建议将以下清单作为联调Checklist。参数项前端 (sm-crypto)后端 (Java Bouncy Castle)必须保持一致算法SM4SM4✅工作模式cbcCBC✅填充方式pkcs#5或pkcs#7PKCS5Padding✅ (两者在16字节块下等价)密钥长度16字节 (128位)16字节 (128位)✅IV长度16字节16字节✅密钥格式十六进制字符串 (32字符)十六进制字符串 (32字符)✅ (内容相同)IV格式十六进制字符串 (32字符)十六进制字符串 (32字符)✅ (内容相同)加密输入UTF-8 字符串UTF-8 字节数组✅ (隐式一致)加密输出格式hex(十六进制字符串)hex(十六进制字符串)✅字符编码UTF-8UTF-8 (StandardCharsets.UTF_8)✅联调步骤建议固定测试向量双方先使用一组已知的、标准的测试数据明文、密钥、IV进行加密比对密文是否一致。可以从国密算法的官方测试向量中选取。后端加密前端解密先让后端用工具类加密一段已知明文将密文、密钥、IV给前端让前端解密看是否能得到原文。这可以验证前端解密逻辑和参数是否正确。前端加密后端解密再让前端用同样的密钥和IV加密一段明文将密文发送给后端解密验证后端解密逻辑。端到端测试最后进行完整的API调用测试。6. 常见问题排查与进阶优化在实际部署中你可能会遇到以下问题6.1 解密失败BadPaddingException: pad block corrupted这是最常见的问题几乎可以断定是前后端参数不一致导致的。排查步骤检查密钥和IV确认双方使用的密钥和IV的十六进制字符串完全一致包括大小写建议统一使用小写。一个字符都不能差。检查模式确认都是CBC模式。ECB模式不需要IV如果后端配了CBC而前端用了ECB或者反之必然失败。检查填充确认填充方案。pkcs#5和pkcs#7在16字节块下通常可以互换但最好明确约定为一种。如果前端是pkcs#5后端是NoPadding那肯定会出错。检查数据格式前端发送的密文是否是纯十六进制字符串有没有被URL编码、Base64编码“二次处理”后端接收时是否做了不必要的解码用日志打印出前端发送的原始密文和后端接收到的密文进行比对。检查编码明文在加密前是否都统一用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 安全性增强建议动态密钥交换不要长期使用固定的静态密钥。可以采用“一次一密”或“一次会话一密”的方式。例如在用户登录时后端生成一个随机的SM4会话密钥用SM2公钥加密后下发给前端。前端用SM2私钥解密出SM4会话密钥用于本次会话的通信加密。完整性校验SM4只提供机密性不提供完整性。为了防止密文在传输中被篡改可以考虑结合国密SM3哈希算法。例如将“明文密钥”计算SM3摘要将摘要和密文一起传输后端解密后重新计算摘要进行比对。HTTPS是基础SM4加密是在应用层增加的安全保障但它不能替代HTTPSTLS。HTTPS提供了传输层的加密、身份认证和完整性保护。务必在已经启用HTTPS的基础上再实施应用层的SM4加密形成双重保障。6.4 关于其他国密算法国密算法是一个体系除了SM4对称加密还有SM2基于椭圆曲线的非对称加密算法相当于RSA/ECC。用于数字签名和密钥交换。SM3密码杂凑算法相当于SHA-256。用于生成消息摘要。SM9基于标识的密码算法。在实际项目中可以根据安全需求组合使用。例如用SM2进行密钥交换和签名用SM4加密业务数据用SM3校验数据完整性。整个方案跑通后给我的感觉是国密算法的集成并没有想象中那么困难。核心难点不在于算法本身而在于前后端开发者在细节上保持高度一致以及对密钥生命周期的安全管理。把这两点做到位这套统一加密方案就能为你的应用数据安全提供一个坚实的合规基础。