bench

Cargo.toml

@@ -28,3 +28,18 @@ ml_kem_1024 = []
 
 [dev-dependencies]
 rand_chacha = "0.3.1"
+criterion = "0.5.1"
+
+
+[[bench]]
+name = "benchmark"
+harness = false
+
+
+[profile.bench]
+debug = 2
+debug-assertions = false
+incremental = false
+lto = true
+opt-level = 3
+overflow-checks = false

README.md

@@ -6,12 +6,12 @@
 ![Apache2/MIT licensed][license-image]
 ![Rust Version][rustc-image]
 
-[mlKem] Module-Lattice-Based Key-Encapsulation Mechanism Standard written in pure Rust.
+[MlKem] Module-Lattice-Based Key-Encapsulation Mechanism Standard written in pure Rust.
 
-This library implements the FIPS 203 **draft** standard in pure Rust.
-All three security parameters sets are fully functional. The code
-does not require the standard library, e.g. `#[no_std]`, and has
-no heap allocations so will be suitable for WASM and embedded applications.
+This library implements the FIPS 203 **draft** standard in pure Rust with minimal and
+mainstream dependencies. All three security parameter sets are fully functional. The
+code does not require the standard library, e.g. `#[no_std]`, and has no heap
+allocations so will be suitable for WASM, embedded and bare-metal applications.
 Significant performance optimizations will be forthcoming.
 
 See: <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.ipd.pdf>
@@ -109,4 +109,4 @@ dual licensed as above, without any additional terms or conditions.
 
 [IntegrityChain]: https://github.com/integritychain/
 
-[mlKem]: https://csrc.nist.gov/pubs/fips/203/ipd
+[MlKem]: https://csrc.nist.gov/pubs/fips/203/ipd

benches/benchmark.rs

@@ -0,0 +1,26 @@
+use criterion::{black_box, Criterion, criterion_group, criterion_main};
+use ml_kem_rs::{ml_kem_1024, ml_kem_512, ml_kem_768};
+
+pub fn criterion_benchmark(c: &mut Criterion) {
+ let (ek_512, dk_512) = ml_kem_512::key_gen();
+ let (_, ct_512) = ek_512.encaps();
+ let (ek_768, dk_768) = ml_kem_768::key_gen();
+ let (_, ct_768) = ek_768.encaps();
+ let (ek_1024, dk_1024) = ml_kem_1024::key_gen();
+ let (_, ct_1024) = ek_1024.encaps();
+
+ c.bench_function("ml_kem_512 KeyGen", |b| b.iter(|| ml_kem_512::key_gen()));
+ c.bench_function("ml_kem_512 Encaps", |b| b.iter(|| ek_512.encaps()));
+ c.bench_function("ml_kem_512 Decaps", |b| b.iter(|| dk_512.decaps(&ct_512)));
+
+ c.bench_function("ml_kem_768 KeyGen", |b| b.iter(|| ml_kem_768::key_gen()));
+ c.bench_function("ml_kem_768 Encaps", |b| b.iter(|| ek_768.encaps()));
+ c.bench_function("ml_kem_768 Decaps", |b| b.iter(|| dk_768.decaps(&ct_768)));
+
+ c.bench_function("ml_kem_1024 KeyGen", |b| b.iter(|| ml_kem_1024::key_gen()));
+ c.bench_function("ml_kem_1024 Encaps", |b| b.iter(|| ek_1024.encaps()));
+ c.bench_function("ml_kem_1024 Decaps", |b| b.iter(|| dk_1024.decaps(&ct_1024)));
+}
+
+criterion_group!(benches, criterion_benchmark);
+criterion_main!(benches);

src/helpers.rs

@@ -6,7 +6,7 @@ use crate::ntt::multiply_ntts;
 use crate::Q;
 use crate::types::Z256;
 
