后量子密码学 MCP 服务器

License: MIT Python 3.10+ liboqs MCP

仅供研究和原型设计使用。 本服务器使用 liboqs，明确不建议用于生产环境或保护敏感数据。使用 store_as 模式（推荐）时，私钥会从工具输出中脱敏，并保存在会话范围的密钥环中。如果不使用 store_as，私钥和共享密钥会出现在工具输出中，这可能会进入模型上下文、客户端日志或转录内容。设置 PQC_REQUIRE_KEY_HANDLES=1 可强制所有私钥操作仅使用句柄模式。适用于实验、教育和互操作性测试。

A 模型上下文协议 (MCP) 服务器，提供使用 Open Quantum Safe 的 liboqs 的后量子密码操作。使 Claude 等 AI 助手能够执行抗量子密码操作，包括密钥生成、加密、签名和验证。

为什么需要后量子密码学？

当前的密码系统（RSA、ECC、ECDSA）将被运行 Shor 算法的量子计算机破解。NIST 已经标准化了新的抗量子算法：

标准	算法	类型	状态
FIPS 203	ML-KEM (原 CRYSTALS-Kyber)	密钥封装	2024 年定稿
FIPS 204	ML-DSA (原 CRYSTALS-Dilithium)	数字签名	2024 年定稿
FIPS 205	SLH-DSA (原 SPHINCS+)	基于哈希的签名	2024 年定稿

此 MCP 服务器使 AI 代理能够访问这些算法，用于研究、开发和集成。

功能特性

通过 liboqs 提供密钥封装机制 (KEMs)：ML-KEM, FrodoKEM, HQC, BIKE, Classic McEliece
通过 liboqs 提供签名算法：ML-DSA, Falcon, SLH-DSA, MAYO, CROSS, UOV
完整的 MCP 集成：适用于 Claude Desktop、Claude Code、Cursor 以及任何 MCP 客户端
支持 NIST 标准化算法：实现了 FIPS 203、204 和 205 算法
安全性分析：比较经典与量子安全性级别

快速入门

先决条件

Python 3.10+
liboqs 共享库
uv（推荐）或 pip

安装

1. 安装 liboqs

macOS (使用共享库的 Homebrew):

# Homebrew only provides static library, build from source for shared:
git clone --depth 1 --branch 0.15.0 https://github.com/open-quantum-safe/liboqs.git
cd liboqs && mkdir build && cd build
cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
make -j4 && make install

Ubuntu/Debian:

sudo apt-get install liboqs-dev

替代方案：使用自动执行上述操作的捆绑安装脚本：

bash scripts/install-liboqs.sh

2. 克隆并安装

git clone https://github.com/scottdhughes/post-quantum-mcp.git
cd post-quantum-mcp

# Install all dependencies (creates .venv automatically)
uv sync --all-extras

3. 配置 Claude Code / Claude Desktop

添加到您的 MCP 配置中：

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "pqc": {
      "type": "stdio",
      "command": "/path/to/post-quantum-mcp/run.sh",
      "args": [],
      "env": {}
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "pqc": {
      "command": "/path/to/post-quantum-mcp/run.sh"
    }
  }
}

该服务器也可以通过 python -m pqc_mcp_server 直接运行。

可用工具

`pqc_list_algorithms`

列出所有可用的后量子算法。

Input: { "type": "kem" | "sig" | "all" }
Output: List of available algorithms with NIST standard mappings

`pqc_algorithm_info`

获取有关特定算法的详细信息。

Input: { "algorithm": "ML-KEM-768" }
Output: Key sizes, security level, performance characteristics

`pqc_generate_keypair`

生成抗量子密钥对。

Input: { "algorithm": "ML-DSA-65" }
Output: Base64-encoded public and secret keys

`pqc_encapsulate`

执行密钥封装（创建共享密钥）。

Input: { "algorithm": "ML-KEM-768", "public_key": "<base64>" }
Output: Ciphertext and shared secret

`pqc_decapsulate`

从密文中恢复共享密钥。

