Expand description
§IntegrityChain: FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard
FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard written in pure Rust for server, desktop, browser and embedded applications. The source repository includes examples demonstrating benchmarking, code provenance, an embedded target, constant-time statistical measurements, a fuzzing harness, WASM execution, C FFI and Python bindings.
This crate implements the released FIPS 203 standard in pure Rust with minimal and mainstream dependencies, and
without any unsafe code. All three security parameter sets are fully supported and tested. The implementation operates
in constant-time (outside of rho, which is part of the encapsulation key sent across the trust boundary in the clear),
does not require the standard library, e.g. #[no_std]
, has no heap allocations, e.g. no alloc
needed, and optionally
exposes the RNG
so it is suitable for the full range of applications down to the bare-metal. The API is stabilized
and the code is heavily biased towards safety and correctness; further performance optimizations will be implemented
as the standard matures. This crate will quickly follow any future changes to FIPS 203 as they become available.
See https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf for a full description of the target functionality.
The functionality is extremely simple to use, as demonstrated by the following example.
// Use the desired target parameter set.
use fips203::ml_kem_512; // Could also be ml_kem_768 or ml_kem_1024.
use fips203::traits::{Decaps, Encaps, KeyGen, SerDes};
// Alice runs `try_keygen()` and then serializes the encaps key `ek` for Bob (to bytes).
let (alice_ek, alice_dk) = ml_kem_512::KG::try_keygen().unwrap();
let alice_ek_bytes = alice_ek.into_bytes();
// Alice sends the encaps key `ek_bytes` to Bob.
let bob_ek_bytes = alice_ek_bytes;
// Bob deserializes the encaps `ek_bytes` and then runs `encaps() to get the shared
// secret `ssk` and ciphertext `ct`. He serializes the ciphertext `ct` for Alice (to bytes).
let bob_ek = ml_kem_512::EncapsKey::try_from_bytes(bob_ek_bytes).unwrap();
let (bob_ssk_bytes, bob_ct) = bob_ek.try_encaps().unwrap();
let bob_ct_bytes = bob_ct.into_bytes();
// Bob sends the ciphertext `ct_bytes` to Alice
let alice_ct_bytes = bob_ct_bytes;
// Alice deserializes the ciphertext `ct` and runs `decaps()` with her decaps key
let alice_ct = ml_kem_512::CipherText::try_from_bytes(alice_ct_bytes).unwrap();
let alice_ssk_bytes = alice_dk.try_decaps(&alice_ct).unwrap();
// Alice and Bob will now have the same secret key
assert_eq!(bob_ssk_bytes, alice_ssk_bytes);
The Rust Documentation lives under each Module corresponding to the desired security parameter below.
§Notes
- This crate is fully functional and corresponds to the released final FIPS 203.
- Constant-time operation targets the source-code level only on the latest version of Rust, with
confirmation via manual review/inspection, the embedded target, and the
dudect
dynamic measurements. - Note that FIPS 203 places specific requirements on randomness per section 3.3, hence the exposed
RNG
. - Requires Rust 1.70 or higher. The minimum supported Rust version (MSRV) may be changed in the future, but it will be done with a minor version bump (when the major version is larger than 0).
- All on-by-default features of this library are covered by
SemVer
. - The FIPS 203 standard is ‘new’ and so this software is experimental – USE AT YOUR OWN RISK!
§License
Contents are licensed under either the Apache License Version 2.0 or MIT license at your option.
§Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above without any additional terms or conditions.
Modules§
- Functionality for the ML-KEM-512 security parameter set, which is claimed to be in security category 1, see table 2 & 3 on page 39 of spec.
- Functionality for the ML-KEM-768 security parameter set, which is claimed to be in security category 3, see table 2 & 3 on page 39 of spec.
- Functionality for the ML-KEM-1024 security parameter set, which is claimed to be in security category 5, see table 2 & 3 on page 39 of spec.
- All functionality is covered by traits, such that consumers can utilize trait objects if desired.
Structs§
- These
rand_core
types are re-exported so that users of fips203 do not have to worry about using the exactly correct version ofrand_core
. Error type of random number generators - The (opaque) secret key that can be de/serialized by each party.
Constants§
- Shared Secret Key length for all ML-KEM variants (in bytes)
Traits§
- These
rand_core
types are re-exported so that users of fips203 do not have to worry about using the exactly correct version ofrand_core
. A marker trait used to indicate that anRngCore
orBlockRngCore
implementation is supposed to be cryptographically secure. - These
rand_core
types are re-exported so that users of fips203 do not have to worry about using the exactly correct version ofrand_core
. The core of a random number generator.