Java国密算法实战：基于Hutool与Bouncy Castle的SM2/SM3/SM4集成指南

1. 项目概述：为什么Java开发者需要掌握国密与Hutool

最近在做一个和政府、金融相关的项目，对接方明确要求所有敏感数据的传输和存储必须使用国密算法。一开始我头都大了，国密SM2、SM3、SM4这些名词听着就专业，网上的资料要么是零散的代码片段，要么是晦涩的理论文档，想找个能直接跑通的完整例子都得翻半天。后来在团队老大的指点下，我系统地把Hutool工具包结合Bouncy Castle的国密支持给摸透了，不仅项目顺利交付，还总结出了一套从环境配置到实战加密、签名、验签的完整流程。

这篇文章，就是把我踩过的坑、验证过的代码和关键的配置细节，毫无保留地分享出来。如果你也在为Java项目中集成国密算法而烦恼，或者想提前储备这块知识应对未来的合规需求，那么这篇实战指南就是为你准备的。我会从最头疼的Bouncy Castle依赖冲突讲起，到用Hutool几行代码搞定SM2非对称加密、SM3摘要计算和SM4对称加密，最后还会附上如何生成密钥对、处理加解密中的异常这些纯干货。保证你看完就能上手，代码复制过去改改就能用。

2. 核心依赖与Bouncy Castle配置详解

国密算法在Java标准库中并没有原生支持，因此我们需要引入第三方加密库。Bouncy Castle是一个强大的开源加密库提供商，它提供了对国密算法的完整实现。而Hutool则是一个国产的Java工具类库，它对包括Bouncy Castle在内的多种底层库进行了友好封装，提供了更简洁易用的API。我们的目标就是利用Hutool的便捷性，来调用Bouncy Castle的国密能力。

2.1 依赖引入与版本选择避坑

首先，在你的Maven项目pom.xml中引入关键依赖。版本选择是第一个坑，不同版本间的兼容性差异很大。

<dependencies> <!-- Hutool 核心工具包，我们主要使用其加密模块 --> <dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-all</artifactId> <version>5.8.16</version> <!-- 建议使用5.8.x及以上稳定版本 --> </dependency> <!-- Bouncy Castle 提供国密算法实现 --> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15to18</artifactId> <version>1.72</version> <!-- 注意：1.70+版本对国密支持更完善 --> </dependency> </dependencies>

注意：这里有一个极易出错的点。bcprov-jdk15to18这个artifactId表示它适用于JDK 1.5到1.8。如果你使用的是JDK 9及以上版本（比如JDK 11, 17, 21），理论上应该使用bcprov-jdk18on。但在实际测试中，尤其是在某些Linux发行版或特定JDK环境下，bcprov-jdk18on可能与Hutool或系统安全提供商注册机制存在兼容性问题，导致NoSuchAlgorithmException或NoSuchProviderException。经过多次实践，我发现在大多数生产环境（包括JDK11和JDK17）下，使用bcprov-jdk15to18反而更稳定。如果遇到问题，可以尝试切换版本或artifactId。

2.2 安全提供者（Provider）的动态注册

引入依赖只是第一步，最关键的一步是向Java的Security框架注册Bouncy Castle作为安全提供者。只有这样，java.security包下的相关类（如KeyPairGenerator,Cipher）才能找到国密算法的实现。

错误做法：在静态代码块或初始化时简单调用Security.addProvider(new BouncyCastleProvider())。这在小程序里可能没问题，但在Web应用或复杂应用中，如果多处注册或容器（如Tomcat）的类加载机制特殊，可能导致提供者重复注册或注册失败。

推荐做法：使用一个单例且幂等（多次调用效果相同）的初始化方法。

