跳至主要內容

Java 对接指南

mumu2025/11/23大约 24 分钟开发指南集成JavaHutoolBouncy CastleKona对接其他语言

Java 对接指南

提示

提示：本章要点

  • 依赖配置
  • JDK 1.8 低版本 & JCE 限制（Oracle vs OpenJDK）
  • 数据要点
  • 模式与填充详解
  • 完整互通示例（Java 端端到端）

本页聚焦 Java 端与 gmkitx 的互通，提供四种集成方案：

项目说明
Hutool + Bouncy Castle推荐方案，需要引入 BC 依赖
直接使用 Bouncy Castle底层实现，更灵活
Tencent Kona SM SuiteJCA 标准提供者，纯 Java 实现
gmkit-java原生 Java 实现（敬请期待）

依赖配置

方案一：Hutool（推荐）

提示

提示：注意
Hutool 的国密算法实现依赖 Bouncy Castle 库，必须同时引入 BC 依赖。

<!-- Maven -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-crypto</artifactId>
    <version>5.8.43</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15to18</artifactId>
    <version>1.70</version>
</dependency>
// Gradle
implementation 'cn.hutool:hutool-crypto:5.8.43'
implementation 'org.bouncycastle:bcprov-jdk15to18:1.70'

方案二：Bouncy Castle

<!-- Maven -->
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15to18</artifactId>
    <version>1.70</version>
</dependency>
// Gradle
implementation 'org.bouncycastle:bcprov-jdk15to18:1.70'

方案三：Tencent Kona SM Suite

Tencent Kona SM Suite 基于 JCA 标准提供者实现 SM2/SM3/SM4，适合希望遵循 JDK 原生 API 的场景。

<!-- Maven -->
<dependency>
    <groupId>com.tencent.kona</groupId>
    <artifactId>kona-crypto</artifactId>
    <version>1.0.19</version>
</dependency>
<dependency>
    <groupId>com.tencent.kona</groupId>
    <artifactId>kona-provider</artifactId>
    <version>1.0.19</version>
</dependency>
// Gradle
implementation 'com.tencent.kona:kona-crypto:1.0.19'
implementation 'com.tencent.kona:kona-provider:1.0.19'

提示

提示：说明
仅需 SM2/SM3/SM4 时引入 kona-crypto 即可；若需要一站式 Provider，可额外引入 kona-provider。

版本说明（Hutool & BC）

  • Hutool 示例统一使用 5.8.43，避免 API 差异导致的互通偏差。
  • Bouncy Castle 建议固定版本以稳定互操作。本文示例以 bcprov-jdk15to18:1.70 为基准。
  • 为避免默认值差异，请显式指定 SM2 密文模式（C1C3C2/C1C2C3）与签名格式（DER/RAW）及编码方式。

Bouncy Castle 版本/产物说明（务必看）

BC 的 artifactId 随版本发生过命名与打包策略变更，最常见的坑是“引错包 / 混用包 / 多版本冲突”。下面把“每个产物家族的适用范围与问题”写清楚（这里说的“版本”指 jdk18on/jdk15to18/jdk15on/jdk14 这些产物家族，而不是具体的 1.70/1.83 版本号）：

1) bcprov-jdk18on（JDK 8+ 主线）

项目说明
适用范围Java 8 及以上。
特性Multi-Release JAR（同一包内为不同 JDK 提供优化实现）。
  • 常见问题：
    • 某些旧容器/打包器/OSGi 运行时对 Multi-Release JAR 识别不全，可能出现类加载异常或能力识别错误。
    • 如果工程同时引入了 bcprov-jdk15on 或 bcprov-jdk15to18，容易出现重复类或类冲突。
  • 何时用：JDK 8+ 且运行环境对 Multi-Release JAR 兼容良好，优先使用。

2) bcprov-jdk15to18（JDK 1.5–1.8 兼容）

项目说明
适用范围Java 1.5–1.8，或无法正确处理 Multi-Release JAR的运行环境。
特性非 Multi-Release 版本，兼容性更保守。
  • 常见问题：
    • 与 bcprov-jdk18on 或 bcprov-jdk15on 同时存在时，重复类冲突最常见。
    • 某些依赖默认拉 -jdk18on，如果你手动引 -jdk15to18 但未排除传递依赖，会出现“双包共存”。
  • 何时用：需要兼容旧 JVM、老容器或对 Multi-Release JAR 有限制的环境。

3) bcprov-jdk15on（历史产物）

项目说明
适用范围历史包名（BC 1.70 及之前常见）。
现状自 1.71 起不再作为主线发布，被 jdk18on 取代。
  • 常见问题：
    • 新版本生态（如依赖 -jdk18on）下容易产生多包冲突。
    • 与 -jdk15to18 混用时，重复类/方法签名冲突是高发问题。
  • 何时用：不建议在新项目中继续使用。除非历史项目被锁死且无法升级。