-/// Vector addition; See bottom of page 9, second row: z_hat = u_hat + v_hat
+/// Vector addition; See bottom of page 9, second row: `z_hat` = `u_hat` + `v_hat`
 #[must_use]
 pub(crate) fn vec_add<const K: usize>(
  vec_a: &[[Z256; 256]; K], vec_b: &[[Z256; 256]; K],
@@ -21,7 +21,7 @@ pub(crate) fn vec_add<const K: usize>(
 }
 
 
-/// Matrix by vector multiplication; See top of page 10, first row: w_hat = A_hat mul u_hat
+/// Matrix by vector multiplication; See top of page 10, first row: `w_hat` = `A_hat` mul `u_hat`
 #[must_use]
 pub(crate) fn mat_vec_mul<const K: usize>(
  a_hat: &[[[Z256; 256]; K]; K], u_hat: &[[Z256; 256]; K],
@@ -41,7 +41,7 @@ pub(crate) fn mat_vec_mul<const K: usize>(
 }
 
 
-/// Matrix transpose by vector multiplication; See top of page 10, second row: y_hat = A_hatT mul u_hat
+/// Matrix transpose by vector multiplication; See top of page 10, second row: `y_hat` = `A_hat^T` mul `u_hat`
 #[must_use]
 pub(crate) fn mat_t_vec_mul<const K: usize>(
  a_hat: &[[[Z256; 256]; K]; K], u_hat: &[[Z256; 256]; K],
@@ -60,7 +60,7 @@ pub(crate) fn mat_t_vec_mul<const K: usize>(
  y_hat
 }
 
-/// Vector dot product; See top of page 10, third row: z_dat = u_hatT mul v_hat
+/// Vector dot product; See top of page 10, third row: `z_hat` = `u_hat^T` mul `v_hat`
 #[must_use]
 pub(crate) fn dot_t_prod<const K: usize>(
  u_hat: &[[Z256; 256]; K], v_hat: &[[Z256; 256]; K],

src/lib.rs

@@ -8,10 +8,10 @@
 /// See <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.ipd.pdf>
 
 // TODO
-// 3. Implement bench
+// 3. Implement bench, fix-->CT
 // 4. Fix github actions
 // 5. Review main Doc; features: no_std, no alloc, minimal dependencies, CT
-// 6. Git push to CC, publish as 0.1.1
+// 6. Tag, Git push to CC, publish as 0.1.1
 // 7. Re-read spec
 #[cfg(test)]
 extern crate alloc;
@@ -131,7 +131,9 @@ macro_rules! functionality {
  #[cfg(test)]
  pub fn key_gen_test(seed: &[u8; 32]) -> (EncapsKey, DecapsKey) {
  let (mut ek, mut dk) = (EncapsKey::default(), DecapsKey::default());
- ml_kem::ml_kem_key_gen::<K, ETA1, ETA1_64, ETA1_512>(&seed, &seed, &mut ek.0, &mut dk.0);
+ ml_kem::ml_kem_key_gen::<K, ETA1, ETA1_64, ETA1_512>(
+ &seed, &seed, &mut ek.0, &mut dk.0,
+ );
  (ek, dk)
  }
 
@@ -222,7 +224,7 @@ macro_rules! functionality {
  DV,
  DV_256,
  J_LEN,
- CT_LEN
+ CT_LEN,
  >(&self.0, &ct.0)
  }
 

src/ml_kem.rs

@@ -110,7 +110,7 @@ pub(crate) fn ml_kem_decaps<
  const DV: usize,
  const DV_256: usize,
  const J_LEN: usize,
- const CT_LEN: usize
+ const CT_LEN: usize,
 >(
  dk: &[u8], ct: &[u8],
 ) -> SharedSecretKey {

src/ntt.rs

@@ -3,7 +3,7 @@ use crate::helpers::{bit_rev_7, pow_mod_q};
 use crate::types::Z256;
 
 /// Algorithm 8 `NTT(f)` on page 22.
-/// Computes the NTT representation f_hat of the given polynomial f ∈ R_q.
+/// Computes the NTT representation `f_hat` of the given polynomial f ∈ `R_q`.
 #[must_use]
 #[allow(clippy::module_name_repetitions)]
 pub fn ntt(array_f: &[Z256; 256]) -> [Z256; 256] {
@@ -45,7 +45,7 @@ pub fn ntt(array_f: &[Z256; 256]) -> [Z256; 256] {
 
 
 /// Algorithm 9 `NTTinv(f)` on page 23.
-/// Computes the polynomial f ∈ R_q corresponding to the given NTT representation f_hat ∈ T_q.
+/// Computes the polynomial f ∈ `R_q` corresponding to the given NTT representation `f_hat` ∈ `T_q`.
 #[must_use]
 #[allow(clippy::module_name_repetitions)]
 pub fn ntt_inv(f_hat: &[Z256; 256]) -> [Z256; 256] {

src/sampling.rs

@@ -5,7 +5,7 @@ use crate::Q;
 use crate::types::Z256;
 
 /// Algorithm 6 `SampleNTT(B)` on page 20.
-/// If the input is a stream of uniformly random bytes, the output is a uniformly random element of T_q.
+/// If the input is a stream of uniformly random bytes, the output is a uniformly random element of `T_q`.
 #[must_use]
 pub fn sample_ntt(mut byte_stream_b: impl XofReader) -> [Z256; 256] {
  // Input: byte stream B ∈ B^{∗}