justinwkUKM/pqc-benchmark-lab

# TLS + PQC 基准测试实验室 一个可复现的基准测试实验室，用于评估跨以下模式的 TLS 迁移路径： - 经典密码学 - 混合经典密码学 + PQC - 纯后量子密码学 (PQC) 本项目帮助团队从一次性测试过渡到基于可重复证据的 rollout 决策。 ## 目录 - [重点分析（2026 年 4 月）](#featured-analysis-2026-pqc-handshake-benchmarks) - [本实验室存在的意义](#why-this-lab-exists) - [什么是 OQS 以及为什么使用它](#what-is-oqs-and-why-it-is-used) - [核心功能](#key-capabilities) - [仓库结构](#repository-structure) - [前置条件](#prerequisites) - [快速开始](#quick-start) - [初级指南](#beginner-guide-first-30-minutes) - [中级指南](#intermediate-guide-repeatable-engineering-benchmarks) - [高级指南](#advanced-guide-decisioning-regression-gates-and-ci) - [系统架构](#system-architecture) - [如何解读输出](#how-to-interpret-outputs) - [配置参考](#configuration-reference) - [CI 工作流](#ci-workflows) - [故障排除](#troubleshooting) - [可复现性清单](#reproducibility-checklist) - [额外工具](#extra-tooling-pqc-playground-and-interop) - [许可证](#license) - [安全与风险提示](#security-and-risk-notice) ## 重点分析：2026 PQC 握手基准测试 一份详细的示例分析，比较了经典模式与混合模式以及纯 PQC 模式之间的 TLS 握手性能。  ## 本实验室存在的意义 正在为后量子密码学做准备的机构需要回答一些实际问题： - 每种迁移模式的握手开销是多少？ - 开销主要受网络影响还是受密码学计算影响？ - 在受限的 profile 下会出现什么失败？ - 哪种模式最适合当前的 rollout，而不仅仅是未来的目标状态？ 本实验室提供可重复的数据，支持 profile 模拟、多会话运行、验收关卡、评分、趋势导出和 CI 自动化。 ## 什么是 OQS 以及为什么使用它 **OQS (Open Quantum Safe)** 提供 PQC 算法和集成（包括支持 OpenSSL 的技术栈），用于在广泛的平台默认设置可用之前进行实际的迁移测试。 本仓库使用启用了 OQS 的 Docker 镜像作为客户端/服务器路径，因此同一个测试框架可以基准测试以下内容： - 经典模式 - 混合模式 - PQC 并在一个可比较的框架中进行。 ## 系统架构 下图展示了从初始化到分析输出的实验室工作流： ``` flowchart TD U[User / CI] --> B[bootstrap.sh] B --> D[(Docker Compose)] D --> C["tls-client container
(OQS OpenSSL + curl)"] D --> S["tls-server container
(OQS NGINX)"] R[run_profiles.sh] --> P["Apply infra profile
(scripts/config_query.py)"] P --> M["Run mode matrix
(config/modes.csv)"] M --> L["Latency
run_latency.sh"] M --> H["Capture
capture_handshake.sh"] M --> Q["Concurrency
run_concurrency.sh"] M --> SP["Crypto speed
run_speed.sh"] L --> O[(results)] H --> O Q --> O SP --> O O --> G[generate_report.sh] G --> PH3[generate_phase3_analytics.py] PH3 --> SC[score_profiles.py] SC --> F[REPORT.md + SUMMARY.md + DECISION_BRIEF.md] ``` ## 核心功能 ### 1) 基础设施 profile 模拟 `config/infra_profiles.csv` 中的 profile 通过网络整形 (`tc`) 和容器限制来应用。 当前的 profile： - `dc_lan` - `cross_region` - `mobile_edge` - `constrained_cpu` - `burst_gateway` ### 2) 配置驱动的 TLS 模式矩阵 `config/modes.csv` 中的模式会被自动发现（仅限启用的行）： - `classical` - `kex_pqc` - `cert_pqc` - `hybrid` - `pqc` - `hybrid_pqc_cert` ### 3) 套件 + 工作负载抽象 - `config/workloads.csv` 中的工作负载 - `config/suites.csv` 中的套件 - 运行器：`scripts/run_suite.sh` 这将运行编排与硬编码的 shell 参数解耦。 ### 4) 运行隔离和可追溯性 每次运行都在唯一的运行 ID 下隔离： - `results/runs//...` 并进行全局索引： - `results/runs/index.csv` - `results/latest-run.txt` ### 5) 报告和分析 每次运行的输出包括： - `SUMMARY.md` - `summary.csv` - `heatmap-p95.csv` - `compatibility-status.csv` - `ACCEPTANCE.md` - `statistical-summary.csv` - `handshake-size-breakdown.csv` - `DECISION_BRIEF.md` - `decision-scores.csv` ### 6) 验收关卡和回归防护 `check_acceptance.py` 评估： - 握手成功阈值 - 混合开销阈值 - 兼容性阻碍因素 - 可选的基线回归限制 阈值在 `config/slo.env` 中控制。 ### 7) 决策评分 `score_profiles.py` 使用 `config/scoring_profiles.yaml` 中的加权标准对模式进行排名： - performance (性能) - compatibility (兼容性) - resource cost (资源成本) - handshake size (握手大小) - security policy fit (安全策略契合度) ### 8) 面向仪表盘的趋势导出 `export_trends.py` 从 `results/runs/index.csv` 构建历史 CSV 数据： - latency timeseries (延迟时间序列) - compatibility timeseries (兼容性时间序列) - run overview timeseries (运行概览时间序列) ### 9) CI 自动化 GitHub Actions 会运行冒烟/完整测试套件并上传报告 artifacts： - `.github/workflows/bench-smoke.yml` - `.github/workflows/bench-full.yml` ### 10) PQC 生态系统工具 包括算法目录、可执行矩阵生成、playground 向量和互操作测试框架。 ## 仓库结构 ``` . ├── config/ │ ├── infra_profiles.csv │ ├── modes.csv │ ├── workloads.csv │ ├── suites.csv │ ├── slo.env │ └── scoring_profiles.yaml ├── docs/ │ ├── pqc_playground.md │ ├── pqc_interop.md │ └── adapter_contract.md ├── schema/ │ └── run_result.json ├── scripts/ │ ├── run_suite.sh │ ├── run_profiles.sh │ ├── validate_config.py │ ├── generate_profiles_report.py │ ├── generate_phase3_analytics.py │ ├── check_acceptance.py │ ├── score_profiles.py │ ├── export_trends.py │ ├── lab_doctor.sh │ ├── playground.sh │ ├── interop.sh │ └── ... ├── vectors/ │ ├── README.md │ ├── kem/ │ ├── sig/ │ └── catalog/ └── results/ ├── runs/ └── trends/ ``` ## 前置条件 - Docker Desktop（支持 Compose） - Python 3 - `openssl` - 可选：Wireshark - 可选：`tshark`（用于握手消息级别的大小调整） ## 快速开始 ``` ./scripts/bootstrap.sh ./scripts/lab_doctor.sh ./scripts/run_profiles.sh 3 50 5 off ``` 打开最新报告： ``` RUN_ID="$(cat results/latest-run.txt)" open "results/runs/${RUN_ID}/reports/SUMMARY.md" open "results/runs/${RUN_ID}/reports/ACCEPTANCE.md" ``` ## 初级指南（前 30 分钟） ### 目标 运行一次快速基准测试，了解决策是如何产生的。 ### 步骤 1. 验证环境： ./scripts/lab_doctor.sh 2. 运行冒烟测试套件： ./scripts/run_suite.sh --suite quick --sessions 1 3. 打开生成的报告： RUN_ID="$(cat results/latest-run.txt)" open "results/runs/${RUN_ID}/reports/ACCEPTANCE.md" open "results/runs/${RUN_ID}/reports/SUMMARY.md" ### 首先阅读什么 - `ACCEPTANCE.md`：Go/No-Go 结果。 - `SUMMARY.md`：profile x 模式的行为和增量。 - `summary.csv`：用于绘图的机器可读数据。 ### 心智模型 - 如果验收失败：将结果作为诊断使用，而不是作为 rollout 建议。 - 如果验收通过：比较权衡，然后进入评分环节。 ## 中级指南（可重复的工程基准测试） ### 目标 运行稳定的实验，以便在跨版本和环境中进行比较。 ### 1) 在长时间运行前验证配置 ``` python3 scripts/validate_config.py ``` ### 2) 使用确定性种子运行广泛套件 ``` ./scripts/run_suite.sh --suite broad_coverage --seed 1337 --run-id-prefix team-baseline ``` ### 3) 运行会话恢复 OFF/ON 对比 ``` ./scripts/run_resumption_ab.sh 1 50 5 ``` ### 4) 从配置调整场景 - 启用/禁用模式：`config/modes.csv` - Profile 行为：`config/infra_profiles.csv` - 工作负载强度和行为：`config/workloads.csv` - 套件组合：`config/suites.csv` ### 5) 为仪表盘导出趋势 ``` python3 scripts/export_trends.py --runs-index results/runs/index.csv --output-dir results/trends ``` ## 高级指南（决策制定、回归防护和 CI） ### 目标 实现基准测试治理的操作化：排名、回归控制、CI 质量关卡。 ### 1) 创建决策简报 ``` python3 scripts/score_profiles.py \ --summary-csv results/runs//reports/summary.csv \ --compat-csv results/runs//reports/compatibility-status.csv \ --preset balanced \ --output-md results/runs//reports/DECISION_BRIEF.md \ --output-csv results/runs//reports/decision-scores.csv ``` 可用的预设定义在 `config/scoring_profiles.yaml` 中： - `low-latency-edge` - `constrained-compute` - `compatibility-first` - `balanced` ### 2) 对基线强制执行回归防护 ``` python3 scripts/check_acceptance.py \ --results-dir results/runs/ \ --report-dir results/runs//reports \ --slo-file config/slo.env \ --baseline-summary-csv results/trends/baseline_smoke_summary.csv \ --baseline-compat-csv results/trends/baseline_smoke_compatibility.csv ``` ### 3) 构建能力感知的可执行矩阵 ``` ./scripts/catalog.sh snapshot --backends openssl,liboqs,python python3 scripts/build_matrix.py \ --capabilities results/catalog//capabilities.json \ --families kem,sig \ --backends openssl,liboqs,python \ --min-level 1 \ --output results/catalog//matrix.csv ``` ### 4) 集成 CI 工作流 - PR 冒烟测试套件：`.github/workflows/bench-smoke.yml` - 每夜/每周完整测试套件：`.github/workflows/bench-full.yml` ## 如何解读输出 请按以下顺序： 1. `ACCEPTANCE.md` - 策略阈值和阻碍因素的 PASS/FAIL 关卡。 2. `SUMMARY.md` - 按 profile/模式划分的执行行为和增量。 3. `DECISION_BRIEF.md` - 用于 rollout 建议上下文的加权排名。 4. CSV artifacts - `summary.csv`、`heatmap-p95.csv`、`statistical-summary.csv`、趋势导出。 分解启发式规则： - KEX 效应 = `kex_pqc - classical` - 证书效应 = `cert_pqc - classical` - 综合 PQC 效应 = `pqc - classical` - 迁移开销 = `hybrid - classical` ## 配置参考 ### `config/modes.csv` 模式目录（启用的行会自动进行基准测试）。 ### `config/infra_profiles.csv` 网络/资源模拟 profile 以及 profile 并发默认值。 ### `config/workloads.csv` 基准测试强度和行为（运行次数、预热、并行度、负载模式、keepalive 混合、模式排序）。 ### `config/suites.csv` 关联工作负载 + profile/模式过滤器 + 种子策略的命名套件组合。 ### `config/slo.env` 验收和回归阈值配置。 ### `config/scoring_profiles.yaml` 加权决策预设和策略目标级别。 ## CI 工作流 ### `bench-smoke.yml` 在 PR 和手动触发时运行快速测试套件，执行回归关卡，并上传报告。 ### `bench-full.yml` 每夜/每周运行更广泛的测试套件，并发布用于趋势分析的 artifacts。 ## 故障排除 如果算法名称与预期的镜像构建不同： ``` docker exec tls-client openssl list -groups docker exec tls-client openssl list -kem-algorithms docker exec tls-client openssl list -signature-algorithms ``` 如果环境检查失败： ``` ./scripts/lab_doctor.sh python3 scripts/validate_config.py ``` 如果运行输出看起来不一致： - 验证是否使用了固定种子（`--seed` 或 `RUN_SEED`） - 确保在运行窗口期间主机负载稳定 - 确认在 `docker-compose.yml` 中锁定了镜像 digest ## 可复现性清单 - 保持镜像按 digest 锁定（`docker-compose.yml`） - 保持明确的 SLO 阈值（`config/slo.env`） - 使用运行范围的 artifacts（`results/runs/`） - 至少运行 3 次会话以获得稳定的中位数 - 在运行前验证配置（`scripts/validate_config.py`） - 使用确定性种子以保证模式排序的可复现性 ## 额外工具（PQC playground 和互操作性） ### 演练场 使用 `scripts/playground.sh` 进行后端算法检查和比较。 参见 `docs/pqc_playground.md`。 ### 互操作测试框架 使用 `scripts/interop.sh` + `scripts/interop_runner.py` 进行跨后端互操作性验证和负面测试。 参见： - `docs/pqc_interop.md` - `docs/adapter_contract.md` ### 向量和目录 - 确定性支持向量：`vectors/README.md` - 算法元数据目录：`vectors/catalog/algorithms.json` ## 许可证 Apache-2.0。参见 `LICENSE`。 ## 安全与风险提示 本项目用于基准测试和研究工作流。在任何迁移或 rollout 决策之前，请先在您自己类似生产的环境中进行验证。

标签：curl, Cutter, DevSecOps, DNS解析, Docker, HTTPS, liboqs, meg, NGINX, OpenQuantumSafe, PQC, SSL/TLS, TLS握手, Web服务器安全, 上游代理, 信息安全, 内核驱动, 加密算法, 可重现性, 后量子密码学, 基准对比, 基准测试工具, 安全测试, 安全测试工具, 安全防御评估, 实验环境, 密码学, 密钥交换, 开源项目, 性能分析, 性能开销分析, 性能评估, 手动系统调用, 攻击性安全, 测试环境, 混合加密, 混合密码学, 系统迁移, 纯后量子, 网络协议, 网络安全, 网络延迟, 蓝队防御, 计算开销, 请求拦截, 负责任AI, 逆向工具, 隐私保护