Spring Boot实战：国密算法SM2/SM3/SM4全栈集成指南
在金融、政务等对数据安全要求极高的领域，国密算法正逐步成为加密技术的首选方案。不同于传统的AES、RSA等国际算法，SM系列算法由我国自主研发，在安全性和性能上都有显著优势。本文将带你从零开始，在Spring Boot项目中完整集成SM2非对称加密、SM3摘要算法和SM4对称加密，构建一个符合国密标准的加密解决方案。
1. 环境准备与依赖配置
1.1 创建Spring Boot项目
首先使用Spring Initializr创建一个基础的Spring Boot项目，选择以下依赖：
- Spring Web（用于构建RESTful API）
- Lombok（简化代码编写）
<!-- pom.xml中添加sm-crypto依赖 --> <dependency> <groupId>com.antherd</groupId> <artifactId>sm-crypto</artifactId> <version>0.3.2</version> </dependency>1.2 国密算法基础认知
在开始编码前，我们需要了解三种核心国密算法的特性：
| 算法类型 | 名称 | 密钥长度 | 特点 | 典型应用场景 |
|---|---|---|---|---|
| SM2 | 非对称 | 256bit | 基于椭圆曲线，安全性高于RSA2048 | 数字签名、密钥交换 |
| SM3 | 摘要 | 256bit | 抗碰撞性强于SHA-1 | 数据完整性校验、数字签名 |
| SM4 | 对称 | 128bit | 分组加密，性能优于3DES | 数据加密存储、通信加密 |
2. SM2非对称加密实现
2.1 密钥对生成与管理
在实际项目中，密钥管理是安全的基础。我们创建一个Sm2Service来处理密钥相关操作：
@Service public class Sm2Service { // 生成SM2密钥对 public KeyPair generateKeyPair() { return Sm2.generateKeyPairHex(); } // 加密数据 public String encrypt(String plainText, String publicKey) { return Sm2.doEncrypt(plainText, publicKey); } // 解密数据 public String decrypt(String cipherText, String privateKey) { return Sm2.doDecrypt(cipherText, privateKey); } }2.2 数字签名与验证
数字签名是SM2的重要应用场景，以下是优化后的签名实现：
public String sign(String message, String privateKey) { SignatureOptions options = new SignatureOptions(); options.setHash(true); // 启用SM3哈希 options.setDer(true); // 使用DER编码 return Sm2.doSignature(message, privateKey, options); } public boolean verify(String message, String signature, String publicKey) { SignatureOptions options = new SignatureOptions(); options.setHash(true); options.setDer(true); return Sm2.doVerifySignature(message, signature, publicKey, options); }提示：对于高频签名场景，可以预生成椭圆曲线点池来提高性能
3. SM3摘要算法深度应用
3.1 基础哈希计算
SM3算法可以替代MD5、SHA-1等传统哈希算法：
public class Sm3Util { public static String hash(String input) { return Sm3.sm3(input); } public static String hash(byte[] input) { return Sm3.sm3(input); } }3.2 文件完整性校验
结合Spring的Resource接口，我们可以实现文件校验功能：
public String calculateFileHash(Resource fileResource) throws IOException { try (InputStream is = fileResource.getInputStream()) { byte[] buffer = new byte[8192]; MessageDigest digest = MessageDigest.getInstance("SM3"); int read; while ((read = is.read(buffer)) > 0) { digest.update(buffer, 0, read); } return Hex.encodeHexString(digest.digest()); } }4. SM4对称加密实战
4.1 基础加密解密
SM4的ECB模式是最简单的使用方式：
public class Sm4Service { private static final String DEFAULT_KEY = "0123456789abcdeffedcba9876543210"; public String encrypt(String plainText) { return Sm4.encrypt(plainText, DEFAULT_KEY); } public String decrypt(String cipherText) { return Sm4.decrypt(cipherText, DEFAULT_KEY); } }4.2 高级模式配置
对于更高安全要求的场景，可以使用CBC模式：
public String encryptWithCbc(String plainText, String key, String iv) { Sm4Options options = new Sm4Options(); options.setMode("cbc"); options.setIv(iv); return Sm4.encrypt(plainText, key, options); } public String decryptWithCbc(String cipherText, String key, String iv) { Sm4Options options = new Sm4Options(); options.setMode("cbc"); options.setIv(iv); return Sm4.decrypt(cipherText, key, options); }5. 构建RESTful加密API
5.1 API设计规范
我们设计一套符合REST规范的加密API：
POST /api/encrypt/sm2 # SM2加密 POST /api/decrypt/sm2 # SM2解密 POST /api/sign # 数字签名 POST /api/verify # 签名验证 POST /api/hash/sm3 # SM3哈希 POST /api/encrypt/sm4 # SM4加密 POST /api/decrypt/sm4 # SM4解密5.2 完整控制器实现
@RestController @RequestMapping("/api") @RequiredArgsConstructor public class CryptoController { private final Sm2Service sm2Service; private final Sm4Service sm4Service; @PostMapping("/encrypt/sm2") public ResponseEntity<String> sm2Encrypt( @RequestBody EncryptRequest request) { String cipherText = sm2Service.encrypt(request.getText(), request.getKey()); return ResponseEntity.ok(cipherText); } // 其他API方法类似实现... }6. 性能优化与安全实践
6.1 线程安全与对象复用
对于高并发场景，我们需要优化资源使用：
@Configuration public class CryptoConfig { @Bean public Queue<Point> sm2PointPool() { // 初始化10个椭圆曲线点供SM2签名使用 return new LinkedList<>(IntStream.range(0, 10) .mapToObj(i -> Sm2.getPoint()) .collect(Collectors.toList())); } }6.2 密钥安全管理方案
在实际生产环境中，推荐以下密钥管理策略：
- 硬件安全模块(HSM)：使用专用硬件存储密钥
- 密钥轮换机制：定期更换加密密钥
- 分级密钥体系：不同安全级别数据使用不同密钥
- 最小权限原则：严格控制密钥访问权限
7. 常见问题排查指南
7.1 SM2加密异常处理
try { String cipherText = sm2Service.encrypt(plainText, publicKey); } catch (CryptoException e) { if (e.getMessage().contains("invalid public key")) { // 处理公钥格式错误 } else if (e.getMessage().contains("data too long")) { // 处理数据过长问题 } }7.2 SM4解密失败排查
当SM4解密失败时，按以下步骤检查：
- 确认密钥是否正确（128bit十六进制字符串）
- 检查加密模式是否匹配（ECB/CBC）
- 验证初始向量IV（CBC模式必须一致）
- 确认填充方式是否相同（PKCS5/None）
8. 完整项目结构参考
一个典型的国密算法集成项目结构如下：
src/main/java ├── com.example.demo │ ├── config # 配置类 │ ├── controller # API控制器 │ ├── service # 业务逻辑 │ │ ├── impl # 实现类 │ ├── util # 工具类 │ └── dto # 数据传输对象 src/main/resources ├── application.yml # 应用配置 └── static # 静态资源在实际开发中，我们通常会遇到各种边界情况。比如处理大文件加密时，内存效率就变得尤为重要。这时可以采用分块加密的策略，将大文件分割为适当大小的块，分别加密后再组合。这种方案不仅能降低内存消耗，还能实现并行加密提升性能。