Input: { "algorithm": "ML-KEM-768", "secret_key": "<base64>", "ciphertext": "<base64>" }
Output: Shared secret

`pqc_sign`

使用后量子签名对消息进行签名。

Input: { "algorithm": "ML-DSA-65", "secret_key": "<base64>", "message": "Hello, quantum world!" }
Output: Base64-encoded signature

`pqc_verify`

验证后量子签名。

Input: { "algorithm": "ML-DSA-65", "public_key": "<base64>", "message": "...", "signature": "<base64>" }
Output: { "valid": true/false }

`pqc_hash`

使用抗量子哈希函数对消息进行哈希处理。

Input: { "message": "data", "algorithm": "SHA3-256" | "SHA3-512" | "SHAKE128" | "SHAKE256" }
Output: Digest in hex and base64

`pqc_security_analysis`

分析算法的安全性属性。

Input: { "algorithm": "ML-KEM-768" }
Output: NIST level, classical/quantum security equivalents, Grover/Shor resistance

混合密钥交换 (X25519 + ML-KEM-768)

套件：mlkem768-x25519-sha3-256 — 借用了 LAMPS 复合 ML-KEM 草案 (id-MLKEM768-X25519-SHA3-256) 中的 KEM 组合器。套件名称中的 sha3-256 指的是 KEM 组合器哈希；HKDF 密钥派生使用 SHA-256（通过 cryptography HKDF）。密封信封层是本项目构建在该组合器之上的自有协议。

这是一种匿名密封盒结构，提供具有密文完整性的混合机密性。它不具备针对接收方密钥泄露的前向安全性，且不提供发送方身份验证。

`pqc_hybrid_keygen`

生成混合密钥对包。

推荐：使用 store_as（私钥已脱敏）

// Input
{"store_as": "alice"}

// Output — no secret keys
{
  "suite": "mlkem768-x25519-sha3-256",
  "handle": "alice",
  "classical": {"algorithm": "X25519", "public_key": "DeRN3xLbEglMdXKO7P98cAvc...", "fingerprint": "a1b2c3d4..."},
  "pqc": {"algorithm": "ML-KEM-768", "public_key": "gDsL8UgEVcMeJgUOQgSlAotx...", "fingerprint": "e5f6a7b8..."}
}

不使用 store_as（返回原始密钥 — 不推荐）：

// Input
{}

// Output — secret keys exposed in tool output
{
  "suite": "mlkem768-x25519-sha3-256",
  "classical": {
    "algorithm": "X25519",
    "public_key": "DeRN3xLbEglMdXKO7P98cAvc...",
    "secret_key": "YEYD9j5c2hpTei0ferXWbAFb..."
  },
  "pqc": {
    "algorithm": "ML-KEM-768",
    "public_key": "gDsL8UgEVcMeJgUOQgSlAotx...",
    "secret_key": "MQB2U0EzNGmloLuiTYG3BTcr..."
  }
}

`pqc_hybrid_encap` / `pqc_hybrid_decap`

构建块密钥封装。返回通过套件的 SHA3-256 组合器派生的组合共享密钥。

`pqc_hybrid_seal` / `pqc_hybrid_open`

使用混合封装 + AES-256-GCM 加密/解密明文。全标头 AAD 绑定。确定性随机数（不在信封中传输）。

// Seal input
{
  "plaintext": "Hello, quantum world!",
  "recipient_classical_public_key": "<base64 X25519 public key>",
  "recipient_pqc_public_key": "<base64 ML-KEM-768 public key>"
}

// Seal output
{
  "envelope": {
    "version": "pqc-mcp-v3",
    "mode": "anon-seal",
    "suite": "mlkem768-x25519-sha3-256",
    "x25519_ephemeral_public_key": "6+b1Y8AkgEycKL5wL2cIeSMv...",
    "pqc_ciphertext": "DF+PYy4zx+OmnW8wLD3EL+4M...",
    "ciphertext": "NnEap2fDq5+xTCwvHdKfy5Xj..."
  }
}

