kstzv/ml-kem

# ML-KEM (FIPS 203) — 纯 C 语言实现 一个用纯 C 编写的 ML-KEM (Kyber) 后量子密钥封装机制的低级实现。 本项目侧重于正确性、透明度和架构清晰度，而不是过早的优化或生产就绪。 ## 📌 概述 该实现侧重于架构清晰度、可移植性以及显式的内存控制。 设计上避免了外部依赖，并引入了自定义的解封装池，以减少分配开销并提高在受限环境或内核环境中的性能。 该实现遵循标准 C 语义，以简化在不同平台（包括用户空间和 Linux 内核）之间的移植。 ## ⚠️ 状态 Beta (v0.2.1) **这是一个早期（beta）版本。** - ✔ 用户空间实现功能正常 - ✔ NIST KAT 测试（密钥生成与封装）通过 - ✔ 已针对有效的封装输出进行端到端解封装验证 - ✔ Linux 内核模块构建及加载/卸载正常 - ✔ 解封装池的压力测试（参见 `test_pool/`） **尚未完成：** - ❌ 完整的恒定时间验证（计划通过 dudect 实现） - ❌ 广泛的模糊测试 - ❌ 内核空间中针对 KAT 的验证 - ❌ 正式的安全审计 ## 🎯 目标 - 提供一个**清晰、易读的 ML-KEM (FIPS 203) 实现** - 保持**对内存和数据流的严格控制** - 避免外部依赖（包括加密库） - 同时支持： - 用户空间 - Linux 内核环境 - 作为**本项目的研究与教育主要实现** ## ✨ 特性 - 纯 C (C11)，无外部库 - 零依赖的加密核心 - 自有实现包括： - SHA3-256 / SHA3-512 - SHAKE128 / SHAKE256 - Keccak-f[1600] - 完整的多项式算术： - NTT / 逆 NTT - Barrett 约减 - ML-KEM 组件： - 密钥生成 - 封装 - 解封装 - 用于解封装上下文的内存池（使用原子操作的无锁实现） - 专为可移植性设计（用户空间 + 内核） ## 🚀 未来工作 - 恒定时间验证 (dudect) - 用于内核测试的 AF_ALG 集成 - 额外的优化阶段 - 扩展的测试覆盖范围 - 文档改进 ### 🔧 硬件加速（探索） 计划研究硬件辅助加速路径，包括： - 集成特定于 CPU 的优化（例如 SIMD、指令集）的可行性 - 潜在的平台提供的加密加速器的使用 - 针对可选硬件后端的抽象层评估 - 硬件辅助路径的恒定时间影响分析 目标是探索性能提升，同时不损害可移植性或引入强制性依赖。 ## 🧱 项目结构 | 文件 | 描述 | |------|------------| | `ml_kem.c` | 公共 API 层 | | `ml_kem_core_header.h` | 核心定义、常量和结构 | | `ml_kem_create_keys.c` | 密钥生成 | | `ml_kem_encaps.c` | 封装逻辑 | | `ml_kem_decrypt.c` | 解封装（解密 + 重新封装） | | `ml_kem_ntt_main.c` | NTT 与多项式运算 | | `math_operations.c` | 模算术（Barrett 约减等） | | `ml_kem_sha.c` | SHA3-256 / SHA3-512 | | `ml_kem_shake.c` | SHAKE128 / SHAKE256 | | `keccak_f1600_ct.c` | Keccak 置换 | | `ml_kem_pool.c` | 解封装池实现 | ## 🧠 架构概述 该实现围绕显式的上下文结构构建： - `ml_kem_ctx` — 持久性密钥材料 - `ml_kem_temp` — 密钥生成的临时缓冲区 - `ml_kem_encaps_ctx` — 封装上下文 - `ml_kem_decrypt_ctx` — 解封装上下文 - `ml_kem_pool_decaps_ctx` — 可重用的解封装插槽池 关键设计理念： - 分离**持久内存与临时内存** - 避免隐藏的分配 - 显式的生命周期控制（分配 / 擦除 / 销毁） - 最小的抽象开销 ## 🔐 安全考量 - 核心加密路径中不存在依赖于秘密数据的分支（在适用情况下） - 显式的内存清零（`ml_kem_memzero`） - 公开数据流与秘密数据流的分离 - 设计时考虑了恒定时间执行原则 ⚠️ 但是： - 恒定时间保证**尚未得到正式验证** - 编译器优化可能会影响行为 - 计划进行进一步的验证 ## 🧪 测试 当前已实现： - ✔ NIST KAT（密钥生成、封装） - ✔ 功能性解封装验证 - ✔ 以下项目的高竞争压力测试： - 解封装池（256 个线程 / 16 个插槽） - ThreadSanitizer (TSan) 无异常 - AddressSanitizer (ASan) / UBSan 无异常 - （有关可重现的压力测试设置和 sanitizer 运行，请参见 `test_pool/`） 计划中： - 基于 dudect 的恒定时间测试 - 内核空间的 KAT 验证 - 池子系统的压力测试 - 随机性质量检查 ## 🐧 内核支持 本项目包含与 Linux 内核兼容的构建： - 不依赖仅限用户空间的 API - 适合与内核加密子系统集成（未来工作） - 潜在的用例： - 嵌入式系统 - 安全固件 - 内核中的加密服务 ## ⚙️ 构建 ### 用户空间 ``` gcc -std=c11 -O2 -Wall -Wextra *.c -o ml_kem --- ## 📌 注意事项 - This project intentionally avoids external crypto libraries. - If your compiler aggressively optimizes memory operations, consider replacing `ml_kem_memzero()` with a platform-specific secure wipe. --- ## License This project is dual-licensed under: - GNU General Public License v2.0 - MIT License You may choose either license. --- ## 🤝 Contributing Feedback, reviews, and suggestions are welcome. --- ## 📬 联系我们 - GitHub: kstzv(https://github.com/kstzv) - Email: kstzavertaylo@gmail.com ```

标签：Barrett约简, C11, FIPS 203, Keccak, KEM, Kyber, Linux内核, ML-KEM, NTT, PQC, SHA3, SHA3-256, SHA3-512, SHAKE128, SHAKE256, 内存池, 内核模块, 分配释放, 原子操作, 后量子密码学, 多项式算术, 安全, 安全资源, 客户端加密, 密码学, 密码库, 密码算法实现, 密钥封装机制, 开源, 手动系统调用, 抗量子计算, 数论变换, 无内存分配, 无锁, 用户态, 纯C, 超时处理, 透明性, 零依赖