4) bcprov-jdk14

项目说明
适用范围仅用于非常老的 JVM（JDK 1.4）。
现状现代工程基本不使用。

为什么会冲突（一定要统一）

项目说明
BC 1.71 的打包变更jdk15on 更名为 jdk18on，基础版本提升到 Java 8。若环境不能处理 Multi-Release JAR，则应改用 jdk15to18。
Multi-Release 限制官方说明 jdk18on 是 multi-release；若需要专门面向 Java 1.8 的版本，应使用 jdk15to18。
重复类冲突bcprov-jdk15on / bcprov-jdk15to18 / bcprov-jdk18on 是不同产物，不是版本号差异，混用会导致重复类或类缺失。
OSGi/容器问题Multi-Release JAR 需要容器正确识别；旧容器可能只看到主版本类或能力识别不完整。BC 1.78.1 起增加了对 OSGi 的 multi-release 元数据支持，但老版本环境仍可能有坑。

推荐的选型与排雷清单

选择速查表

场景推荐产物
JDK 8+ 且容器/构建链支持 Multi-Releasebcprov-jdk18on（配套 bcpkix-jdk18on / bcutil-jdk18on）
JDK 8 但运行环境对 Multi-Release 不友好bcprov-jdk15to18（配套 bcpkix-jdk15to18 / bcutil-jdk15to18）
JDK 7 及以下bcprov-jdk15to18 或更旧的 bcprov-jdk14（视 JVM 版本而定）
  1. 只保留一个 BC 产物族（建议三件套一起锁）：
    bcprov + bcpkix + bcutil 同版本、同系列（jdk18on 或 jdk15to18）。
  2. 显式排除冲突依赖：
    对传递依赖中的 bcprov-jdk15on / bcprov-jdk18on / bcprov-jdk15to18 做 exclude，确保只留下一个。
  3. 运行时确认：
    若遇到 ClassNotFound / NoSuchMethodError / Duplicate class，优先检查 BC 是否“多包共存”。

JDK 1.8 低版本 & JCE 限制（Oracle vs OpenJDK）

JCE（Java Cryptography Extension）决定了算法与密钥长度的上限，尤其影响 AES-256、RSA 大密钥、部分 TLS 套件等。JDK 1.8 的小版本差异很大，请按版本处理。

相关信息

说明：快速结论

项目说明
8u161+Unlimited cryptography 默认启用（仍可用 crypto.policy 覆盖）。
8u151/8u152Unlimited policy 已随 JDK 提供，但默认仍是 limited，需要手动开启。
< 8u151没有 crypto.policy，需手动安装 JCE policy JAR。
版本时间线（重点小版本）
JDK 版本段关键变化默认行为说明
8u151 / 8u152引入 crypto.policy默认 limitedUnlimited policy JAR 随 JDK 提供，需显式启用
8u161+Unlimited 默认启用默认 unlimited同时保留 limited，可用 crypto.policy 切换
< 8u151没有 crypto.policy默认 limited需手动下载/替换 policy JAR

Oracle JDK vs OpenJDK（务必验真）

两者差异更多来自发行版打包策略而非代码实现本身：

发行版常见默认行为风险提示
Oracle JDK（8u161 之前）默认 limitedAES-256 等需要开启/安装 unlimited policy
OpenJDK 发行版很多发行版默认可用 AES-256具体行为依赖发行版，务必运行时检测

结论：不要仅凭“Oracle/OpenJDK”判断，以运行时检测为准。

低版本“签名/校验”坑（JCE policy JAR）

如果你从旧 JDK 拷贝 local_policy.jar/US_export_policy.jar 到新版本，可能触发：

java.lang.SecurityException: Jurisdiction policy files are not signed by trusted signers!

原因是 JAR 签名标准在 6u131 / 7u121 / 8u111 后更新，旧 policy JAR 不符合新签名要求。
正确做法：使用目标 JDK 自带的 policy 目录 + crypto.policy，避免跨版本复制。

如何确认当前 JCE 限制（推荐放到启动日志）

import javax.crypto.Cipher;

public class JceCheck {
  public static void main(String[] args) throws Exception {
    System.out.println(Cipher.getMaxAllowedKeyLength("AES"));
  }
}

结果解释：

  • 128 = limited（AES-256 不可用）
  • 2147483647 = unlimited

提示

提示：生产建议

  1. 固定 JDK 小版本（写入 README / 部署脚本）。
  2. 统一 JCE 策略：
    • 8u151/8u152：在 java.security 设置 crypto.policy=unlimited
    • 8u161+：确保没有遗留 legacy policy JAR 干扰
  3. 运行时检测（见 JceCheck）并在启动日志输出。
