AWS Payment Cryptography

AWS Payment Cryptography MCP Server

一个适用于 AWS Payment Cryptography（APC） 的 MCP 服务。让 AI 编码助手能够直接访问 APC 控制平面（密钥生命周期）和数据平面（加密操作），并内置支付标准、HSM 厂商命令集和 PCI PIN v3.1 合规要求相关知识。本工具仅用于开发和测试，不应直接用于生产系统。它旨在通过提供面向领域的 AWS Payment Cryptography 接口，加快“概念验证”阶段和迁移分析。兼容 Claude Code、Codex CLI 以及任何兼容 MCP 的客户端。

使用它有三个理由：

1. 你正在 APC 上构建新的收单方或处理方集成，希望有一个了解该领域的 AI 副驾驶——无需为每次 API 调用都阅读文档，就能理解密钥层级、DUKPT、TR-31/TR-34、PIN 格式和合规限制。

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 服务与客户端无关——它通过 stdio 使用标准 Model Context Protocol，可与任何兼容 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 或环境变量。将 AWS_REGION 设置为 APC 资源所在的区域。

请参阅 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）需要明确确认。Agent 会解释为何优先采用现代方案，询问你是否已确认下游系统不支持该方案，然后帮助你正确实现旧方案，并添加记录说明的代码注释，以及可能需要 QSA 例外审批的提示。

合规性执行内置于工具层，且无法关闭。代码中强制执行的硬性限制包括：非法的 PIN 格式转换组合（PCI PIN Req 3-3）、使用非 CMAC KCV 的 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 双字符命令代码（CA、G0、M6 等），然后在命令注册表中查找每项命令。
4. 对于检测到的每项命令，提供要调用的 APC 操作、所需的密钥类型（TR-31 用途代码）、置信度，以及迁移说明。
5. AI 使用 APC SDK 编写重构后的代码，并根据合规规则进行验证。

LMK 密钥迁移： 以 LMK 加密 Blob 的形式存储在应用或数据库中的密钥无法直接导入 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. 配置 apc-hsm-proxy，设置 discover.enabled: true、将 hsm_host 指向真实 HSM，并将 log_file: discovery.jsonl 设为日志文件。在应用和真实 HSM 之间启动代理。代理会将未处理的命令转发给真实 HSM，同时针对每个唯一命令代码向 discovery.jsonl 写入一条 JSON 记录，包含命令代码、厂商和参数名称（密钥块和 PIN 块会被删去）。

2. 让应用运行一组有代表性的事务。停止代理。打开 discovery.jsonl，其中每条记录对应应用发送过的一种不同命令。

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 M8 会发送截断的 MAC（例如 4 字节）。传入截断的输出会导致 ValidationException。解决方法：调用 generate_mac，然后在处理程序中比较前 mac_size 个字节。
• IBM 3624 PIN 偏移量填充： IBM 3624 的 verify_pin_data 要求 PinOffset 仅包含数字（^[0-9]+$）。payShield 会将偏移量填充为 12 个十六进制字符，并使用 F（例如 9237FFFFFFFF）。调用 APC 前，请在处理程序中移除末尾的 F 字符。

发现日志是这两个工具之间的交接内容。由于它会去重——每种命令代码只写入一次，而非每笔事务写入一次——因此文件很小，可直接作为 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)

知识库通过 MCP 资源 payment://knowledge-base 提供。它涵盖卡数据、PIN 块、卡验证值、EMV 标签、ISO 8583 字段、密钥类型、HSM 命令、加密算法和限制规则。Agent 会按需读取，不会注入系统提示词。向 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 参考