PQC-Tool 抗量子密码算法工具

版本: v1.0
日期: 2026-07-01
作者: duww.com

1. 项目概述

1.1 项目背景

随着量子计算技术的快速发展，传统基于 RSA、ECC 的公钥密码体系面临被 Shor 算法攻破的威胁。NIST 于 2024 年正式发布了三项抗量子密码标准：

本项目旨在开发一个免安装、即开即用的 Windows 桌面工具，帮助用户直观地体验和理解这三种抗量子密码算法的完整操作流程。

1.2 设计目标

1. 免安装运行：双击启动.bat即可使用，首次运行自动创建虚拟环境并安装依赖
2. 完整功能覆盖：支持三大 FIPS 标准的所有核心操作（密钥生成、封装/解封、签名/验证）
3. 多参数级别：每种算法支持多个安全等级的参数集选择
4. 本地密钥管理：密钥持久化存储，支持加载、删除、按算法筛选
5. 直观用户体验：暗色主题 UI、流程引导、自动填充、一键复制
6. 真实算法实现：基于 pqcrypto 库（PQClean C 实现），非模拟

1.3 目标用户

• 密码学研究人员与教育工作者
• 信息安全工程师与架构师
• 需要评估 PQC 算法性能与密钥大小的开发团队
• 对抗量子密码感兴趣的技术爱好者

2. 系统架构

2.1 总体架构

系统采用B/S 架构 + 本地服务模式：

