Vault PKIエンジン 実務ガイド：証明書発行と管理（Associate/Ops対応）

本稿は、VaultのPKIエンジンで「安全に証明書を発行・管理」するための実務指針を、Associate/Opsレベルの資格対策に沿ってまとめたものです。

公式ドキュメントの安定機能に基づき、用語整理、セットアップ、ロール設計、運用、セキュリティ、トラブル対応までを一気通貫で解説します。

PKIエンジンの全体像と基本用語

VaultのPKIエンジンは、内部または外部のルートCA/中間CAを起点に、X.509証明書を発行・失効し、CRLや（バージョンにより）OCSPレスポンスを提供するための専用エンジンです。運用の中心は「ロール（roles）」で、発行可能なドメイン、SAN、TTL、鍵種別/サイズ、Key Usageなどの制約を定義します。

推奨設計は、オフラインRoot CAで中間CAを署名し、その中間CAをVaultに搭載して日常の発行を担当させる方式です。CRL配布点や発行済みCA証明書のURLは、pki/config/urlsで公開エンドポイントとして設定します。

試験・実務で混同しやすい点はTTLの境界です。リクエスト時のttlは、ロールのmax_ttlとエンジンのmax-lease-ttl（tuneで設定）の双方を超えられません。失効はserial_number指定で行い、CRLは自動再構築を有効化して最新状態を配布します。

• ロールが発行ポリシーの中核（allowed_domains, allow_subdomains, key_type, max_ttl等）
• ttl ≤ role.max_ttl ≤ mount.max_lease_ttl（超過するとエラー）
• オフラインRoot + Vault中間CAが実務の定番
• CRL/発行CA URLをpki/config/urlsで外部公開
• CSR署名（sign/<role>）と鍵付き発行（issue/<role>）を使い分ける

発行フロー（オフラインRoot + Vault中間CA）

 [Client]                          [Vault (pki_int)]                      [Offline Root]
    |   CSR (optional)  issue/sign         |   verify policy/role          |  used only to sign
    |------------------------------------->|--------------------------------|  intermediate once
    |                                      |                                 |
    |<------------ cert/key/chain ---------|                                 |
    |                                      |-- CRL build / OCSP (ver.dep) --|
    |<------------- CRL/OCSP --------------|                                 |

 説明:
 - Vaultは中間CAを保持。Rootはオフライン保管。
 - 発行: issue/<role> で秘密鍵も生成し返却、sign/<role> でCSRを署名。
 - CRL/OCSPの配布URLは pki/config/urls で設定。

概念セクション（参考：CLIは後続セクションで詳述）

# このセクションは用語と全体像の説明です。
# 実コマンドは次セクション以降を参照してください。

セットアップの流れ（最小構成から実用構成へ）

最小構成は単一マウントでRootを内蔵して即時発行できますが、実運用は「オフラインRoot + Vault中間CA」構成が基本です。Root用と中間用でマウントを分けるとTTLや運用方針を明確に分離できます。

URL公開（issuing_certificates, crl_distribution_points）は早い段階で設定し、アプリが即時にチェーンとCRLへ到達できるようにします。

• Root用マウント（pki_root）と中間用マウント（pki_int）を分離
• 中間CAのCSRをRootで署名し、pki_intに取り込み
• pki_int/config/urls を必ず設定（CAチェーン/CRLの外部到達性）
• ロール定義 → テスト発行 → CRLの自動再構築を確認

典型的手順（オフラインRoot + Vault中間CA）

# 1) マウント作成（Root/Intermediateを分離推奨）
vault secrets enable -path=pki_root pki
vault secrets tune  -path=pki_root -max-lease-ttl=87600h

vault secrets enable -path=pki_int pki
vault secrets tune  -path=pki_int  -max-lease-ttl=8760h

# 2) Rootを内蔵生成（Rootをオフライン運用するなら以降は停止/隔離）
vault write pki_root/root/generate/internal \
  common_name="Example Corp Root CA" \
  ttl=87600h

