💡 完整可运行示例已在 GitHub 上提供: sign-pdf-with-vault-managed-key-java

过去的做法很痛苦

Java 签名服务的运行手册往往包含一步没人愿意写下的操作:将 signing.pfx 复制到新主机,然后把密码放入环境变量。从那一刻起,私钥就会出现在至少三个本不该出现的地方。它存在于镜像层、主机的备份以及加载它的 JVM 内存中,堆转储会轻易地把它展示给拥有转储文件的任何人。

External signing 是 GroupDocs.Signature 为 Java 提供的功能,它将文档摘要交给你提供的回调,而不是使用应用加载的私钥进行签名。这正是让你可以删除那一步运行手册的关键。签名密钥迁移到 HashiCorp Vault,服务只保留一个令牌而不是密钥,签名过程中唯一跨网络传输的值是 32 字节的哈希。

当审查提出显而易见的问题——还有谁可以用你的名义签名——以及诚实的答案是“任何曾经拥有该文件的人”时,团队会采用这种方式。即使通过权限和加密卷锁定文件,也只能缩小泄露窗口,无法根除复制。

有更好的办法

Vault 的 Transit 引擎将密码学作为服务提供。你向它发送一个值,它使用内部持有的密钥进行签名并返回结果。Transit 中创建的密钥可以标记为不可导出,这样根本就没有需要复制到主机上的密钥,Vault 也不存储你发送的内容。

这只有在签名库能够委托时才有用,而这正是 GroupDocs.Signature 的作用所在。DigitalSignOptions.setCustomSignHash 接受一个回调。库负责完成除密码学之外的所有工作:打开 PDF,计算签名覆盖的字节范围,对其进行哈希,调用你的回调获取摘要,然后将返回的字节连同证书一起嵌入。

你需要 JDK 8 或更高版本、Maven、本地 Vault 的 Docker,以及用于证书的 BouncyCastle。示例基于 GroupDocs.Signature for Java 26.10 运行;在没有许可证的评估模式下,最多支持 2 页文档。

新方式:回调而非密钥文件

步骤 1 - 从 Vault 读取密钥

服务向 Vault 请求它被授权使用的密钥,并获取带有公钥的版本号。私钥部分永远不会出现在响应中。

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

Vault 返回 404 表示密钥或 Transit 挂载不存在,因此示例将其视为首次运行的初始化,而不是错误。在生产环境中,管理员会预先启用 Transit 并创建密钥,应用的令牌没有权限执行这些操作。

读取一次版本号并保存。一个证书只能包含一个公钥,因此证书和每个签名必须来自同一版本。

步骤 2 - 基于公钥构建证书

PDF 签名携带 X.509 证书,以便验证者能够找到公钥。JDK 本身无法构建签名来源于其他地方的证书,但 BouncyCastle 可以:X509v3CertificateBuilder 会委托给 ContentSigner,而由 Vault 支持的 ContentSigner 只需约十五行代码。

@Override
public byte[] getSignature() {
    try {
        byte[] digest =
            MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
        return vault.signHash(keyName, keyVersion, digest, "sha2-256");
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

BouncyCastle 将待签名的字节写入签名者的流,然后请求签名。字节在本地进行哈希,只有摘要会发送到 Vault。接口不声明受检异常,因此 Vault 失败必须以包装形式向外抛出并由调用方解包;如果不这样处理,Vault 返回的 403 会表现为令人困惑的运行时错误。

步骤 3 - 签名后立即验证

DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);

DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);

ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));

在回调内部,摘要会发送到 transit/sign,并携带两个决定结果有效性的字段:prehashed = true(因为输入已经是哈希),以及 signature_algorithm = pkcs1v15(因为 Vault 默认对 RSA 密钥使用 PSS,而 PDF 签名要求的是 sha256WithRSAEncryption)。

随后在文件写入任何位置之前进行验证。一次运行中完成签名和验证,能够将唯一的静默失败模式转变为即时可见的错误。

对比:改动前后

主机上的 PFX Vault Transit 回调
私钥的副本数量 每台主机、镜像和备份各一份 仅一份,存放在 Vault 中
服务持有的内容 密钥及其密码 仅限两个操作的令牌
部署新主机的步骤 复制 PFX 并设置密码 无需任何操作
每次签名的记录 应用日志(如果有记录) Vault 的审计条目
发现泄露后的处理 撤销、重新发行、在所有地方重新部署 在 Vault 中轮换,重新发行一次
谁可以以你的名义签名 拥有文件和密码的任何人 拥有有效 Vault 令牌的任何人

最后一行值得明确说明:这并没有消除秘密,而是将其迁移。令牌是短期的、可在单点撤销、仅限读取一个密钥并调用签名,并且每次使用都会被记录。

实际案例:对账单服务

某服务生成月度对账单并在将其放入客户门户前进行签名。过去的做法是容器镜像中携带证书,且三个人拥有密码,因为需要有人轮换它。使用回调后,镜像不再包含任何秘密:Pod 启动时获取 AppRole 令牌,vault/sample-signer.hcl 中的策略允许读取密钥并进行签名,令牌的任何其他操作都会返回 403 permission denied。

当审计员询问三月份签署了多少文档以及使用了哪个密钥版本时,答案来自 Vault 的审计设备,而不是从应用日志中 grep 得到。

轮换是此设计发挥价值的地方,也可能带来风险。执行 transit/keys/:name/rotate 后,Vault 会使用最新版本进行签名,除非另有指定。因此,使用版本 1 构建的证书配合版本 2 的签名会产生一个看似正常但无法验证的 PDF。因为签名者在构造时绑定了特定版本,这种情况不会意外发生:对账单服务会一直使用其证书所属的版本进行签名,直到有人为新版本颁发新证书。随后在密钥上设置 min_encryption_version,旧版本将不可用,Vault 会以拒绝签名而非错误签名的形式响应。

在 26.10 版本上会遇到哪些怪癖?

四个,都是在运行此构建时发现的。ICustomSignHash 方法名在 jar 中被混淆,所以请传入方法引用而不是实现接口。签名输出会在签名块之外带有零字节,需要去除。DigitalVerifyOptions 需要的是证书文件而不是流。最后,可见的签名框需要系统已安装 Arial 字体。

还能用 GroupDocs.Signature 做什么?

回调本身并不知道背后是什么实现,因此相同的三步可以用于硬件模块、智能卡或云 KMS。我将此示例从 .NET 和 Python 版本移植而来,Vault 的请求体保持不变;证书构建以及上述四个怪癖是唯一真正与 Java 相关的部分。除了数字签名,库还支持在 PDF、Word、Excel、PowerPoint 和图片格式中添加和搜索文本、图像、条形码、二维码以及元数据签名。

结论

在 Java 中实现不持有私钥的 PDF 签名,需要一个回调、一个围绕公钥构建的证书以及一个具备两项权限的令牌。示例在开发模式的 Vault 上仅用两条命令即可运行,同样的代码通过修改 VAULT_ADDR 和 VAULT_TOKEN 即可指向生产环境的 Vault。

其他资源