SSH PQC 延迟基准测试

本项目用于在本地构建的 OQS OpenSSH 工具链上，对经典、纯后量子和混合三种 SSH 算法模式的握手延迟进行对比测试。项目当前只关注连接延迟，不再抓包，也不再统计报文大小；所有真实连接都会被强制经过一条本地虚拟网络拓扑。

项目目标

仓库的核心用途，是在不同网络条件下比较三组固定 SSH 算法组合的建连延迟：

• classic
• pure-pq
• hybrid

每一个 benchmark case 都是真实的 SSH 建连：客户端命名空间连接到服务端命名空间，中间经过路由命名空间，并通过 tc netem 注入时延、抖动、丢包和可选的带宽限制。

项目结构

• scripts/bootstrap_local_ssh.sh：构建本地 liboqs、OQS OpenSSH 和 hyperfine
• scripts/check_env.sh：验证三种模式都能完成真实 SSH 建连
• scripts/run_comprehensive_bench.sh：主 benchmark 入口
• scripts/run_bench.sh：轻量包装，默认只跑 ideal 网络画像
• scripts/run_large_scale_bench.sh：轻量包装，默认跑全部预设网络画像
• scripts/benchmark_latency.py：采集延迟样本并计算分位数
• scripts/matrix_visualization.py：生成 CSV 汇总和 SVG 热力图
• scripts/pqcbench_cli.py：用于重新生成矩阵结果的小型 CLI
• scripts/lib/common.sh：共享的模式定义、密钥生成、SSH/sshd 启动逻辑
• scripts/lib/network_topology.sh：命名空间拓扑和 tc netem 管理
• scripts/lib/network_profiles.tsv：预设网络画像定义
• testbed/sshd_config：运行时渲染使用的 sshd 模板
• tests/：shell 和 Python 回归测试
• docs/ssh-kem-mvp-plan.md：当前延迟测试方案说明

网络拓扑

基准测试使用三个 Linux network namespace：

• pqcbench-client
• pqcbench-router
• pqcbench-server

地址规划如下：

组件	地址
client	10.200.1.2/24
router west	10.200.1.1/24
router east	10.200.2.1/24
server	10.200.2.2/24

流量路径固定为：

client namespace -> router namespace -> server namespace

实现要点：

• 客户端固定连接目标 10.200.2.2
• 路由命名空间开启 IPv4 转发
• tc netem 对 client/server 两端接口对称施加网络条件
• 如果画像 RTT 为 X，则每端注入 X / 2 的延迟
• 抖动由 RTT 推导，并写入 benchmark 元数据
• 丢包率在两端对称施加
• 支持可选 rate 字段来限制带宽

算法模式

当前 benchmark 以 scripts/lib/common.sh 中的定义为准：

模式	KEX	Signature	Key Type
classic	curve25519-sha256	ssh-ed25519	ed25519
pure-pq	mlkem768-sha256	ssh-mldsa-65	mldsa-65
hybrid	mlkem768x25519-sha256	ssh-ecdsa-nistp384-mldsa-65	ssh-ecdsa-nistp384-mldsa-65

其他固定项：

• 对称加密算法：aes256-gcm@openssh.com
• 认证方式：仅公钥认证
• 客户端命令会显式固定 KEX、HostKeyAlgorithms、PubkeyAcceptedAlgorithms 和 Cipher
• 每种模式都会分别生成 host key 和 client key，保存在 testbed/keys/ 下

预设网络画像

预设网络画像保存在 scripts/lib/network_profiles.tsv：

画像	RTT	Jitter	Client Loss	Server Loss	Rate
ideal	0ms	0ms	0%	0%	unlimited
metro	15ms	3.75ms	0.05%	0.05%	unlimited
wan	105ms	26.25ms	0.3%	0.3%	unlimited
lossy	230ms	57.5ms	1%	1%	unlimited

预设分组：

• --lan：ideal,metro
• --wan：wan,lossy
• --all-networks：ideal,metro,wan,lossy

自定义画像格式：

name:rtt:loss[:rate]

示例：

custom:20ms:0.1%
limited:68ms:0.6%:10mbit

运行要求

项目默认运行在支持 network namespace 的 Linux 环境上。

构建和运行过程中会依赖如下工具：