┌─────────────────────────────────────────────────────┐ │ Windows 桌面 │ │ │ │ ┌─────────────── 启动.bat ──────────────────┐ │ │ │ 1. 检查 Python 环境 │ │ │ │ 2. 自动创建 venv（首次） │ │ │ │ 3. 安装依赖 pip install（首次） │ │ │ │ 4. 启动 Flask 服务 127.0.0.1:5200 │ │ │ │ 5. 自动打开浏览器 │ │ │ └────────────────────────────────────────────┘ │ │ │ │ ┌─────────────── Flask 后端 ─────────────────┐ │ │ │ │ │ │ │ app.py ─── Flask REST API │ │ │ │ │ │ │ │ │ ├── pqc_core.py ── PQC 算法核心封装 │ │ │ │ │ ├── PQCCrypto 类 │ │ │ │ │ │ ├── ML-KEM 操作 │ │ │ │ │ │ ├── ML-DSA 操作 │ │ │ │ │ │ └── SLH-DSA 操作 │ │ │ │ │ └── KeyStore 类 │ │ │ │ │ └── data/*.json 密钥存储 │ │ │ │ │ │ │ │ │ ├── templates/index.html ── Web UI │ │ │ │ ├── static/css/style.css ── 暗色主题 │ │ │ │ └── static/js/app.js ── 前端交互逻辑 │ │ │ └────────────────────────────────────────────┘ │ │ │ │ ┌──── pqcrypto (C 扩展) ────────────────────┐ │ │ │ PQClean 官方参考实现的 Python 绑定 │ │ │ │ ├── pqcrypto.kem.ml_kem_* │ │ │ │ ├── pqcrypto.sign.ml_dsa_* │ │ │ │ └── pqcrypto.sign.sphincs_* │ │ │ └────────────────────────────────────────────┘ │ │ │ │ ┌──── 浏览器 (http://127.0.0.1:5200) ────────┐ │ │ │ 用户交互界面 │ │ │ └────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘

2.2 技术栈

2.3 目录结构

PQC-Tool/ ├── app.py # Flask 后端入口（REST API + 页面路由） ├── pqc_core.py # PQC 算法核心封装类 ├── requirements.txt # Python 依赖列表 ├── 启动.bat # 免安装启动脚本 ├── data/ # 密钥存储目录（运行时自动创建） │ └── ML-KEM-768_xxxx.json │ └── ML-DSA-65_xxxx.json │ └── SLH-DSA-SHA2-128s_xxxx.json ├── templates/ │ └── index.html # Web UI 主页面 ├── static/ │ ├── css/ │ │ └── style.css # 暗色主题样式 │ └── js/ │ └── app.js # 前端交互逻辑 └── venv/ # Python 虚拟环境（首次运行自动创建）

3. 核心模块设计

3.1 pqc_core.py — PQC 算法核心模块

3.1.1 PQCCrypto 类

负责所有抗量子密码算法的操作执行，提供统一接口封装。

类结构：

classPQCCrypto:_pqcrypto_available:bool# pqcrypto 库可用性标志def_check_pqcrypto()# 检查 pqcrypto 是否已安装def_get_kem_module(name)# 动态加载 KEM 模块（importlib）def_get_sign_module(name)# 动态加载签名模块（importlib）# ML-KEM (FIPS 203) 操作defml_kem_keygen(param_name)→dictdefml_kem_encapsulate(param_name,pk_hex)→dictdefml_kem_decapsulate(param_name,sk_hex,ct_hex)→dict# ML-DSA (FIPS 204) 操作defml_dsa_keygen(param_name)→dictdefml_dsa_sign(param_name,sk_hex,message)→dictdefml_dsa_verify(param_name,pk_hex,message,sig_hex)→dict# SLH-DSA (FIPS 205) 操作defslh_dsa_keygen(param_name)→dictdefslh_dsa_sign(param_name,sk_hex,message)→dictdefslh_dsa_verify(param_name,pk_hex,message,sig_hex)→dict

关键设计决策：

1. 动态模块加载：使用importlib.import_module()按需加载算法模块，避免启动时导入所有 18+ 个变体
2. 双重编码输出：所有密钥/签名数据同时输出 Hex 和 Base64 两种格式，满足不同使用场景
3. 密钥指纹：使用 SHA-256 哈希前 16 字节作为密钥指纹，便于密钥识别和比对
4. 降级模式：当 pqcrypto 不可用时，使用os.urandom()生成随机数据作为模拟结果，确保 UI 仍可演示操作流程

pqcrypto API 映射关系：

3.1.2 KeyStore 类

负责密钥的持久化存储与管理。

类结构：

classKeyStore:data_dir:Path# data/ 目录def_key_file_path(algorithm,key_id)→ Pathdefsave_key(algorithm,key_data)→str# 保存密钥，返回 key_iddefload_key(algorithm,key_id)→dict# 加载密钥deflist_keys(algorithm=None)→list# 列出密钥（可按算法筛选）defdelete_key(algorithm,key_id)→bool# 删除密钥

存储格式：每个密钥保存为独立 JSON 文件，命名规则{algorithm}_{key_id}.json

{"algorithm":"ML-KEM-768","fips_standard":"FIPS 203","public_key":"9d4c...","public_key_b64":"nUwM...","secret_key":"8a3f...","secret_key_b64":"ij8L...","pk_size":1184,"sk_size":2400,"pk_fingerprint":"a1b2c3d4e5f6a7b8","sk_fingerprint":"f0e1d2c3b4a59687","key_id":"a1b2c3d4e5f6a7b8","saved_at":"2026-07-01T10:30:00"}

key_id 生成规则：使用公钥的 SHA-256 哈希前 16 字节（即pk_fingerprint），确保密钥唯一标识与公钥绑定。

3.2 算法参数配置

3.2.1 ML-KEM (FIPS 203) 参数

pqcrypto 模块映射：ML-KEM-512→pqcrypto.kem.ml_kem_512，以此类推

3.2.2 ML-DSA (FIPS 204) 参数

pqcrypto 模块映射：ML-DSA-44→pqcrypto.sign.ml_dsa_44，以此类推

3.2.3 SLH-DSA (FIPS 205) 参数

SLH-DSA 提供 SHA2 和 SHAKE 两个哈希函数族，每个族提供小签名 (s)和快速签名 (f)两种变体：

设计特点：

• SLH-DSA 的公钥/私钥远小于 ML-DSA，但签名体积显著更大
• “s”（small）变体牺牲签名速度换取更小签名，“f”（fast）变体反之
• 作为 ML-DSA 的备用签名方案，其安全性基于哈希函数而非格假设，提供数学上可证明的安全性

4. API 设计

4.1 REST API 端点一览

通用接口

ML-KEM (FIPS 203) 接口

ML-DSA (FIPS 204) 接口

SLH-DSA (FIPS 205) 接口

4.2 请求/响应数据格式

密钥生成响应

{"algorithm":"ML-KEM-768","fips_standard":"FIPS 203","public_key":"9d4c1a3f...（Hex 全文）","public_key_b64":"nUwMGj8/...（Base64 全文）","secret_key":"8a3f2b1c...（Hex 全文）","secret_key_b64":"ij8LGhwM...（Base64 全文）","pk_size":1184,"sk_size":2400,"pk_fingerprint":"a1b2c3d4e5f6a7b8","sk_fingerprint":"f0e1d2c3b4a59687","key_id":"a1b2c3d4e5f6a7b8",// 仅当 save=true"saved":true// 仅当 save=true}

KEM 封装响应

{"algorithm":"ML-KEM-768","fips_standard":"FIPS 203","ciphertext":"5e7f...（Hex 全文）","ciphertext_b64":"Xn8M...（Base64 全文）","shared_secret":"3a1b...（Hex 全文）","shared_secret_b64":"OhsM...（Base64 全文）","ct_size":1088,"ss_size":32}

KEM 解封响应

{"algorithm":"ML-KEM-768","fips_standard":"FIPS 203","shared_secret":"3a1b...（Hex 全文）","shared_secret_b64":"OhsM...（Base64 全文）","ss_size":32}

签名响应

{"algorithm":"ML-DSA-65","fips_standard":"FIPS 204","signature":"7c2d...（Hex 全文）","signature_b64":"fC0M...（Base64 全文）","message_hex":"48656c6c6f...（消息的 Hex）","message_text":"Hello PQC World!",// 仅当输入为文本"sig_size":3293,"msg_size":16}

验证响应

{"algorithm":"ML-DSA-65","fips_standard":"FIPS 204","valid":true,"message_hex":"48656c6c6f...","message_text":"Hello PQC World!","signature_hex":"7c2d..."}

错误响应

{"error":"缺少公钥"}

HTTP 状态码：400（参数错误）、404（密钥不存在）、500（算法执行异常）

4.3 消息输入格式

签名和验证接口支持两种消息输入方式：

1. 文本模式：message_text— UTF-8 编码的文本字符串
2. Hex 模式：message— 十六进制编码的原始字节

两种方式互斥，优先使用message_text；当两者都提供时，message_text生效。

5. 前端 UI 设计

5.1 页面布局

┌──────────────────────────────────────────────┐ │ 🔐 抗量子密码算法工具 v1.0 pqcrypto 已加载 │ ← 顶部标题栏 ├──────────────────────────────────────────────┤ │ 🔑ML-KEM ✍️ML-DSA 🧬SLH-DSA 📂密钥管理 │ ← 标签导航 ├──────────────────────────────────────────────┤ │ │ │ ML-KEM FIPS 203 │ ← 面板标题 │ 基于模块格的密钥封装机制... │ ← 算法说明 │ │ │ 参数级别：[ML-KEM-768 ▾] PK:1184B SK:2400B │ ← 参数选择 │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 密钥生成 │ │ 密钥封装 │ │ 密钥解封 │ │ ← 操作卡片网格 │ │ KeyGen │ │ Encap. │ │ Decap. │ │ │ │ [生成] │ │ [PK输入] │ │ [SK输入] │ │ │ │ ☑保存 │ │ [封装] │ │ [CT输入] │ │ │ │ │ │ │ │ [解封] │ │ │ │ 结果区域 │ │ 结果区域 │ │ 结果区域 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ML-KEM 工作流程 │ ← 流程说明 │ ①生成(pk,sk) → ②发送pk → ③封装(ct,ss) │ │ → ④发送ct → ⑤解封(ss) │ │ 双方共享 ss 可用于 AES 等对称加密 │ │ │ ├──────────────────────────────────────────────┤ │ FIPS 203·FIPS 204·FIPS 205 就绪 │ ← 底部状态栏 └──────────────────────────────────────────────┘

5.2 交互流程设计

ML-KEM 操作流程（自动填充链）

密钥生成 → 自动填充公钥到"封装"输入框 → 自动填充私钥到"解封"输入框 密钥封装 → 自动填充密文到"解封"输入框 密钥解封 → 显示共享密钥，可验证与封装结果一致

ML-DSA / SLH-DSA 操作流程（自动填充链）

密钥生成 → 自动填充私钥到"签名"输入框 → 自动填充公钥到"验证"输入框 签名 → 自动填充签名到"验证"输入框 → 自动填充消息文本到"验证"输入框 验证 → 显示验证结果（通过/失败）

密钥管理流程

密钥管理页 → 刷新列表 → 显示所有已保存密钥卡片 → 加载密钥 → 切换到对应算法标签页 → 自动填充密钥到操作输入框 → 删除密钥 → 确认后删除 → 刷新列表

5.3 UI 组件清单

5.4 CSS 主题设计

采用深色科技风格主题，CSS 变量体系：

:root{--bg-primary:#0a0e17;/* 主背景：深海蓝 */--bg-secondary:#111827;/* 二级背景：暗灰蓝 */--bg-card:#1a2332;/* 卡片背景：蓝灰 */--bg-input:#0f1724;/* 输入框背景：深蓝 */--border-color:#2a3a50;/* 边框：蓝灰 */--border-focus:#4f8cff;/* 聚焦边框：亮蓝 */--text-primary:#e2e8f0;/* 主文字：亮灰 */--text-secondary:#94a3b8;/* 辅助文字：灰蓝 */--text-muted:#64748b;/* 弱化文字：暗灰 */--accent-blue:#4f8cff;/* 主强调色：科技蓝 */--accent-green:#22c55e;/* 成功色：翠绿 */--accent-red:#ef4444;/* 错误色：亮红 */--accent-orange:#f59e0b;/* 警告色：琥珀 */--accent-purple:#a78bfa;/* 信息色：紫罗兰 */}