# 3) 中間CAのCSRを生成
vault write -field=csr pki_int/intermediate/generate/internal \
  common_name="Example Corp Intermediate CA" > pki_int.csr

# 4) Rootで中間CAを署名し、バンドルを取り込み
vault write -field=certificate pki_root/root/sign-intermediate \
  csr=@pki_int.csr format=pem_bundle ttl=43800h > pki_int.pem
vault write pki_int/intermediate/set-signed certificate=@pki_int.pem

# 5) URLの公開設定（CAチェーン/CRLの外部到達性）
vault write pki_int/config/urls \
  issuing_certificates="https://vault.example.com/v1/pki_int/ca" \
  crl_distribution_points="https://vault.example.com/v1/pki_int/crl"

# 6) ロール作成（発行ポリシー）
vault write pki_int/roles/web \
  allowed_domains="example.com" \
  allow_subdomains=true \
  allow_bare_domains=true \
  max_ttl="168h" \
  key_type="rsa" key_bits=2048 \
  require_cn=false

# 7) 発行（鍵同梱）
vault write pki_int/issue/web \
  common_name="api.example.com" \
  alt_names="api-1.example.com" \
  ip_sans="10.0.0.10" \
  uri_sans="spiffe://cluster/ns/prod/sa/api" \
  ttl="24h"

# 8) CRL自動更新（名称/詳細はバージョンで差異があるため導入前に確認）
vault write pki_int/config/crl auto_rebuild=true expiry="72h"

ロール設計と発行パラメータ（試験で狙われやすい要点）

ロールは「どの名前に、どの鍵・拡張で、最大どれくらいのTTLまで発行できるか」を縛る最小単位です。SANベース運用が主流のため、require_cn=falseを指定し、CNに依存しない設計が安全です。

ttlパラメータはロールのmax_ttlとエンジンのmax-lease-ttlの両方で上限がかかります。どちらか一方でも超えるとエラーになります。KeyUsage/ExtKeyUsageは用途（例：サーバ認証、クライアント認証）に合わせて明示します。

• allowed_domains と allow_subdomains の組み合わせでFQDN許可範囲を定義
• allowed_uri_sans, allowed_ip_sans でSANの種類を制御
• key_type=rsa|ec、rsaはkey_bits、ECはnamed_curveを選択
• key_usage と ext_key_usage は用途適合（server_auth, client_auth 等）
• sign/<role>（CSR署名）と issue/<role>（Vaultが鍵生成）の使い分け

ロール定義とCSR署名の例

# サーバ認証/クライアント認証を許容するロール
vault write pki_int/roles/app \
  allowed_domains="svc.cluster.local,example.internal" \
  allow_subdomains=true \
  require_cn=false \
  max_ttl="240h" \
  key_type="ec" \
  key_bits=256 \
  key_usage="DigitalSignature,KeyEncipherment" \
  ext_key_usage="ServerAuth,ClientAuth" \
  allowed_uri_sans="spiffe://cluster/*" \
  allowed_ip_sans="10.0.0.0/8"

# CSRを渡して署名（秘密鍵はアプリ側で管理）
openssl req -new -newkey rsa:2048 -nodes -keyout server.key -subj "/CN=api.svc.cluster.local" -reqexts SAN \
  -config <(printf "[req]\ndistinguished_name=req\n[SAN]\nsubjectAltName=DNS:api.svc.cluster.local,URI:spiffe://cluster/ns/prod/sa/api") \
  -out server.csr

vault write pki_int/sign/app [email protected] ttl="24h"

発行・失効・CRL/OCSPの運用ポイント

失効はserial_numberを指定して実行します。CRLは自動再構築を有効化し、配布URLを通じてクライアントが取得できることを定期点検します。発行数が多い場合は、tidyで古いエントリをクリーンアップします（安全バッファを十分に確保）。