// Open input
{
  "envelope": { "...envelope from seal..." },
  "classical_secret_key": "<base64 X25519 secret key>",
  "pqc_secret_key": "<base64 ML-KEM-768 secret key>"
}

// Open output
{
  "suite": "mlkem768-x25519-sha3-256",
  "plaintext": "Hello, quantum world!",
  "plaintext_base64": "SGVsbG8sIHF1YW50dW0gd29ybGQh"
}

混合提示词示例

"生成一个混合密钥对并为我密封一条消息"

"执行混合密钥交换并向我展示共享密钥"

"使用混合 PQC 加密 '机密数据' 然后解密它"

已验证的混合信封

使用 ML-DSA-65 (FIPS 204) 签名将发送方身份验证添加到混合机密层。发送方对覆盖整个信封的规范二进制转录进行签名。接收方在解密前验证发送方身份。

这是一种发送方验证的密封信封结构。它仍然不具备针对后续接收方长期密钥泄露的前向安全性。密封信封层是本项目构建的自有协议。

`pqc_hybrid_auth_seal`

加密 + 签名。需要发送方 ML-DSA-65 签名密钥 + 接收方混合密钥。

推荐：使用密钥句柄

// Input
{
  "plaintext": "Authenticated message",
  "recipient_key_store_name": "bob",
  "sender_key_store_name": "alice-signing"
}

// Output
{
  "envelope": {
    "version": "pqc-mcp-v3",
    "mode": "auth-seal",
    "suite": "mlkem768-x25519-sha3-256",
    
    "sender_signature_algorithm": "ML-DSA-65",
    "sender_public_key": "0ji6POTItnZUX8rELwVwWSOV...",
    "sender_key_fingerprint": "0f617ece2f1d04c0...",
    "recipient_classical_key_fingerprint": "c1deade4a5300a9a...",
    "recipient_pqc_key_fingerprint": "bb0e084213d6ac74...",
    "x25519_ephemeral_public_key": "5LEikNANeJNhZSiq...",
    "pqc_ciphertext": "ybgWc3ruG3JwXmr4...",
    "ciphertext": "6OYdADdh0eH/LviD...",
    "signature": "BOniPALs1kfhWcRh..."
  }
}

替代方案：使用原始密钥（不推荐）

// Input
{
  "plaintext": "Authenticated message",
  "recipient_classical_public_key": "<base64 X25519 public key>",
  "recipient_pqc_public_key": "<base64 ML-KEM-768 public key>",
  "sender_secret_key": "<base64 ML-DSA-65 secret key>",
  "sender_public_key": "<base64 ML-DSA-65 public key>"
}

`pqc_hybrid_auth_open`

验证发送方 + 解密。需要 expected_sender_public_key 或 expected_sender_fingerprint。在解密前验证签名 — 身份验证失败与解密失败是不同的。

// Open with expected sender public key
{
  "envelope": { "...envelope from auth_seal..." },
  "classical_secret_key": "<base64 X25519 secret key>",
  "pqc_secret_key": "<base64 ML-KEM-768 secret key>",
  "expected_sender_public_key": "<base64 ML-DSA-65 public key>"
}

// Or open with expected sender fingerprint
{
  "envelope": { "...envelope from auth_seal..." },
  "classical_secret_key": "...",
  "pqc_secret_key": "...",
  "expected_sender_fingerprint": "0f617ece2f1d04c0481aa0fe..."
}

// Output
{
  "suite": "mlkem768-x25519-sha3-256",
  "plaintext": "Authenticated message",
  "plaintext_base64": "QXV0aGVudGljYXRlZCBtZXNzYWdl",
  "sender_key_fingerprint": "0f617ece2f1d04c0481aa0fe...",
  "sender_signature_algorithm": "ML-DSA-65",
  "authenticated": true
}

`pqc_hybrid_auth_verify`

在不解密的情况下验证已验证信封上的发送方签名。无需私钥。检查发送方绑定、指纹一致性、ML-DSA-65 签名和时间戳新鲜度。

// Input
{
  "envelope": { "...envelope from auth_seal..." },
  "expected_sender_fingerprint": "0f617ece2f1d04c0..."
}