响应式适配：

• 默认布局：grid-template-columns: repeat(auto-fit, minmax(340px, 1fr))
• ≤768px：单列布局，流程图垂直排列

6. 数据流与安全性设计

6.1 数据流

用户操作 (浏览器) │ │ POST /api/ml-kem/keygen {param_name, save} │ ▼ Flask app.py │ 解析请求参数 │ 验证参数合法性 │ ▼ PQCCrypto.ml_kem_keygen(param_name) │ 动态加载 pqcrypto.kem.ml_kem_768 │ module.generate_keypair() → (pk_bytes, sk_bytes) │ bytes_to_hex(pk_bytes) → pk_hex │ bytes_to_base64(pk_bytes) → pk_b64 │ key_fingerprint(pk_bytes) → fingerprint │ ▼ KeyStore.save_key (if save=true) │ 写入 data/ML-KEM-768_fingerprint.json │ ▼ Flask jsonify(result) │ ▼ 浏览器渲染结果 │ 显示 Hex/Base64 密钥数据 │ 自动填充到后续操作输入框

6.2 安全性设计

6.2.1 密钥数据安全

6.2.2 算法实现安全

6.2.3 注意事项

⚠️ 本工具为演示与教育用途，密钥以明文 JSON 存储在本地磁盘。
生产环境中应使用密钥管理系统（KMS）或硬件安全模块（HSM）保护私钥。
本工具不建议直接用于生产加密或签名操作。

