EliottFlechtner/libPQC

# libPQC [](https://github.com/EliottFlechtner/libPQC/actions/workflows/ci.yml) [](https://github.com/EliottFlechtner/libPQC/actions/workflows/codeql.yml) [](https://github.com/EliottFlechtner/libPQC/actions/workflows/release.yml) [](https://github.com/EliottFlechtner/libPQC/actions/workflows/experiments-baseline.yml) [](coverage/summary.md) 基于格的后量子密码学实验场，专注于 ML-KEM 和 ML-DSA 的清晰、可测试实现。 当前状态：v0.2.0（v0.1.0 之后的当前整合版本）。 ## 文档 - 使用指南：`docs/USAGE_GUIDE.md` - API 参考：`docs/API_REFERENCE.md` - 架构：`docs/ARCHITECTURE.md` - 安全说明：`docs/SECURITY.md` - 性能指南：`docs/PERFORMANCE.md` - 变更日志：`docs/CHANGELOG.md` ## 发布亮点 - 完整的 ML-KEM 流程：密钥生成、封装、解封装 - 完整的 ML-DSA 流程：密钥生成、签名、验证 - 完整的 CLI 用于演示、性能测试、配置和互操作包 - 默认运行流程中集成了分析演示 - 两种方案均可重现的确定性演示 - 自动化 CI、CodeQL、发布流程和覆盖率发布 ## 当前已实现的内容 - `src/core` 中的核心代数原语： - 整数环 - 多项式环和商多项式环 - 模运算 - 序列化辅助函数 - NTT 和采样工具 - `src/schemes/ml_kem` 中的 ML-KEM PKE 基础： - 密钥生成 - 加密/解密 - 参数预设（`ML-KEM-512`、`ML-KEM-768`、`ML-KEM-1024`） - 确定性矩阵扩展辅助函数 - 密文压缩/解压缩（`c1`/`c2` 流程） - 过渡期间用于传统 `u`/`v` 密文负载的兼容分支 - `src/schemes/ml_kem` 中的 ML-KEM KEM 层： - `ml_kem_keygen` - `ml_kem_encaps` - `ml_kem_decaps` - FO 风格哈希辅助函数（`G`、`H`、`J`） - `src/schemes/ml_dsa` 中的 ML-DSA 层： - `ml_dsa_keygen` - `ml_dsa_sign` - `ml_dsa_verify` - 参数预设（`ML-DSA-44`、`ML-DSA-65`、`ML-DSA-87`） - Power2Round 分割（`t1` 公开，`t0` 秘密） - 基于提示的签名/验证流程（`MakeHint`/`UseHint` 风格） ## 当前范围 - `src/schemes/ml_kem` 和 `src/schemes/ml_dsa` 用于密码学核心流程 - `src/app` 用于命令行工作流（演示、性能测试、配置、互操作） - `tests/conformance` 用于 KAT 验证和向量级兼容性检查 ## 项目结构 ``` src/ analysis/ cost_calculator.py # classical/quantum cost helpers lattice_attacks.py # lattice attack estimators (LLL/BKZ) ml_kem_attacks.py # ML-KEM attack-surface analysis helpers ml_dsa_attacks.py # ML-DSA attack-surface analysis helpers app/ __init__.py # app package exports __main__.py # python -m src.app entrypoint cli.py # command routing and JSON output handlers performance.py # benchmark/profile orchestration helpers interoperability.py # export/import bundle conversion helpers core/ integers.py # integer ring arithmetic polynomials.py # polynomial ring operations module.py # module arithmetic ntt.py # number-theoretic transform sampling.py # sampling utilities (CBD, uniform) serialization.py # byte serialization helpers schemes/ utils.py # shared utilities (CRH, XOF, PRF) ml_kem/ kyber_pke.py # PKE foundation layer pke_utils.py # PKE helper functions vectors.py # matrix/vector definitions params.py # ML-KEM parameter presets kyber_ntt.py # NTT-based operations for ML-KEM kyber_sampling.py # ML-KEM-specific sampling keygen.py # KEM key generation encaps.py # KEM encapsulation decaps.py # KEM decapsulation hashes.py # G/H/J hash and derivation functions ml_kem.py # canonical high-level exports ml_dsa/ params.py # ML-DSA parameter presets keygen.py # key generation sign.py # signing logic verify.py # verification logic sign_verify_utils.py # signing/verification utilities ml_dsa.py # canonical high-level exports comms/ # reserved communication-layer workspace experiments/ # reserved experiments workspace tests/ analysis/ test_*.py # attack-analysis and cost-model tests app/ cli/ test_*.py # CLI command routing and branch-path tests interoperability/ test_*.py # export/import helpers and payload validation tests performance/ test_*.py # benchmark/profile helper tests test_main_module.py # module entrypoint behavior conformance/ common/ # shared KAT/RSP loaders and helpers ml_kem/ # ML-KEM vector adapters/loaders ml_dsa/ # ML-DSA vector adapters/loaders test_ml_kem_kat.py # ML-KEM KAT suite test_ml_dsa_kat.py # ML-DSA KAT suite test_rsp.py # RSP adapter round-trip tests vectors/ # checked-in ML-KEM/ML-DSA vector corpus core/ test_*.py # core algebra tests integration/ test_*.py # end-to-end and MLWE integration tests schemes/ ml_kem/ test_*.py # ML-KEM tests ml_dsa/ test_*.py # ML-DSA tests test_analysis.py # top-level analysis compatibility test module ``` ## 快速开始 ### 1. 运行演示 ``` python3 scratch.py ``` 这将一步运行完整的演示套件（密码学流程和分析演示）。 ### 2. 运行方案特定的演示 ``` python3 demos/ml_kem_demo.py python3 demos/ml_dsa_demo.py ``` ### 3. 直接使用 PKE API ``` from src.schemes.ml_kem.kyber_pke import ( kyber_pke_keygen, kyber_pke_encryption, kyber_pke_decryption, ) params = "ML-KEM-768" pk, sk = kyber_pke_keygen(params) message = b"0123456789abcdef0123456789abcdef" # 32 bytes required ciphertext = kyber_pke_encryption(pk, message, params=params, coins=b"a" * 32) recovered = kyber_pke_decryption(ciphertext, sk, params=params) assert recovered == message ``` ## 互操作性 CLI 现在包含导出/导入辅助函数，可发出规范的 JSON 包和标准友好的压缩十六进制，供下游工具使用： ``` python3 scratch.py interop export ml-kem keypair --params ML-KEM-768 --output ml-kem-keypair.json python3 scratch.py interop export ml-dsa test-vector --params ML-DSA-87 --message 'interop message 32-bytes exact!!' --output ml-dsa-vector.json python3 scratch.py interop import ml-kem keypair --input ml-kem-keypair.json ``` 导出的包包含 libPQC JSON 负载以及适用的压缩 RSP 十六进制，便于将数据输入 KAT 工具或外部测试框架。 ## 测试 运行完整测试套件（递归发现）： ``` python3 -m unittest discover -s tests -p 'test_*.py' ``` 仅运行核心数学测试： ``` python3 -m unittest discover -s tests/core -p 'test_*.py' ``` 仅运行 ML-KEM 方案测试： ``` python3 -m unittest discover -s tests/schemes/ml_kem -p 'test_*.py' ``` 运行集成风格测试： ``` python3 -m unittest discover -s tests/integration -p 'test_*.py' ``` 在迭代时运行单个方案测试模块： ``` python3 -m unittest tests/schemes/ml_dsa/test_ml_dsa_sign.py ``` ## KAT 一致性 该仓库包含 ML-KEM 和 ML-DSA 的基于向量的一致性套件： - `tests/conformance/test_ml_kem_kat.py` - `tests/conformance/test_ml_dsa_kat.py` 在严格全向量模式下运行两个 KAT 套件： ``` LIBPQC_KAT_MAX_RECORDS=1000 LIBPQC_KAT_REQUIRE_FULL=1 \ python3 -m unittest tests/conformance/test_ml_kem_kat.py tests/conformance/test_ml_dsa_kat.py ``` 运行快速 KAT 冒烟检查（每个向量文件 2 条记录），带进度和计时： ``` LIBPQC_KAT_MAX_RECORDS=2 LIBPQC_KAT_PROGRESS=1 LIBPQC_KAT_TIMING=1 \ python3 -m unittest tests/conformance/test_ml_kem_kat.py tests/conformance/test_ml_dsa_kat.py ``` 生成每个向量的一致性摘要（通过/失败、已处理计数、耗时）： ``` python3 scripts/conformance_summary.py --max-records 2 ``` 全向量摘要模式： ``` python3 scripts/conformance_summary.py --max-records 1000 --full ``` 有用的运行时控制： - `LIBPQC_KAT_MAX_RECORDS`：每个向量文件最多处理记录数 - `LIBPQC_KAT_REQUIRE_FULL`：强制处理每个文件中的所有记录 - `LIBPQC_KAT_PROGRESS`：打印每个文件的进度计数器 - `LIBPQC_KAT_TIMING`：在完成输出中打印每个文件的耗时秒数 - `LIBPQC_KAT_VECTOR_FILTER`：向量文件名的可选正则表达式过滤器 CI 行为： - 拉取请求和非计划 CI 运行执行常规非一致性套件加缩减的一致性冒烟模式（`LIBPQC_KAT_MAX_RECORDS=2`）。 - 夜间计划 CI 执行严格全向量一致性（`LIBPQC_KAT_MAX_RECORDS=1000` + `LIBPQC_KAT_REQUIRE_FULL=1`）。 有关一致性辅助函数、适配器层和推荐文件夹架构的详细信息，请参阅 `tests/conformance/README.md`。 ### 当前 KAT 状态（已验证） 截至 2026-04-06，两个一致性套件均通过当前签入的向量语料库验证（`tests/conformance/vectors/ml_kem/*.rsp` 和 `tests/conformance/vectors/ml_dsa/*.rsp`）。 已验证的运行： - 默认模式 - `python3 -m unittest tests/conformance/test_ml_kem_kat.py tests/conformance/test_ml_dsa_kat.py` - 结果：`Ran 6 tests ... OK` - 严格全向量模式 - `LIBPQC_KAT_MAX_RECORDS=1000 LIBPQC_KAT_REQUIRE_FULL=1 python3 -m unittest tests/conformance/test_ml_kem_kat.py tests/conformance/test_ml_dsa_kat.py` - 结果：`Ran 6 tests ... OK` 当前保证的内容： - ML-KEM 向量比较通过压缩公钥、压缩私钥、密文字节和共享密钥检查。 - ML-DSA 向量比较通过压缩验证/签名密钥、签名字节和向量特定消息域处理的验证接受（`raw`、`pure`、`hashed` 和 hedged/确定性模式）。 ## 覆盖率 生成覆盖率数据和报告： ``` coverage erase coverage run -m unittest discover -s tests -p 'test_*.py' coverage json -o coverage/coverage.json coverage html -d coverage/html coverage xml -o coverage/coverage.xml python3 scripts/update_coverage_assets.py ``` 有用的输出： - `coverage/summary.md` - `coverage/badge.svg` 注意： - HTML 覆盖率输出在本地生成（`coverage html -d coverage/html`）或作为 CI 产物提供，不会提交到仓库。 ## 发布流程 该仓库包含 `.github/workflows/release.yml` 中的发布工作流。 对于标签发布： ``` git checkout main git pull --ff-only git tag vX.Y.Z git push origin vX.Y.Z ``` 工作流运行测试并在 GitHub Releases 中发布源代码包。 发布说明请参阅 `docs/CHANGELOG.md`。 ## 设计说明 - 导入应使用规范的 `src.*` 路径。 - 当前 Kyber-PKE 辅助函数的消息固定为 32 字节。 - 仓库倾向于明确的、可测试的构建块，而不是紧密耦合的抽象。 ## 路线图 当前重点领域： - 性能分析和可选的优化路径 - 更丰富的协议级示例（密钥交换 + 签名通道框架） - API 稳定性和打包改进 - 打包和分发的人体工程学（CLI/文档/发布流程） ## 许可证 本项目根据 `LICENSE` 中的条款获得许可。

标签：CVE, DNS解析, KAT测试, Lattice-based Cryptography, ML-DSA, ML-KEM, NTT, Post-quantum Cryptography, PQC, Python, 代码覆盖率, 后量子密码学, 多项式环, 密码学原语, 密码学库, 密钥封装, 开源框架, 开源项目, 持续集成, 数字签名, 无后门, 格密码学, 模块算术, 测试驱动开发, 确定性测试, 逆向工具