国密算法SM2与SM3的Java加解密实战：附可直接运行jar包

简介：面向Java开发者的国密算法工具包，基于SM2非对称加密与SM3杂凑算法，实现字符串与文件的加密、解密及完整性校验，适用于业务系统国密合规改造、敏感数据保护，以及希望系统学习SM2/SM3工程化落地的初中级开发者。压缩包共5个文件，包含4个Java源文件与1个Jar依赖包，整体约4.89MB；源文件分别承担密钥管理、加解密操作、摘要计算与文件流读取等职责，Jar包为Bouncy Castle加密库，提供底层密码学实现，免去额外下载依赖。包内未引入复杂配置，核心逻辑集中在几个工具类中，调用入口清晰，便于快速集成到普通Java工程或Maven项目。目前已有428人学习下载，表明其在国密应用场景中有一定参考热度；下载后可直接使用工具类完成字符串和文件的加解密，也可对照源码理解SM2密钥协商、SM3摘要生成、文件分块处理等细节。通过该工具包，既能获得开箱即用的国密功能，也能借此掌握Java与Bouncy Castle库的配合写法，适合作为二次开发基础或算法学习样例。

1. 自带jar包的国密工具箱：SM2与SM3怎么从代码变成可用的加解密能力

对接上游系统，对方要求接口报文用SM2加密、关键文件用SM3做完整性校验，密钥必须按国密标准生成。很多团队第一次遇到这种事都心里没底：网上资料东一榔头西一棒槌，光搞明白BC库里SM2密钥怎么生成、密文为什么是C1C3C2而不是C1C2C3，就要耗掉大半天。这份sm2sm3国密字符文件加解密资源好就好在不自嗨——压缩包里除了源码，连能直接运行的jar包都打包好了，字符串加解密和文件加解密两条路径都有可执行的示例。适合两类人：手里有国密对接需求、想快速跑通的，以及没写过国密、想借一套完整实现搞懂SM2和SM3在Java里怎么落地做二次开发的。下面把结构、运行、核心实现和改造的坑依次拆开讲。

2. 项目结构与技术选型：SM2和SM3在代码里各管一段

2.1 解压后的目录结构：源码、jar包、依赖各归其位

解压压缩包，里面不是一堆散落的class文件，而是按标准Maven工程整理的目录。这类工程解压后常见的长相是这样：

sm2sm3-encrypt-decrypt/ ├── lib/ # 第三方依赖与打包产物 │ ├── sm2sm3.jar # 打包好的可执行jar（含Main入口） │ └── bcprov-jdk15on-xxx.jar # BC加密库，版本以实际压缩包为准 ├── src/ │ └── main/ │ └── java/ │ └── com/example/sm/ │ ├── SM2Util.java # SM2密钥对、加解密 │ ├── SM3Util.java # SM3摘要 │ ├── FileEncryptUtil.java # 文件分块加解密 │ └── Main.java # 命令行入口 ├── keys/ # 示例密钥或运行后生成的密钥 └── README.md # 使用说明

这个结构很典型：SM2Util负责非对称加解密，SM3Util负责摘要，FileEncryptUtil负责把文件切块并调用前两者，Main把这三者串成命令行工具。如果要改功能，直接从这几个类入手就行，不用在工程里翻半天目录。

需要注意，jar是放在lib目录下的。如果你的环境缺少这个lib，或者classpath没有把bcprov的jar带上，运行时会直接报ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider，这是用BC库的项目最常见的启动失败原因，后面运行部分会专门说。

2.2 SM2和SM3的分工：非对称加密与哈希摘要怎么配合

SM2和SM3虽然都叫国密，但解决的问题完全不同。SM2是椭圆曲线非对称加密，核心特点是“公钥加密、私钥解密”；SM3是哈希摘要算法，核心特点是“输出固定、单向不可逆”。这两个算法在项目里各管一段：SM2负责让数据只有持私钥的人能解开，SM3负责让数据在传输过程中有没有被改动一眼就能看出来。