OCSPはバージョンにより提供方法や可否が異なるため、導入時にサポート状況を確認してください。CRLのみでの検証でも運用可能ですが、レスポンス速度要件に応じて選択します。

• 失効: vault write pki_int/revoke serial_number=...
• CRL自動再構築（auto_rebuild）とURL公開（config/urls）
• tidyのsafety_bufferで近未来の失効・期限切れ境界を保護
• 大量発行時はCRLサイズと配布レイテンシを監視
• 監査ログ（audit device）で署名操作を追跡

運用系コマンド例（失効、CRL、Tidy）

# 失効（シリアルはコロン区切り形式が一般的）
vault write pki_int/revoke serial_number="15:3a:9f:..."

# CRLの現在値（HTTPで配布する。CLI例は参考）
curl -s https://vault.example.com/v1/pki_int/crl > crl.pem

# Tidy（古い証明書/失効済の整理）。本番はメンテ時間帯などで実行
vault write pki_int/tidy \
  safety_buffer="72h" \
  tidy_cert_store=true \
  tidy_revoked_certs=true

セキュリティ/可用性設計（ポリシー、TTL境界、HA）

発行APIは最小権限で保護します。特定ロールのissue/signのみに絞ったポリシーを付与し、CAやロール定義の変更権限は別ロールに分離します。監査ログを必ず有効化し、発行・失効要求を追える状態にします。

TTLの境界は、エンジン（mount）のmax-lease-ttl、ロールのmax_ttl、発行要求のttlの三層で成立します。期待TTLを満たせない場合、どの層で制限されているかを確認します。Vault自体のHA/レプリケーション設計は、PKIエンジンの可用性を直接左右します。

• ポリシーはissue/signエンドポイントを限定公開（最小権限）
• ロール定義変更は管理者専用ポリシーに分離
• 監査ログ有効化とログ保全（改ざん対策）
• mount.max-lease-ttl ≥ role.max_ttl ≥ 発行時ttl
• PKI用マウントの分離で影響範囲を局所化

ポリシー例（特定ロールの発行のみ許可）

# pki-issue.hcl
path "pki_int/issue/web" {
  capabilities = ["create", "update"]
}
path "pki_int/sign/web" {
  capabilities = ["create", "update"]
}
# 管理系（ロール作成/変更、CA更新）は別ポリシーで管理者のみに付与

# 運用に合わせてマウントの上限TTLを調整
vault secrets tune -path=pki_int -max-lease-ttl=168h

トラブル対応とありがちな落とし穴

TTL超過エラーは、ほとんどがrole.max_ttlまたはmount.max-lease-ttlに起因します。まずロール定義とマウント設定を確認しましょう。SANが拒否される場合は、ロール側のallowed_*_sansに網羅性があるかを見直します。

CRLサイズが肥大化する場合、発行/失効の頻度に対しexpiryや再構築間隔を見直し、tidyの実行も計画に組み込みます。チェーン不整合（中間証明書の欠落）はconfig/urlsのissuing_certificatesが正しく公開されているかを確認します。

• エラー: requested ttl is greater than the maximum allowed → role.max_ttl と mount.max-lease-ttlを確認
• SAN拒否 → allowed_uri_sans / allowed_ip_sans / allowed_domains の再確認
• チェーン不整合 → issuing_certificates URLから正しいチェーン取得可否を確認
• CRL取得失敗 → crl_distribution_pointsの公開可否/ネットワーク到達性を確認
• シリアル表記ミス → コロン区切り形式に統一

確認に使える読み取り系コマンド

# CAチェーンの確認
vault read pki_int/ca/pem

# ある証明書シリアルの詳細（REST経由の例）
curl -s https://vault.example.com/v1/pki_int/cert/15:3a:9f:... | jq .

# URL設定の確認
vault read pki_int/config/urls

問題で確認

よくある質問