💡 完全に動作するサンプルはGitHubで入手できます: sign-pdf-with-vault-managed-key-java

以前の方法は苦痛だった

Java の署名サービスのランブックには、誰も書きたがらない手順が含まれがちです。signing.pfx を新しいホストにコピーし、パスワードを環境変数に設定する、というものです。この時点で、秘密鍵は意図した以上に少なくとも 3 カ所に存在します。イメージ層、ホストのバックアップ、そしてそれをロードする JVM のメモリです。ヒープダンプを取得すれば、ダンプを持つ者は誰でも鍵を見ることができます。

外部署名は Java 用 GroupDocs.Signature の機能で、アプリケーションが秘密鍵で署名する代わりに、あなたが提供するコールバックに文書ダイジェストを渡します。これにより、ランブックの手順を削除できます。署名鍵は 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 を有効化し、事前に鍵を作成し、アプリケーションのトークンはどちらも実行できないようにします。

バージョンは一度取得して保持します。証明書は正確に 1 つの公開鍵を保持するため、証明書とすべての署名は同じバージョンから来る必要があります。

手順 2 - 公開鍵から証明書を構築

PDF 署名は X.509 証明書を含み、検証者が公開鍵を取得できるようにします。JDK だけでは外部署名から証明書を作成できませんが、BouncyCastle なら可能です。X509v3CertificateBuilder は ContentSigner に委譲し、Vault バックエンドの ContentSigner は約 15 行で実装できます。

@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 に送ります。このとき 2 つのフィールドで結果の有効性が決まります:prehashed = true(入力はすでにハッシュであるため)と signature_algorithm = pkcs1v15(Vault のデフォルトは RSA 鍵で PSS ですが、PDF 署名は sha256WithRSAEncryption が必要です)。

その後、ファイルがどこかに行く前に検証します。署名と検証を同一実行で行うことで、唯一のサイレント失敗モードが即時エラーに変わります。

並列比較:Before vs. After

ホスト上の PFX Vault Transit コールバック
秘密鍵のコピー数 ホスト、イメージ、バックアップごとに 1 つずつ Vault 内に 1 つ
サービスが保持するもの 鍵とパスワード 2 つの操作に限定されたトークン
新しいホストへのデプロイ手順 PFX をコピーし、パスワードを設定 なし
各署名の記録 アプリケーションログ(記録されていれば) Vault の監査エントリ 1 件
漏洩が疑われた場合 鍵を取り消し、再発行し、全て再デプロイ Vault でローテーションし、1 回だけ再発行
あなたになりすまして署名できる人 ファイルとパスワードを持つ全員 有効な Vault トークンを持つ全員

最後の行ははっきり述べておく価値があります:これはシークレットを廃止するのではなく、シークレットを「移動」させます。トークンは短命で、1 カ所で取り消し可能、1 つの鍵の読み取りと署名に限定され、使用されるたびにログが残ります。

実例:ステートメントサービス

あるサービスは月次ステートメントを生成し、顧客ポータルに投入する前に署名します。従来の構成ではコンテナイメージに証明書が含まれ、パスワードは 3 人が保持していました(ローテーション担当者が必要だったため)。コールバックに切り替えると、イメージにはシークレットが全く含まれません。Pod は起動時に AppRole トークンを取得し、vault/sample-signer.hcl のポリシーで鍵の読み取りと署名が許可され、トークンがそれ以外を試みると 403 permission denied が返ります。

監査人が「3 月に何件の文書が署名され、どの鍵バージョンが使われたか」を尋ねたとき、答えはアプリケーションログの grep ではなく Vault の監査デバイスから取得します。

ローテーションはこの設計の価値を発揮する場面でもあり、注意が必要な点でもあります。transit/keys/:name/rotate 後は Vault が最新バージョンで署名します(別途指定しない限り)。そのためバージョン 1 用に作成した証明書とバージョン 2 の署名を組み合わせると、エラーが出ず検証も通らない PDF が生成されます。署名者は単一バージョンで構築されているため、ここでの偶発的ミスマッチは起きません:ステートメントサービスは証明書が属するバージョンで署名し続け、誰かが新バージョン用に新証明書を発行するまでそれを続けます。キーに min_encryption_version を設定すれば古いバージョンは使用不可となり、Vault は署名拒否として応答し、署名が不正になることはありません。

バージョン 26.10 で予想すべき奇妙な点は?

ビルド実行中に見つかった 4 つのポイントです。ICustomSignHash メソッド名が JAR 内で難読化されているため、インターフェースを実装するのではなくメソッド参照を渡します。署名後の出力に署名領域外のゼロバイトが残るので、トリムが必要です。DigitalVerifyOptions はストリームではなく証明書ファイルを要求します。そして、可視署名ボックスを表示するには Arial フォントがインストールされている必要があります。

GroupDocs.Signature で他に何ができる?

コールバックは背後に何があるかを意識しません。そのため、同じ 3 手順でハードウェアモジュール、スマートカード、クラウド KMS でも利用可能です。私は同じサンプルを .NET と Python バージョンから移植しましたが、Vault のリクエストボディは変更なしで流れ、証明書構築と上記 4 つの奇妙な点だけが実質的に Java 固有でした。デジタル署名に加えて、ライブラリは PDF、Word、Excel、PowerPoint、画像形式に対してテキスト、画像、バーコード、QR コード、メタデータ署名の追加と検索も行えます。

結論

Java で秘密鍵を保持せずに PDF に署名するには、コールバック、公開鍵から構築した証明書、そして 2 つの権限を持つトークンが必要です。サンプルは開発モードの Vault に対して 2 コマンドで実行でき、VAULT_ADDR と VAULT_TOKEN を変更すれば本番 Vault を指すように同じコードを利用できます。

追加リソース