一个经典的配合流程是：发送方持有接收方的SM2公钥，用它对明文做加密得到密文；接收方拿到密文后用自己的SM2私钥解密还原明文。同时，发送方在加密前先用SM3对明文算出一个摘要值，把摘要跟着密文一起发过去；接收方解密出明文后再算一次SM3，两个摘要一致，就能确认数据在中间环节没有被动手脚。如果只加密不校验，密文被截获改了几个字节，接收方解密出来就是错乱数据，还很难定位问题出在哪。

所以在这套代码里，SM2承担内容的保密性，SM3承担内容的完整性。两者不是二选一的关系，而是组合使用。后面核心模块拆解里，你会在方法层面看到这两条线是怎么落到代码上的。

2.3 技术选型的背后：为什么是国密而不是RSA加SHA

从纯技术实现上说，非对称加密用RSA、摘要用SHA-256，生态更成熟，资料更多，为什么项目还要专门用SM2和SM3？最直接的原因是合规。金融、政务、能源这类行业的数据交换场景，很多合同或监管要求里明确写了“使用国密算法”，尤其跟政务平台对接时，算法不符合国密标准可能连验收都过不了。代码本身没多少玄学，难的是把算法选型这件事往合规要求上靠。

技术层面也有可比之处。SM2使用256位的sm2p256v1椭圆曲线，单位安全强度对应的密钥长度比RSA短，算力开销和密钥存储成本都低于同等级RSA；SM3输出256位摘要，安全性大致相当于SHA-256。下表是一个粗略对比，方便你在改造方案时对外解释为什么这么选：

所以这套代码的技术栈并不复杂：Java标准库加一个BC依赖，就同时拿下了国密非对称加密和国密摘要。搞懂这一点，后面看代码就不会觉得陌生。

3. 核心模块拆解：SM2密钥生成、加解密与SM3摘要的完整实现

3.1 SM2密钥对生成：一把钥匙开一把锁

SM2是公钥密码体制，一切加解密的前提是先有一套密钥对。这一节先讲密钥生成。

