skradfasket/pqcproto_cpp20

# pqcproto (C++20) — MATH 410 协议核心脚手架 本仓库提供了一个使用 **C++20** 编写的、与传输层无关的认证密钥交换核心，并带有 **C ABI 包装器**。 当前基线范围： - KEM 通过 **liboqs**：`ML-KEM-768`、`NTRU-HPS-2048-677` - 数字签名通过 **liboqs**：`ML-DSA-65` - 密钥调度通过 **libsodium**：`HKDF-SHA256` - 证明 AEAD 通过 **libsodium**：`XChaCha20-Poly1305` - 显式套件目录、跟踪钩子、场景线束和拆分测试 - 暂无传输层代码 该项目的目标是首先构建 *协议核心*，保持后端和套件选择的显式化，并将传输层集成推迟到核心、线束和审计体系稳定之后再进行。 ## 审计与最终报告文档 有关审计、审查和最终论文的准备工作，请参见： - [docs/PROTOCOL_MAP.md](docs/PROTOCOL_MAP.md)： 将传输层无关的协议流程映射到具体的代码层面。 - [docs/SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md)： 总结了当前的安全目标、信任假设、验证证据、 局限性、秘密处理或日志记录说明，以及未来的生产环境工作。 - [docs/VALIDATION_ARTIFACTS.md](docs/VALIDATION_ARTIFACTS.md)： 解释了如何复现和解释验证矩阵、JSONL 报告、 汇总器输出以及近期的本地验证构件。 这些文档旨在支持审计或审查工作，以及 MATH 409 或 MATH 410 最终论文的准备工作。它们并非生产环境的部署声明。 ## 依赖项 (WSL Ubuntu/Debian) ``` sudo apt update sudo apt install -y build-essential cmake ninja-build pkg-config git libsodium-dev ``` ### liboqs 如果您尚未安装 `liboqs`： ``` git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git cd liboqs cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DOQS_USE_OPENSSL=OFF cmake --build build sudo cmake --install build sudo ldconfig ``` ## 已确认的 WSL 快速入门 本仓库在当前里程碑下经过验证的本地检查点环境 （除了明确限制版本的地方，并非严格的精确要求）： - `liboqs 0.15.0` - `libsodium 1.0.22` - `cmake 3.28.3` - `ninja 1.11.1` - `g++ 13.3.0` 当前严格的版本限制： - 要求 `libsodium >= 1.0.19`，因为 HKDF 后端使用了 `crypto_kdf_hkdf_sha256_*`。 - OpenSSL 对比路径要求已发现的 `OpenSSL >= 3.5` 如果您需要 OpenSSL 对比套件，而您默认的系统 OpenSSL 版本低于 `3.5`， 请明确指定 CMake 使用合适的安装路径： ``` cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DOPENSSL_ROOT_DIR=/path/to/openssl-prefix # 或 cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DCMAKE_PREFIX_PATH=/path/to/openssl-prefix ``` 如果您只想在带有较旧 OpenSSL 的机器上运行基线 `liboqs` + `libsodium` 路径： ``` cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DPQCPROTO_ENABLE_OPENSSL_COMPARISON=OFF ``` 在该检查点环境中确认可用的确切 WSL 构建、测试和 CLI 验证步骤： ``` sudo apt update sudo apt install -y build-essential cmake ninja-build pkg-config git libsodium-dev # 如果尚未安装 liboqs： git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git cd liboqs cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DOQS_USE_OPENSSL=OFF cmake --build build sudo cmake --install build sudo ldconfig cd .. cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ctest --test-dir build --output-on-failure ./build/pqcprotoctl --help ./build/pqcprotoctl --list-suites ./build/pqcprotoctl --list-kems ./build/pqcprotoctl --list-sigs ./build/pqcprotoctl kem --kem liboqs:ML-KEM-768 ./build/pqcprotoctl sig --sig liboqs:ML-DSA-65 ./build/pqcprotoctl kem --kem openssl:ML-KEM-768 ./build/pqcprotoctl sig --sig openssl:ML-DSA-65 ./build/pqcprotoctl handshake \ --suite baseline.liboqs-libsodium.ml-kem-768.ml-dsa-65.hkdf-sha256.xchacha20-poly1305 \ --verification-mode strict_profile \ --seed 410 \ --verbose ./build/pqcprotoctl handshake \ --suite baseline.liboqs-libsodium.ntru-hps-2048-677.ml-dsa-65.hkdf-sha256.xchacha20-poly1305 \ --verification-mode strict_profile \ --json ./build/pqcprotoctl handshake \ --suite interop.openssl.ml-kem-768.ml-dsa-65.hkdf-sha256.chacha20-poly1305 \ --verification-mode strict_profile \ --seed 411 \ --verbose ``` ## 构建 + 测试 ``` cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ctest --test-dir build --output-on-failure ``` ## 验证矩阵 当前里程碑已验证的矩阵为： - 基线构建和测试： `RelWithDebInfo`、`PQCPROTO_ENABLE_OPENSSL_COMPARISON=OFF` - 启用 OpenSSL 的构建和测试： `RelWithDebInfo`、`PQCPROTO_ENABLE_OPENSSL_COMPARISON=ON` - 启用 Sanitizer 的基线构建和测试： `Debug`、`PQCPROTO_ENABLE_SANITIZERS=ON`、`PQCPROTO_ENABLE_OPENSSL_COMPARISON=OFF` - 启用 Sanitizer 的 OpenSSL 构建和测试： `Debug`、`PQCPROTO_ENABLE_SANITIZERS=ON`、`PQCPROTO_ENABLE_OPENSSL_COMPARISON=ON` - 对抗性 JSON 活动摘要： 启用 Sanitizer 的 OpenSSL 构建下的 `test_scenarios`，通过 `scripts/pqcproto_test_report_summary.py` 进行汇总 使用辅助脚本端到端运行完整的矩阵： ``` ./scripts/run_validation_matrix.sh ``` 如果您的系统 OpenSSL 版本低于 `3.5`，请让脚本指向合适的安装路径： ``` OPENSSL_ROOT_DIR=/path/to/openssl-prefix \ CMAKE_PREFIX_PATH=/path/to/openssl-prefix \ ./scripts/run_validation_matrix.sh ``` 该脚本是保守且快速失败的： - 它按顺序配置、构建和测试每个矩阵行 - 如果任何配置、构建、测试或报告步骤失败，它会立即停止 - 它在启用 Sanitizer 的 OpenSSL 构建目录下 写入对抗性 JSONL 活动和文本摘要 上次验证行的预期构件： - `build-asan-openssl/test_scenarios.jsonl` - `build-asan-openssl/test_scenarios.summary.txt` 用于不使用完整矩阵脚本的直接 Sanitizer 工作流： ``` cmake -S . -B build-asan -GNinja \ -DCMAKE_BUILD_TYPE=Debug \ -DPQCPROTO_ENABLE_SANITIZERS=ON \ -DPQCPROTO_ENABLE_OPENSSL_COMPARISON=OFF cmake --build build-asan ctest --test-dir build-asan --output-on-failure cmake -S . -B build-asan-openssl -GNinja \ -DCMAKE_BUILD_TYPE=Debug \ -DPQCPROTO_ENABLE_SANITIZERS=ON \ -DPQCPROTO_ENABLE_OPENSSL_COMPARISON=ON \ -DOPENSSL_ROOT_DIR=/path/to/openssl-prefix \ -DCMAKE_PREFIX_PATH=/path/to/openssl-prefix cmake --build build-asan-openssl ctest --test-dir build-asan-openssl --output-on-failure ASAN_OPTIONS=detect_leaks=0 PQCPROTO_TEST_REPORT_MODE=json \ ./build-asan-openssl/test_scenarios \ | python3 scripts/pqcproto_test_report_summary.py ``` 当 `PQCPROTO_ENABLE_SANITIZERS=ON` 时，CTest 运行会使用 `ASAN_OPTIONS=detect_leaks=0` 禁用泄漏检测，以避免此环境中已知的 LeakSanitizer ptrace 限制。常规的构建和测试保持不变。 ## 运行 CLI 演示 ``` ./build/pqcprotoctl --list-suites ./build/pqcprotoctl --list-kems ./build/pqcprotoctl --list-sigs ./build/pqcprotoctl kem --kem liboqs:ML-KEM-768 ./build/pqcprotoctl kem --kem liboqs:NTRU-HPS-2048-677 ./build/pqcprotoctl kem --kem openssl:ML-KEM-768 ./build/pqcprotoctl sig --sig liboqs:ML-DSA-65 ./build/pqcprotoctl sig --sig openssl:ML-DSA-65 ./build/pqcprotoctl handshake \ --suite baseline.liboqs-libsodium.ml-kem-768.ml-dsa-65.hkdf-sha256.xchacha20-poly1305 \ --verification-mode strict_profile \ --seed 410 \ --verbose ./build/pqcprotoctl handshake \ --suite baseline.liboqs-libsodium.ntru-hps-2048-677.ml-dsa-65.hkdf-sha256.xchacha20-poly1305 \ --verification-mode strict_profile \ --json ./build/pqcprotoctl handshake \ --suite interop.openssl.ml-kem-768.ml-dsa-65.hkdf-sha256.chacha20-poly1305 \ --verification-mode strict_profile \ --seed 411 \ --verbose ``` ## 安装 (库 + 头文件) ``` sudo cmake --install build sudo ldconfig ``` 此操作会安装： - `libpqcproto.so` - 头文件至 `/usr/local/include/pqcproto` 目录下 - `pqcprotoctl` 至 `/usr/local/bin` 目录下 ## C ABI 包装器 C API 声明于： - `include/pqcproto/c_api.h` 可将其用于 C、Python ctypes 或其他语言。 ## 备注 - 线束当前在运行时生成用于测试和演练的身份密钥。 - CLI 默认可使用安全随机性运行，或通过 `--seed` 使用确定性种子随机性运行。 - 验证默认设置为 `strict_profile`；`algorithm_compatible` 保留用于精确算法的比较工作。 - 可复现性检查固定于序列化的握手/证明构件以及通过语义查询的跟踪元数据，而不是基于总的 trace-list 身份。 - 旧的 C API 构建辅助程序仍然从 KEM + 签名句柄推断已实现的基线套件；该兼容路径是临时的，并在 C 头文件中作为此类情况进行了记录。 - OpenSSL 对比套件仅在构建启用对比路径并发现 `OpenSSL >= 3.5` 时才会实现。 - OpenSSL 对比套件有意采用了与基线 libsodium XChaCha 配置文件不同的构造。 - 请参阅 `MISSION.md`、`ARCHITECTURE.md`、`SUITES.md` 和 `ROADMAP.md` 以了解当前范围与推迟的工作。

标签：AEAD, Bash脚本, C++20, C ABI, HKDF, JSONLines, liboqs, libsodium, ML-DSA, ML-KEM, NTRU, OpenSSL, PQC, XChaCha20-Poly1305, 传输无关, 加密库, 协议核心, 后量子密码学, 安全测试工具, 密码学协议, 密钥交换, 对抗性验证, 抗量子计算, 数学建模, 本体建模, 网络安全, 逆向工具, 隐私保护, 零信任