LatticeArc/latticearc

# LatticeArc [](https://crates.io/crates/latticearc) [](https://docs.rs/latticearc) [](https://github.com/LatticeArc/latticearc/actions/workflows/ci.yml) [](docs/NIST_COMPLIANCE.md) [](https://codecov.io/gh/LatticeArc/latticearc) [](LICENSE) Rust 的后量子密码学。您只需描述要保护的内容——LatticeArc 会自动选择算法、安全级别和合规模式。默认为混合模式（PQ + 经典）。单一 crate。 | 您通常需要自己手动组合的部分 | 可能出现的问题 | |--------------------------------------|-------------------| | 从 4 个 NIST 标准和 11 个参数集中进行选择 | 选错安全级别、选错算法类型 | | 组合 ML-KEM + X25519 + HKDF + AES-GCM | 密钥组合器损坏、缺少域分离 | | 清零秘密、常数时间比较 | 通过 Debug 或计时侧信道发生泄露 | | FIPS 140-3、CNSA 2.0 模式限制 | 无声地选择了不合规的算法 | ``` use latticearc::{encrypt, decrypt, CryptoConfig, UseCase, EncryptKey, DecryptKey}; use latticearc::generate_hybrid_keypair_with_level; use latticearc::primitives::kem::ml_kem::MlKemSecurityLevel; // HealthcareRecords resolves to ML-KEM-1024 (NIST Level 5), so the keypair // must be generated at the matching level — `generate_hybrid_keypair()` // defaults to ML-KEM-768 and would be rejected by `validate_key_matches_scheme`. let (pk, sk) = generate_hybrid_keypair_with_level(MlKemSecurityLevel::MlKem1024)?; let encrypted = encrypt(b"patient records", EncryptKey::Hybrid(&pk), CryptoConfig::new().use_case(UseCase::HealthcareRecords))?; let decrypted = decrypt(&encrypted, DecryptKey::Hybrid(&sk), CryptoConfig::new())?; // ML-KEM-1024 + X25519 + HKDF-SHA256 + AES-256-GCM — selected automatically ``` ## 快速入门 ### 库 ``` [dependencies] latticearc = "0.8" ``` **混合加密**（默认 — PQ + 经典，攻击者必须同时攻破两者才能成功）： ``` use latticearc::{encrypt, decrypt, CryptoConfig, EncryptKey, DecryptKey}; let (pk, sk) = latticearc::generate_hybrid_keypair()?; let encrypted = encrypt(b"secret data", EncryptKey::Hybrid(&pk), CryptoConfig::new())?; let decrypted = decrypt(&encrypted, DecryptKey::Hybrid(&sk), CryptoConfig::new())?; ``` **数字签名**（ML-DSA-65 + Ed25519 混合）： ``` use latticearc::{generate_signing_keypair, sign_with_key, verify, CryptoConfig}; let config = CryptoConfig::new(); let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?; let signed = sign_with_key(b"document", &sk, &pk, config.clone())?; assert!(verify(&signed, config)?); ``` ### 命令行工具 (CLI) ``` cargo install --path latticearc-cli ``` ``` # 签署法律文件 latticearc-cli keygen --use-case legal-documents --output ./keys latticearc-cli sign --input contract.pdf \ --key keys/hybrid-ml-dsa-87-ed25519.sec.json \ --public-key keys/hybrid-ml-dsa-87-ed25519.pub.json latticearc-cli verify --input contract.pdf \ --signature contract.pdf.sig.json \ --key keys/hybrid-ml-dsa-87-ed25519.pub.json # 加密医疗记录 latticearc-cli keygen --algorithm aes256 --output ./keys latticearc-cli encrypt --use-case healthcare-records \ --input patient.json --output patient.enc.json \ --key keys/aes256.key.json ``` ## 核心亮点 - **全部 4 项 NIST PQC 标准** — ML-KEM (FIPS 203)、ML-DSA (FIPS 204)、SLH-DSA (FIPS 205)、FN-DSA（FIPS 206 草案） - **默认混合模式** — PQ + 经典算法实现深度防御（[NIST](https://csrc.nist.gov/projects/post-quantum-cryptography/faqs)、[NSA CNSA 2.0](https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF)、[ENISA](https://www.enisa.europa.eu/publications/post-quantum-cryptography-current-state-and-quantum-mitigation)）；也可使用纯 PQ 模式 - **22 个用例** 提供自动算法选择 — `UseCase::HealthcareRecords` → ML-KEM-1024，`UseCase::IoTDevice` → ML-KEM-512 - **两个正交维度** — `SecurityLevel` (NIST 1/3/5) × `CryptoMode` (Hybrid/PqOnly) - **多层验证** — 形式化证明（Kani + SAW）、三路恒定时间门控、跨实现差分测试、31 个模糊测试目标、突变测试覆盖率达 80%。详见[验证](#verification)。 - **可选的 FIPS 后端** — `--features fips` 会将 AES-GCM、ML-KEM、HKDF、SHA-2 通过经过 CMVP 认证的 aws-lc-rs 构建路由。PQ 签名使用符合 NIST 标准但未经验证的 crate。详见[算法与后端](#algorithms--backends)。 - **单一 crate** — `cargo add latticearc` 即可使用 ## 适用与不适用场景 **在以下需求时使用 LatticeArc：** - 无需自行组合 ML-KEM + X25519 + HKDF + AES-GCM 即可实现 PQ + 经典混合加密/解密 - 基于用例的算法选择（22 种工作负载，3 种合规模式） - 运维团队无需编写 Rust 即可使用的命令行工具 - 无需修改代码即可启用 FIPS 路由 **在以下需求时请寻找其他方案：** - 单一低级原语 — 直接使用 `aws-lc-rs`、`fips204`、`fips205` 或 `fn-dsa` - 端到端的 CMVP 认证模块 — 目前尚无针对 PQ 签名的 CMVP 后端 - 跨语言绑定 — `liboqs` 支持 C、Python、Go、Java - `no_std` / 嵌入式环境 — `wolfCrypt` 在嵌入式 PQ 领域处于领先地位 - TLS 协议栈 — 使用 `rustls`、OpenSSL 3.5 或 wolfSSL ## 工作原理 ``` flowchart LR subgraph "You provide" DATA["Plaintext"] KEY["Key type"] CFG["CryptoConfig"] end subgraph "LatticeArc decides" ENGINE["Policy\nEngine"] end subgraph "Hybrid mode" H_KEM["ML-KEM\nencapsulate"] H_ECDH["X25519\nkey exchange"] H_HKDF["HKDF\ncombine"] H_AES["AES-256-GCM\nencrypt"] H_KEM --> H_HKDF H_ECDH --> H_HKDF H_HKDF --> H_AES end subgraph "PQ-only mode" P_KEM["ML-KEM\nencapsulate"] P_HKDF["HKDF\nderive"] P_AES["AES-256-GCM\nencrypt"] P_KEM --> P_HKDF P_HKDF --> P_AES end DATA --> ENGINE KEY --> ENGINE CFG --> ENGINE ENGINE -->|"CryptoMode::Hybrid"| H_KEM ENGINE -->|"CryptoMode::PqOnly"| P_KEM style ENGINE fill:#8b5cf6,stroke:#6d28d9,color:#fff style H_AES fill:#10b981,stroke:#059669,color:#fff style P_AES fill:#3b82f6,stroke:#1d4ed8,color:#fff ``` ## 算法与后端 算法合规性 ≠ 模块验证。`--features fips` 会将其涵盖的算法切换到 aws-lc-rs 经过 CMVP 认证的构建版本。PQ 签名始终使用未经验证的 crate。LatticeArc 本身**不是**一个经过 CMVP 认证的模块。 | 类别 | 算法 | 后端 | |----------|-----------|---------| | **PQ 密钥封装** | ML-KEM-512/768/1024 (FIPS 203) | aws-lc-rs — 启用 `--features fips` 时通过 FIPS 140-3 认证 | | **PQ 签名** | ML-DSA-44/65/87 (FIPS 204) | fips204 — 符合 NIST 标准，未经 CMVP 认证 | | **PQ 哈希签名** | SLH-DSA (FIPS 205) | fips205 — 符合 NIST 标准，未经 CMVP 认证 | | **PQ 格签名** | FN-DSA-512/1024 (FIPS 206 草案) | fn-dsa — 符合 NIST 标准，未经 CMVP 认证 | | **经典签名** | Ed25519 | ed25519-dalek — 已审计 | | **经典密钥交换** | X25519 | aws-lc-rs — 启用 `--features fips` 时通过 FIPS 140-3 认证 | | **对称加密** | AES-256-GCM | aws-lc-rs — 启用 `--features fips` 时通过 FIPS 140-3 认证 | | **对称加密** | ChaCha20-Poly1305 | chacha20poly1305 — 非 FIPS | | **哈希** | SHA-2 (256/384/512) | RustCrypto `sha2` crate — 广泛审查过，但未经 CMVP 认证。`--features fips` 标志**不会**将 SHA-2 切换至 aws-lc-rs（在 FIPS 下，只有 AES-GCM、ML-KEM、X25519 和 HKDF 会通过 aws-lc-rs 进行路由）。 | | **哈希** | SHA-3, BLAKE2 | sha3 / blake2 crate — 非 FIPS | | **KDF** | HKDF-SHA256 | aws-lc-rs — 启用 `--features fips` 时通过 FIPS 140-3 认证 | ## 验证 采用多层设计 — 每一层都能捕获其下一层无法捕获的问题。 ### 证明级别 | 工具 | 验证内容 | 范围 | |------|----------------|-------| | [SAW](https://github.com/awslabs/aws-lc-verification) (通过 aws-lc-rs 继承) | C 语言原语的机器验证正确性 | AES-GCM、HMAC-SHA2、SHA-256/384/512、ECDSA P-256/P-384 | | [Kani](https://github.com/model-checking/kani) | Rust 代码的有界模型检查 | 30 个证明；18 个为 PR 阻塞级别，全套计划在每夜构建中运行 | ### 基于属性与差分测试 | 工具 | 检测内容 | |------|-----------------| | [Proptest](https://proptest-rs.github.io/proptest/) | 往返、不可伪造性、单比特拒绝不变量（40 多个属性 × 256 个以上用例） | | 跨实现差分测试 | ML-KEM (fips203 对比 aws-lc-rs，每次运行 600 个往返)、ML-DSA (fips204 对比 pqcrypto-mldsa)、SLH-DSA (fips205 对比 pqcrypto-sphincsplus) — 跨这三个算法共 21 项测试 | | [Wycheproof](https://github.com/nicholasblaskey/wycheproof-rs) | 通过我们的 AES-GCM、ChaCha20-Poly1305、HMAC 和 HKDF 封装运行 555 个攻击者选择的向量 | ### 恒定时间验证（三路门控） | 工具 | 方法论 | 调度计划 | |------|-------------|----------| | Criterion | 输入类别之间的定性挂钟时间差异 | 每周（周日） | | [DudeCT](https://eprint.iacr.org/2016/1123) | 统计 Welch t 检验；`|max t| < 10` 门控 | 每周（周一） | | ctgrind (Valgrind memcheck) | 将秘密字节标记为未初始化；若存在任何依赖于它们的分支或索引则失败 | 每周（周二） | ### DoS 防护 | 工具 | 门控内容 | |------|---------------| | `stats_alloc` 分配预算 | 每次加密操作中每次 API 调用的分配上限；回归门控 | | DoS 模糊测试目标 | 有分配预算限制的对抗性输入；当分配超过 1 MiB/次时会导致模糊测试器发生 panic | | 资源限制覆盖脚本 | 如果任何接收 `&[u8]` 参数的公有函数没有声明大小上限，则 CI 将失败 | ### 持续模糊测试与突变测试 - **31 个 libfuzzer 目标**，涵盖 AEAD、KEM、签名、KDF、序列化和 DoS；每周计划矩阵。OSS-Fuzz 脚手架在 [`fuzz/oss-fuzz/`](fuzz/oss-fuzz/) 中提供。 - **`cargo-mutants --in-diff`**，80% 得分下限，对更改过加密文件的 PR 构成阻塞。 ### 运行时清理器 ASan、TSan 和 LSan 为阻塞级别。MSan 正在分阶段进行 — aws-lc-rs 1.16.3 添加了 `AWS_LC_SYS_SANITIZER=msan`，以通过 FFI 边界检测 C 代码；FIPS 路径正在等待 [aws/aws-lc#3167](https://github.com/aws/aws-lc/pull/3167)。 `#![forbid(unsafe_code)]` 在工作区级别强制执行。 ## 架构 ``` block-beta columns 3 block:API["Unified API"]:3 columns 3 encrypt["encrypt()"] decrypt["decrypt()"] sign["sign_with_key()"] end block:CONFIG["Configuration"]:3 columns 3 cc["CryptoConfig"] mode["CryptoMode"] level["SecurityLevel"] end block:HYBRID["Hybrid & PQ-Only Encryption"]:2 columns 2 henc["hybrid\nML-KEM + X25519\n+ HKDF + AES-GCM"] pqenc["pq_only\nML-KEM\n+ HKDF + AES-GCM"] end block:SIG["Signatures"]:1 columns 1 hsig["ML-DSA + Ed25519\nSLH-DSA · FN-DSA"] end block:PRIM["Primitives"]:3 columns 5 kem["ML-KEM\nFIPS 203"] dsa["ML-DSA\nFIPS 204"] slh["SLH-DSA\nFIPS 205"] fn["FN-DSA\ndraft FIPS 206"] sym["AES-GCM\nX25519 · Ed25519"] end block:BACK["Backends"]:3 columns 3 awslc["aws-lc-rs\n(FIPS opt-in)"] fips204["fips204 · fips205"] fndsa["fn-dsa · ed25519-dalek"] end style API fill:#3b82f6,stroke:#1d4ed8,color:#fff style CONFIG fill:#e2e8f0,stroke:#64748b style HYBRID fill:#10b981,stroke:#059669,color:#fff style SIG fill:#f59e0b,stroke:#d97706,color:#fff style PRIM fill:#e2e8f0,stroke:#94a3b8 style BACK fill:#374151,stroke:#1f2937,color:#fff ``` ## 安全性 基于任何单一算法都可能出现被攻破的假设进行设计 — 混合模式确保攻击者必须同时击败两个组件。密钥材料在 drop 时被清零，标签比较以恒定时间运行，秘密类型具有可隐藏内容的自定义 `Debug` 实现。 ### 限制 - **不是经过 CMVP 认证的加密模块。** 目前尚无针对 PQ 签名的 CMVP 后端。请使用 `--features fips` 来获取通过 aws-lc-rs 路由的子集。 - **未经独立审计。** 我们欢迎安全研究人员审查我们的代码。 - **1.0 版本之前的软件。** API 可能会随版本更新而发生变化。 ### 上游贡献 - **[aws-lc-rs#1029](https://github.com/aws/aws-lc-rs/pull/1029)** — ML-KEM `DecapsulationKey` 序列化（已在 v1.16.0 中发布） - **[aws-lc-rs#1034](https://github.com/aws/aws-lc-rs/pull/1034)** — 基于 ML-DSA 种子的确定性密钥生成（已在 v1.16.0 中发布） 如需报告安全问题，请联系：Security@LatticeArc.com — 详见 [SECURITY.md](SECURITY.md)。 ## 构建先决条件 需要 Rust 1.93+ 以及 C/C++ 编译器。如果是 FIPS 构建，还需要 CMake 和 Go。 ``` # Default cargo build # FIPS-validated backend brew install cmake go # macOS # sudo apt install cmake golang-go build-essential # Ubuntu cargo build --features fips ``` ### Cargo 特性 | 特性 | 默认 | 启用内容 | |---|:---:|---| | `fips` | 关闭 | 将 AES-GCM、ML-KEM、HKDF 和 SHA-2 路由至经过 CMVP 认证的 `aws-lc-rs` 构建。`ComplianceMode::Fips140_3` 和 `Cnsa2_0` 的必需选项。**传递性地启用了 `fips-self-test`**，从而按照 FIPS 140-3 §10.3.1 的要求运行开机 KAT。如果您仅需要经验证的后端而不需要自检布线，请设置 `default-features = false` 并直接启用 `aws-lc-rs/fips`。 | | `fips-self-test` | 关闭 | 针对 FIPS 边界算法（ML-KEM、AES-GCM、SHA-2、ML-DSA、SLH-DSA）的上电 KAT 自检。会被 `fips` 传递性地引入；也可以在非IPS 构建中单独启用，以获得自检 KAT 覆盖。 | | `tracing-init` | 关闭 | 暴露 `init_tracing` / `init_tracing_with_file` 辅助函数及其底层的 `tracing-subscriber` + `tracing-appender` 依赖。**库代码不应启用此特性** — 订阅者布线是二进制文件的责任，传递性库若调用 `init_tracing` 将导致下游第一个调用自身订阅者初始化的消费者发生 `panic!`。`latticearc-cli` 启用了此特性。 | | `secret-mlock` | 关闭 | 通过 `mlock(2)` / `VirtualLock` 将堆支持的 `SecretVec` 缓冲区锁定在 RAM 中，防止它们出现在交换空间或核心转储中。 | | `kat-test-vectors` | 关闭 | 暴露 `AeadCipher::new_allow_weak_key`，这是一个绕过 `AeadError::WeakKey` 对全零密钥拒绝机制的可选构造器。**仅限测试使用** — 重现使用全零密钥的 NIST AES-GCM 测试用例 1 和 2（McGrew & Viega）时需要。生产构建必须保持此特性关闭，以便未初始化内存的密钥能够安全地失效。 | | 错误 | 解决方法 | |-------|-----| | `CMake not found` | 安装 CMake（仅限 FIPS） | | `Go not found` | 安装 Go 1.18+（仅限 FIPS） | | `cc not found` (Linux) | `sudo apt install build-essential` | | 首次构建时间过长 | 首次构建会从源代码编译 AWS-LC（约 2-3 分钟） | ## 文档 | 文档 | 描述 | |----------|-------------| | [算法选择指南](docs/ALGORITHM_SELECTION.md) | 用例表格、安全级别映射、合规模式 | | [统一 API 指南](docs/UNIFIED_API_GUIDE.md) | 零信任会话、所有 22 个用例、纯 PQ 模式 | | [密钥格式规范](docs/KEY_FORMAT.md) | LatticeArc 便携式密钥 (LPK) 模式，JSON + CBOR | | [生态图](docs/ECOSYSTEM.md) | 与 OpenSSL、aws-lc-rs、liboqs、RustCrypto、age、Sequoia 的比较 | | [NIST 合规性](docs/NIST_COMPLIANCE.md) | 每种算法的 FIPS 合规状态 | | [形式化验证](docs/FORMAL_VERIFICATION.md) | 完整的 Kani 证明清单 | | [设计与架构](docs/DESIGN.md) | Crate 结构、模块边界、设计决策 | | [设计模式](docs/DESIGN_PATTERNS.md) | 配置、加密安全和测试模式 | | [CLI 参考](latticearc-cli/README.md) | latticearc-cli 的完整命令参考 | ## 许可证 Apache 2.0。详见[许可证](LICENSE)。 ## 贡献 详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

标签：AES-GCM, CNSA 2.0, FIPS 140-3, ML-KEM, NIST FIPS 203-206, PQC, ProjectDiscovery, Rust, X25519, 内存安全, 医疗数据安全, 可视化界面, 后量子密码学, 安全合规, 密码学库, 密码算法, 密钥封装, 恒定时间算法, 抗量子加密, 数据保护, 数据加密, 机密性, 格密码学, 混合加密, 网络代理, 网络安全, 网络流量审计, 蓝队防御, 通知系统, 隐私保护, 零知识侧信道防护