项目介绍
QU3 - 量子安全MCP客户端
本项目提供了一个客户端应用程序（qu3-app），用于与支持量子安全多计算提供商（MCP）环境进行安全交互。它利用后量子密码学（PQC）标准来建立安全通信通道，确保客户端的真实性，并验证服务器的声明。
此客户端设计用于与支持QU3交互协议的MCP服务器协同工作。对于开发和测试，scripts/mock_mcp_server.py中包含了兼容的模拟服务器实现。
架构与流程
安全通信流程
下图展示了QU3客户端与MCP服务器之间实现的端到端安全通信模式：
sequenceDiagram
participant Client as QU3 Client (CLI)
participant Server as MCP Server
Note over Client,Server: 初始设置（首次运行/密钥丢失）
Client->>+Server: GET /keys (获取服务器公钥)
Server-->>-Client: 服务器KEM公钥, 服务器签名公钥 (Base64)
Client->>Client: 本地存储服务器公钥
Note over Client,Server: 建立安全会话
Client->>+Server: POST /kem-handshake/initiate { 客户端KEM公钥, 客户端签名公钥 }
Server->>Server: 封装共享秘密（使用客户端KEM公钥）
Server->>Server: 导出AES-256会话密钥并存储会话详情
Server-->>-Client: { KEM密文 }
Client->>Client: 解封装共享秘密并导出AES-256会话密钥
Client->>Client: 存储AES会话密钥
Note over Client,Server: 安全推理请求
Client->>Client: 准备安全请求（签名负载，使用AES密钥加密）
Client->>+Server: POST /inference { 客户端KEM公钥, nonce, 密文 }
Server->>Server: 处理安全请求（查找会话，验证时间戳，解密，验证签名）
Server->>Server: 执行模型(input_data) -> output_data
Server->>Server: 准备安全响应（准备声明，签名，使用AES密钥加密）
Server-->>-Client: { resp_nonce, resp_ciphertext }
Client->>Client: 处理安全响应（解密，验证声明）
Client->>Client: 处理结果
Note over Client,Server: 安全策略更新
Client->>Client: 准备安全策略（读取，签名，使用AES密钥加密）
Client->>+Server: POST /policy-update { 客户端KEM公钥, policy_nonce, policy_ciphertext, policy_sig }
Server->>Server: 处理安全策略（查找会话，验证时间戳，解密，验证签名）
Server->>Server: 处理策略（模拟）
Server->>Server: 准备安全状态（签名状态，使用AES密钥加密）
Server-->>-Client: { status_nonce, status_ciphertext, status_sig }
Client->>Client: 处理安全状态（解密，验证签名）
Client->>Client: 显示状态
客户端组件交互
下图展示了客户端应用中的主要Python模块如何交互：
graph TD
A("用户CLI (Typer)") --> B("src_main");
B -- 初始化 --> C("src_mcp_client (MCPClient)");
B -- 使用 --> D("src_config_utils");
C -- 使用 --> E("src_pqc_utils");
C -- 使用 --> G("requests Session");
D -- 使用 --> H("PyYAML");
D -- 管理 --> I("密钥文件");
D -- 使用 --> G;
E -- 使用 --> J("liboqs_python");
E -- 使用 --> K("cryptography");
subgraph 密码学
J
K
end
subgraph 网络
G
end
subgraph "配置与密钥"
H
I
end
密钥管理概述
密钥对于安全协议至关重要。以下是它们的管理方式：
graph LR
subgraph 客户端侧
A["CLI: generate-keys"] --> B{"src_main.py"};
B --> C["src_pqc_utils.py"]:::pqc --> D{"生成KEM/签名对"};
D --> E["src_config_utils.py"]:::config --> F["保存客户端密钥 (.pub, .sec)"];
G["CLI: run-inference/etc."] --> B;
B --> H{"初始化客户端"};
H --> E --> I{"加载客户端密钥？"};
I -- 找到 --> J["使用密钥"];
I -- 未找到 --> D;
H --> E --> K{"加载服务器密钥？"};
K -- 找到 --> J;
K -- 未找到 --> L{"获取服务器密钥？"};
L -- 调用 --> E --> M["GET /keys"]:::net;
M -- 响应 --> E --> N["保存服务器公钥 (.pub)"];
N --> J;
L -- 获取失败 --> O["(错误 - 无法继续)"];
end
subgraph "服务器侧（模拟）"
P["服务器启动"] --> Q["scripts_mock_mcp_server.py"];
Q --> R["src_config_utils.py"]:::config --> S{"加载/生成服务器密钥"};
S --> T["保存服务器密钥 (.pub, .sec)"];
Q --> U["注册 /keys 端点"];
U -- 请求 /keys --> V{"返回服务器公钥"};
end
subgraph "文件系统（密钥目录）"
F
T
N
end
classDef pqc fill:#f9d,stroke:#333,stroke-width:2px;
classDef config fill:#cfc,stroke:#333,stroke-width:2px;
classDef net fill:#cdf,stroke:#333,stroke-width:2px;
核心组件
src/main.py: 使用Typer构建的命令行界面（CLI）。处理用户命令，协调客户端操作，并显示结果。包括密钥生成、推理、代理工作流和策略更新的命令。src/mcp_client.py: 主客户端类（MCPClient），负责：- 管理PQC密钥。
- 定义请求（
MCPRequest）和响应（MCPResponse）数据结构。 - 通过KEM握手（
connect）建立安全会话。 - 发送已签名和加密的请求（
send_request）。 - 处理和验证加密/签名的响应。
- 处理断开连接（
disconnect）。
src/pqc_utils.py: PQC操作的实用函数（Kyber KEM，SPHINCS+签名）使用liboqs-python，AES-GCM加密/解密使用cryptography，以及HKDF密钥派生。src/config_utils.py: 处理从config.yaml加载配置，从文件加载/保存密钥，以及从/keys端点获取服务器公钥。scripts/mock_mcp_server.py: 一个FastAPI开发/测试服务器，模拟MCP环境。实现了服务器端的KEM握手逻辑、请求解密/验证、基本模型执行、声明签名、响应加密、策略更新和密钥分发。config.yaml: 配置文件，用于存储默认密钥目录（key_directory）和服务器URL（server_url）等设置。tests/: 包含核心组件（pqc_utils，config_utils，mcp_client）的单元测试（unittest）的目录。
功能
- PQC算法：使用NIST PQC决赛选手：
- KEM:
Kyber-768 - 签名:
SPHINCS+-SHA2-128f-simple
- KEM:
- PQC密钥管理：生成和加载Kyber和SPHINCS+密钥对。
- 安全会话建立：在网络握手（
/kem-handshake/initiate）期间使用Kyber KEM来建立共享秘密。 - 密钥派生：使用HKDF-SHA256从KEM共享秘密派生32字节的AES-256密钥。
- 加密通信：在KEM握手之后使用AES-256-GCM和派生的会话密钥加密请求/响应负载。
- 客户端认证：客户端使用SPHINCS+签名请求；服务器验证。
- 服务器声明：服务器使用SPHINCS+签名响应（声明数据）；客户端验证。
- 配置：从
config.yaml加载密钥目录和服务器URL。 - 自动服务器密钥获取：如果本地找不到，客户端会自动从
/keys端点获取服务器公钥。 - CLI命令：
generate-keys: 创建客户端密钥对。run-inference: 发送单个安全推理请求。run-agent: 执行顺序工作流（modelA->modelB），传递输出作为输入（包装非字典输出），具有逐步报告和强大的故障处理。update-policy: 向服务器发送加密和签名的策略文件。
- 模拟服务器：包括端点（
/，/keys，/kem-handshake/initiate，/inference，/policy-update），实现相应的服务器端PQC和通信逻辑以供测试。提供了示例模型model_caps和model_reverse。 - 单元测试：包括覆盖核心加密工具、配置管理和客户端通信逻辑（带网络模拟）的单元测试。
设置
- 克隆仓库：
git clone <repository_url> cd qu3-app - 创建虚拟环境：
python3 -m venv venv source venv/bin/activate - 安装依赖项：
(注意：pip install -r requirements.txtliboqs-python可能需要系统依赖项，如C编译器和liboqsC库。如果安装失败，请参阅其文档。) - （可选）配置
config.yaml：如有需要，修改key_directory或server_url。默认密钥目录是~/.qu3/keys/。
快速开始
# 简易安装
./scripts/install.sh
# 验证设置
python -m src.main validate-config
# 测试连接
python -m src.main test-connection
# 运行基准测试
python -m src.main benchmark
运行模拟服务器
在一个终端中运行：
# 确保虚拟环境处于激活状态
source venv/bin/activate
python -m scripts.mock_mcp_server
服务器将启动（通常在http://127.0.0.1:8000），并在配置的密钥目录中自动生成其自己的密钥对（如果不存在）。
运行客户端CLI
在另一个终端（激活虚拟环境）中：
-
生成客户端密钥：（仅需执行一次，除非使用
--force）python -m src.main generate-keys -
获取服务器密钥（自动）：客户端会在初始化时尝试从服务器的
/keys端点获取密钥（run-inference，run-agent，update-policy），如果server_kem.pub和server_sign.pub在config.yaml指定的密钥目录中未找到。在执行需要连接的客户端命令之前，请确保模拟服务器正在运行。 -
运行单次推理：
# 示例使用模拟服务器的model_caps python -m src.main run-inference model_caps '{"text": "处理这些数据"}' # 示例指定服务器URL python -m src.main run-inference model_reverse '{"text": "向后"}' --server-url http://127.0.0.1:8000 -
运行代理工作流：
# 示例链接两个模拟模型 python -m src.main run-agent "model_caps -> model_reverse" '{"text": "流程开始"}' -
更新策略： 创建一个策略文件（例如，
my_policy.txt）并添加一些内容。echo "允许访问model_caps。" > my_policy.txt python -m src.main update-policy --policy-file my_policy.txt
运行测试
要运行单元测试：
# 确保虚拟环境处于激活状态
source venv/bin/activate
python -m unittest discover tests
或者运行特定的测试文件：
python -m unittest tests.test_pqc_utils
python -m unittest tests.test_config_utils
python -m unittest tests.test_mcp_client
🆕 最新更新
最新发布包括显著改进了开发者体验：
新的CLI命令
validate-config: 全面的环境和配置验证inspect-keys: 详细的密钥检查和状态报告test-connection: 无操作的服务器连接性测试benchmark: 量子安全操作的性能测量
增强的安装
- 自动化安装脚本（
scripts/install.sh）处理复杂依赖项 - 改进的Docker开发环境
- 更好的错误处理和诊断
文档与示例
- 全面的故障排除指南（
TROUBLESHOOTING.md）