mlkem-native 是一个安全、快速且可移植的 ML-KEM[^FIPS203] C90[^C90] 实现。 它是 ML-KEM 参考实现[^REF]的一个分支。
mlkem/src/* 和 mlkem/src/fips202/* 中的所有 C 代码(除 AArch64 和 x86_64 以外平台的后端以及调试代码外),均使用 CBMC[^CBMC] 证明了内存安全(无内存溢出)和类型安全(无整数溢出)。 所有 AArch64 和 x86_64 汇编均使用 HOL-Light[^HOL-Light] 证明了功能正确、 内存安全,且具有与秘密无关的时序(常数时间)。
mlkem-native 包含针对 Arm(64 位,Neon)、Intel/AMD(64 位,AVX2)、RISC-V(64 位,RVV)和 POWER(ppc64le,VSX)的原生后端。性能数据请参见基准测试。
mlkem-native 由后量子密码学联盟支持,是Linux 基金会的一部分。
# Install base packages
sudo apt-get update
sudo apt-get install make gcc python3 git
# Clone mlkem-native
git clone https://github.com/pq-code-package/mlkem-native.git
cd mlkem-native
# Build and run tests
make build
make test
# The same using `tests`, a convenience wrapper around `make`
./scripts/tests all
# Show all options
./scripts/tests --help
更多信息请参见 BUILDING.md。
mlkem-native 被用于
mlkem/src/* 和 mlkem/src/fips202/* 中的所有 C 代码(除 AArch64 和 x86_64 以外平台的后端以及调试代码外)均被证明是内存安全的(无内存溢出)和类型安全的(无整数溢出)。 这使用了 C 有界模型检查器(CBMC),并基于源代码中的函数契约和循环不变式注解。 详情请参见 proofs/cbmc。
所有 AArch64 和 x86_64 汇编均在目标代码级别被证明功能正确、内存安全且具有与秘密无关的时序 (常数时间)。这使用了 HOL-Light 交互式定理证明器和 s2n-bignum 验证基础设施(其中包含 Arm 和 x86 架构相关部分的模型)。详情请参见 proofs/hol_light。
注意: 形式化验证从来都不是绝对的。关于 mlkem-native 形式化验证工作的范围、假设和风险的详细分析,请参见 SOUNDNESS.md。
mlkem-native 中的所有 AArch64 和 x86_64 汇编均已在 HOL Light 中被形式化证明不存在依赖于秘密的控制流、 内存访问模式和可变延迟指令,从而抵御大多数时序侧信道 (详情请参见 proofs/hol_light)。C 代码通过适当的屏障和常数时间模式, 针对编译器引入的时序侧信道(如 KyberSlash[^KyberSlash] 或 clangover[^clangover])进行了加固。C 代码假定 32x32->32 和 32x32->64 乘法为常数时间, 而某些目标平台并不提供这一特性,例如没有硬件乘法器或具有提前终止乘法指令的核心。
不存在依赖于秘密的分支、内存访问模式和可变延迟指令这一点,也通过 valgrind
在各种编译器和编译选项组合下进行了测试。
其他攻击。 mlkem-native 仅针对时序侧信道进行抵抗。其他攻击类别,如功耗和电磁侧信道、微架构侧信道(例如推测执行)或故障注入攻击,目前不在范围内。
mlkem-native 分为一个 前端 和两个用于算术和 FIPS202 / SHA3 的 后端。前端是 固定的,用 C 编写,涵盖所有对性能不关键的例程。后端是灵活的,负责 性能敏感的例程,可以用 C 或原生代码(汇编/内建函数)实现;算术后端请参见 mlkem/src/native/api.h,FIPS-202 后端请参见 mlkem/src/fips202/native/api.h。
mlkem-native 目前提供以下后端:
如果您希望贡献新的后端,请联系我们或直接提交 PR。
我们的 AArch64 汇编是使用 SLOTHY 超级优化器开发的,遵循 SLOTHY 论文[^SLOTHY_Paper]中描述的方法: 我们手写“干净”的汇编,并自动化微优化(例如参见 clean 与 optimized 的 AArch64 NTT)。 更多细节请参见 dev/README.md。
mlkem-native 已针对所有官方 ACVP ML-KEM 测试向量[^ACVP]以及 Wycheproof[^wycheproof] ML-KEM 测试向量进行了测试。
您可以使用 tests 脚本或直接使用 ACVP 客户端 来运行 ACVP 测试:
# Using the tests script
./scripts/tests acvp
# Using a specific ACVP release
./scripts/tests acvp --version v1.1.0.41
# Using the ACVP client directly
python3 ./test/acvp/acvp_client.py
python3 ./test/acvp/acvp_client.py --version v1.1.0.41
# Using specific ACVP test vector files (downloaded from the ACVP-Server)
# python3 ./test/acvp/acvp_client.py -p {PROMPT}.json -e {EXPECTED_RESULT}.json
# For example, assuming you have run the above
python3 ./test/acvp/acvp_client.py \
-p ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/prompt.json \
-e ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/expectedResults.json
你可以使用 tests 脚本或直接使用 Wycheproof 客户端 来运行 Wycheproof[^wycheproof] 测试:
# Using the tests script
./scripts/tests wycheproof
# Using the Wycheproof client directly
python3 ./test/wycheproof/wycheproof_client.py
你可以使用 tests 脚本测量性能、内存占用和二进制大小:
# Speed benchmarks (-c selects cycle counter: NO, PMU, PERF, or MAC)
# Note: PERF/MAC may require the -r flag to run benchmarking binaries using sudo
./scripts/tests bench -c PMU
./scripts/tests bench -c PERF -r
# Stack usage analysis
./scripts/tests stack
# Binary size measurement
./scripts/tests size
有关 CI 基准测试结果和历史性能数据,请参阅基准测试页面。
如果你想使用 mlkem-native,请将 mlkem 导入到项目的源码树中,并使用你喜欢的构建系统进行构建。更多信息请参阅 mlkem,简单示例请参阅 examples/basic。本仓库提供的构建系统仅用于开发目的。
有关适用于所有公共函数的约定(例如返回值、指针有效性以及出错时输出缓冲区的状态),请参阅 API-CONVENTIONS.md。
mlkem-native 依赖并自带 FIPS-202[^FIPS202] 的实现。如果你的库有自己的 FIPS-202 实现,你可以用它替代 mlkem-native 自带的实现。请参阅 FIPS202.md,以及 examples/bring_your_own_fips202 中使用 tiny_sha3[^tiny_sha3] 的示例。