7. 算法工作流程详解

7.1 ML-KEM (FIPS 203) — 密钥封装机制

ML-KEM 是一种基于模块格（Module-Lattice）的密钥封装机制，用于在不安全信道中安全地协商共享密钥。

工作流程：

Alice Bob │ │ │ ① KeyGen → (pk, sk) │ │ │ │ ② 发送 pk ──────────────────→ │ │ │ ③ Encapsulate(pk) → (ct, ss) │ │ │ ④ ←───────────── 发送 ct ───── │ │ │ │ ⑤ Decapsulate(sk, ct) → ss │ │ │ │ ss ≡ ss（双方共享相同密钥） │

关键属性：

• 共享密钥ss固定 32 字节（256-bit），可用于后续 AES-256 等对称加密
• 密文ct的大小与参数级别相关（768B ~ 1568B）
• 即使攻击者截获pk和ct，也无法恢复ss（基于格问题的困难性）

7.2 ML-DSA (FIPS 204) — 数字签名算法

ML-DSA 是一种基于模块格的数字签名算法，用于身份认证和消息完整性验证。

工作流程：

签名者 验证者 │ │ │ ① KeyGen → (pk, sk) │ │ │ │ ② 发送 pk ──────────────────→ │ │ │ │ ③ Sign(sk, message) → sig │ │ │ │ ④ 发送 (message, sig) ───────→ │ │ │ ⑤ Verify(pk, message, sig) → ✓/✗

