💡 完全に動作するサンプルは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 を指すように同じコードを利用できます。