import org.bouncycastle.jce.provider.BouncyCastleProvider; import java.security.Security; public class GmUtil { private static volatile boolean providerRegistered = false; /** * 安全地注册BouncyCastle提供者（幂等操作） */ public static synchronized void initBouncyCastle() { if (!providerRegistered) { // 先检查是否已存在，避免重复添加 if (Security.getProvider(BouncyCastleProvider.PROVIDER_NAME) == null) { Security.addProvider(new BouncyCastleProvider()); } providerRegistered = true; System.out.println("BouncyCastle Provider 注册成功。"); } } }

在你的应用启动入口（如Spring Boot的@PostConstruct、Servlet的init()方法或main方法最开始）调用GmUtil.initBouncyCastle()一次即可。

实操心得：在Spring Boot项目中，我更喜欢使用一个配置类，并利用@PostConstruct来初始化，这样能确保在Bean加载早期就完成提供者注册，避免后续加密操作时出现“找不到算法”的报错。

import org.springframework.context.annotation.Configuration; import javax.annotation.PostConstruct; @Configuration public class CryptoConfig { @PostConstruct public void init() { GmUtil.initBouncyCastle(); } }

3. SM2非对称加密实战：密钥对、加密与解密

SM2是基于椭圆曲线密码的非对称加密算法，相当于国际上的ECC算法。它主要用于数字签名和密钥交换，也可以用于加密解密。在国密体系中，SM2通常用于签名和验签，但其加密功能也常用在一些对安全性要求极高的数据交换场景。

3.1 生成SM2密钥对

进行SM2操作，首先需要一对密钥：公钥（Public Key）和私钥（Private Key）。公钥可以公开，用于加密或验证签名；私钥必须严格保密，用于解密或生成签名。

Hutool的SmUtil类让生成密钥对变得非常简单：

import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.asymmetric.KeyType; import cn.hutool.crypto.asymmetric.SM2; import java.security.KeyPair; public class Sm2Demo { public static void main(String[] args) { // 1. 初始化BouncyCastle（务必先执行） GmUtil.initBouncyCastle(); // 2. 使用Hutool生成SM2密钥对 KeyPair keyPair = SmUtil.generateSm2KeyPair(); // 获取Base64编码的公钥和私钥字符串，方便存储和传输 String publicKeyBase64 = SmUtil.toBase64Str(keyPair.getPublic()); String privateKeyBase64 = SmUtil.toBase64Str(keyPair.getPrivate()); System.out.println("公钥(Base64): " + publicKeyBase64); System.out.println("私钥(Base64): " + privateKeyBase64); // 也可以直接获取十六进制字符串 // String publicKeyHex = SmUtil.getPublicKeyHex(keyPair); // String privateKeyHex = SmUtil.getPrivateKeyHex(keyPair); } }

注意事项：

1. 密钥存储：生成的私钥字符串是高度敏感的，绝不能写入日志、前端代码或版本控制系统。在生产环境中，通常将私钥存储在硬件安全模块（HSM）、密钥管理系统（KMS）或经过加密的配置中心。
2. 密钥格式：Hutool生成的密钥是符合PKCS#8标准的。在与使用其他语言（如C++、Go）或不同库生成的密钥对进行交互时，务必确认双方的密钥格式（如PKCS#1, PKCS#8, SEC1）和椭圆曲线参数（国密SM2使用sm2p256v1曲线）是否一致，否则会导致无法解密或验签。

3.2 使用公钥加密与私钥解密

假设我们有一个需要加密传输的敏感字符串。

public class Sm2EncryptDecryptDemo { public static void main(String[] args) { GmUtil.initBouncyCastle(); // 假设这是从上面步骤生成或从配置读取的密钥 String publicKeyBase64 = "MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAEPJpK6t..."; // 你的公钥 String privateKeyBase64 = "MIGHAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBG0wawIBAQQg..."; // 你的私钥 String originalText = "这是一段需要加密的敏感数据，比如身份证号或合同金额。"; // 1. 创建SM2对象，传入公钥和私钥 // 通常，加密方只需要公钥，解密方只需要私钥。这里演示同一个对象加解密。 SM2 sm2 = SmUtil.sm2(privateKeyBase64, publicKeyBase64); // 2. 使用公钥加密（KeyType.PublicKey） String encryptedBase64 = sm2.encryptBase64(originalText, KeyType.PublicKey); System.out.println("加密后(Base64): " + encryptedBase64); // 3. 使用私钥解密（KeyType.PrivateKey） String decryptedText = sm2.decryptStr(encryptedBase64, KeyType.PrivateKey); System.out.println("解密后: " + decryptedText); // 验证是否一致 System.out.println("原文与解密文是否一致: " + originalText.equals(decryptedText)); } }

关键点解析：

• SmUtil.sm2(privateKey, publicKey)：构造SM2对象。两个参数都可以为null，但至少需要一个才能执行相应操作。例如，如果只进行加密，可以只传公钥：SmUtil.sm2(null, publicKeyStr)。
• encryptBase64：加密方法，返回Base64字符串，便于网络传输或文本存储。对应的还有encryptHex（返回16进制字符串）和encrypt（返回字节数组）。
• decryptStr：解密方法，它内部会自动识别输入是Base64还是Hex（Hutool会尝试解码），并返回明文字符串。对应的有decrypt（返回字节数组）。

3.3 SM2签名与验签实战

数字签名用于验证数据的完整性和来源真实性。发送方用私钥对数据（或数据的摘要）生成签名，接收方用公钥验证签名。

public class Sm2SignVerifyDemo { public static void main(String[] args) { GmUtil.initBouncyCastle(); String privateKeyBase64 = "你的私钥"; String publicKeyBase64 = "你的公钥"; String dataToSign = "这是一份重要的电子合同内容，需要确保未被篡改。"; SM2 sm2 = SmUtil.sm2(privateKeyBase64, publicKeyBase64); // 1. 使用私钥对数据进行签名 // 默认使用SM3算法对数据进行摘要，然后用SM2私钥签名。 String signatureBase64 = sm2.signBase64(dataToSign, null); // 第二个参数是摘要算法ID，null表示使用SM3 System.out.println("生成的签名(Base64): " + signatureBase64); // 2. 使用公钥验证签名 boolean verifyResult = sm2.verify(dataToSign.getBytes(), signatureBase64); System.out.println("验签结果: " + verifyResult); // 3. 模拟数据被篡改 String tamperedData = dataToSign + "（此处被恶意修改）"; boolean verifyResultAfterTamper = sm2.verify(tamperedData.getBytes(), signatureBase64); System.out.println("篡改后验签结果: " + verifyResultAfterTamper); // 应为 false } }

实操心得：在实际业务中，我们通常不是对原始长数据直接签名，而是先对数据用SM3计算一个固定长度的摘要（哈希值），然后对这个摘要进行签名。Hutool的sign方法内部已经帮我们做了这个“SM3摘要+SM2签名”的标准流程。verify方法内部也做了同样的“SM3摘要+SM2验签”操作。这符合国密规范，也是最常见的用法。

4. SM3摘要算法实战：数据完整性校验

SM3是一种密码杂凑算法（哈希算法），类似于国际上的SHA-256。它接收任意长度的输入，生成一个固定长度（256位，32字节）的摘要。特点是不可逆（无法从摘要反推原文）和抗碰撞（极难找到两个不同的数据产生相同的摘要）。常用于密码存储、文件完整性校验和数字签名的前置步骤。

4.1 基础摘要计算

使用Hutool计算SM3摘要极其简单。

import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.digest.DigestUtil; public class Sm3BasicDemo { public static void main(String[] args) { String data = "需要计算摘要的原始数据"; // 方法1：使用 SmUtil.sm3() 返回 DigestUtil 对象，可以链式调用 String hexDigest1 = SmUtil.sm3().digestHex(data); System.out.println("SM3摘要(Hex): " + hexDigest1); // 方法2：使用 DigestUtil.sm3() 静态方法 String hexDigest2 = DigestUtil.sm3Hex(data); System.out.println("SM3摘要(Hex) - 静态方法: " + hexDigest2); // 获取Base64格式的摘要 String base64Digest = SmUtil.sm3().digestBase64(data, "UTF-8"); System.out.println("SM3摘要(Base64): " + base64Digest); // 对于文件，可以计算其SM3值 // File file = new File("/path/to/your/file.zip"); // String fileDigest = SmUtil.sm3().digestHex(file); // System.out.println("文件SM3值: " + fileDigest); } }

4.2 加盐（Salt）与密码存储实践

在存储用户密码时，直接对密码进行SM3哈希是不安全的（容易受到彩虹表攻击）。标准的做法是“加盐”——将一个随机字符串（盐）与密码组合后再哈希。

import cn.hutool.core.util.RandomUtil; import cn.hutool.crypto.digest.Digester; public class Sm3WithSaltDemo { /** * 生成密码的加盐哈希值 * @param password 明文密码 * @return 一个包含盐和哈希值的字符串，格式为 `盐$哈希值` */ public static String encryptPassword(String password) { // 1. 生成一个随机的盐（例如16字节，用Hex存储） String salt = RandomUtil.randomString(16); // 2. 创建Digester对象，设置盐 Digester sm3Digester = SmUtil.sm3().setSalt(salt.getBytes()); // 3. 计算加盐后的摘要 String hashedPassword = sm3Digester.digestHex(password); // 4. 将盐和哈希值一起存储，用特定分隔符（如$）连接 return salt + "$" + hashedPassword; } /** * 验证密码 * @param inputPassword 用户输入的密码 * @param storedHash 数据库中存储的 `盐$哈希值` 字符串 * @return 验证是否通过 */ public static boolean verifyPassword(String inputPassword, String storedHash) { // 1. 从存储的字符串中分离出盐和哈希值 String[] parts = storedHash.split("\\$"); if (parts.length != 2) { return false; } String salt = parts[0]; String originalHash = parts[1]; // 2. 用相同的盐对输入密码进行哈希计算 Digester sm3Digester = SmUtil.sm3().setSalt(salt.getBytes()); String computedHash = sm3Digester.digestHex(inputPassword); // 3. 比较计算出的哈希值与存储的哈希值 return originalHash.equals(computedHash); } public static void main(String[] args) { String userPassword = "MySecretPass123!"; String storedHash = encryptPassword(userPassword); System.out.println("存储的密码哈希（含盐）: " + storedHash); boolean success = verifyPassword("MySecretPass123!", storedHash); System.out.println("正确密码验证: " + success); boolean fail = verifyPassword("WrongPassword", storedHash); System.out.println("错误密码验证: " + fail); } }

注意事项：盐必须是每个用户独立、随机的，并且需要和哈希值一起存储，以便后续验证。不能使用固定的全局盐。

5. SM4对称加密实战：高效的数据加解密

SM4是一种分组对称加密算法，密钥长度和分组长度均为128位。它类似于国际上的AES算法，用于对大量数据进行高效的加密和解密，例如数据库字段加密、配置文件加密、通信报文体加密等。

5.1 ECB模式与CBC模式的选择与实现

SM4支持多种工作模式，最常用的是ECB和CBC。

• ECB模式：电子密码本模式。相同的明文块会被加密成相同的密文块。缺点是对于重复模式的数据，安全性较差，一般不推荐用于加密结构化数据。
• CBC模式：密码分组链接模式。需要一个初始化向量（IV），每个明文块在加密前会先与前一个密文块进行异或操作，因此即使明文相同，加密结果也不同。安全性更高，是推荐模式。

5.1.1 ECB模式示例

import cn.hutool.crypto.SmUtil; import cn.hutool.crypto.symmetric.SM4; public class Sm4EcbDemo { public static void main(String[] args) { // 密钥（必须是16字节，即128位）。可以从密码派生，但这里直接指定。 // 注意：生产环境应从安全的地方获取密钥，而不是硬编码。 byte[] key = "0123456789abcdef".getBytes(); // 16字节 SM4 sm4 = SmUtil.sm4(key); // 默认使用ECB/PKCS5Padding String plainText = "这是一段使用SM4-ECB加密的测试文本。"; // 加密 String encryptedHex = sm4.encryptHex(plainText); System.out.println("ECB加密结果(Hex): " + encryptedHex); // 解密 String decryptedText = sm4.decryptStr(encryptedHex); System.out.println("ECB解密结果: " + decryptedText); } }

5.1.2 CBC模式示例（推荐）

import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.SM4; public class Sm4CbcDemo { public static void main(String[] args) { // 密钥 (16字节) byte[] key = "0123456789abcdef".getBytes(); // 初始化向量 IV (16字节，必须与密钥长度相同) byte[] iv = "fedcba9876543210".getBytes(); // 构建SM4对象，指定模式为CBC，填充为PKCS5Padding SM4 sm4 = new SM4(Mode.CBC, Padding.PKCS5Padding, key, iv); String plainText = "这是一段使用SM4-CBC加密的测试文本，更安全。"; // 加密 String encryptedBase64 = sm4.encryptBase64(plainText); System.out.println("CBC加密结果(Base64): " + encryptedBase64); // 解密 String decryptedText = sm4.decryptStr(encryptedBase64); System.out.println("CBC解密结果: " + decryptedText); } }

关键点解析：

• 密钥管理：对称加密的密钥安全性至关重要。在实际项目中，密钥绝不能像示例中这样硬编码在代码里。应该从安全的配置源（如KMS、经过加密的配置文件、环境变量）动态获取。
• IV管理：CBC模式的IV不需要像密钥一样绝对保密，但必须是随机的且不可预测。对于同一密钥，每次加密都应使用不同的IV。通常将IV和密文一起存储或传输（例如，将IV拼接在密文前面）。Hutool在解密时需要提供相同的IV。
• 填充：Padding.PKCS5Padding（或PKCS7Padding）是标准填充方式，确保明文长度是分组长度的整数倍。

5.2 封装一个更健壮的SM4-CBC工具类

结合上面的经验，我们可以封装一个更实用、更接近生产环境的工具类。

import cn.hutool.core.util.HexUtil; import cn.hutool.core.util.RandomUtil; import cn.hutool.crypto.Mode; import cn.hutool.crypto.Padding; import cn.hutool.crypto.symmetric.SM4; import java.nio.charset.StandardCharsets; public class Sm4CbcHelper { private final byte[] key; public Sm4CbcHelper(String base64Key) { // 假设传入的是Base64编码的密钥 this.key = cn.hutool.core.codec.Base64.decode(base64Key); if (this.key.length != 16) { throw new IllegalArgumentException("SM4密钥长度必须为16字节(128位)"); } } /** * 加密：生成随机IV，并将IV+密文一起返回（Hex格式） */ public String encrypt(String plaintext) { // 1. 生成16字节的随机IV byte[] iv = RandomUtil.randomBytes(16); // 2. 创建SM4 Cipher对象 SM4 sm4 = new SM4(Mode.CBC, Padding.PKCS5Padding, key, iv); // 3. 加密明文 byte[] ciphertextBytes = sm4.encrypt(plaintext); // 4. 将IV和密文拼接在一起（IV + Ciphertext） byte[] combined = new byte[iv.length + ciphertextBytes.length]; System.arraycopy(iv, 0, combined, 0, iv.length); System.arraycopy(ciphertextBytes, 0, combined, iv.length, ciphertextBytes.length); // 5. 转换为Hex字符串便于传输或存储 return HexUtil.encodeHexStr(combined); } /** * 解密：从组合字符串中提取IV和密文，然后解密 */ public String decrypt(String combinedHex) { // 1. 将Hex字符串解码为字节数组 byte[] combined = HexUtil.decodeHex(combinedHex); if (combined.length < 16) { throw new IllegalArgumentException("无效的加密数据"); } // 2. 提取前16字节作为IV byte[] iv = new byte[16]; System.arraycopy(combined, 0, iv, 0, 16); // 3. 提取剩余部分作为密文 byte[] ciphertextBytes = new byte[combined.length - 16]; System.arraycopy(combined, 16, ciphertextBytes, 0, ciphertextBytes.length); // 4. 创建SM4 Cipher对象并解密 SM4 sm4 = new SM4(Mode.CBC, Padding.PKCS5Padding, key, iv); byte[] plaintextBytes = sm4.decrypt(ciphertextBytes); return new String(plaintextBytes, StandardCharsets.UTF_8); } // 示例用法 public static void main(String[] args) { // 从安全的地方获取密钥，这里用示例 String base64Key = "QUJDREVGR0hJSktMTU5PUA=="; // "ABCDEFGHIJKLMNOP"的Base64 Sm4CbcHelper helper = new Sm4CbcHelper(base64Key); String secretData = "用户的银行卡号或隐私信息"; String encrypted = helper.encrypt(secretData); System.out.println("加密后(IV+Ciphertext in Hex): " + encrypted); String decrypted = helper.decrypt(encrypted); System.out.println("解密后: " + decrypted); System.out.println("解密成功: " + secretData.equals(decrypted)); } }

这个工具类自动处理了IV的生成和拼接，调用者无需关心IV的管理，更加方便安全。

6. 常见问题、性能调优与实战心得

在实际集成和开发过程中，你肯定会遇到各种各样的问题。下面是我总结的一些典型问题及其解决方案，以及一些性能上的考量。

6.1 依赖冲突与NoSuchProviderException

这是集成初期最常见的问题。

问题现象：程序抛出java.security.NoSuchAlgorithmException: no such algorithm: SM4/CBC/PKCS5Padding for provider BC或NoSuchProviderException: no such provider: BC。

排查步骤：

1. 确认依赖：检查pom.xml或build.gradle，确保bcprov-jdk15to18和hutool-all的依赖已正确引入且版本兼容。
2. 确认Provider注册：确保在调用任何国密算法相关代码之前，已经成功执行了Security.addProvider(new BouncyCastleProvider())。使用我们前面推荐的GmUtil.initBouncyCastle()幂等方法。
3. 检查类路径冲突：如果你的项目是一个大型Web应用，可能存在多个不同版本的Bouncy Castle Jar包。使用mvn dependency:tree命令查看依赖树，排除掉冲突的低版本或非必要依赖。
4. JDK版本问题：尝试更换Bouncy Castle的artifactId，如在JDK11+环境下，如果bcprov-jdk15to18不行，可以试试bcprov-jdk18on。

6.2 SM2解密或验签失败

可能原因及解决方案：

6.3 性能考量与最佳实践

1. 算法选择：

   • 非对称加密（SM2）：计算开销大，速度慢。不适合加密大量数据。通常用于加密对称加密的密钥（密钥协商）或进行数字签名。
   • 对称加密（SM4）：计算开销小，速度快。适合加密实际的业务数据、报文体、文件等大量数据。
   • 摘要算法（SM3）：速度很快。用于完整性校验和密码存储。

2. 典型混合加密流程： 在实际的安全数据传输中，通常采用混合加密体系，结合了非对称加密和对称加密的优点：

   • 发送方：随机生成一个一次性的SM4会话密钥，用SM4加密原始数据得到密文A。再用接收方的SM2公钥加密这个SM4会话密钥，得到密文B。将密文A和密文B一起发送给接收方。
   • 接收方：用自己的SM2私钥解密密文B，得到SM4会话密钥。再用这个SM4会话密钥解密密文A，得到原始数据。
   • 优点：既利用了SM4加密大数据的高效性，又利用了SM2非对称加密安全交换密钥的优点。

3. 密钥生命周期管理：

   • 对称密钥（SM4）：建议定期更换（如每次会话、每天）。可以使用密钥派生函数从主密钥和随机数生成会话密钥。
   • 非对称密钥对（SM2）：生命周期较长（如一年或更久），但也需要定期更换。过期密钥应及时归档或销毁。
   • 绝对不要将密钥硬编码在源代码中。使用专业的密钥管理系统（KMS）或至少是安全的配置中心。

4. 日志安全：

   • 在日志中，务必避免打印出完整的密钥、明文密码、加密前的敏感数据。
   • 即使打印密文，也要注意日志聚合系统可能存在的风险。可以只打印密文的前后几位用于调试，如encryptedData: a1b2c3...f0e9。

6.4 与外部系统对接的注意事项

当你需要与使用其他语言（如C++、Python、Go）或不同密码库（如GmSSL、TongSuo）实现的国密系统对接时，要格外小心：

1. 密钥格式：确认对方提供的公钥/私钥是哪种编码格式（PEM, DER）和标准（PKCS#1, PKCS#8）。Hutool主要处理Base64或Hex编码的PKCS#8格式。可能需要使用KeyUtil或Bouncy Castle的低阶API进行转换。
2. 签名/验签格式：SM2签名值通常由两个大整数(r, s)组成。不同库对这两个值的编码和拼接方式可能不同（如ASN.1 DER编码或简单拼接）。Hutool默认使用ASN.1 DER编码。对接时需要明确约定。
3. 加密填充模式：SM2加密本身有特定的填充标准（如SM2标准中定义的）。Hutool封装后默认使用标准填充。与底层库对接时需确认。
4. IV处理：对于SM4-CBC，必须明确IV的生成方式、长度（16字节）以及如何与密文一起传递（通常是拼接在密文前）。

最好的对接方式是，在联调前，双方先用一组标准的测试向量（可以从国密标准文档或权威测试网站获取）进行自测和互测，确保基础算法实现一致。

我个人在几个金融和政府项目里趟平了国密集成的路，最大的体会就是：细节决定成败。一个依赖版本、一个编码格式、一个初始化步骤的疏忽，都可能导致整个加解密流程失败。希望这份融合了实战代码和踩坑经验的指南，能帮你把国密集成这条路走得顺畅一些。如果遇到文中没覆盖的怪问题，不妨从Bouncy Castle的Provider是否成功注册、密钥格式、数据编码这几个最经典的排查点入手，祝你好运。