QU3 - Quantum-Safe MCP Client

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: Initial Setup (First Run / Keys Missing)
    Client->>+Server: GET /keys (Fetch Server Public Keys)
    Server-->>-Client: Server KEM PK, Server Sign PK (Base64)
    Client->>Client: Store Server Public Keys Locally

    Note over Client,Server: Establish Secure Session
    Client->>+Server: POST /kem-handshake/initiate { Client KEM PK, Client Sign PK }
    Server->>Server: Encapsulate Shared Secret (using Client KEM PK)
    Server->>Server: Derive AES-256 Session Key & Store Session Details
    Server-->>-Client: { KEM Ciphertext }
    Client->>Client: Decapsulate Shared Secret & Derive AES-256 Session Key
    Client->>Client: Store AES Session Key

    Note over Client,Server: Secured Inference Request
    Client->>Client: Prepare Secure Request (Sign Payload, Encrypt with AES Key)
    Client->>+Server: POST /inference { Client KEM PK, nonce, ciphertext }
    Server->>Server: Process Secure Request (Lookup Session, Validate Timestamp, Decrypt, Verify Signature)
    Server->>Server: Execute Model(input_data) -> output_data
    Server->>Server: Prepare Secure Response (Prepare Attestation, Sign, Encrypt with AES Key)
    Server-->>-Client: { resp_nonce, resp_ciphertext }
    Client->>Client: Process Secure Response (Decrypt, Verify Attestation)
    Client->>Client: Process Result

    Note over Client,Server: Secured Policy Update
    Client->>Client: Prepare Secure Policy (Read, Sign, Encrypt with AES Key)
    Client->>+Server: POST /policy-update { Client KEM PK, policy_nonce, policy_ciphertext, policy_sig }
    Server->>Server: Process Secure Policy (Lookup Session, Validate Timestamp, Decrypt, Verify Signature)
    Server->>Server: Process Policy (Mock)
    Server->>Server: Prepare Secure Status (Sign Status, Encrypt with AES Key)
    Server-->>-Client: { status_nonce, status_ciphertext, status_sig }
    Client->>Client: Process Secure Status (Decrypt, Verify Signature)
    Client->>Client: Display Status

客户端组件交互

此图表显示客户端应用程序中主要 Python 模块的交互方式：

graph TD
    A("User CLI (Typer)") --> B("src_main");
    B -- Initiates --> C("src_mcp_client (MCPClient)");
    B -- Uses --> D("src_config_utils");
    C -- Uses --> E("src_pqc_utils");
    C -- Uses --> G("requests Session");
    D -- Uses --> H("PyYAML");
    D -- Manages --> I("Key Files");
    D -- Uses --> G;
    E -- Uses --> J("liboqs_python");
    E -- Uses --> K("cryptography");

    subgraph Cryptography
        J
        K
    end

    subgraph Networking
        G
    end

    subgraph "Configuration & Keys"
        H
        I
    end

密钥管理概览

密钥对于安全协议至关重要。以下是它们的管理方式：

graph LR
    subgraph Client Side
        A["CLI: generate-keys"] --> B{"src_main.py"};
        B --> C["src_pqc_utils.py"]:::pqc --> D{"Generate KEM/Sign Pairs"};
        D --> E["src_config_utils.py"]:::config --> F["Save Client Keys (.pub, .sec)"];

        G["CLI: run-inference/etc."] --> B;
        B --> H{"Initialize Client"};
        H --> E --> I{"Load Client Keys?"};
        I -- Found --> J["Use Keys"];
        I -- Not Found --> D;

        H --> E --> K{"Load Server Keys?"};
        K -- Found --> J;
        K -- Not Found --> L{"Fetch Server Keys?"};
        L -- Calls --> E --> M["GET /keys"]:::net;
        M -- Response --> E --> N["Save Server Keys (.pub)"];
        N --> J;
        L -- Fetch Fail --> O["(Error - Cannot Proceed)"];
    end

    subgraph "Server Side (Mock)" 
        P["Server Startup"] --> Q["scripts_mock_mcp_server.py"];
        Q --> R["src_config_utils.py"]:::config --> S{"Load/Generate Server Keys"};
        S --> T["Save Server Keys (.pub, .sec)"];
        Q --> U["Register /keys Endpoint"];
        U -- Request for /keys --> V{"Return Server Public Keys"};
    end

    subgraph "Filesystem (Key Dir)"
        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）。处理用户命令、协调客户端操作和显示结果。包含用于密钥生成、推理、Agent 工作流和策略更新的命令。