启用 unlimited 的常见方式
  • 配置文件：编辑 JAVA_HOME/jre/lib/security/java.security，设置
    crypto.policy=unlimited
  • 代码方式（需在 JCE 初始化前执行）：
    java.security.Security.setProperty("crypto.policy", "unlimited");
  • 注意：8u151/8u152 默认是 limited，未显式设置则不会启用 unlimited。
参考链接

方案四：gmkit-java

相关信息

说明：开发中
gmkit-java 是纯 Java 实现的国密算法库，不依赖第三方库。敬请期待！

<!-- 即将发布 -->
<dependency>
    <groupId>com.cherryrum</groupId>
    <artifactId>gmkit-java</artifactId>
    <version>1.0.0</version>
</dependency>

数据要点

项目约定备注
SM2 公钥非压缩 04+X+Y（130 hex）保持与 Java 侧一致
SM2 私钥64 hex参见 defaults.sm2PrivateKeyHex
SM2 密文模式C1C3C2（默认）、C1C2C3两端一致
SM4 密钥32 hex（128bit）
SM4 填充PKCS7/PKCS5，或 NONE/ZERO流模式不填充
传输编码UTF-8 + 小写 hex

模式与填充详解

SM2 密文模式

SM2 加密后的密文由三部分组成：

项目说明
C1椭圆曲线点（65字节，非压缩格式）
C2密文数据（与明文等长）
C3摘要值（32字节，SM3哈希）

两种排列模式：

项目说明
C1C3C2gmkitx 默认模式，国密标准推荐格式
C1C2C3部分旧版实现使用，需显式指定

注意

注意：重要
对接时必须确保双方使用相同的密文模式，否则无法正确解密！

提示

提示：Kona 说明
Tencent Kona 的 SM2 Cipher 输出 ASN.1 DER（C1C3C2），gmkitx 解密时可自动识别 0x30 开头的 ASN.1 格式。

SM4 填充模式

SM4 是分组密码，块大小为 16 字节。当明文长度不是 16 的倍数时需要填充：

  • PKCS7/PKCS5：标准填充，自动添加 1-16 字节填充数据，每个字节值为填充长度
    • 示例：明文 11 字节，填充 5 个 0x05
  • ZERO：补零填充，填充 0x00 直到块大小
    • 注意：解密后需手动去除尾部零
  • NONE：无填充，仅用于 CTR/OFB/CFB 等流模式，或明文已对齐 16 字节

提示

提示：推荐
ECB/CBC 模式推荐使用 PKCS7 填充，可自动处理任意长度明文。

完整互通示例（Java 端端到端）

下面示例展示 SM2 加解密 + 签名验签、SM3 摘要、SM4 CBC 的完整流程。
可直接运行（Hutool + Bouncy Castle），与 gmkitx 互通时只需确保 密钥/IV/模式/编码 一致即可。

import cn.hutool.core.util.HexUtil;
import cn.hutool.crypto.Mode;
import cn.hutool.crypto.Padding;
import cn.hutool.crypto.SmUtil;
import cn.hutool.crypto.asymmetric.SM2;
import cn.hutool.crypto.symmetric.SymmetricAlgorithm;
import cn.hutool.crypto.symmetric.SymmetricCrypto;
import org.bouncycastle.crypto.engines.SM2Engine;

public class FullInteropDemo {
  public static void main(String[] args) {
    // 固定测试向量（与 gmkitx interop.json defaults 一致）
    String sm2PubHex = "045647ebf2adcaf54f8102bea9a7ca8905794a3f2f29622593269bb55d72e0a140dc81f3dce73bb609f8a056640db0e04c08e0bd8be79140702bbdb0206e95b7ac";
    String sm2PriHex = "228049e009de869baf9aba74f8f8c52e09cde1b52cafb0df7ab154ba4593743e";
    String sm4KeyHex = "0123456789abcdeffedcba9876543210";
    String sm4IvHex  = "000102030405060708090a0b0c0d0e0f";

    String message = "Hello GMKit";

    // SM2 加解密 + 签名验签（显式指定 C1C3C2）
    SM2 sm2 = SmUtil.sm2(HexUtil.decodeHex(sm2PriHex), HexUtil.decodeHex(sm2PubHex));
    sm2.setMode(SM2Engine.Mode.C1C3C2);
    String sm2Cipher = sm2.encryptHex(message);
    String sm2Plain = sm2.decryptStr(sm2Cipher);
    String sm2Sig = sm2.signHex(message);
    boolean sm2Ok = sm2.verifyHex(message, sm2Sig);

    // SM3 摘要
    String sm3Hex = SmUtil.sm3().digestHex(message);

    // SM4 CBC + PKCS7/PKCS5
    SymmetricCrypto sm4 = new SymmetricCrypto(
      Mode.CBC,
      Padding.PKCS5Padding, // 与 PKCS7 等价（块大小 16）
      SymmetricAlgorithm.SM4.getValue(),
      HexUtil.decodeHex(sm4KeyHex),
      HexUtil.decodeHex(sm4IvHex)
    );
    String sm4Cipher = sm4.encryptHex(message);
    String sm4Plain = sm4.decryptStr(sm4Cipher);

    System.out.println("SM2 cipher : " + sm2Cipher);
    System.out.println("SM2 plain  : " + sm2Plain);
    System.out.println("SM2 verify : " + sm2Ok);
    System.out.println("SM3 hex    : " + sm3Hex);
    System.out.println("SM4 cipher : " + sm4Cipher);
    System.out.println("SM4 plain  : " + sm4Plain);
  }
}

SM2 对接

gmkitx
import { sm2Encrypt, sm2Decrypt, sign, verify, SM2CipherMode } from 'gmkitx';

// 使用测试向量中的密钥
const publicKey = '04a09455a450af78e7bc6b2f8c7f1e0e...'; // 完整的04开头公钥
const privateKey = '228049e009de869baf9aba74f8f8c52e...'; // 64位十六进制私钥

// 加密 - C1C3C2 模式（默认）
const plaintext = 'Hello, SM2!';
const ciphertext = sm2Encrypt(publicKey, plaintext, { mode: SM2CipherMode.C1C3C2 });
console.log('密文:', ciphertext);

// 解密
const decrypted = sm2Decrypt(privateKey, ciphertext, { mode: SM2CipherMode.C1C3C2 });
console.log('明文:', decrypted); // 'Hello, SM2!'

// 签名
const message = 'Important message';
const signature = sign(privateKey, message);
console.log('签名:', signature);

// 验签
const isValid = verify(publicKey, message, signature);
console.log('验签结果:', isValid); // true

SM3 对接

gmkitx
import { digest, hmac } from 'gmkitx';

// 计算 SM3 摘要
const hash = digest('Hello, SM3!');
console.log('SM3摘要:', hash);
// 输出: 32字节（64位十六进制）哈希值

// HMAC-SM3
const mac = hmac('secret-key', 'message');
console.log('HMAC-SM3:', mac);

// 增量哈希
import { SM3 } from 'gmkitx';
const sm3 = new SM3();
sm3.update('Hello, ');
sm3.update('World!');
const result = sm3.digest();
console.log('增量哈希:', result);

SM4 对接

gmkitx
import { sm4Encrypt, sm4Decrypt, CipherMode, PaddingMode } from 'gmkitx';

const key = '0123456789abcdeffedcba9876543210'; // 32位十六进制（16字节）
const iv = 'fedcba98765432100123456789abcdef';   // CBC模式需要IV
const plaintext = 'Hello, SM4!';

// ECB 模式 + PKCS7 填充
const cipherECB = sm4Encrypt(key, plaintext, {
  mode: CipherMode.ECB,
  padding: PaddingMode.PKCS7
});
console.log('ECB密文:', cipherECB);

const plainECB = sm4Decrypt(key, cipherECB, {
  mode: CipherMode.ECB,
  padding: PaddingMode.PKCS7
});
console.log('ECB明文:', plainECB);

// CBC 模式 + PKCS7 填充
const cipherCBC = sm4Encrypt(key, plaintext, {
  mode: CipherMode.CBC,
  padding: PaddingMode.PKCS7,
  iv
});
console.log('CBC密文:', cipherCBC);

const plainCBC = sm4Decrypt(key, cipherCBC, {
  mode: CipherMode.CBC,
  padding: PaddingMode.PKCS7,
  iv
});
console.log('CBC明文:', plainCBC);

// 面向对象 API
import { SM4 } from 'gmkitx';
const sm4ecb = SM4.ECB(key);
const encrypted = sm4ecb.encrypt('Hello, SM4 OOP!');
const decrypted = sm4ecb.decrypt(encrypted);

扩展指引

  • 本页展示 Java 与 gmkitx 的对接方案；其他语言对接请参考对应的语言指南。
  • 所有语言对接均使用统一的测试向量 test/vectors/interop.json，确保跨语言互操作性。
  • 如需切换 Java 库，保持密钥/IV/模式/编码约定不变，替换代码即可。
  • 扩展 CTR/OFB/CFB/GCM 或固定随机源的 SM2 用例时，先确认计数器/AAD/随机策略一致，再写入测试向量并在备注中标明。