Crate ferritls_core 

ferritls-core

Pure-Rust cryptographic primitives, providing everything that ferritls-rustls (the rustls CryptoProvider adapter) needs. No C, no assembly, no unsafe.

FIPS 140-3 module boundary

This crate is the module boundary intended for future CMVP validation: every algorithm is implemented in-boundary in pure Rust (#![forbid(unsafe_code)]), and the dependency whitelist is exactly subtle, zeroize and getrandom (OS entropy input). New dependencies require updating the whitelist and audit rationale in docs/FIPS.md first (AGENTS.md hard rule 2).

Note that the module is not yet CMVP-validated; the fips cargo feature selects the approved-algorithm mode, it is not a certification claim.

Default feature simd

The default simd feature uses the standard library’s core::simd (portable_simd) for explicit vectorization of the AES and ChaCha20 hot paths — std code, not a third-party dependency, so the whitelist is unchanged. On the stable toolchain it compiles via RUSTC_BOOTSTRAP=1 (provided by this repository’s .cargo/config.toml; downstream users set the env themselves or opt out with default-features = false, which keeps the scalar fallback path). Vector width follows the compile target (SSE2/NEON baseline, widening to AVX2/AVX-512 with the corresponding target-feature RUSTFLAGS); there is no runtime dispatch and no unsafe.

Usage

Hashing:

use ferritls_core::sha2::Sha256;

let digest = Sha256::one_shot(b"abc");
assert_eq!(&digest[..4], &[0xba, 0x78, 0x16, 0xbf]); // FIPS 180-4 example

Authenticated encryption (AES-128-GCM; the same shape exists for gcm::Aes256Gcm, ccm and chacha20poly1305):

use ferritls_core::gcm::Aes128Gcm;

let cipher = Aes128Gcm::new(&[7u8; 16]);
let nonce = [9u8; 12]; // unique per key — never repeat a (key, nonce) pair

let ct_and_tag = cipher.seal(&nonce, b"aad", b"plaintext");
let plaintext = cipher.open(&nonce, b"aad", &ct_and_tag).expect("authentic");
assert_eq!(plaintext, b"plaintext");

// Tampered ciphertexts fail verification before any plaintext is returned:
let mut tampered = ct_and_tag.clone();
tampered[0] ^= 0x01;
assert!(cipher.open(&nonce, b"aad", &tampered).is_err());

Key agreement, signatures, KEMs and the DRBG follow the same pattern: typed keys, explicit errors (no panics on attacker-controlled input), and zeroization of secret material on drop.

Module map

Module	Contents	FIPS approval
sha2	SHA-256/384/512	approved
sha3	SHA3-224/256/384/512, SHAKE-128/256 (full FIPS 202 family)	approved
hmac / hkdf	HMAC, HKDF	approved
aes / gcm / ccm	AES, AES-GCM, AES-CCM	approved
chacha20poly1305	ChaCha20-Poly1305	not approved
ecdh	X25519 (not approved), P-256/384 (approved)	mixed
mlkem	ML-KEM-512/768/1024 (FIPS 203)	approved
sign	ECDSA, RSA (approved), Ed25519 (not approved)	mixed
drbg / entropy	SP 800-90A CTR-DRBG, OS entropy	approved
selftest	Power-on self-tests (KATs)	required
der	Minimal DER/PKCS#8/SEC1 parsing	—
ct / policy / ops	Constant-time utilities, approval policy, backend dispatch	—

All modules are fully implemented and covered by official NIST/RFC/CAVP vectors, Wycheproof and the RFC 8448 key schedule (see docs/VECTOR-PROVENANCE.md for sources). AES-GCM and SHA-256 public types dispatch through ops: the default is a zero-overhead direct software path, and an optional out-of-boundary hardware backend crate can be installed to replace the execution core (see ops).

Re-exports

pub use policy::Approval;

Modules

aes

AES 块密码（FIPS 197），128/192/256 位密钥的软件实现。

ccm

AES-CCM（RFC 3610 / SP 800-38C），认证加密。

chacha20poly1305

ChaCha20-Poly1305（RFC 8439），认证加密。

ct

常数时间工具与边界内标准 crate 的统一出口。

der

最小 DER 解析：PKCS#8 / SEC1 / PKCS#1 私钥与 SPKI 公钥的拆包。

drbg

CTR-DRBG（NIST SP 800-90A Rev.1 §10.2.1），AES-256 为基、无推导 函数（no df），安全强度 256 位，seedlen = 48 字节。

ecdh

椭圆曲线 Diffie-Hellman 密钥交换：X25519（RFC 7748）与 NIST P-256/P-384（SP 800-56A）。

entropy

OS 熵源接入（getrandom 系统调用）。

gcm

AES-GCM（NIST SP 800-38D），认证加密。

hkdf

HKDF（RFC 5869），基于 crate::hmac。

hmac

HMAC（RFC 2104 / FIPS 198-1），基于 crate::sha2。

mlkem

FIPS 203：ML-KEM 模格 KEM——全部三个参数集（M8.3 起 768， M8.4 泛化为 512/768/1024）。

ops

后端分发入口（性能优化的唯一挂接点）。

policy

批准策略：FIPS 140-3 下各算法的批准状态与批准模式门控。

selftest

上电自检（FIPS 140-3 ISO/IEC 19790 §7.9.2 强制项）。

sha2

SHA-2 家族：SHA-256 / SHA-384 / SHA-512（FIPS 180-4）。

sha3

FIPS 202：Keccak 海绵族——SHA3-224/256/384/512 与 SHAKE-128/256 （家族全部 6 个函数；M8.3 落地 256/512 与 SHAKE，同轮补齐 224/384）。

sign

数字签名：ECDSA（P-256/P-384，RFC 6979 确定性 nonce）、Ed25519 （RFC 8032）、RSA（PKCS#1 v1.5 / PSS，M4b 落地）。

Enums

Error

The unified error type of the module boundary.