// Output
{
  "verified": true,
  "sender_key_fingerprint": "0f617ece2f1d04c0...",
  "sender_signature_algorithm": "ML-DSA-65",
  "version": "pqc-mcp-v3",
  "mode": "auth-seal",
  "replay_seen": false,
  "timestamp": "1711929600"
}

`pqc_envelope_inspect`

在不解密的情况下检查信封元数据。无需私钥。返回版本、套件、指纹和字段大小。

// Input
{"envelope": { "...any sealed or authenticated envelope..." }}

// Output
{
  "version": "pqc-mcp-v3",
  "mode": "auth-seal",
  "suite": "mlkem768-x25519-sha3-256",
  "authenticated": true,
  "sender_key_fingerprint": "0f617ece2f1d04c0...",
  
  
  "ciphertext_size": 1234,
  "plaintext_size_approx": 1218,
  "pqc_ciphertext_size": 1088,
  "signature_size": 3309
}

`pqc_fingerprint`

计算公钥的 SHA3-256 指纹。返回小写十六进制。

// Input
{"public_key": "<base64-encoded public key>"}

// Output
{"fingerprint": "a1b2c3d4e5f6...", "algorithm": "SHA3-256"}

`pqc_benchmark`

基准测试 PQC 算法：计时密钥生成、封装/签名、解封装/验证以及密钥/密文/签名大小。

// Input
{"algorithm": "ML-KEM-768", "iterations": 10}

// Output — timing and size measurements

密钥生成流程

1. Sender: generate ML-DSA-65 signing keys via pqc_generate_keypair
2. Recipient: generate hybrid keys via pqc_hybrid_keygen
3. Exchange public keys out-of-band
4. Sender: pqc_hybrid_auth_seal with both key sets
5. Recipient: pqc_hybrid_auth_open with expected sender identity

已验证提示词示例

"生成一个 ML-DSA-65 签名密钥对和一个混合接收方密钥对，然后发送一条已验证的加密消息"

"打开此已验证信封并验证它来自预期的发送方"

"将消息密封给 Bob 并用我的 ML-DSA 密钥签名，然后让 Bob 使用我的指纹打开它"

密钥句柄（私钥脱敏）

选择性模式，私钥存储在进程本地，绝不会出现在工具输出中。句柄是进程全局的，在服务器重启时丢失。

使用句柄生成

// pqc_hybrid_keygen with store_as
{"store_as": "alice"}

// Output — no secret keys
{
  "suite": "mlkem768-x25519-sha3-256",
  "handle": "alice",
  "classical": {"algorithm": "X25519", "public_key": "...", "fingerprint": "..."},
  "pqc": {"algorithm": "ML-KEM-768", "public_key": "...", "fingerprint": "..."}
}

在下游工具中使用句柄

// pqc_hybrid_seal with store name instead of raw keys
{
  "plaintext": "Hello via handle!",
  "recipient_key_store_name": "alice"
}

// pqc_hybrid_auth_seal with two store names
{
  "plaintext": "Authenticated via handles",
  "recipient_key_store_name": "alice",
  "sender_key_store_name": "bob-signing"
}

通用 PQC 工具（pqc_sign、pqc_verify、pqc_encapsulate、pqc_decapsulate）也接受 key_store_name。

为同一角色同时提供存储名称和原始密钥是错误的。

密钥存储管理

pqc_key_store_save：按名称保存密钥生成输出，以便于引用。会话范围，无持久化。
pqc_key_store_load：按名称加载存储的密钥。仅返回句柄条目的公共材料。
pqc_key_store_list：列出所有带有元数据（名称、类型、指纹）的存储密钥。不显示私钥材料。
pqc_key_store_delete：按名称删除存储的密钥。

安全特性

v3 信封协议

