HashiCorp Vault Transform エンジン実践ガイド: FPE / マスキング / トークナイゼーションを運用者目線で設計・運用する

Transform エンジンは機密データを“フォーマットを保ったまま”変換するための Vault Enterprise 機能です。用途は大別して3つ、FPE（Format-Preserving Encryption）、マスキング、トークナイゼーション。どれを選ぶかは、可逆性・保存要件・性能・監査要件で決まります。

本稿は運用（Ops）観点で、導入手順、権限設計、レート制限、レプリケーション/DR、ローテーション、よくある落とし穴を具体的にまとめ、Vault の認定（Security Automation 系）対策にも直結する要点を整理します。

Transform エンジンの全体像とユースケース

Transform は Vault Enterprise のシークレットエンジンで、FPE、マスキング、トークナイゼーションの3方式を提供します。アプリは Vault に値を渡し、変換済みの値（またはトークン）を受け取り、保存時や転送時のリスクを下げます。FPE とマスキングは基本的にステートレス（設定と鍵のみ）で、トークナイゼーションは値↔トークンの対応を保存するためステートフルです。

運用上のキーポイントは、変換『定義（transformation）』と『ロール（role）』の分離、テンプレート/アルファベット/チュイーク（tweak）管理、レプリケーション、レート制限、監査/Audit、そして最小権限ポリシーです。Ops では可用性（HA/PR/DR）とスループットを担保しつつ、誤用（例: アルファベット外文字）を即時検知できる監視も必要です。

• Enterprise 専用。FPE は形式保持の可逆暗号、マスキングは不可逆な部分秘匿、トークナイゼーションは参照トークン化。
• ロールに対して使用可能な transformation を限定し、encode/decode/tokenize/detokenize を権限分離。
• FPE はキーバージョンを内部に保持し、ローテーション後の後方互換を考慮（旧バージョンでの decode を許容期間管理）。
• トークナイゼーションはストレージ依存（スキュー/ホットキー対策と TTL/リテンション設計が要点）。

Transform エンジンの論理構成（FPE: ステートレス / Tokenization: ステートフル）

FPE（形式保持暗号）の仕組みと設計ポイント

FPE は NIST SP 800-38G 系列の FF1 モードに基づく形式保持暗号（Vault の実装では FF1 を利用）で、桁数や許可文字集合（アルファベット）を保ったまま暗号化します。入力検証はアルファベットに基づいて厳格に行われ、無効文字が含まれるとエラーを返します。区切り文字の扱いはテンプレート設計（例: 数字ブロックとハイフンの分離）でコントロールします。

設計上はアルファベットの選定（numeric/alphanumeric/カスタム）、テンプレート粒度、チュイーク（tweak）ソース（internal/supplied）を決め、復号が必要な主体だけに decode を許可します。決定論的であるため、同一入力は同一出力になる点を念頭に置き（テストデータ生成に便利）、同値検出リスクとログ露出に注意します。

• アルファベット外文字はエラー。前処理（空白/区切り除去）かテンプレート定義で吸収する。
• tweak は暗号多様性を高める。アプリ供給（supplied）時は取り回しと保管に注意。
• FPE 出力の長さは入力と同じ。スキーマ変更不要だが、索引やユニーク制約の再評価は必須。
• 鍵ローテーション後の decode 可否ポリシー（旧鍵保持期間）を決め、再暗号化のバッチ設計も用意。

マスキングとトークナイゼーション：違いと使い分け

マスキングは不可逆の変換で、監査ログや下流参照のために“最低限の可読性”を残したいときに有効です。暗号鍵やストレージは不要で、性能影響が小さいのが利点です。一方、トークナイゼーションは元値を保存せずにトークンで代用し、必要時のみ detokenize できる方式です。可逆だが、マッピングの保存・レプリケーション・TTL といった運用要素を伴います。

PCI DSS などで PAN を広範に扱う場合は、保存系にはトークンを、限定された境界の中でのみ detokenize を許可するのが定石です。監査ログや開発者プレビューに“見えてよい一部だけ”を残す場合はマスキングを併用します。

• 保存先での検索ニーズが高い場合は FPE（決定論的）またはトークンの二次インデックス設計を検討。
• 不可逆が要件ならマスキング。可逆＋保存せずに参照可能にしたいならトークナイゼーション。
• レイテンシ重視のホットパスは FPE/マスキング、強い分離が必要な保存系はトークナイゼーション。

導入手順（最小構成）と CLI 例

以下は代表的なシーケンスです。実際にはテンプレート/アルファベット名、ロール名、パスは組織標準に合わせて設計してください。正確な API パスや追加パラメータはご利用の Vault バージョンの公式ドキュメントを参照してください。

ポイントは、1) エンジンを有効化、2) transformation を作成、3) role に transformation をひも付け、4) encode/decode または tokenize/detokenize を実行、の4段階です。