public class SM2Util { // BC 的 Provider 实例，整个 JVM 初始化一次即可 private static final Provider BC = new BouncyCastleProvider(); // 生成 SM2 密钥对 public static KeyPair generateKeyPair() throws Exception { // 注意算法名是 "EC"，不是 "SM2"——SM2 本质是椭圆曲线算法 KeyPairGenerator kpg = KeyPairGenerator.getInstance("EC", BC); // 国密标准指定的曲线参数，不能随意换成 prime256v1 ECGenParameterSpec spec = new ECGenParameterSpec("sm2p256v1"); kpg.initialize(spec, new SecureRandom()); return kpg.generateKeyPair(); } }

这里最容易写错的是算法名和曲线参数。KeyPairGenerator注册的是“EC”而不是“SM2”；曲线参数必须用sm2p256v1，如果图省事写成prime256v1，生成的密钥虽然是合法椭圆曲线密钥，但并不是国密体系内的标准曲线，对接方用SM2解密时大概率失败。SecureRandom是安全随机数源，保证每次生成的密钥都不相同。

密钥对生成之后，通常需要把公钥和私钥以字符串形式保存下来，下次直接加载。常见做法是转成Hex：

// 私钥 -> Hex 字符串，方便存文件和配置 public static String privateKeyToHex(PrivateKey privateKey) { return Hex.toHexString(privateKey.getEncoded()); } // Hex 字符串 -> PrivateKey，加载时用 public static PrivateKey hexToPrivateKey(String hexKey) throws Exception { PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(Hex.decode(hexKey)); KeyFactory keyFactory = KeyFactory.getInstance("EC", BC); return keyFactory.generatePrivate(keySpec); }

公钥的序列化和私钥类似，用getEncoded()拿DER编码的字节，再转Hex。要注意的是，有些对接方给的不是DER编码的密钥，而是按SM2的原始点格式只给x、y坐标拼出来的64字节。遇到这种格式，最好先跟对方确认密钥编码规范，否则KeyFactory解析时会报InvalidKeySpecException。这个坑在对接外部系统时特别常见。

3.2 SM2加解密：密文的C1C2C3顺序不能想当然

拿到公钥私钥之后，SM2加解密本身其实很短。

// 公钥加密：明文进，密文出 public static byte[] sm2Encrypt(byte[] plainText, PublicKey publicKey) throws Exception { Cipher cipher = Cipher.getInstance("SM2", BC); cipher.init(Cipher.ENCRYPT_MODE, publicKey); return cipher.doFinal(plainText); } // 私钥解密：密文进，明文出 public static byte[] sm2Decrypt(byte[] cipherText, PrivateKey privateKey) throws Exception { Cipher cipher = Cipher.getInstance("SM2", BC); cipher.init(Cipher.DECRYPT_MODE, privateKey); return cipher.doFinal(cipherText); }

SM2加解密使用方式和RSA很像，但有几个点必须注意。第一，SM2输出的密文不是固定长度的，它由三部分拼接而成：C1是椭圆曲线点（固定65字节），C2是密文主体（长度与明文相同），C3是SM3校验值（固定32字节），所以整体比明文多97字节。第二，C1C2C3的排列顺序在不同的实现里不一样——BC默认输出C1C3C2，而国标文档里的顺序是C1C2C3。如果你的数据要交给用另一种顺序的实现去解密，必须先把密文重排，否则解密端直接抛Invalid Cipher Text。

这也是这套代码里最值得看的一个细节：它把密文的兼容处理放在了解密入口，让字符串和文件两条路径共用同一个重排逻辑。常见的重排代码像这样：

// 把 BC 默认的 C1C3C2 重排成国标文档里的 C1C2C3 public static byte[] rebuildC1C2C3(byte[] bcCipher) { int c1Len = 65; // 椭圆曲线点长度，未压缩格式固定 65 字节 int c3Len = 32; // SM3 校验值固定 32 字节 int c2Len = bcCipher.length - c1Len - c3Len; byte[] result = new byte[bcCipher.length]; System.arraycopy(bcCipher, 0, result, 0, c1Len); System.arraycopy(bcCipher, c1Len + c3Len, result, c1Len, c2Len); System.arraycopy(bcCipher, c1Len, result, c1Len + c2Len, c3Len); return result; }

参数说明：c1Len取65是因为SM2的椭圆曲线点以未压缩格式表示时，前缀0x04加x坐标32字节加y坐标32字节；c3Len取32是因为SM3摘要固定输出32字节。如果你的对接实现用了压缩点格式，c1Len会变成33，这个重排函数就不能直接复用，需要按实际格式调整。

这里多说一句：SM2每次加密同一个明文，输出的密文都不一样。原因是加密过程引入了随机数k，C1就是由这个随机数算出的椭圆曲线点，换了k，C1就变，整个密文就变。这不是bug，恰恰是非对称加密抵抗重放分析的重要手段。所以不要在测试时拿“两次密文不一致”来怀疑代码出了问题。

3.3 SM3摘要：为什么哈希能做完整性校验

SM3在项目里承担的是“给数据盖个不会被篡改的章”。

public class SM3Util { // 计算 SM3 摘要，返回 64 位 Hex 字符串（32 字节哈希值） public static String sm3(byte[] data) { SM3Digest digest = new SM3Digest(); digest.update(data, 0, data.length); byte[] hash = new byte[digest.getDigestSize()]; digest.doFinal(hash, 0); return Hex.toHexString(hash); } }

参数只有一个：输入的字节数组。SM3Digest是BC对国密SM3的实现，update把要计算的数据喂进去，doFinal把结果写进固定32字节的数组。同一个输入永远得到同一个64位Hex摘要，但输入只要改一个bit，摘要就会面目全非，这就是它能在加密体系中做校验的原因。

在使用上有个细节：摘要计算的对象必须是原始字节。别在中间做无谓的String转换——如果数据先转成String又getBytes()取回，字符集一变，摘要就对不上了。在Java里尽量用byte[]传递，确需转String时固定用StandardCharsets.UTF_8。这套代码里的SM3Util只吃byte[]，也是为了让调用方自己控制数据的编码边界。

3.4 文件加解密链路：分块循环与摘要验证

字符串加解密直接调用SM2Util的两个方法就行，文件加解密则要多一层分块逻辑。SM2是非对称算法，开销比对称加密大得多，一次性把整个文件读进内存再一次性加密，大文件会直接把内存打满。这套代码里的FileEncryptUtil用的是分块处理：

public static void encryptFile(File src, File dest, PublicKey publicKey) throws Exception { try (FileInputStream in = new FileInputStream(src); FileOutputStream out = new FileOutputStream(dest)) { byte[] buf = new byte[4096]; int len; while ((len = in.read(buf)) != -1) { // 最后一块可能不足 4096，按实际长度切出来 byte[] block = Arrays.copyOf(buf, len); byte[] encrypted = SM2Util.sm2Encrypt(block, publicKey); out.write(encrypted); } } }

这里的逻辑按块循环：每次从原文件读出最多4096字节，调用SM2Util加密这一块，把密文块顺序写到目标文件。decryptFile的逻辑对称：读密文块、解密、写明文。值得说明的是分块大小不是随便定的——块太小，每一块都要承担65字节C1和32字节C3的膨胀开销，文件会大很多；块太大，单块加密耗时变长，内存占用升高。对SM2来说，4KB这个量级算是一个比较常规的折中。

这个实现还有一个隐藏问题：解密时怎么知道每一块密文对应多长的明文？加密方的分块是按原文长度切的，解密方读密文时如果不知道块的边界，没法正确切割。演示代码里往往按“每块大小一致”来约定。落到生产环境，我一般会在密文文件头部写4字节的明文总长度和4字节的块大小，解密时先读头，再按固定逻辑切割密文块。这部分改造在做文件传输对接时是绕不开的。

4. 运行与验证：命令行把字符串和文件两套流程跑通

4.1 环境准备：JDK版本、classpath和BC依赖

运行这套代码的前提很简单：JDK 8及以上，再把压缩包里的jar包和lib目录解压到一个固定目录。如果工程是用Maven的，也可以直接import到IDE里，但命令行场景下最稳的方式是用java -cp把依赖的jar全部拉进classpath。

我一般会这样跑：

# Linux / macOS java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --help # Windows 下分隔符换成英文分号 java -cp "sm2sm3.jar;lib/*" com.example.sm.Main --help

classpath里的sm2sm3.jar和lib/*，分别指向主程序jar和BC依赖。注意Windows的分隔符是分号，很多人第一次在Windows跑这种命令时用的冒号，就会报找不到主类。如果看到ClassNotFoundException，排查顺序就两步：第一，jar路径是否写对；第二，lib目录下的BC依赖有没有被通配符带进classpath。

4.2 字符串加解密的最小闭环

把密钥生成到解密这一整条链路跑通，是验证环境有没有装对的最快办法。命令行入口提供的模式大致包括keygen、encrypt、decrypt、sm3四组，参数名不同版本略有差异，但用法是同一套：

# 第一步：生成密钥对 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --keygen --pub public.key --pri private.key # 第二步：用公钥加密一段字符串 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --encrypt --data "hello sm2" --pub public.key # 第三步：把上一步输出的密文作为参数传进去解密 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --decrypt --data <上一步输出的密文> --pri private.key

第二步输出的密文是一长串Hex字符串。这一步值得多看一眼：同样的明文，每次运行输出的密文都不同，这是SM2随机数k造成的正常现象。解密时要把整个Hex串原样传进去，不要手动截断或去掉头尾的空格，否则会报解密失败。整个闭环跑通后，你会看到解密输出和“hello sm2”完全一致，说明SM2加解密这条线是通的。

4.3 文件加解密实操与分块协议

文件操作的命令行入口大致长这样：

# 加密一个文件 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --encrypt-file --src report.pdf --dest report.pdf.enc --pub public.key # 解密还原 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --decrypt-file --src report.pdf.enc --dest report.pdf.dec --pri private.key

文件加密用的是3.4节的分块逻辑。运行完之后你可以对比原文件和解密文件的字节数，正常情况下应该完全一致。如果不一致，优先查两件事：第一，分块长度在加密和解密两侧是否一致；第二，最后不满一块数据的处理逻辑是否对称。这两个地方不对称，文件尾部就会多出或丢失字节。

还有一个值得注意的现象：加密后的文件比原文件大。SM2每块密文比明文多97字节，文件越大、块边界划得越碎，膨胀就越明显。如果只是演示，这个膨胀可以接受；如果文件达到几十上百MB，就要考虑第6章要讲的混合加密方案了。

4.4 用SM3验证文件在加密解密后没有被改动

文件能解出来不等于数据是对的。文件在磁盘上存储、拷贝、传输的过程中，任何一个bit翻转都会让还原结果出错。这时候SM3就派上用场了。

# 对原始文件计算摘要 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --sm3 --file original.pdf # 对解密后的文件计算摘要 java -cp "sm2sm3.jar:lib/*" com.example.sm.Main --sm3 --file decrypted.pdf

两个输出完全一致，说明“原始文件 → 加密 → 解密 → 还原文件”这条链路是干净的。如果不同，说明中间某个环节出了问题，要么是分块逻辑不对称，要么是文件尾部被截断，要么是磁盘I/O写坏了。

5. 常见问题与避坑记录：对接国密时最容易翻车的四个地方

写这一章是因为我在看这套代码和跑通流程之后，把最容易出问题的点整理成了实际的排查记录。每条都按现象、原因、解决的顺序写。

5.1 公钥和私钥不配对：加密成功但解不出来

现象：用A生成的公钥加密，再用B生成的私钥解密，解密报错或者解出来是一堆乱码字节。

原因：多数情况下不是算法问题，而是流程问题。生成密钥对之后，公钥发给多方使用，私钥只有接收方保留，如果有人把公钥和私钥拿错了组合，加解密自然对不上。还有一种隐蔽情况是密钥序列化格式不一致，一端用的是PKCS8格式的私钥，另一端用的是PKCS1或原始点格式。

解决：先把密钥来源理清。确认公钥和私钥来自同一次generateKeyPair()的调用；然后在解密前用私钥的getEncoded()序列化结果和生成时的记录比对一下。如果你的对接方提供的是固定格式的密钥文件，可以自己写一个十六进制转储的小工具，先目检一下文件头和长度，能少走很多弯路。

5.2 密文报Invalid Cipher Text：C1C3C2和C1C2C3的顺序之争

现象：同一段密文在A实现里能解，在B实现里抛InvalidCipherTextException。

原因：SM2密文的C1、C2、C3三段排列顺序在不同实现里不一致。BC默认输出C1C3C2，部分实现和标准文档的示例代码按C1C2C3排列。解密端按它自己的顺序去解析，遇到另一端按其他顺序拼出来的密文，自然解析失败。

解决：加密和解密的双方必须事先约定密文顺序。如果是BC生态内部互操作，保持默认C1C3C2即可；如果对接方要求C1C2C3，加密端拿到BC的密文后先调用3.2节里的rebuildC1C2C3做一次重排。判断方法也简单：密文的第65字节往后，如果读出来是32字节长的C3，说明是C1C3C2顺序；如果是和明文等长的C2，说明是C1C2C3顺序。

5.3 解密结果中文乱码或摘要对不上

现象：英文和数字解密正常，中文解出来全是乱码；或者SM3摘要怎么算都对不上。

原因：绝大多数是字符集问题。加密时用plainText.getBytes()用了默认字符集，解密后又用new String(bytes)用默认字符集转回，两端的默认字符集只要不一致，中文必然乱码。摘要对不上也是同一个根源——摘要是对byte[]算的，中间一旦经过String的字符集转换，字节序列就变了。

解决：在代码里把所有跟字符集相关的入口收口。明文转byte[]统一用StandardCharsets.UTF_8，解密后转回String也用UTF_8；对外提供的接口明确要求入参和出参都是UTF-8。SM3Util的入参设计成byte[]而不是String，就是为了逼着调用方在边界就把字符集定死。

5.4 文件加密后体积暴涨、耗时翻倍

现象：一个10MB的文件加密完多出接近250KB的附加数据，加密耗时也从毫秒级拉到秒级以上。

原因：SM2每块密文要附加C1的65字节和C3的32字节，按4KB分块大概会切成2500多块，附加数据累积起来相当可观，再配合非对称加密的标量乘法开销，文件一大，膨胀和慢速就会同时出现。

解决：判断这属于正常的SM2开销，但工程上不要用SM2直接加密大文件。标准做法是混合加密：生成一个随机的SM4会话密钥，用SM4对称加密文件内容，再用SM2公钥加密这个SM4密钥，把密文文件和加密后的密钥一起传过去。接收方先解SM4密钥，再用它解开文件。这个改造不复杂，收益却很明显，第6章会给具体代码思路。

6. 二次开发改造：从命令行工具到国密加密服务

这套代码的改造空间其实比想象中大。给你三条我亲自试过的路子，按投入从低到高排。

6.1 包一层HTTP接口，变成加密服务

第一步是把Main的调用逻辑包进Spring Boot的Controller。核心代码很短：

@RestController @RequestMapping("/api/sm") public class SmController { // 密钥从配置中心读取，不要在代码里硬编码 private final PublicKey publicKey = loadPublicKeyFromConfig(); private final PrivateKey privateKey = loadPrivateKeyFromConfig(); @PostMapping("/encrypt") public String encrypt(@RequestBody String plainText) throws Exception { byte[] encrypted = SM2Util.sm2Encrypt(plainText.getBytes(StandardCharsets.UTF_8), publicKey); return Hex.toHexString(encrypted); } @PostMapping("/decrypt") public String decrypt(@RequestBody String cipherHex) throws Exception { byte[] decrypted = SM2Util.sm2Decrypt(Hex.decode(cipherHex), privateKey); return new String(decrypted, StandardCharsets.UTF_8); } }

这里有一个很细节的坑：Cipher不是线程安全的，别把Cipher对象作为字段在多线程请求里共享。最省事的做法是每次请求都new一个Cipher实例，或者用ThreadLocal包装。SM2密钥对的生成开销不大，但加解密操作本身在并发高的时候会成为热点，需要评估一下QPS再决定是否要加缓存。

6.2 混合加密：SM2保护SM4密钥，SM4加密内容

文件加密场景，最值得做的改造是引入SM4。原理前面说过：SM4对称加密速度快、密文不膨胀，SM2只加密一段随机生成的SM4密钥。

// 生成随机会话密钥，SM4密钥长度固定16字节 byte[] sm4Key = SM4Util.generateKey(); // 文件内容用SM4加密 byte[] encryptedData = SM4Util.encrypt(fileData, sm4Key); // SM4密钥用SM2公钥加密，随密文一起传输 byte[] encryptedKey = SM2Util.sm2Encrypt(sm4Key, publicKey);

接收方先解encryptedKey拿到sm4Key，再用sm4Key解encryptedData。这套方案的传输数据量、加密耗时都远优于纯SM2分块，而且仍然满足国密合规。做这个改造时，别忘了把会话密钥的版本号或标识一起发给对端，方便后续密钥轮换。

6.3 安全加固：随机源、日志与密钥轮换

最后说几个容易被忽略的加固点。随机数生成统一用SecureRandom，不要图方便用new Random()，否则密钥的可预测性会让加密形同虚设；私钥不要出现在日志和异常信息里，报错时只输出异常类型；密钥按周期轮换，会话密钥一次一换，固定的公私钥对至少要有轮换预案。这些点都做齐了，这套SM2加解密代码才算真正能扛线上环境。

踩过这些坑之后，我的习惯也固定下来了：每次拿到一套国密加解密的代码，第一时间不急着看接口，先用“生成密钥→加密→解密→SM3比对”四步闭环跑一遍，再谈改造。这个流程能过滤掉大半的兼容性问题。希望帮到你。

本文还有配套的精品资源，点击获取