v3 信封是模式绑定的：每个信封都携带一个显式的 mode 字段（anon-seal 或 auth-seal），该字段绑定到 HKDF 信息、AAD 和身份验证转录中。这提供了真正的跨模式隔离 — 一种模式生成的密文无法被另一种模式解密，从而在 AEAD 层阻止了身份验证剥离降级攻击。AAD 在 v3 中使用长度前缀框架（自定界）。已验证信封在规范转录中包含一个已签名的 timestamp 字段；在验证/打开时，服务器会检查新鲜度（默认：24 小时，可通过 max_age_seconds 配置）。时钟偏差容差为 5 分钟。

重放保护

服务器维护一个带有 TTL 的签名摘要缓存（信封签名字节的 SHA3-256）。pqc_hybrid_auth_verify 执行只读重放检查。pqc_hybrid_auth_open 执行解密前检查和成功后标记。缓存持久化到 ~/.pqc/state/replay-cache.json 并在服务器重启后保留。最多 50,000 条目，采用先进先出驱逐策略。

信封大小验证

所有信封在进行任何密码处理前都会经过验证：每个 base64 字段（ciphertext、pqc_ciphertext、signature、sender_public_key、x25519_ephemeral_public_key）最大 1MB，总共最多 50 个字段。防止内存炸弹和资源耗尽。

服务器安全策略

设置 PQC_REQUIRE_KEY_HANDLES=1 以强制执行仅句柄模式：服务器拒绝任何传递原始私钥的工具调用，强制所有私钥操作（密钥生成、签名、解封装和混合信封操作）使用 store_as/key_store_name。这是一个无法被行为不端的代理绕过的服务器端检查。

v1/v2 向后兼容性

v1 信封 (pqc-mcp-v1) 在打开/验证时被接受以实现向后兼容，但会产生明显的警告。v1 信封缺少已签名的时间戳，因此跳过新鲜度检查且不提供重放保护。v2 信封 (pqc-mcp-v2) 被接受但缺少模式绑定；响应中包含弃用警告。

中继传输

该项目包含一个用于跨机器 A2A 消息传递的 Cloudflare Worker 中继。

在线： https://quantum-seal-relay.novoamorx1.workers.dev

中继是一个不透明的信封邮箱 — 它存储和转发 JSON 数据块，而不执行密码操作或访问私钥。

端点	方法	用途
`/mailboxes/:fp`	POST	将信封存入收件人邮箱
`/mailboxes/:fp`	GET	获取待处理信封
`/mailboxes/:fp/:id`	DELETE	确认收到
`/mailboxes/:fp/allowlist`	PUT	配置发送方白名单

限制： 最大 50KB 信封，每个邮箱 1000 条消息，24 小时 TTL，速率限制（每个 IP 每分钟 60 次 POST，120 次 GET）。

安全性： 中继永远看不到明文。端到端机密性、完整性和发送方身份验证在客户端强制执行。请参阅 deploy/relay/RELAY-SPEC.md 获取完整的传输协议。

支持的算法

注意： 旧算法名称（Kyber, Dilithium, SPHINCS+）被接受为别名，以兼容旧版本的 liboqs。

密钥封装机制 (KEMs)

算法	NIST 级别	公钥	密文	共享密钥
ML-KEM-512	1	800 B	768 B	32 B
ML-KEM-768	3	1,184 B	1,088 B	32 B
ML-KEM-1024	5	1,568 B	1,568 B	32 B
FrodoKEM-640	1	9,616 B	9,720 B	16 B
HQC-128	1	2,249 B	4,481 B	64 B

数字签名

算法	NIST 级别	公钥	签名	备注
ML-DSA-44	2	1,312 B	2,420 B	平衡
ML-DSA-65	3	1,952 B	3,309 B	推荐
ML-DSA-87	5	2,592 B	4,627 B	高安全性
Falcon-512	1	897 B	653 B	最小签名
Falcon-1024	5	1,793

后量子密码学 MCP 服务器

为什么需要后量子密码学？

功能特性

快速入门

先决条件

安装

1. 安装 liboqs

2. 克隆并安装

3. 配置 Claude Code / Claude Desktop

可用工具

pqc_list_algorithms

pqc_algorithm_info

pqc_generate_keypair

pqc_encapsulate

pqc_decapsulate

pqc_sign

pqc_verify

pqc_hash

pqc_security_analysis