crt26/PQC-LEO
GitHub: crt26/PQC-LEO
一个面向研究人员的后量子密码学性能基准测试框架，自动化完成从依赖环境搭建到计算与 TLS 性能数据采集、解析的全流程。
Stars: 34 | Forks: 16
# PQC-LEO
### 项目描述
PQC-LEO (PQC-Library Evaluation Operator) 提供了一个自动化且全面的评估框架，用于对后量子密码学 (PQC) 算法进行基准测试。它专为希望评估在其环境中集成 PQC 可行性的研究人员和开发人员而设计。该框架简化了 PQC 实现的设置和测试，通过一套专用的自动化脚本，能够在 x86 和 ARM 系统上收集计算和网络性能指标。
PQC 实现源于多个库，包括 OpenSSL 3.5.0 原生支持的算法，以及 [Open Quantum Safe (OQS)](https://openquantumsafe.org/) 项目的 `Liboqs` 和 `OQS-Provider` 库中提供的算法。该框架还提供了自动化机制，用于在物理或虚拟网络上测试 PQC TLS 握手性能，为真实环境测试提供有价值的见解。结果输出为原始 CSV 文件，并使用提供的 Python 解析脚本自动处理，以提供详细的指标和平均值，便于分析。
该项目的未来版本旨在支持更多的 PQC 库，进一步扩大支持的基准测试范围。
### 支持的自动化功能
该项目提供以下自动化功能：
- 验证并安装所需的系统包和 Python PIP 依赖项。
- 编译和配置 OpenSSL、OQS 和 ARM PMU 依赖库。
- 使用 Liboqs 库收集 PQC 计算性能数据，包括 CPU 和峰值内存使用指标。
- 利用 OpenSSL 3.5.0 原生可用及通过 OQS-Provider 提供的 PQC 支持，收集集成到 TLS 1.3 协议中的 PQC 方案的网络性能数据。
- 通过环回接口或在服务器与客户端设备之间的物理网络上运行协调的 PQC TLS 握手测试。
- 自动或手动解析原始性能数据，包括计算多次测试运行的平均值。
### 项目开发
有关项目开发和即将推出的功能的详细信息，请参阅项目的 GitHub Projects 页面：
[PQC-LEO 项目页面](https://github.com/users/crt26/projects/2)
## 目录
- [支持的硬件和软件](#supported-hardware-and-software)
- [支持的密码算法](#supported-cryptographic-algorithms)
- [安装说明](#installation-instructions)
- [克隆仓库](#cloning-the-repository)
- [选择安装模式](#choosing-installation-mode)
- [确保根目录路径标记存在](#ensuring-root-dir-path-marker-is-present)
- [可选设置标志](#optional-setup-flags)
- [自动化测试工具](#automated-testing-tools)
- [计算性能测试](#computational-performance-testing)
- [TLS 性能测试](#tls-performance-testing)
- [测试输出文件](#testing-output-files)
- [解析测试结果](#parsing-test-results)
- [附加文档](#additional-documentation)
- [许可证](#licence)
- [致谢](#acknowledgements)
## 支持的硬件和软件
### 兼容的硬件和操作系统
自动化测试工具目前仅在以下环境中受支持：
- 使用基于 Debian 的操作系统的 x86 Linux 机器
- 使用 64 位基于 Debian 的操作系统的 ARM Linux 设备
### 已测试的密码依赖库
此版本的仓库已使用以下库版本进行了全面测试：
- Liboqs 版本：Post-0.13.0 提交 **†**
- OQS-Provider 版本 0.9.0
- OpenSSL 版本 3.5.0
默认情况下，此仓库配置为使用 OQS 库的**最后测试版本**。这有助于确保所有自动化脚本在已知的工作版本上可靠运行。列出的 OpenSSL 版本固定为 3.5.0，以保持与 OQS-Provider 和项目性能测试工具的兼容性。
虽然此设置最大限度地提高了可靠性，但需要访问最新更新的用户可以相应地配置设置过程。但是，请注意 OQS 库仍处于活跃开发中，上游更改有时可能会破坏与本项目自动化脚本的兼容性。这在 [安装说明](#installation-instructions) 部分有详细说明。
如果出现任何此类问题，请将其报告给本仓库的 GitHub Issues 页面，以便及时解决。有关修改基准测试套件使用的库版本的说明，请在安装说明部分中提供。
**†** 有关依赖库最后测试版本所使用的特定提交的信息，请参阅 [项目依赖项](./docs/developer_information/project_dependencies.md) 文档。
## 支持的密码算法
有关本项目支持的经典和 PQC 算法的更多信息，包括有关任何排除项的信息，请参阅以下文档：
[支持的算法](docs/supported_algorithms.md)
**注意：** 在最新版本的 Liboqs 和 OQS-Provider 中，HQC KEM 算法默认被禁用，因为其当前实现不符合最新的规范，该规范包含重要的安全修复。出于基准测试目的，设置过程包含一个可选标志以在这些库中启用 HQC，并附带用户确认提示和警告。启用 HQC 由用户自行决定，本项目对其使用不承担任何责任。有关启用 HQC 的说明，请参阅 [高级设置配置指南](docs/advanced_setup_configuration.md)，并参考 [免责声明文档](./DISCLAIMER.md) 以获取有关此问题的更多信息。
## 安装说明
标准设置过程使用项目依赖库的最后测试提交，以确保与本项目自动化工具的兼容性。设置脚本执行系统检测，安装所有必需组件，并根据所需的测试配置支持多种安装模式。
虽然默认配置优先考虑稳定性，但用户可以选择配置设置以拉取更新版本的 OQS 库。这对于测试上游更改或最近的算法更新很有用。有关更高级的配置选项，请参阅 [可选设置标志](#optional-setup-flags) 部分。
以下说明描述了标准设置过程，这是默认且推荐的选项。
### 克隆仓库
克隆当前的稳定版本：
```
git clone https://github.com/crt26/PQC-LEO.git
```
进入克隆的仓库目录并执行设置脚本：
```
cd PQC-LEO
./setup.sh
```
您可能需要更改设置脚本的权限；如果是这种情况，可以使用以下命令完成：
```
chmod +x ./setup.sh
```
### 选择安装模式
执行设置脚本时，系统将提示您选择以下安装选项之一：
1. **仅计算性能测试** - 安装用于独立性能基准测试（CPU 和内存）的组件。
2. **完整安装** - 安装用于计算和 TLS 性能测试的所有组件。
3. **仅 TLS 测试库** - 仅安装 TLS 基准测试组件。（**需要先完成选项 1**）。
设置脚本还将在仓库的 `lib` 目录中构建 [OpenSSL 3.5.0](https://github.com/openssl/openssl/releases/tag/openssl-3.5.0)。此版本是支持 OQS 库所必需的，并且与系统的默认 OpenSSL 安装分开构建。它不会干扰系统级二进制文件。
如果安装了 TLS 测试库（选项 2 或 3），系统将提示您进行以下附加设置选项：
- **启用所有禁用的签名算法** – 包括 OQS-Provider 库中默认禁用的所有数字签名算法。这确保可以在 TLS 性能测试中测试全部支持的算法 **†**。
- **启用 KEM 编码器** – 添加对 OpenSSL 可选 KEM 编码器功能的支持。基准测试套件目前不使用此功能，但希望对其进行试验的开发人员可以使用它。
选择所有相关选项后，设置脚本将下载、配置和构建每个库。它还将通过应用适当的构建标志，针对您的系统架构调整构建。
### 确保根目录路径标记存在
在设置期间，会在项目的根目录中创建一个名为 `.pqc_leo_dir_marker.tmp` 的隐藏文件。自动化脚本使用此标记来可靠地识别根路径，这对于它们的正确运行至关重要。
运行设置脚本时，务必从仓库的根目录执行，以便正确放置此文件。
在项目处于配置状态时，请**勿**删除或重命名此文件。使用 `cleaner.sh` 实用脚本卸载所有库时，它将被自动删除。如果手动删除了该文件，可以通过重新运行设置脚本或手动创建来重新生成它。
要验证文件是否存在，请使用：
```
ls -la
```
要手动重新创建文件，请从项目根目录运行以下命令：
```
touch .pqc_leo_dir_marker.tmp
```
### 可选设置标志
有关高级设置选项，包括：
- 拉取最新版本的 OQS 库而不是默认的测试版本
- 自定义 OpenSSL `speed.c` 限制
- 在 OQS 库中启用 HQC 算法
请参阅 [高级设置配置指南](docs/advanced_setup_configuration.md)。
## 自动化测试工具
该仓库提供两类自动化 PQC 基准测试：
- **计算性能测试** – 对 PQC 密码操作的独立性能进行基准测试，收集有关 CPU 和峰值内存使用情况的数据。
- **TLS 性能测试** – 对集成到 TLS 1.3 协议中的 PQC、Hybrid-PQC 和经典算法进行基准测试，包括握手和密码操作性能。
测试工具位于 `scripts/test_scripts` 目录中，并且是完全自动化的。这些工具支持为收集的结果分配自定义机器 ID，以便于比较不同系统上的性能。
### 计算性能测试
此工具对 Liboqs 库支持的各种 PQC 算法的 CPU 和峰值内存使用情况进行基准测试。它为每个测试算法生成详细的性能指标。
有关详细的使用说明，请参阅：
[自动化计算性能测试说明](docs/testing_tools_usage/computational_performance_testing.md)
### TLS 性能测试
此工具对在 TLS 1.3 协议中使用的 PQC、Hybrid-PQC 和经典算法的性能进行基准测试。它利用 OpenSSL 3.5.0 中原生可用的 PQC 实现以及通过 OQS-Provider 添加的实现。
它进行两种类型的测试：
- **TLS 握手性能测试** – 测量 TLS 1.3 握手期间 PQC 和 Hybrid-PQC 算法的性能。
- **密码操作基准测试** – 测量集成在 OpenSSL 中的单个 PQC/Hybrid-PQC 数字签名和密钥封装机制 (KEM) 密码操作的 CPU 性能。
测试可以在单台机器上执行，也可以在通过物理/虚拟网络连接的两台机器上执行。虽然多机器设置涉及额外的配置，但自动化工具完全支持它。
有关详细的使用说明，请参阅：
[自动化 TLS 性能测试说明](docs/testing_tools_usage/tls_performance_testing.md)
### 测试输出文件
测试完成后，未解析的结果和自动解析的结果将存储在生成的 `test_data/` 目录中：
**未解析结果：** `test_data/up_results/`
**已解析结果：** `test_data/results/`
## 解析测试结果
默认情况下，测试结果会在每个测试脚本结束时自动解析。这将根据执行的性能测试类型生成结构化的 CSV 输出文件。
根据执行的测试，已解析的结果将存储在以下目录中：
- `test_data/results/computational_performance/machine_x`
- `test_data/results/tls_performance/machine_x`
其中 `machine_x` 是执行测试脚本时分配给结果的机器 ID 编号。如果未分配自定义机器 ID，则将为结果设置默认 ID 1。
如果需要，可以通过向测试脚本传递标志，在调用测试脚本时禁用自动解析。这有助于手动调用 Python 解析脚本。
有关解析功能和收集的性能指标细分的完整详细信息，请参阅以下文档：
- [解析性能结果使用指南](docs/performance_results/parsing_scripts_usage_guide.md)
- [性能指标指南](docs/performance_results/performance_metrics_guide.md)
## 附加文档
### 内部项目文档
下面的链接提供了对各种内部项目文档的访问。但是，这些文档大多可以在项目根目录的 `docs` 目录中找到。
| **类别** | **文档** |
|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **测试工具使用** | - [自动化计算性能测试](docs/testing_tools_usage/computational_performance_testing.md)
- [自动化 TLS 性能测试](docs/testing_tools_usage/tls_performance_testing.md) | | **设置与配置** | - [高级设置配置](docs/advanced_setup_configuration.md)
- [支持的算法](docs/supported_algorithms.md) | | **项目依赖与开发者信息** | - [项目依赖项](./docs/developer_information/project_dependencies.md)
- [项目脚本](docs/developer_information/project_scripts.md)
- [仓库结构](docs/developer_information/repository_directory_structure.md) | | **性能结果** | - [解析性能结果使用指南](docs/performance_results/parsing_scripts_usage_guide.md)
- [性能指标指南](docs/performance_results/performance_metrics_guide.md) | | **其他资源** | - [项目免责声明](./DISCLAIMER.md) | ### 项目 Wiki 页面 内部文档中提供的信息也可通过项目的 GitHub Wiki 获取： [PQC-LEO Wiki](https://github.com/crt26/PQC-LEO/wiki) ### 有用的外部文档链接 - [Liboqs 网页](https://openquantumsafe.org/liboqs/) - [Liboqs GitHub 页面](https://github.com/open-quantum-safe/liboqs) - [OQS-Provider 网页](https://openquantumsafe.org/applications/tls.html#oqs-openssl-provider) - [OQS-Provider GitHub 页面](https://github.com/open-quantum-safe/oqs-provider) - [最新 Liboqs 发布说明](https://github.com/open-quantum-safe/liboqs/blob/main/RELEASE.md) - [最新 OQS-Provider 发布说明](https://github.com/open-quantum-safe/oqs-provider/blob/main/RELEASE.md) - [OpenSSL(3.5.0) 文档](https://docs.openssl.org/3.5/) - [TLS 1.3 RFC 8446](https://www.rfc-editor.org/rfc/rfc8446) ## 许可证 本项目根据 MIT 许可证授权 – 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ##致谢 本项目依赖于以下第三方软件和库： 1. **[Liboqs](https://github.com/open-quantum-safe/liboqs)** – 用于提供后量子密钥封装机制 (KEM) 和数字签名算法的独立实现，以进行计算性能测试。本项目包含 `test_kem_mem.c` 和 `test_sig_mem.c` 文件的修改版本，以便在基准测试期间以最少的终端输出收集详细的内存使用指标。这些修改保留在原始 MIT 许可证下，该许可证在每个修改文件的顶部注明。 2. **[OQS-Provider](https://github.com/open-quantum-safe/oqs-provider)** – 用于通过 Provider 接口将来自 `Liboqs` 的后量子算法集成到 OpenSSL 中，从而实现基于 TLS 的性能测试。修改包括动态更改 `generate.yml` 模板，以有选择地启用所有默认禁用的签名算法。该 Provider 在本地构建并动态链接到 OpenSSL。它根据 MIT 许可证授权。 3. **[OpenSSL](https://github.com/openssl/openssl)** – 用作 TLS 测试和基准测试的核心密码库。本项目在构建过程中应用运行时修改，以增加 `speed.c` 中的硬编码算法限制（`MAX_KEM_NUM` 和 `MAX_SIG_NUM`），以支持更广泛算法集的基准测试，并向 `openssl.cnf` 附加配置指令以注册和激活 `oqsprovider`。OpenSSL 根据 Apache License 2.0 授权。 4. **[pqax](https://github.com/mupq/pqax)** – 用于在 ARM 系统上（如 Raspberry Pi）启用对 ARM 性能监视器单元 (PMU) 的访问。这允许对 CPU 周期进行精确的基准测试。未对原始源代码进行任何修改。Pqax 根据 Creative Commons Zero v1.0 Universal (CC0) 许可证授权，将其置于公共领域。
- [自动化 TLS 性能测试](docs/testing_tools_usage/tls_performance_testing.md) | | **设置与配置** | - [高级设置配置](docs/advanced_setup_configuration.md)
- [支持的算法](docs/supported_algorithms.md) | | **项目依赖与开发者信息** | - [项目依赖项](./docs/developer_information/project_dependencies.md)
- [项目脚本](docs/developer_information/project_scripts.md)
- [仓库结构](docs/developer_information/repository_directory_structure.md) | | **性能结果** | - [解析性能结果使用指南](docs/performance_results/parsing_scripts_usage_guide.md)
- [性能指标指南](docs/performance_results/performance_metrics_guide.md) | | **其他资源** | - [项目免责声明](./DISCLAIMER.md) | ### 项目 Wiki 页面 内部文档中提供的信息也可通过项目的 GitHub Wiki 获取： [PQC-LEO Wiki](https://github.com/crt26/PQC-LEO/wiki) ### 有用的外部文档链接 - [Liboqs 网页](https://openquantumsafe.org/liboqs/) - [Liboqs GitHub 页面](https://github.com/open-quantum-safe/liboqs) - [OQS-Provider 网页](https://openquantumsafe.org/applications/tls.html#oqs-openssl-provider) - [OQS-Provider GitHub 页面](https://github.com/open-quantum-safe/oqs-provider) - [最新 Liboqs 发布说明](https://github.com/open-quantum-safe/liboqs/blob/main/RELEASE.md) - [最新 OQS-Provider 发布说明](https://github.com/open-quantum-safe/oqs-provider/blob/main/RELEASE.md) - [OpenSSL(3.5.0) 文档](https://docs.openssl.org/3.5/) - [TLS 1.3 RFC 8446](https://www.rfc-editor.org/rfc/rfc8446) ## 许可证 本项目根据 MIT 许可证授权 – 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ##致谢 本项目依赖于以下第三方软件和库： 1. **[Liboqs](https://github.com/open-quantum-safe/liboqs)** – 用于提供后量子密钥封装机制 (KEM) 和数字签名算法的独立实现，以进行计算性能测试。本项目包含 `test_kem_mem.c` 和 `test_sig_mem.c` 文件的修改版本，以便在基准测试期间以最少的终端输出收集详细的内存使用指标。这些修改保留在原始 MIT 许可证下，该许可证在每个修改文件的顶部注明。 2. **[OQS-Provider](https://github.com/open-quantum-safe/oqs-provider)** – 用于通过 Provider 接口将来自 `Liboqs` 的后量子算法集成到 OpenSSL 中，从而实现基于 TLS 的性能测试。修改包括动态更改 `generate.yml` 模板，以有选择地启用所有默认禁用的签名算法。该 Provider 在本地构建并动态链接到 OpenSSL。它根据 MIT 许可证授权。 3. **[OpenSSL](https://github.com/openssl/openssl)** – 用作 TLS 测试和基准测试的核心密码库。本项目在构建过程中应用运行时修改，以增加 `speed.c` 中的硬编码算法限制（`MAX_KEM_NUM` 和 `MAX_SIG_NUM`），以支持更广泛算法集的基准测试，并向 `openssl.cnf` 附加配置指令以注册和激活 `oqsprovider`。OpenSSL 根据 Apache License 2.0 授权。 4. **[pqax](https://github.com/mupq/pqax)** – 用于在 ARM 系统上（如 Raspberry Pi）启用对 ARM 性能监视器单元 (PMU) 的访问。这允许对 CPU 周期进行精确的基准测试。未对原始源代码进行任何修改。Pqax 根据 Creative Commons Zero v1.0 Universal (CC0) 许可证授权，将其置于公共领域。
标签：ARM架构, Benchmark, Cutter, Liboqs, Open Quantum Safe, OpenSSL, PQC, Python, TLS 1.3, x86架构, 后量子密码学, 安全测试工具, 密码学, 性能评估, 手动系统调用, 握手测试, 无后门, 科研工具, 算法测试, 网络安全, 网络性能, 自动化框架, 计算性能, 逆向工具, 隐私保护