• 本番では Namespaces を前提にパスを明示（例: namespace=payments/）。
• 変換系エンドポイントにはレート制限（sys/quotas）を必ず設定。
• 最小権限：encode と decode/tokenize/detokenize をロール・パスで分離。

CLI 例（FPE / マスキング / トークナイゼーション）

# 1) Transform エンジン有効化（Enterprise）
vault secrets enable -path=transform transform

# 2) FPE transformation の作成とロールの作成
vault write transform/role/payments \
  transformations=ccn-fpe

vault write transform/transformations/fpe/ccn-fpe \
  template="16" \
  alphabet="numeric" \
  tweak_source="internal" \
  allowed_roles="payments"

# 3) FPE でエンコード/デコード（ロールスコープ）
vault write transform/encode/payments \
  transformation=ccn-fpe \
  value=4111111111111111

vault write transform/decode/payments \
  transformation=ccn-fpe \
  value=<encoded-value>

# 4) マスキング transformation の作成と利用（例: 9桁を ***-**-**** で一部秘匿）
vault write transform/transformations/masking/ssn-mask \
  template="3-2-4" \
  masking_character="*" \
  allowed_roles="hr"

vault write transform/encode/hr \
  transformation=ssn-mask \
  value=123456789

# 5) トークナイゼーションの作成と利用
vault write transform/tokenization/pan-token \
  allowed_roles="payments" \
  max_ttl=24h

vault write transform/tokenize/payments \
  transformation=pan-token \
  value=4111111111111111

vault write transform/detokenize/payments \
  transformation=pan-token \
  value=<token>

運用とセキュリティ設計：ポリシー、監査、レート制限、レプリケーション

ポリシーはロール単位でエンドポイントを分離します。多くの現場では encode のみをアプリに付与し、decode/detokenize は限られたバッチ/オペレーションだけが実行できるようにします。トークナイゼーションは detokenize と lookup（許可する場合）をさらに限定します。

レプリケーションは Performance Replication（PR）でスループットを確保し、DR で災害対策を行います。トークナイゼーションはマッピングデータを含むため、PR/DR の整合性と遅延が意味を持ちます。RPO/RTO を明示し、バーストに備えて sys/quotas の rate-limit を transform マウント配下に適用します。

• 監査ログ: Transform の入力値/出力値が露出しないよう、適切にマスキング/ハッシュ化される監査デバイス設定を確認。
• レート制限: sys/quotas/rate-limit をロールまたはマウント単位で設定し、ブルートフォース/大量誤送信を遮断。
• メトリクス監視: encode/decode/tokenize/detokenize のレイテンシ、失敗率（invalid alphabet 等）、レプリケーション遅延を可視化。

ポリシー（最小権限）とレート制限の例

# 最小権限ポリシー例（アプリは encode のみ）
path "transform/encode/payments" {
  capabilities = ["update"]
}
# decode は運用ロールのみに
auth_method "userpass" { }
path "transform/decode/payments" {
  capabilities = ["update"]
}
# detokenize はさらに限定
path "transform/detokenize/payments" {
  capabilities = ["update"]
}

# レート制限（1秒あたり 200 リクエスト、バースト 400 の例）
vault write sys/quotas/rate-limit/transform-payments \
  path="transform/encode/payments" \
  rate=200 \
  interval=1s \
  burst=400

ローテーション、可用性、トラブルシューティング

鍵ローテーションは計画的に行い、旧バージョンでの decode を一定期間許容して移行の猶予を設けます。FPE は再暗号化の一括処理（オフライン/バッチ）を用意し、アプリ側キャッシュや二次索引の更新順序を明確にします。

可用性面では、PR で読み取り/処理をスケールし、トークナイゼーションのマップ整合性を常に検証します。DR フェイルオーバー演習は transform エンドポイントも含めてリハーサルし、アプリの再試行と遅延しきい値を事前に検証します。

• よくあるエラー: invalid character（アルファベット外）→ 前処理/テンプレート修正。
• tweak 不一致で decode 失敗→ tweak ソース/供給経路の監査とリトライ方針。
• トークン未検出（TTL 超過/複製遅延）→ 監視と補助的な再問い合わせ/キューイングを設計。

運用 Runbook 例（概念）

# FPE 鍵ローテーション（概念例。実際のパスはドキュメントで要確認）
# 1) 新バージョン発行
vault write -f transform/transformations/fpe/ccn-fpe/rotate
# 2) 旧バージョン decode 許容期間を設定（ポリシー/設定で管理）
# 3) バッチで再暗号化（アプリ/ETL 側で）
# 4) 許容期間終了後、旧鍵を失効

# ヘルスチェック/計測（例）
vault read sys/health
vault metrics

# レプリケーション状態確認
yvault read sys/replication/status   # 実環境では適切な権限で実行

問題で確認

よくある質問