Qu3 App

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）。处理用户命令、编排客户端操作并显示结果。包括用于密钥生成、推理、代理工作流和策略更新的命令。
• 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：模拟MCP环境的FastAPI开发/测试服务器。实现KEM握手、请求解密/验证、基本模型执行、证明签名、响应加密、策略更新和密钥分发的服务器端逻辑。
• config.yaml：用于存储默认密钥目录等设置的配置文件(key_directory)以及服务器URL(server_url).
• tests/：包含单元测试的目录(unittest)用于核心部件(pqc_utils, config_utils, mcp_client).

特性

• PQC算法：使用NIST PQC决赛选手：

- KEM： Kyber-768 - 签字： SPHINCS+-SHA2-128f-simple

• PQC密钥管理：生成并加载Kyber和SPHINCS+密钥对。
• 安全会话建立：通过网络握手使用Kyber KEM(/kem-handshake/initiate)建立共享秘密。
• 导出密钥：使用HKDF-SHA256从KEM共享密钥中导出32字节AES-256密钥。
• 加密通信：使用带有派生会话密钥的AES-256-GCM加密请求/响应有效载荷（在KEM握手后）。
• 客户端身份验证：客户使用SPHINCS+签署请求；服务器验证。
• 服务器认证：服务器使用SPHINCS+对响应（证明数据）进行签名；客户端验证。
• 配置：从加载密钥目录和服务器URL config.yaml.
• 自动服务器密钥获取：客户端自动从 /keys 如果在本地找不到端点。
• CLI命令:

- generate-keys：创建客户端密钥对。 - run-inference：发送单个安全的推理请求。 - run-agent：执行顺序工作流(modelA->modelB)，将输出作为输入传递（包装非字典输出），具有逐步报告和强大的故障处理功能。 - update-policy：将加密和签名的策略文件发送到服务器。

• 模拟服务器：包括端点(/, /keys, /kem-handshake/initiate, /inference, /policy-update)实现相应的服务器端PQC和通信逻辑以进行测试。提供示例模型 model_caps 和 model_reverse.
• 单元测试：包括涵盖核心加密实用程序、配置管理和客户端通信逻辑（带网络模拟）的单元测试。

设置

1. 克隆存储库：

   git clone 
   cd qu3-app

1. 创建虚拟环境：

   python3 -m venv venv
   source venv/bin/activate

1. 安装依赖项：

   pip install -r requirements.txt

*（注： liboqs-python 可能需要系统依赖关系，如C编译器和 liboqs C库。如果安装失败，请参阅其文档。)*

1. （可选）配置 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)如果配置的密钥目录中不存在，则自动生成自己的密钥对。

运行客户端CLI

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

1. 生成客户端密钥： （只需要做一次，除非 --force 使用）

   python -m src.main generate-keys

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

1. 运行单一推理：

   # Example using mock server's model_caps
   python -m src.main run-inference model_caps '{"text": "process this data"}'

   # Example specifying server URL
   python -m src.main run-inference model_reverse '{"text": "backward"}' --server-url http://127.0.0.1:8000

1. 运行代理工作流：

   # Example chaining two mock models
   python -m src.main run-agent "model_caps -> model_reverse" '{"text": "flow start"}'

1. 更新策略：

创建策略文件（例如。， 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)