ferritls_core/
lib.rs

1//! # ferritls-core
2//!
3//! 纯 Rust 实现的密码学核心，为 [ferritls-rustls](https://docs.rs/ferritls-rustls)
4//! （rustls `CryptoProvider` 适配层）提供全部密码原语。
5//!
6//! ## FIPS 140-3 模块边界
7//!
8//! 本 crate 是规划中提交 CMVP 验证的**模块边界**：所有算法在边界内用纯 Rust
9//! 自研实现（无 C、无汇编、`#![forbid(unsafe_code)]`），依赖白名单仅
10//! [`subtle`] 与 [`zeroize`]（M3 起增加 `getrandom` 作为边界外熵源输入）。
11//! 任何新依赖都必须先更新 `docs/FIPS.md` 的白名单与审计依据（见 AGENTS.md
12//! 硬性规则 2）。
13//!
14//! ## 默认 feature `simd`（P2）
15//!
16//! 默认启用的 `simd` feature 在 AES/ChaCha20 热路径使用标准库
17//! `core::simd`（portable_simd）的显式向量类型——属 std，**不是第三方
18//! 依赖，白名单不变**。stable 工具链上需要 `RUSTC_BOOTSTRAP=1` 环境变量
19//! （本仓库 `.cargo/config.toml` 已提供；下游用户自带该 env 或以
20//! `default-features = false` 退出到标量回退）。通道宽度按编译目标自动
21//! 选择（SSE2/NEON 基线；用户以 RUSTFLAGS 开启 target-feature 时升级
22//! AVX2/AVX-512），无运行时分发、无 unsafe。
23//!
24//! ## 模块地图
25//!
26//! | 模块 | 内容 | FIPS 批准状态 | 落地里程碑 |
27//! |---|---|---|---|
28//! | [`sha2`] | SHA-256/384/512 | 批准 | M1 |
29//! | [`sha3`] | SHA3-256/512、SHAKE-128/256（FIPS 202） | 批准 | M8.3 |
30//! | [`hmac`] / [`hkdf`] | HMAC、HKDF | 批准 | M1 |
31//! | [`aes`] / [`gcm`] / [`ccm`] | AES、AES-GCM、AES-CCM | 批准 | M2 |
32//! | [`chacha20poly1305`] | ChaCha20-Poly1305 | 非批准 | M2 |
33//! | [`ecdh`] | X25519（非批准）、P-256/384（批准） | 混合 | M3 |
34//! | [`mlkem`] | ML-KEM-768（FIPS 203，批准 KEM） | 批准 | M8.3 |
35//! | [`sign`] | ECDSA、RSA、Ed25519（非批准） | 混合 | M4 |
36//! | [`drbg`] / [`entropy`] | SP 800-90A CTR-DRBG、OS 熵 | 批准 | M5 |
37//! | [`selftest`] | 上电自检（KAT） | 要求项 | M5 |
38//! | [`der`] | 最小 DER/PKCS#8/SEC1 解析 | — | M4 |
39//! | `rsabig`（内部） | RSA 固定宽度大数 + Montgomery 模幂 | 非公开支撑 | M4 |
40//! | [`ct`] / [`policy`] / [`ops`] | 常数时间工具、批准策略、后端分发 | — | M0（M8.1 分发实装） |
41//!
42//! ## 实现状态
43//!
44//! M1–M7 已全部落地：上表各模块的实现与向量测试（NIST/RFC 官方向量、
45//! Wycheproof、RFC 8448 密钥调度）均已启用并全绿，无 `todo!()` 残留。
46//! M8.1 起 AES-GCM 公开类型经 [`ops`] 对象分发、SHA-256 块压缩经
47//! [`ops`] 函数分发（均为默认软件直连、零开销；可安装边界外硬件
48//! 后端 crate 替换执行核心，见 [`ops`] 模块文档）。
49//! 新增测试向量时沿用既有流程：核对官方原文 → 入库 → 全绿
50//! （见 AGENTS.md“测试体系”）。
51
52#![forbid(unsafe_code)]
53// 默认 feature `simd`（P2）：显式 core::simd（portable_simd）向量化路径，
54// 属标准库、全部 safe 代码。stable 工具链上经 RUSTC_BOOTSTRAP=1 编译该
55// feature gate（仓内 .cargo/config.toml [env] / CI env 提供，下游自带 env
56// 或 default-features = false 退出到标量回退）。约束集与档位选择规则见
57// AGENTS.md §5.5；portable_simd 稳定后拆除 RUSTC_BOOTSTRAP 依赖。
58#![cfg_attr(feature = "simd", feature(portable_simd))]
59// 未来硬件加速后端（AES-NI/SHA 扩展）必然需要 unsafe；它们不得进入本 crate，
60// 而是作为边界外的独立后端 crate 通过 ops 模块的 trait 挂接（见 ops 模块文档
61// 与 docs/ARCHITECTURE.md），届时是否将后端纳入 FIPS 边界需重新评估。
62
63/// `simd` feature 编译金丝雀：确保当前配置下 portable_simd 真正可用
64///（P2 各模块的热路径在 aes / chacha20poly1305 中使用）。
65#[cfg(feature = "simd")]
66#[allow(dead_code)]
67fn _portable_simd_canary(v: std::simd::u32x4) -> std::simd::u32x4 {
68    v + std::simd::u32x4::splat(1)
69}
70
71pub mod aes;
72pub mod ccm;
73pub mod chacha20poly1305;
74pub mod ct;
75pub mod der;
76pub mod drbg;
77pub mod ecdh;
78pub mod entropy;
79mod fields;
80pub mod gcm;
81pub mod hkdf;
82pub mod hmac;
83pub mod mlkem;
84pub mod ops;
85pub mod policy;
86mod rsabig;
87pub mod selftest;
88pub mod sha2;
89pub mod sha3;
90pub mod sign;
91
92pub use policy::Approval;
93
94/// 边界内统一的错误类型。
95///
96/// 规则：攻击者可控输入（网络数据、证书、密钥文件）不得引发 panic，
97/// 一切失败以本错误返回（AGENTS.md 硬性规则 5）。`non_exhaustive`：
98/// 实现里程碑落地时允许追加变体。
99#[derive(Clone, Copy, Debug, PartialEq, Eq)]
100#[non_exhaustive]
101pub enum Error {
102    /// 输入长度或格式不满足算法要求。
103    InvalidInput,
104    /// 密钥/IV/标签等验证失败（认证加密打开失败、签名验证失败等）。
105    /// 比较必须常数时间，不得通过错误类型区分失败原因。
106    VerificationFailed,
107    /// 请求的算法或曲线在当前构建（批准模式）下不可用。
108    Unsupported,
109    /// 熵源失败（OS 随机数不可用）。
110    EntropyFailed,
111    /// DRBG 失败（健康测试不过、超出生成上限等）。
112    RngError,
113    /// 上电自检失败：模块处于错误状态，拒绝服务，直到重新初始化。
114    SelfTestFailed(&'static str),
115}
116
117impl core::fmt::Display for Error {
118    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
119        match self {
120            Error::InvalidInput => write!(f, "invalid input length or format"),
121            Error::VerificationFailed => write!(f, "verification failed"),
122            Error::Unsupported => write!(f, "algorithm unavailable in this build/mode"),
123            Error::EntropyFailed => write!(f, "OS entropy source failed"),
124            Error::RngError => write!(f, "DRBG failure"),
125            Error::SelfTestFailed(which) => {
126                write!(f, "power-up self-test failed: {which}")
127            }
128        }
129    }
130}
131
132impl std::error::Error for Error {}
ferritls_core/lib.rs

ferritls_core/
lib.rs
