pq-code-package/mldsa-native
GitHub: pq-code-package/mldsa-native
安全、快速且可移植的 ML-DSA 后量子签名标准 C90 实现，具备形式化验证和常量时间安全保障。
Stars: 57 | Forks: 39
# mldsa-native
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://opensource.org/licenses/ISC)
[](https://opensource.org/licenses/MIT)
mldsa-native 是 ML-DSA[^FIPS204] 后量子签名标准的 C90[^C90] 实现，具有安全、快速且可移植的特点。它是 ML-DSA 参考实现[^REF] 的一个分支。
mldsa-native 由 [Linux Foundation](https://linuxfoundation.org/) 旗下的 [Post-Quantum Cryptography Alliance](https://pqca.org/) 提供支持。
## 为什么选择 mldsa-native？
mldsa-native 允许开发者以极低的性能和维护成本支持 ML-DSA。
**最小依赖：** mldsa-native 使用可移植的 C90 编写，对标准库的依赖极小且可配置。
**可维护性与安全性：** 每次代码变更都会通过静态模型检查（使用 CBMC）和动态检测（使用 valgrind）相结合的方式，自动检查内存安全性、类型安全性以及是否存在各类时序泄露。这降低了审查和维护负担，并加速了安全代码的交付。请参阅 [形式化验证](#formal-verification) 和 [安全性](#security)。
**架构支持：** 原生后端在统一的接口下添加，最大限度地减少了重复代码和推理工作。mldsa-native 附带 AArch64 和 x86-64 的后端。请参阅 [设计](#design)。
## Ubuntu 快速入门指南
```
# 安装基础软件包
sudo apt-get update
sudo apt-get install make gcc python3 git
# 克隆 mldsa-native
git clone https://github.com/pq-code-package/mldsa-native.git
cd mldsa-native
# 构建并运行测试
make build
make test
# 使用 `tests`（`make` 的便捷封装）执行相同操作
./scripts/tests all
# 显示所有选项
./scripts/tests --help
```
## 应用场景
mldsa-native 被用于
- AWS 的加密库 [AWS-LC](https://github.com/aws/aws-lc/)
- Open Quantum Safe 项目的 [libOQS](https://github.com/open-quantum-safe/liboqs/)
- [zeroRISC 的 OpenTitan 分支](https://github.com/zerorisc/expo) —— 一个开源的硅信任根 (RoT)
- [CHERIoT-PQC](https://github.com/CHERIoT-Platform/cheriot-pqc) —— CHERIoT 平台的后量子密码学支持
## 形式化验证
我们使用 [C Bounded Model Checker (CBMC)](https://github.com/diffblue/cbmc) 来证明 C 代码中不存在各类未定义行为，包括越界内存访问和整数溢出。这些证明覆盖了使用 C 后端运行 mldsa-native 时涉及的 [mldsa/src/*](mldsa) 和 [mldsa/src/fips202/*](mldsa/src/fips202) 中的所有 C 代码。详情请参阅 [proofs/cbmc](proofs/cbmc)。
**注意：** `MLD_CONFIG_REDUCE_RAM` 配置选项目前不在 CBMC 证明的覆盖范围内。
HOL-Light 功能正确性证明可在 [proofs/hol_light](proofs/hol_light) 中找到。目前，以下函数已被证明正确：
- AArch64 poly_caddq [poly_caddq_asm.S](mldsa/src/native/aarch64/src/poly_caddq_asm.S)
- x86_64 NTT [ntt.S](mldsa/src/native/x86_64/src/ntt.S)
这些证明利用了 [s2n-bignum](https://github.com/awslabs/s2n-bignum) 中的验证基础设施。
最后，[proofs/isabelle](proofs/isabelle/compress) 包含了 [Isabelle/HOL](https://isabelle.in.tum.de/) 中关于计算 ML-DSA 中使用的标量分解例程的不同方法的正确性证明。这些仍处于实验阶段，尚未在源代码级别上进行操作。
## 安全性
mldsa-native 中的所有汇编代码都是常量时间的，即不存在依赖于秘密数据的控制流、内存访问以及常见的可变时间指令，从而阻止了大多数时序侧信道攻击。C 代码通过适当的屏障和常量时间模式进行了加固，以防止编译器引入的时序侧信道。
我们还使用 `valgrind` 结合各种编译器和编译选项的组合，来测试是否存在依赖于秘密数据的分支、内存访问模式和可变延迟指令。
## 设计
mldsa-native 分为 _前端_ 和两个用于算术与 FIPS202 / SHA3 的 _后端_。前端是固定的，用 C 编写，涵盖所有对性能不关键的例程。后端是灵活的，负责处理对性能敏感的例程，可以用 C 或原生代码（汇编/内建函数）实现；有关算术后端请参阅 [mldsa/src/native/api.h](mldsa/src/native/api.h)，有关 FIPS-202 后端请参阅 [mldsa/src/fips202/native/api.h](mldsa/src/fips202/native/api.h)。
mldsa-native 目前提供以下后端：
* 默认的可移植 C 后端
* 64 位 Arm 后端（使用 Neon）
* 64 位 Intel/AMD 后端（使用 AVX2）
* 32 位 Armv8.1-M 后端（使用 Helium/MVE）。这仍处于实验阶段，默认禁用。
如果您想贡献新的后端，请联系我们！
## ACVP 测试
mldsa-native 已针对所有官方 ACVP ML-DSA 测试向量[^ACVP] 进行了测试。
您可以使用 [`tests`](./scripts/tests) 脚本或直接使用 [ACVP client](./test/acvp/acvp_client.py) 运行 ACVP 测试：
```
# 使用 tests 脚本
./scripts/tests acvp
# 使用特定的 ACVP release
./scripts/tests acvp --version v1.1.0.41
# 直接使用 ACVP client
python3 ./test/acvp/acvp_client.py
python3 ./test/acvp/acvp_client.py --version v1.1.0.41
# 使用特定的 ACVP test vector 文件（从 ACVP-Server 下载）
# python3 ./test/acvp/acvp_client.py -p {PROMPT}.json -e {EXPECTED_RESULT}.json
# 例如，假设您已运行上述命令
python3 ./test/acvp/acvp_client.py \
-p ./test/acvp/.acvp-data/v1.1.0.41/files/ML-DSA-sigVer-FIPS204/prompt.json \
-e ./test/acvp/.acvp-data/v1.1.0.41/files/ML-DSA-sigVer-FIPS204/expectedResults.json
```
## 基准测试
您可以使用 [`tests`](./scripts/tests) 脚本测量性能、内存使用和二进制大小：
```
# 速度 benchmarks（-c 选择 cycle counter：NO、PMU、PERF 或 MAC）
# 注意：PERF/MAC 可能需要 -r flag 以使用 sudo 运行 benchmarking binaries
./scripts/tests bench -c PMU
./scripts/tests bench -c PERF -r
# Stack usage 分析
./scripts/tests stack
# Binary size 度量
./scripts/tests size
```
有关 CI 基准测试结果和历史性能数据，请参阅 [基准测试页面](https://pq-code-package.github.io/mldsa-native/dev/bench/)。
## 使用方法
如果您想使用 mldsa-native，请将 [mldsa](mldsa) 导入到您项目的源代码树中，并使用您喜欢的构建系统进行构建。有关简单示例，请参阅 [examples/basic](examples/basic)。本仓库中提供的构建系统仅用于开发目的。
### 我可以自带 FIPS-202 实现吗？
mldsa-native 依赖并附带 FIPS-202[^FIPS202] 的实现。如果您的库有自己的 FIPS-202 实现，您可以代替 mldsa-native 附带的版本使用。请参阅 [FIPS202.md](FIPS202.md)，以及使用 tiny_sha3[^tiny_sha3] 的示例 [examples/bring_your_own_fips202](examples/bring_your_own_fips202)。
### 我需要使用汇编后端吗？
不需要。如果您想要纯 C 构建，只需在导入时省略 [mldsa/src/native](mldsa/src/native) 和/或 [mldsa/src/fips202/native](mldsa/src/fips202/native) 目录，并在您的 [mldsa_native_config.h](mldsa/mldsa_native_config.h) 中取消设置 `MLD_CONFIG_USE_NATIVE_BACKEND_ARITH` 和/或 `MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202`。
### 使用 mldsa-native 需要配置 CBMC 吗？
不需要。虽然我们建议您考虑使用它，但在没有 CBMC 的情况下，mldsa-native 也能正常构建和运行 —— 只需确保包含 [cbmc.h](mldsa/src/cbmc.h) 并保持 `CBMC` 未定义。特别是，您_不需要_从代码中删除所有函数契约和循环不变式；除非设置了 `CBMC`，否则它们将被忽略。
### mldsa-native 支持 ML-DSA 的所有安全级别吗？
是的。mldsa-native 支持 FIPS 204 中定义的所有三个 ML-DSA 安全级别（ML-DSA-44, ML-DSA-65, ML-DSA-87）。安全级别是一个编译时参数，通过在 [mldsa_native_config.h](mldsa/mldsa_native_config.h) 中设置 `MLD_CONFIG_PARAMETER_SET=44/65/87` 进行配置。
### 我可以减少嵌入式系统的 RAM 使用量吗？
可以。mldsa-native 提供了一个编译时选项 `MLD_CONFIG_REDUCE_RAM`，可以减少 RAM 使用量。这是以牺牲性能换取内存。有关每个参数集和操作的内存使用情况，请参阅 [mldsa_native.h](mldsa/mldsa_native.h) 中的 `MLD_TOTAL_ALLOC_*` 常量。
要启用此模式，请在 [mldsa_native_config.h](mldsa/mldsa_native_config.h) 中定义 `MLD_CONFIG_REDUCE_RAM`，或作为编译器标志传递 `-DMLD_CONFIG_REDUCE_RAM`。
### mldsa-native 使用 Hedged 还是确定性签名？
默认情况下，mldsa-native 使用 FIPS 204 第 3.4 节中规定的随机化 "hedged" 签名变体。Hedged 变体在签名时同时使用新鲜随机数和来自私钥的预计算随机数。这有助于缓解故障注入攻击和侧信道攻击，同时防止随机数生成器中的潜在缺陷。
如果您需要 ML-DSA 的确定性变体，可以直接调用 `crypto_sign_signature_internal` 并传入全零的 `rnd` 参数。
但是，请注意 FIPS 204 警告称，在存在故障注入攻击和侧信道攻击风险的平台上不应使用此变体，因为缺乏新鲜随机数使得故障攻击更难以缓解。
### mldsa-native 支持外部 mu 模式吗？
是的。mldsa-native 支持外部 mu 模式，该模式允许在签名之前对消息进行预哈希。这解决了 NIST PQC FAQ[^NIST_FAQ] 中提到的预哈希能力以及 NIST 关于 FIPS 204 第 6 节的指导[^NIST_FIPS204_SEC6] 中详述的内容。
外部 mu 模式允许应用程序在外部计算消息摘要 并将其提供给签名实现，这对于大型消息或流式应用程序（签名时无法将整个消息保留在内存中）特别有用。
### mldsa-native 支持 HashML-DSA 吗？
是的。mldsa-native 支持 HashML-DSA，即 FIPS 204 算法 4 和 5 中定义的 ML-DSA 预哈希变体。
mldsa-native 提供两个级别的 API：
- `crypto_sign_signature_pre_hash_internal` 和 `crypto_sign_verify_pre_hash_internal` - 接受预哈希消息摘要的低级函数。此函数支持所有 12 种允许的哈希函数。
- `crypto_sign_signature_pre_hash_shake256` 和 `crypto_sign_verify_pre_hash_shake256` - 为方便起见，在内部执行 SHAKE256 预哈希的高级函数。目前仅支持 SHAKE256。如果您需要其他哈希函数，请使用 `*_pre_hash_internal` 函数或提交 issue。
## 有问题？
如果您认为在 mldsa-native 中发现了安全漏洞，请通过 Github 的 [私人漏洞报告](https://github.com/pq-code-package/mldsa-native/security) 报告该漏洞。
请**不要**创建公开的 GitHub issue。
如果您有任何其他问题 / 非安全问题 / 功能请求，请提交 GitHub issue。
## 贡献
如果您想帮助我们构建 mldsa-native，请联系我们。您可以通过 [PQCA Discord](https://discord.com/invite/xyVnwzfg5R) 联系 mldsa-native 团队。另请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
[^C90]: 严格来说，我们依赖 C90 + `stdint.h` + 64 位 `unsigned long long`。
[^ACVP]: National Institute of Standards and Technology: Automated Cryptographic Validation Protocol (ACVP) Server, [https://github.com/usnistgov/ACVP-Server](https://github.com/usnistgov/ACVP-Server)
[^FIPS202]: National Institute of Standards and Technology: FIPS202 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions, [https://csrc.nist.gov/pubs/fips/202/final](https://csrc.nist.gov/pubs/fips/202/final)
[^FIPS204]: National Institute of Standards and Technology: FIPS 204 Module-Lattice-Based Digital Signature Standard, [https://csrc.nist.gov/pubs/fips/204/final](https://csrc.nist.gov/pubs/fips/204/final)
[^NIST_FAQ]: National Institute of Standards and Technology: Post-Quantum Cryptography FAQs, [https://csrc.nist.gov/Projects/post-quantum-cryptography/faqs#Rdc7](https://csrc.nist.gov/Projects/post-quantum-cryptography/faqs#Rdc7)
[^NIST_FIPS204_SEC6]: National Institute of Standards and Technology: FIPS 204 Section 6 Guidance, [https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf](https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf)
[^REF]: Bai, Ducas, Kiltz, Lepoint, Lyubashevsky, Schwabe, Seiler, Stehlé: CRYSTALS-Dilithium reference implementation, [https://github.com/pq-crystals/dilithium/tree/master/ref](https://github.com/pq-crystals/dilithium/tree/master/ref)
[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)
标签：AArch64, C90, CBMC, CVE, FIPS 204, Linux基金会, ML-DSA, PQC, Valgrind, x86-64, 云安全监控, 内存安全, 后量子密码学, 安全报告生成, 密码学库, 底层实现, 形式化验证, 抗量子计算, 数字签名, 逆向工具, 静态分析