4. SDk 环境搭建：Java PKI SDK（Bouncy Castle）引入与 Maven/Gradle 配置

说实话，在 PKI 相关开发里，Bouncy Castle（BC）几乎就是事实标准。我最早接触它是在做一个银行柜面签名项目，当时被自签名证书折腾得够呛，后来才发现 BC 早就封装好了全套解决方案。这一章我们就来聊聊怎么把 BC 引入项目，把环境搭稳。

4.1 你需要的核心库

Bouncy Castle 不是一个大而全的 jar，它按功能拆成了好几个模块。我个人习惯，只引入真正用到的，避免依赖冲突。下面这个表列出了最常见的选择：

嗯，这里要注意：你选版本号时要看 jdk 版本。BC 从 1.70 开始用「jdk18on」这个后缀，意思是支持 Java 18 及以上。如果项目还在用 Java 11，那就用带「jdk15on」的旧版。我个人强烈建议升级 JDK17+，否则后面有些 SM2/SM4 国密支持会缺。

4.2 Maven 配置

Maven 用户直接在 dependencies 里加这几行。我用的是 1.77 版，你们按实际更新版本号：

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId>
    <version>1.77</version>
</dependency>

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcpkix-jdk18on</artifactId>
    <version>1.77</version>
</dependency>

为什么要显式写版本？我记得有一次项目里同时引了 BC 的旧版和新版，导致 X509CertificateHolder 序列化异常。显式锁定版本后用 mvn dependency:tree 检查一下就放心了。

4.3 Gradle 配置

Gradle 的更简洁。如果是 Kotlin DSL，这么写：

dependencies {
    implementation("org.bouncycastle:bcprov-jdk18on:1.77")
    implementation("org.bouncycastle:bcpkix-jdk18on:1.77")
}

Groovy DSL 也一样，只是语法风格不同。你想想看，这种配置三五分钟就能跑起来，但真要出问题，往往不在配置本身，而在 JDK 的 JCE 策略限制上。下面我们就聊这个。

4.4 注册 Provider——关键一步

依赖拉下来只是第一步。BC 需要作为 Security Provider 注册到 JVM 中，否则 JDK 根本不认它的算法。注册方式有几种，我推荐用代码主动注册：

import org.bouncycastle.jce.provider.BouncyCastleProvider;
import java.security.Security;

public class PkiBootstrap {
    static {
        if (Security.getProvider(BouncyCastleProvider.PROVIDER_NAME) == null) {
            Security.addProvider(new BouncyCastleProvider());
        }
    }
}

为什么用静态块？因为注册动作要在任何 PKI 操作前完成，写在 static 块里最安全。我曾经见过有人把注册写在 Servlet 初始化方法里，结果并发请求先于初始化触发，直接报 NoSuchAlgorithmException。

4.5 验证环境是否就绪

配置好之后，写个简单测试来确认：

public class CheckBcReady {
    public static void main(String[] args) {
        System.out.println("BC Provider version: " +
            Security.getProvider("BC").getVersion());
        
        System.out.println("SM2 available: " +
            (Security.getAlgorithms("KeyPairGenerator")
                .contains("SM2") ? "yes" : "no"));
    }
}

如果输出版本号，就说明 Provider 正确注册了。至于 SM2 支不支持，取决于你引入的是 jdk15on 还是 jdk18on——后者才有完整的国密实现。

4.6 知识结构一览

下面这张图概括了 BC 环境搭建的核心脉络，你把每个绿色节点都跑通了，环境就算稳了：

4.7 一个让我长记性的坑

前面说了静态块判空，但还有一个容易被忽略的问题：JDK 的 JCA 配置文件。在 $JAVA_HOME/jre/lib/security/java.security 里，有个 security.provider. 开头的列表。如果你把 BC 加到这里，它会在 JVM 启动时自动注册。听起来挺方便对吧？我一开始也这么干。

另外，BC 的 Provider 需要放在 Sun 原生 Provider 之后，否则某些算法会冲突。注册顺序可以通过 Security.insertProviderAt(provider, position) 控制，数值越小优先级越高。

4.8 快速检查清单

环境搭建完成后，对照这个清单过一遍，基本不会出问题：

• ✅ bcprov-jdk18on 和 bcpkix-jdk18on 都在 classpath 中
• ✅ 没有因为传递依赖拉入旧版 bcprov（用 dependency:tree 确认）
• ✅ 代码静态块中注册 Provider 并判重
• ✅ 测试代码输出 BC Provider 版本号
• ✅ 如果需要国密 SM2/SM3/SM4，确认版本 >= 1.72（jdk18on）
• ✅ 如果项目部署在容器中，确认各应用不会共用冲突的 BC 版本