跳至主要內容

Java 使用手册

Java 使用手册

本手册只描述 0.10.1 已发布行为。主包提供 SM2、SM3、SM4、ZUC 和混合加密；SM9 是包含本地动态库（native）的独立制品。

选择制品

普通国密算法只引入主包：

<dependency>
  <groupId>cn.gmkit</groupId>
  <artifactId>gmkit</artifactId>
  <version>0.10.1</version>
</dependency>

使用 SM9 时再增加：

<dependency>
  <groupId>cn.gmkit</groupId>
  <artifactId>gmkit-sm9</artifactId>
  <version>0.10.1</version>
</dependency>

两个制品最低支持 Java 8。gmkit-sm9 是否能运行还取决于操作系统、CPU 架构和 JAR 中是否包含对应本地库，不能只靠 Maven 依赖解析成功判断。

首次运行

下面的 JUnit 测试不注册全局 Provider。它创建一个 BC Provider 实例，连同 SecureRandom 放入 GmSecurityContext，随后验证 SM2 密钥生成和 SM3 固定向量。

package cn.gmkit;

import cn.gmkit.core.BcProviders;
import cn.gmkit.core.GmSecurityContext;
import cn.gmkit.sm2.SM2;
import cn.gmkit.sm2.SM2KeyPair;
import cn.gmkit.sm3.SM3Util;
import org.junit.jupiter.api.Test;

import java.security.Provider;
import java.security.SecureRandom;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;

class ManualJavaStartTest {

    @Test
    void verifiesProviderRandomAndFixedVector() {
        // 1. 创建 Provider：实例直接传给算法，不修改 JVM 的全局 Provider 顺序。
        Provider provider = BcProviders.create();
        GmSecurityContext context = GmSecurityContext.builder()
            .provider(provider)
            .secureRandom(new SecureRandom())
            .registerProvider(false)
            .build();
        assertFalse(context.registerProvider());
        assertEquals("BC", context.provider().getName());

        // 2. 生成 SM2 密钥：验证 Provider 和 SecureRandom 能完成随机密码操作。
        SM2KeyPair keyPair = new SM2(context).generateKeyPair();
        assertEquals(64, keyPair.privateKey().length());
        assertEquals(130, keyPair.publicKey().length());

        // 3. 计算 SM3 固定向量：SM3("abc") 必须得到标准 32 字节摘要。
        assertEquals(
            "66c7f0f462eeedd9d1f2d46bdc10e4e2"
                + "4167c4875cf2f7a2297da02b8f4ba8e0",
            SM3Util.digestHex("abc"));

        // 4. 随机源断言：安全上下文必须始终提供非空 SecureRandom。
        assertNotNull(context.secureRandom());
    }
}

运行本手册的主包样例：

cd packages/java
mvn -B -ntp -pl gmkit \
  -Dtest=ManualJavaStartTest,ManualJavaCoreTest,ManualJavaSm2Test,ManualJavaSm3Test,ManualJavaSm4Test,ManualJavaZucTest \
  test

Provider 策略

策略配置对 JVM 全局状态的影响使用位置
默认上下文new SM2()、new SM4()首次取 Provider 时确保 BC 已注册独立应用、简单接入
显式且不注册registerProvider(false)不修改 Security Provider 列表容器、共享 JVM、测试
显式且自动注册registerProvider(true)调用 context.provider() 时按需注册应用启动层统一管理

同一业务模块应把一个不可变 GmSecurityContext 传给 SM2 和 SM4。不要在请求处理中反复修改 JVM Provider 顺序。

主线入口

任务本手册使用的入口说明
SM2new SM2(context)标准 `SM3(Z
SM3SM3Util一次性摘要和 HMAC，无需保存实例
SM4new SM4(context) + SM4Options模式、nonce、AAD 和 tag 明确放入选项
ZUCZUC 静态方法区分 byte、word 和 bit 长度
SM9SM9 门面 + 句柄类型独立制品；所有句柄使用 try-with-resources

按任务阅读

基础核心类型与错误编码、字节、Provider、安全上下文和异常。身份与密钥SM2标准 Z 签名、C1C3C2 加解密和密钥交换。摘要与认证SM3固定向量、HMAC、String、byte[] 和 Charset。业务数据SM4GCM、AAD、tag、二进制和认证失败。协议指定ZUC密钥流、EEA3、EIA3 和 bitLength。独立制品SM9平台检查、KGC、身份私钥、IBE、PEM 和句柄。大消息SM2 + SM4会话 key、GCM 载荷、篡改失败和 schema。

已发布兼容入口统一见旧系统迁移，不要带入新协议。全部签名见 Java API 说明书。

最近更新: