AWS Payment Cryptography

AWS Payment Cryptography MCP サーバー

AWS Payment Cryptography（APC）用のMCP サーバーです。AI コーディングアシスタントが、APC のコントロールプレーン（キーライフサイクル）とデータプレーン（暗号処理）に直接アクセスできるようにします。また、決済標準、HSM ベンダーのコマンドセット、PCI PIN v3.1 のコンプライアンス要件に関する知識を内蔵しています。このツールは開発およびテスト目的専用であり、本番システム内で直接使用しないでください。AWS Payment Cryptography に関するドメイン知識を備えたインターフェースを提供し、「概念実証」フェーズと移行分析の迅速化を目的として設計されています。Claude Code、Codex CLI、その他MCP対応クライアントで動作します。

このツールを使う理由は3つあります。

1. APC上で新しいアクワイアラーまたはプロセッサーとの連携を構築しており、API呼び出しごとにドキュメントを読むことなく、キー階層、DUKPT、TR-31/TR-34、PIN形式、コンプライアンス上の制約などのドメイン知識を理解したAIコパイロットを利用したい場合。

2. Thales payShield 10KまたはFuturex Excrypt Enterprise SSP v.2で動作する既存のコードがあり、APCに移行する前に、その動作を理解したい場合。

3. apc-hsm-proxyを使って、リファクタリングせずにアプリケーションをAPCに移行しており、アプリケーションが送信する特定のコマンドに対応するハンドラーを構築する必要がある場合。

カードのパーソナライズ、IMK/CMKの導出、発行者スクリプト処理など、発行者向け機能は対象外です。一部の発行者関連APC操作（PIN生成方式、EMVセキュアメッセージング）は網羅性のために公開していますが、主な対象ではありません。これはテンプレートであり、本番システムではありません。

---

アーキテクチャと信頼境界

graph LR
      subgraph "Your Local Host"
          A[AI Client] <--> B[MCP Server]
          B --> G([Boto3])
      end
      subgraph "Your AWS Account"
          D[APC Control Plane]
          E[APC Data Plane]
      end
      subgraph "Your LLM Provider"
          F[LLM API]
      end

      G --> D
      G --> E
      A <-- "Prompts/Responses" --> F
      D ~~~ F
      D ~~~ E

---

セットアップ

pip install -e .
apc-agent        # starts the MCP server over stdio

このMCP サーバーはクライアントを問いません — 標準のModel Context Protocolをstdio経由で使用し、あらゆるMCP対応クライアントで動作します。.claude/にはClaude Codeの設定が含まれ、.codex/はCodex CLIに相当する設定です。どちらもサーバー自体の実行には必要ありません。

Claude Code — このリポジトリの.claude/settings.jsonがサーバーを自動登録します。Claude Desktopの場合は、同じブロックを~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または%APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "apc-agent": {
      "command": "apc-agent",
      "env": { "AWS_REGION": "us-east-1" }
    }
  }
}

Codex CLI — このリポジトリの.codex/config.tomlがサーバーを自動登録します。ユーザーレベルで登録する場合（すべてのプロジェクトに適用）、同じブロックを~/.codex/config.tomlに追加します。

[mcp_servers.apc-agent]
command = "apc-agent"
env = { AWS_REGION = "us-east-1" }

または、CLIから登録します。

codex mcp add apc-agent --env AWS_REGION=us-east-1 -- apc-agent

Kiro —

AWS認証情報は、標準のboto3チェーン（IAMロール、~/.aws/credentials、または環境変数）を通じて使用されます。APCリソースが存在するリージョンにAWS_REGIONを設定してください。

ワークフローごとに1つずつ、プロンプト、ツール呼び出し、結果を正確に示したエンドツーエンドのセッション抜粋については、EXAMPLES.mdを参照してください。

---

ワークフロー 1 — 新しいインテグレーションの構築

対象者： AWS 上で新しいアクワイアラーまたはプロセッサーシステムを構築する決済エンジニアやソリューションアーキテクト。ゼロから構築する場合も、APC 上でグリーンフィールドとして構築する場合も対象です。

実施内容： アーキテクチャを自然な言葉で説明します。AI は APC を直接呼び出し、各判断の理由を説明し、API を呼び出す前にコンプライアンスを確認します。ドキュメントへの参照だけでなく、動作するコードと鍵の階層を得られます。

仕組み：

1. MCP サーバーをインストールし、AI クライアント（Claude Code、Codex CLI など）に接続します。
2. 構築するものを説明します。例：「POS 端末群向けに AES DUKPT が必要です。PIN ブロックは ISO Format 4 にし、ZPK を介してネットワークプロセッサーに変換して送信し、ISO 8583 のフィールド 64 には CMAC を付ける必要があります。」
3. AI が APC で鍵を作成し、その階層を説明して、インテグレーションコードを記述します。また、API を呼び出す前にコンプライアンス上の問題があれば指摘します。

新しいアクワイアラーインテグレーションのデフォルト：

Terminal / POI
  └── AES DUKPT (BDK in APC, KSN per transaction)
        └── ISO Format 4 PIN block → translate_pin_data
              └── ZPK (AES P0) → host-to-host PIN routing
                    └── CMAC (AES M6) on ISO 8583 field 64

Key Exchange with Network / Processor
  └── TR-34 (asymmetric KEK establishment)
        └── TR-31 / X9.143 for all subsequent symmetric key transport

Card Data Protection
  └── AES (D0) or FF1 FPE for format-preserving tokenization

この方針から逸脱する場合（TDES、Format 0 PIN ブロック、TDES DUKPT、CBC-MAC）は、明示的な確認が必要です。エージェントは最新の方法が推奨される理由を説明し、下流システムが対応していないことを確認済みか尋ねたうえで、文書化されたコードコメントと、QSA の例外承認が必要になる可能性についての通知を添えて、レガシー方式を正しく実装できるよう支援します。

コンプライアンスの適用はツールレイヤーに組み込まれており、無効化できません。コードで適用されるハードストップには、違法な PIN フォーマット変換の組み合わせ（PCI PIN Req 3-3）、KCV が CMAC ではない AES 鍵（PCI PIN Annex C）、不明な TR-31 鍵用途コードが含まれます。レガシー構成（Format 0、CBC-MAC、リテール MAC）の警告では、続行する前に明示的な確認が必要です。PIN 変換中の PAN の同一性確認、およびアルゴリズムレベルの禁止事項（シングル DES、RSA < 2048）は APC によって API レベルで適用され、禁止パラメーターを含む呼び出しはサービスによって拒否されます。

---

ワークフロー 2 — 既存の HSM コードの移行

対象者： 現在、Thales payShield 10K または Futurex Excrypt Enterprise SSP v.2 にコマンドを送信するアプリケーションを移行しており、APC の置き換えコードを書く前に、コードの動作を把握する必要がある開発者。

作業内容： 既存のソースコードを AI に提示します。AI は使用中の HSM 操作をすべて特定し、それぞれを正しい鍵タイプに対応する APC 呼び出しにマッピングします。また、直接対応するものがない操作や、アーキテクチャの変更が必要な操作を明示します。

仕組み：

1. MCP サーバーを AI クライアントに接続し、関連するソースファイルを開きます。
2. コードを分析するよう依頼します。例：「このコードではどの HSM 操作が使われていますか？ APC での同等の操作は何ですか？」
3. AI は hsm_analyze_code を呼び出します。このツールはソース内の Futurex Excrypt の角括弧で区切られたコマンド（[AOTPIN;...] / [TPIN;...]）と、Thales の 2 文字のコマンドコード（CA、G0、M6 など）をスキャンし、それぞれをコマンドレジストリで検索します。
4. 検出されたコマンドごとに、呼び出す APC 操作、必要な鍵タイプ（TR-31 の用途コード）、確信度、移行に関する注記が示されます。
5. AI は APC SDK を使用してリファクタリング済みのコードを作成し、コンプライアンスルールに照らして検証します。

LMK 鍵の移行： アプリケーションまたはデータベースに LMK 暗号化されたブロブとして保存されている鍵は、APC に直接インポートできません。まず、ソース HSM から TR-31 または TR-34 形式でエクスポートする必要があります。LMK への参照が検出されると、サーバーはこの点を明示し、get_parameters_for_import と import_key を使用したインポート手順を案内します。

対応範囲： Futurex Excrypt Enterprise SSP v.2 / Standard API（正式な根拠 — Futurex General Payment HSM Integration Guide 2024）、Thales payShield 10K Legacy コマンド（正式な根拠 — Thales payShield 10K Legacy Host Commands manual）、Thales payShield 10K International/Core コマンド（一部対応 — コアとなる PIN/MAC/CVV/ARQC コードは Futurex Integration Guide により正式に確認済み。鍵管理および PIN 検証コードは参考情報の品質）、Atalla/HPE/NCR（ディレクトリの情報品質 — コマンド名と APC のマッピングのみ。パラメーターの詳細はなく、プロキシのサポートは未実装）。

ワークフロー 3 — プロキシハンドラーの構築

対象: apc-hsm-proxy を使用しているチームです。アプリケーションがブラックボックス、サードパーティ製、またはリファクタリングできない場合に、プロトコル変換レイヤーで HSM と APC 間の変換を処理します。

実施内容: プロキシを検出モードで実行して、アプリケーションが実際に送信するコマンドを確認し、このサーバーを使って該当するコマンド専用のハンドラーを構築します。

仕組み:

1. discover.enabled: true、実際の HSM を指す hsm_host、および log_file: discovery.jsonl を設定して、apc-hsm-proxy を構成します。アプリケーションと実際の HSM の間でプロキシを起動します。プロキシは未処理のコマンドを実際の HSM に転送しながら、コマンドコードごとに 1 件の JSON レコードを discovery.jsonl に書き込みます。記録されるのはコマンドコード、ベンダー、パラメーター名です（キー ブロックと PIN ブロックはマスキングされます）。

2. 代表的な一連のトランザクションをアプリケーションで実行します。プロキシを停止します。discovery.jsonl を開くと、アプリケーションが送信したコマンドごとに 1 件のエントリーが記録されています。

3. MCP サーバーに接続した AI コーディングセッションで、discovery.jsonl を読み込み、その内容を指定して hsm_analyze_discovery_log を呼び出します。このツールは、プロキシに既存のハンドラーがあるコマンド、構築が必要なコマンド、それぞれに対応する APC オペレーションとキータイプ、さらに各コマンドを実装するための正確なファイルパスとハンドラー構造を返します。

4. AI は、プロキシの src/handlers/<vendor>/ ディレクトリにある既存のハンドラーを参考に、各コマンドの Rust ハンドラーを記述します。ファイルを追加して mod.rs に登録し、プロキシを再ビルドします。

5. 検出モードを無効にし（discover.enabled: false）、実際のアプリケーションでテストします。プロキシはハンドラーのあるコマンドを APC にルーティングし、認識できないコマンドにはエラー 68 を返すようになります。

ハンドラー実装時によくある APC の制約 — apc-hsm-proxy を実際の APC に接続したライブ統合テストで判明した制約です。

• DUKPT キーのバリアント: DukptKeyVariant::Bidirectional が有効なのは AES DUKPT（X9.24-3）のみです。3DES DUKPT（X9.24-1／TDES_2KEY）では Request または Response が必要です。Bidirectional を渡すと ValidationException: Invalid DukptKeyVariant provided for key algorithm が返されます。端末起点の MAC には Request を使用してください。
• AES-CMAC の切り詰め検証: AES-CMAC の verify_mac には、完全な 16 バイト（32H）の MAC が必要です。payShield は切り詰められた MAC（例：4 バイト）を送信します。切り詰められた出力を渡すと ValidationException が発生します。回避策として、ハンドラーで generate_mac を呼び出し、先頭から mac_size バイトを比較してください。
• IBM 3624 PIN オフセットのパディング: IBM 3624 の verify_pin_data では、数字のみの PinOffset（^[0-9]+$）が必要です。payShield はオフセットを F で 12 桁の 16 進数文字列にパディングします（例：9237FFFFFFFF）。APC を呼び出す前に、ハンドラーで末尾の F 文字を削除してください。

検出ログは 2 つのツール間の受け渡しに使われます。トランザクションごとではなくコマンドコードごとに 1 回だけ記録するため、ログは小さく保たれ、AI コーディングセッションのソースコンテキストとしてそのまま使えます。

---

テスト

pip install pytest pytest-asyncio "moto[payment-cryptography]"
python -m pytest

---

プロジェクト構成

src/apc_agent/
├── server.py          — FastMCP entry point; registers all tool groups and the KB resource
├── control_plane.py   — Key lifecycle tools (payment-cryptography client)
├── data_plane.py      — Cryptographic operation tools (payment-cryptography-data client)
├── hsm_tools.py       — HSM analysis and discovery log MCP tools
├── hsm_analysis.py    — HSM command registry and regex patterns
├── system_prompt.py   — Domain knowledge injected as MCP instructions
└── compliance.py      — PCI guard-rail logic: hard stops, warnings, key usage registry

payment-knowledge-base.md                    — MCP resource: payment://knowledge-base
aws-payment-cryptography-data-plane-use-cases.json  — APC data plane capability catalog (source of truth for tool implementation)

ナレッジベースは、payment://knowledge-base の MCP リソースとして公開されています。カードデータ、PIN ブロック、カード検証値、EMV タグ、ISO 8583 フィールド、キータイプ、HSM コマンド、暗号化アルゴリズム、制約ルールを網羅しています。エージェントは必要に応じてこれを読み込み、システムプロンプトには注入されません。新しいエントリーは payment-knowledge-base.md に追加し、末尾の Sources テーブルを更新してください。サーバーを再起動する必要はありません。

HSM コマンドマッピングのリファレンス: docs/hsm-apc-command-mapping.md — Thales payShield（International/Core および Legacy）のコマンドコードを APC オペレーションと TR-31 キータイプに対応付けた、人が読みやすいテーブルと移行に関する注記を記載しています。Futurex Excrypt と Atalla のセクションは、今後の追加に備えてスタブになっています。

---

推薦コメント

CyberChef Payments の作業中に：

私：「apc-agent MCP サーバーは、完了した作業に実際に役立ちましたか？」

Kiro：「はい、本当に役立ちました。しかも、コードを読むだけでは気づけなかった具体的な点で役立ちました。コードだけでは確認が難しい決済ドメインの情報、つまりキー種別の制約、PCI 要件の番号、AES DUKPT の移行境界について、迅速で信頼できる参照先として機能しました。この種のドメイン知識を補う作業には、導入する価値があります。」

---

セキュリティとプライバシー

本番データ： このツールを本番環境の暗号鍵、実際の主口座番号（PAN）、または本番の PIN ブロックで使用しないでください。

データの取り扱い： このツールは大規模言語モデル（LLM）と連携します。プロンプトに含まれるデータ（キーのメタデータ、コマンドログ、テスト識別子など）は、LLM プロバイダーに送信される可能性があります。このサーバーで使用するデータはすべて、開発または合成テスト専用であることを確認してください。

認証情報の安全性： このサーバーは、標準の boto3 認証情報チェーンを使用します。決済暗号化の操作に必要な最小権限の IAM 権限で、環境を設定してください。

平文キーは使用しません： このツールは、平文のキー素材（クリアコンポーネント）をサポートしておらず、その入力を求めることもありません。すべてのキー操作は、AWS Payment Cryptography 内の暗号化トークンまたはサービス管理キーを使用して実行する必要があります。

---

開発に関する注記

このプロジェクトは、AI 支援による開発で作成されました。AI は、実装、テスト、ドキュメント作成、調査結果の統合を効率化するために使用されました。アーキテクチャ、範囲、ソースの選定、レビュー、最終的な公開の判断は、作成者が行いました。

このプロジェクトは決済暗号化に関する内容を扱うため、コードとドキュメント内の記述は、可能な限り信頼できるベンダーおよび AWS のドキュメントと照合してレビューしました。残る制限事項と不確実性については、明示しています。

---

信頼できる参考資料

このコードベースにおける APC API の動作は、すべて以下の情報源に基づいています。

• APC ユーザーガイド
• コントロールプレーン API リファレンス
• データプレーン API リファレンス