• bash
• python3
• ip
• sudo 或直接 root 权限，用于 namespace 和 tc 操作
• curl
• git
• cmake
• make
• gcc
• pkg-config
• cargo
• autoreconf
• tar
• mktemp
• cksum

快速开始

先构建本地依赖：

./scripts/bootstrap_local_ssh.sh

验证三种模式都可正常建连：

./scripts/check_env.sh

运行全部预设网络画像的基准测试：

./scripts/run_comprehensive_bench.sh --all-networks

运行测试：

./tests/run_tests.sh

使用方式

1. 默认单画像 benchmark

这个包装脚本默认使用 ideal 网络画像，除非你显式传入网络相关参数：

./scripts/run_bench.sh
./scripts/run_bench.sh -m classic

2. 大规模 benchmark

这个包装脚本默认跑所有预设网络画像，除非你显式覆盖：

./scripts/run_large_scale_bench.sh
./scripts/run_large_scale_bench.sh -r 100 -w 10

3. 主 benchmark 命令

./scripts/run_comprehensive_bench.sh [OPTIONS]

常用参数：

• -m, --modes：逗号分隔的模式列表，默认 classic,pure-pq,hybrid
• -n, --network：自定义网络画像列表，格式为 name:rtt:loss[:rate]
• -r, --runs：最终参与统计的有效样本数
• -w, --warmup：先执行但不参与统计的预热次数
• -p, --port：SSH 端口
• -o, --output：输出目录
• --lan：使用 LAN 风格预设组
• --wan：使用 WAN 风格预设组
• --all-networks：使用全部预设画像
• -v, --verbose：输出更详细的日志

示例：

./scripts/run_comprehensive_bench.sh --all-networks -r 50 -w 5
./scripts/run_comprehensive_bench.sh -m classic,hybrid --wan
./scripts/run_comprehensive_bench.sh -n "custom:20ms:0.1%"
./scripts/run_comprehensive_bench.sh -n "limited:68ms:0.6%:10mbit"

4. 基于已有结果重新生成图表

python3 scripts/matrix_visualization.py results/runs/<run-id>
python3 scripts/pqcbench_cli.py matrix results/runs/<run-id>

采样与分位数

对每一个 benchmark case：

• 总执行次数 = warmup + runs
• warmup 样本先执行，但不会参与统计
• 分位数只基于有效样本计算
• 当前输出的分位数为 P50、P75、P90、P95

延迟样本由 scripts/benchmark_latency.py 顺序采集。

输出结果

默认输出目录为：

results/runs/<timestamp>

最近一次运行的结果路径也会写入：

results/latest_path.txt

每次运行通常会生成以下文件：

• environment.txt：环境快照、模式、网络画像、依赖、拓扑和相关命令输出
• latency_samples_<mode>_<profile>.json：单个 case 的原始样本和有效样本
• matrix_percentiles.csv：分位数矩阵汇总
• matrix_latency_percentiles.svg：组合热力图，按分位数分组列
• matrix_latency_p50.svg
• matrix_latency_p75.svg
• matrix_latency_p90.svg
• matrix_latency_p95.svg

latency_samples_<mode>_<profile>.json 中的关键字段：

• mode、profile、kex、signature
• rtt、jitter、client_loss、server_loss、rate
• warmup_runs、measured_runs、total_runs
• samples_ms
• effective_samples_ms
• percentiles.p50_ms、percentiles.p75_ms、percentiles.p90_ms、percentiles.p95_ms

出图方式

项目最终图表不依赖 matplotlib 一类绘图库。scripts/matrix_visualization.py 会读取 JSON 结果，先生成 CSV 汇总，再直接输出 SVG 热力图。

热力图布局如下：

• 行：网络画像
• 列：算法模式
• 组合图：按 P50、P75、P90、P95 分组展示列
• 单元格数值：延迟毫秒值
• 颜色范围：根据当前这批结果的最小/最大延迟动态缩放

验证方式

可用的验证入口包括：

• ./scripts/check_env.sh：确认三种算法模式都能完成真实 SSH 建连
• ./tests/run_tests.sh：运行 topology、模式定义、环境快照、可视化相关的 shell 和 Python 测试

说明

• README 以当前代码实现为准。
• OQS OpenSSH 会被构建到 .local/openssh。
• benchmark 目标地址固定为服务端命名空间的 10.200.2.2。
• namespace 和 tc 相关操作需要 root 或免密 sudo。