• src/mcp_client.py：主客户端类（MCPClient），负责：
  • 管理 PQC 密钥。
  • 定义请求（MCPRequest）和响应（MCPResponse）数据结构。
  • 通过 KEM 握手建立安全会话（connect）。
  • 发送已签名和已加密的请求（send_request）。
  • 处理和验证已加密/已签名的响应。
  • 处理断开连接（disconnect）。
• src/pqc_utils.py：PQC 操作的实用函数（使用 liboqs-python 进行 Kyber KEM 和 SPHINCS+ 签名）、使用 cryptography 进行 AES-GCM 加密/解密，以及 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）的目录。

功能

• 后量子密码学算法：使用 NIST 后量子密码学最终入选者：
  • KEM：Kyber-768
  • 签名：SPHINCS+-SHA2-128f-simple
• 后量子密码学密钥管理：生成并加载 Kyber 和 SPHINCS+ 密钥对。
• 安全会话建立：通过网络握手（/kem-handshake/initiate）使用 Kyber KEM 建立共享密钥。
• 密钥派生：使用 HKDF-SHA256 从 KEM 共享密钥派生 32 字节的 AES-256 密钥。
• 加密通信：使用 AES-256-GCM 和派生的会话密钥加密请求/响应负载（KEM 握手后）。
• 客户端身份验证：客户端使用 SPHINCS+ 签署请求；服务器验证。
• 服务器证明：服务器使用 SPHINCS+ 签署响应（证明数据）；客户端验证。
• 配置：从 config.yaml 加载密钥目录和服务器 URL。
• 自动化服务器密钥获取：如果本地未找到，客户端会自动从 /keys 端点获取服务器公钥。
• 命令行命令：
  • generate-keys：创建客户端密钥对。
  • run-inference：发送单个安全推理请求。
  • run-agent：执行顺序工作流（modelA->modelB），将输出作为输入传递（包装非字典输出），包含逐步报告和健壮的故障处理。
  • update-policy：向服务器发送加密和签署的策略文件。
• 模拟服务器：包括端点（/、/keys、/kem-handshake/initiate、/inference、/policy-update），实现相应的服务器端后量子密码学和通信逻辑用于测试。提供示例模型 model_caps 和 model_reverse。
• 单元测试：包括覆盖核心密码学工具、配置管理和客户端通信逻辑（带网络模拟）的单元测试。

设置

1. 克隆仓库：

   git clone <repository_url>
   cd qu3-app
   

2. 创建虚拟环境：

   python3 -m venv venv
   source venv/bin/activate
   

3. 安装依赖：

   pip install -r requirements.txt
   

   （注意：liboqs-python 可能需要系统依赖，如 C 编译器和 liboqs C 库。如果安装失败，请参考其文档。）
4. （可选）配置 config.yaml： 如需要，修改 key_directory 或 server_url。默认密钥目录是 ~/.qu3/keys/。

快速开始

# Easy installation
./scripts/install.sh
# Validate setup
python -m src.main validate-config
# Test connection
python -m src.main test-connection
# Run benchmarks
python -m src.main benchmark

运行模拟服务器

在一个终端中运行：

# Ensure virtual environment is active
source venv/bin/activate

python -m scripts.mock_mcp_server

服务器将启动（通常在 http://127.0.0.1:8000），如果密钥对不存在，会自动在配置的密钥目录中生成。

运行客户端命令行

在另一个终端中（激活虚拟环境）：

1. 生成客户端密钥：（除非使用 --force，否则只需执行一次）

   python -m src.main generate-keys
   

2. 获取服务器密钥（自动）： 如果在 config.yaml 指定的密钥目录中未找到 server_kem.pub 和 server_sign.pub，客户端将在初始化时（run-inference、run-agent、update-policy）尝试从服务器的 /keys 端点获取密钥。执行需要连接的客户端命令前，请确保模拟服务器正在运行。

3. 运行单个推理：

   # 使用模拟服务器的 model_caps 的示例
   python -m src.main run-inference model_caps '{"text": "process this data"}'
   
   # 指定服务器 URL 的示例
   python -m src.main run-inference model_reverse '{"text": "backward"}' --server-url http://127.0.0.1:8000
   

4. 运行 Agent 工作流：

   # 链接两个模拟模型的示例
   python -m src.main run-agent "model_caps -> model_reverse" '{"text": "flow start"}'
   

5. 更新策略： 创建策略文件（例如 my_policy.txt）并填写内容。

   echo "Allow model_caps access." > my_policy.txt
   python -m src.main update-policy --policy-file my_policy.txt
   

运行测试

要运行单元测试：

# Ensure virtual environment is active
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）