关键属性：

• 签名大小远小于 SLH-DSA（2,420B ~ 4,627B vs 7,856B ~ 49,856B）
• 签名速度更快，适合高频签名场景
• 安全性基于格问题假设

7.3 SLH-DSA (FIPS 205) — 基于哈希的签名算法

SLH-DSA 是一种无状态（stateless）的基于哈希的数字签名算法，作为 ML-DSA 的备用方案。

关键属性：

• 安全性仅依赖哈希函数（SHA-2 或 SHAKE），不依赖格假设
• 提供数学上可证明的安全性（reducible security proof）
• 公钥/私钥非常小（32B ~ 128B），但签名体积较大（7,856B ~ 49,856B）
• “s”（small）变体签名更小但速度更慢，“f”（fast）变体签名更大但速度更快
• 无状态设计：每次签名独立，无需维护签名状态计数器

8. 运行与部署

8.1 启动方式

1. 双击启动.bat
2. 脚本自动检查 Python 环境
3. 首次运行：自动创建venv/虚拟环境并安装依赖
4. 后续运行：直接激活已有虚拟环境
5. 启动 Flask 服务（127.0.0.1:5200）
6. 自动打开浏览器

8.2 停止方式

• 在命令行窗口按Ctrl+C
• 关闭命令行窗口
• 或通过taskkill /F /PID <进程PID>终止

8.3 系统要求

8.4 首次运行依赖安装

requirements.txt内容：

flask>=3.0 pqcrypto>=0.4.0 cffi>=1.17

pqcrypto 包含预编译的 Windows wheel，安装过程无需本地 C 编译器。

9. 测试验证

9.1 已完成的验证测试

9.2 密钥大小验证结果

所有算法的密钥/签名大小与 pqcrypto 模块常量完全一致，与 FIPS 规范匹配。

10. 附录

10.1 FIPS 标准参考

• FIPS 203: ML-KEM Standard — Module-Lattice-Based Key-Encapsulation Mechanism
• FIPS 204: ML-DSA Standard — Module-Lattice-Based Digital Signature Algorithm
• FIPS 205: SLH-DSA Standard — Stateless Hash-Based Digital Signature Algorithm

10.2 pqcrypto 库参考

• GitHub: github.com/cryptoang/pqcrypto
• 基于 PQClean 项目：github.com/PQClean/PQClean
• PQClean 是 NIST PQC 标准化过程的官方参考实现集合

10.3 算法命名对照表

10.4 与传统密码算法的对比