本文是混合加密前端 SM2 SM4后端 Spring Boot Hutool 解密的完整示例。方案的逻辑是前端随机生成一个SM4 key用SM4加密整个业务 JSON用后端提供的SM2 公钥加密这个 SM4 key后端先用SM2 私钥解出 SM4 key再用SM4解出业务 JSONHutool 官方文档明确支持SM2 / SM3 / SM4并给出了SmUtil.sm2(...)、SmUtil.sm4(...)以及encryptHex / decryptStr这类用法同时文档说明国密算法需要引入 Bouncy Castle 依赖。sm-crypto系列前端库也支持SM2 / SM3 / SM4。(Hutool)方案统一用前端公钥SM2 原始公钥 Hex04 X YSM2 密文HexSM4 密文HexSM4 key16 字节字符串SM2 模式C1C3C2一、前后端协议前端原始数据{ username: admin, password: 123456, timestamp: 1710000000000 }前端最终提交给后端{ key: SM2加密后的SM4密钥(hex), data: SM4加密后的业务JSON(hex) }二、后端 Spring Boot 代码1Maven 依赖dependencies !-- Spring Boot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Hutool -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.29/version /dependency !-- Bouncy CastleHutool 国密依赖 -- dependency groupIdorg.bouncycastle/groupId artifactIdbcpkix-jdk18on/artifactId version1.83/version /dependency /dependenciesHutool 的国密文档明确写了 SM2/SM3/SM4 依赖 Bouncy CastleHutool 加密模块文档也说明其封装入口之一就是SmUtil。(Hutool)2启动类package com.example.demo; import org.bouncycastle.jce.provider.BouncyCastleProvider; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import java.security.Security; SpringBootApplication public class DemoApplication { public static void main(String[] args) { Security.addProvider(new BouncyCastleProvider()); SpringApplication.run(DemoApplication.class, args); } }3密钥工具类这个类负责生成 SM2 密钥对导出前端可用的原始公钥 Hex导出后端解密用的原始私钥 HexSm2KeyUtil.javapackage com.example.demo.crypto; import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.asymmetric.SM2; import org.bouncycastle.jce.interfaces.BCECPrivateKey; import org.bouncycastle.jce.interfaces.BCECPublicKey; import org.bouncycastle.math.ec.ECPoint; public class Sm2KeyUtil { private Sm2KeyUtil() { } public static SM2 generateSm2() { return SmUtil.sm2(); } /** * 前端 sm-crypto 可直接使用的公钥 * 04 X(64位hex) Y(64位hex) */ public static String getPublicKeyHexForFrontend(SM2 sm2) { BCECPublicKey publicKey (BCECPublicKey) sm2.getPublicKey(); ECPoint point publicKey.getQ(); String x leftPad64(point.getAffineXCoord().toBigInteger().toString(16)); String y leftPad64(point.getAffineYCoord().toBigInteger().toString(16)); return 04 x y; } /** * 后端原始私钥 hex64位 */ public static String getPrivateKeyHexRaw(SM2 sm2) { BCECPrivateKey privateKey (BCECPrivateKey) sm2.getPrivateKey(); return leftPad64(privateKey.getD().toString(16)); } /** * 按原始私钥重建 SM2 对象 */ public static SM2 buildSm2ByPrivateKeyHex(String privateKeyHex) { return SmUtil.sm2(privateKeyHex, null); } private static String leftPad64(String hex) { if (hex null) { return null; } if (hex.length() 64) { return hex; } return 0.repeat(64 - hex.length()) hex; } }Hutool 官方文档明确区分了 SM2 密钥的几种格式私钥可为 D 值、PKCS#8、PKCS#1公钥可为 Q 值、X.509、PKCS#1并说明新版本构造方法对这些格式做了兼容。文档还给出了用私钥 D 值和公钥 Q 值构建/验签的示例。(Hutool)4密钥持有类演示用启动时生成。生产环境要固定保存不要每次重启都换。Sm2KeyHolder.javapackage com.example.demo.crypto; import cn.hutool.crypto.asymmetric.SM2; import jakarta.annotation.PostConstruct; import org.springframework.stereotype.Component; Component public class Sm2KeyHolder { private String publicKeyHexForFrontend; private String privateKeyHexRaw; private SM2 sm2; PostConstruct public void init() { this.sm2 Sm2KeyUtil.generateSm2(); this.publicKeyHexForFrontend Sm2KeyUtil.getPublicKeyHexForFrontend(sm2); this.privateKeyHexRaw Sm2KeyUtil.getPrivateKeyHexRaw(sm2); System.out.println( SM2密钥初始化 ); System.out.println(前端公钥Hex: publicKeyHexForFrontend); System.out.println(后端私钥Hex: privateKeyHexRaw); } public String getPublicKeyHexForFrontend() { return publicKeyHexForFrontend; } public String getPrivateKeyHexRaw() { return privateKeyHexRaw; } public SM2 getSm2() { return sm2; } }5请求 DTOEncryptedLoginRequest.javapackage com.example.demo.dto; public class EncryptedLoginRequest { /** * SM2加密后的SM4 keyhex */ private String key; /** * SM4加密后的业务数据hex */ private String data; public String getKey() { return key; } public void setKey(String key) { this.key key; } public String getData() { return data; } public void setData(String data) { this.data data; } }LoginPlainRequest.javapackage com.example.demo.dto; public class LoginPlainRequest { private String username; private String password; private Long timestamp; public String getUsername() { return username; } public void setUsername(String username) { this.username username; } public String getPassword() { return password; } public void setPassword(String password) { this.password password; } public Long getTimestamp() { return timestamp; } public void setTimestamp(Long timestamp) { this.timestamp timestamp; } }6解密服务HybridCryptoService.javapackage com.example.demo.service; import cn.hutool.core.util.StrUtil; import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.asymmetric.KeyType; import cn.hutool.crypto.asymmetric.SM2; import cn.hutool.crypto.symmetric.SM4; import com.example.demo.crypto.Sm2KeyHolder; import com.example.demo.crypto.Sm2KeyUtil; import org.springframework.stereotype.Service; import java.nio.charset.StandardCharsets; Service public class HybridCryptoService { private final Sm2KeyHolder keyHolder; public HybridCryptoService(Sm2KeyHolder keyHolder) { this.keyHolder keyHolder; } /** * 用后端私钥解密前端传来的 SM4 key */ public String decryptSm4Key(String encryptedSm4KeyHex) { SM2 sm2 Sm2KeyUtil.buildSm2ByPrivateKeyHex(keyHolder.getPrivateKeyHexRaw()); byte[] keyBytes sm2.decryptFromBcd(encryptedSm4KeyHex, KeyType.PrivateKey); return StrUtil.utf8Str(keyBytes); } /** * 用 SM4 key 解密业务数据 */ public String decryptBusinessData(String sm4Key, String encryptedDataHex) { SM4 sm4 SmUtil.sm4(sm4Key.getBytes(StandardCharsets.UTF_8)); return sm4.decryptStr(encryptedDataHex, StandardCharsets.UTF_8); } }Hutool 官方文档给出了SmUtil.sm4(key)、encryptHex(...)、decryptStr(...)的 SM4 用法也给出了sm2.decryptFromBcd(..., KeyType.PrivateKey)的 SM2 私钥解密示例。(Hutool)7控制器LoginController.javapackage com.example.demo.controller; import cn.hutool.json.JSONUtil; import com.example.demo.crypto.Sm2KeyHolder; import com.example.demo.dto.EncryptedLoginRequest; import com.example.demo.dto.LoginPlainRequest; import com.example.demo.service.HybridCryptoService; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api) public class LoginController { private final Sm2KeyHolder keyHolder; private final HybridCryptoService hybridCryptoService; public LoginController(Sm2KeyHolder keyHolder, HybridCryptoService hybridCryptoService) { this.keyHolder keyHolder; this.hybridCryptoService hybridCryptoService; } /** * 提供前端可直接使用的 SM2 原始公钥 */ GetMapping(/public-key) public MapString, Object getPublicKey() { MapString, Object result new HashMap(); result.put(code, 0); result.put(publicKey, keyHolder.getPublicKeyHexForFrontend()); return result; } /** * 混合加密登录接口 */ PostMapping(/login) public MapString, Object login(RequestBody EncryptedLoginRequest request) { MapString, Object result new HashMap(); try { // 1. 解密 SM4 key String sm4Key hybridCryptoService.decryptSm4Key(request.getKey()); // 2. 解密业务 JSON String plainJson hybridCryptoService.decryptBusinessData(sm4Key, request.getData()); // 3. 转换为明文请求对象 LoginPlainRequest loginRequest JSONUtil.toBean(plainJson, LoginPlainRequest.class); // 4. 演示校验 if (admin.equals(loginRequest.getUsername()) 123456.equals(loginRequest.getPassword())) { result.put(code, 0); result.put(message, 登录成功); } else { result.put(code, 401); result.put(message, 用户名或密码错误); } // 生产环境不要打印明文 // System.out.println(解密后JSON: plainJson); } catch (Exception e) { result.put(code, 500); result.put(message, 解密失败: e.getMessage()); } return result; } }三、前端代码这里是通用 JSVue / React / 原生都能直接使用。1安装依赖使用sm-crypto也可以用更新一点的sm-crypto-v2。npm 上显示sm-crypto-v2近期仍有更新并明确支持 SM2/SM3/SM4。下面示例先按sm-crypto风格来写。(NPM)npm install sm-crypto2混合加密工具hybrid-login.jsimport { sm2, sm4 } from sm-crypto; /** * 生成 16 字节 SM4 key * 这里用 16 个 ASCII 字符后端按 UTF-8 字节拿到就是 16 字节 */ function randomSm4Key(length 16) { const chars ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789; let result ; for (let i 0; i length; i) { result chars.charAt(Math.floor(Math.random() * chars.length)); } return result; } /** * 获取后端提供的 SM2 公钥原始hex04开头 */ export async function getPublicKey() { const resp await fetch(/api/public-key); const json await resp.json(); return json.publicKey; } /** * 混合加密 * 1. 随机生成 SM4 key * 2. 用 SM4 加密整个业务 JSON * 3. 用 SM2 公钥加密 SM4 key */ export async function encryptLoginPayload(username, password) { const publicKey await getPublicKey(); // 1. 随机 SM4 key const sm4Key randomSm4Key(16); // 2. 原始业务 JSON const payload JSON.stringify({ username, password, timestamp: Date.now(), }); // 3. SM4 加密业务 JSON输出 hex const encryptedData sm4.encrypt(payload, sm4Key); // 4. SM2 加密 SM4 keycipherMode1 表示 C1C3C2 const cipherMode 1; const encryptedKey sm2.doEncrypt(sm4Key, publicKey, cipherMode); return { key: encryptedKey, data: encryptedData, }; } /** * 提交登录 */ export async function login(username, password) { const body await encryptLoginPayload(username, password); const resp await fetch(/api/login, { method: POST, headers: { Content-Type: application/json, }, body: JSON.stringify(body), }); return await resp.json(); }sm-crypto/同类包支持 SM2、SM4Hutool 文档则说明SM4可以使用自定义 key并通过encryptHex/decryptStr处理字符串数据。(NPM)3页面调用示例import { login } from ./hybrid-login; async function submitLogin() { const username document.getElementById(username).value; const password document.getElementById(password).value; const result await login(username, password); console.log(result); }四、完整交互过程1前端获取公钥请求GET /api/public-key响应{ code: 0, publicKey: 04xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx }这个公钥是给前端sm2.doEncrypt(...)直接用的原始 SM2 公钥。2前端组装明文 JSON{ username: admin, password: 123456, timestamp: 1710000000000 }3前端生成随机 SM4 key例如A8cD3eF7hJ2kL9mN4前端加密data sm4.encrypt(payload, sm4Key)key sm2.doEncrypt(sm4Key, publicKey, 1)最终请求体{ key: SM2加密后的SM4密钥(hex), data: SM4加密后的业务JSON(hex) }5后端解密用 SM2 私钥解出sm4Key用 SM4 key 解出plainJson解析出username/password/timestamp五、为什么这样更合理“为什么不直接用 SM2”。这里混合加密的优势就是SM2负责保护一个很小的随机密钥SM4负责高效加密真正的业务数据Hutool 文档本身也把 SM2 归为非对称加密把 SM4 归为对称加密这两类算法在工程上本来就常常配合使用。(Hutool)六、最容易踩的坑1. 前端公钥格式错不能把getPublicKeyBase64()直接给前端。前端要的是04 X Y的原始公钥不是 X.509/ASN.1 编码的公钥。Hutool 文档明确区分了公钥的Q 值和X.509两种不同格式。(Hutool)2. SM2 模式不一致前端这里固定const cipherMode 1;联调时就按C1C3C2统一不要混。3. SM4 key 长度不对Hutool 文档中自定义 SM4 key 的示例是128 位也就是 16 字节。这里前端随机生成 16 个 ASCII 字符后端按 UTF-8 读取后恰好是 16 字节。(Hutool)4. 后端每次重启重新生成密钥演示可以这样。生产不行。生产环境要把私钥固定存起来不然前端今天拿到的公钥和明天后端的私钥就不是一对了。5. 仍然必须用 HTTPS这套字段级加密不能替代 TLS。Hutool 只解决加解密实现不负责传输层安全。(Hutool)七、生产版建议可以先用上面代码跑通之后再补这几项固定私钥放配置中心 / KMS / HSM时间戳校验比如 5 分钟内有效nonce 防重放签名校验在混合加密外再加签防篡改不要打印明文 JSON / 密码全站 HTTPS八、最小可验证步骤先启动后端。第一步调用GET /api/public-key确认返回的publicKey是04开头的长 hex 字符串。第二步前端执行const body await encryptLoginPayload(admin, 123456); console.log(body);应该能看到{ key: 一串SM2 hex密文, data: 一串SM4 hex密文 }第三步调用login(admin, 123456)应该返回{ code: 0, message: 登录成功 }