Merge pull request #8 from supinie/update_API

Update api
supinie · Jun 5, 2024 · aeaa776 · aeaa776
2 parents e3c02ba + 7cb50bc
commit aeaa776
Show file tree

Hide file tree

Showing 8 changed files with 128 additions and 65 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -56,7 +56,7 @@ jobs:
         with:
           components: rustfmt
       - name: Check formatting
-        run: cargo fmt
+        run: cargo fmt --all -- --check
 
   clippy:
     name: Clippy
@@ -70,4 +70,4 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy
-      - run: cargo clippy
+      - run: cargo clippy -- -D warnings
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,6 @@ Cargo.lock
 
 # Proptest
 proptest-regressions
+
+# Flamegraph
+benches/flamegraph/
diff --git a/Cargo.toml b/Cargo.toml
@@ -20,6 +20,9 @@ codegen-units = 1
 panic = "abort"
 strip = "symbols"
 
+[profile.bench]
+debug = true
+
 [dependencies]
 byteorder = "1.4.3"
 more-asserts = "0.3.1"
@@ -34,12 +37,12 @@ zeroize = { version = "1.7.0", default-features = false }
 [dev-dependencies]
 rand = "0.8.5"
 proptest = "1.4.0"
-criterion = "0.3" # 0.5.1 latest
+criterion = "0.5.1"
 
 # [workspace]
 # members = ["src/kyber"]
 # default-members = ["src/kyber"]
 
 [[bench]]
-name = "my_benchmark"
+name = "api"
 harness = false
diff --git a/benches/my_benchmark.rs → benches/api.rs b/benches/my_benchmark.rs → benches/api.rs
@@ -3,61 +3,61 @@ use enc_rust::kem::*;
 
 pub fn gen_key_benchmark_512(c: &mut Criterion) {
     c.bench_function("key_gen_bench_512", |b| {
-        b.iter(|| generate_key_pair(None, 2))
+        b.iter(|| generate_keypair_512(None))
     });
 }
 
 pub fn gen_key_benchmark_768(c: &mut Criterion) {
     c.bench_function("key_gen_bench_768", |b| {
-        b.iter(|| generate_key_pair(None, 3))
+        b.iter(|| generate_keypair_768(None))
     });
 }
 
 pub fn gen_key_benchmark_1024(c: &mut Criterion) {
     c.bench_function("key_gen_bench_1024", |b| {
-        b.iter(|| generate_key_pair(None, 4))
+        b.iter(|| generate_keypair_1024(None))
     });
 }
 
 pub fn encap_benchmark_512(c: &mut Criterion) {
-    let (pk, _) = generate_key_pair(None, 2).unwrap();
+    let (pk, _) = generate_keypair_512(None).unwrap();
     c.bench_function("encap_benchmark_512", |b| {
         b.iter(|| pk.encapsulate(None, None))
     });
 }
 
 pub fn encap_benchmark_768(c: &mut Criterion) {
-    let (pk, _) = generate_key_pair(None, 3).unwrap();
+    let (pk, _) = generate_keypair_768(None).unwrap();
     c.bench_function("encap_benchmark_768", |b| {
         b.iter(|| pk.encapsulate(None, None))
     });
 }
 
 pub fn encap_benchmark_1024(c: &mut Criterion) {
-    let (pk, _) = generate_key_pair(None, 4).unwrap();
+    let (pk, _) = generate_keypair_1024(None).unwrap();
     c.bench_function("encap_benchmark_1024", |b| {
         b.iter(|| pk.encapsulate(None, None))
     });
 }
 
 pub fn decap_benchmark_512(c: &mut Criterion) {
-    let (pk, sk) = generate_key_pair(None, 2).unwrap();
+    let (pk, sk) = generate_keypair_512(None).unwrap();
     let (ciphertext_obj, _) = pk.encapsulate(None, None).unwrap();
     c.bench_function("decap_benchmark_512", |b| {
         b.iter(|| sk.decapsulate(ciphertext_obj.as_bytes()))
     });
 }
 
 pub fn decap_benchmark_768(c: &mut Criterion) {
-    let (pk, sk) = generate_key_pair(None, 3).unwrap();
+    let (pk, sk) = generate_keypair_768(None).unwrap();
     let (ciphertext_obj, _) = pk.encapsulate(None, None).unwrap();
     c.bench_function("decap_benchmark_768", |b| {
         b.iter(|| sk.decapsulate(ciphertext_obj.as_bytes()))
     });
 }
 
 pub fn decap_benchmark_1024(c: &mut Criterion) {
-    let (pk, sk) = generate_key_pair(None, 4).unwrap();
+    let (pk, sk) = generate_keypair_1024(None).unwrap();
     let (ciphertext_obj, _) = pk.encapsulate(None, None).unwrap();
     c.bench_function("decap_benchmark_1024", |b| {
         b.iter(|| sk.decapsulate(ciphertext_obj.as_bytes()))

diff --git a/src/kem.rs b/src/kem.rs
@@ -55,7 +55,7 @@ impl Ciphertext {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (pk, sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (pk, sk) = generate_keypair_768(None).unwrap();
     /// let (ciphertext_obj, shared_secret) = pk.encapsulate(None, None)?;
     /// let ciphertext = ciphertext_obj.as_bytes();
     ///
@@ -122,22 +122,33 @@ fn new_key_from_seed(
 /// [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
 pub trait AcceptableRng: RngCore + CryptoRng {}
 
-/// Generates a new keypair for a given security level.
+pub(crate) fn generate_key_pair(
+    rng: Option<&mut dyn AcceptableRng>,
+    k: K,
+) -> Result<(PublicKey, PrivateKey), KeyGenerationError> {
+    let mut seed = [0u8; 2 * SYMBYTES];
+
+    if let Some(rng) = rng {
+        rng.try_fill_bytes(&mut seed)?;
+    } else {
+        let mut chacha = ChaCha20Rng::from_entropy();
+        chacha.try_fill_bytes(&mut seed)?;
+    };
+
+    let sec_level = SecurityLevel::new(k);
+
+    new_key_from_seed(&seed, sec_level)
+}
+
+/// Generates a new keypair for the 512 Security Parameters.
 ///
 /// # Inputs
 /// - `rng`: (Optional) RNG to be used when generating the keypair. Must satisfy the
-/// [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
-/// [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
-/// If RNG is not present, then
-/// [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
-/// will be used.
-/// - `k`: The k value corresponding to the security value to be used:
-///
-/// | Security Level | K |
-/// |----------------|---|
-/// | 512            | 2 |
-/// | 768            | 3 |
-/// | 1024           | 4 |
+///   [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
+///   [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
+///   If RNG is not present, then
+///   [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
+///   will be used.
 ///
 /// # Outputs
 /// - [`PublicKey`] object
@@ -151,32 +162,78 @@ pub trait AcceptableRng: RngCore + CryptoRng {}
 /// # Example
 /// ```
 /// # use enc_rust::kem::*;
-/// let (pk, sk) = generate_key_pair(None, 3)?;
+/// let (pk, sk) = generate_keypair_512(None)?;
 ///
 /// # Ok::<(), enc_rust::errors::KeyGenerationError>(())
 /// ```
-pub fn generate_key_pair(
+pub fn generate_keypair_512(
     rng: Option<&mut dyn AcceptableRng>,
-    k: usize,
 ) -> Result<(PublicKey, PrivateKey), KeyGenerationError> {
-    let k_result = K::try_from(k);
-
-    if let Ok(k_value) = k_result {
-        let mut seed = [0u8; 2 * SYMBYTES];
-
-        if let Some(rng) = rng {
-            rng.try_fill_bytes(&mut seed)?;
-        } else {
-            let mut chacha = ChaCha20Rng::from_entropy();
-            chacha.try_fill_bytes(&mut seed)?;
-        };
-
-        let sec_level = SecurityLevel::new(k_value);
+    generate_key_pair(rng, K::Two)
+}
 
-        return new_key_from_seed(&seed, sec_level);
-    }
+/// Generates a new keypair for the 768 Security Parameters.
+///
+/// # Inputs
+/// - `rng`: (Optional) RNG to be used when generating the keypair. Must satisfy the
+///   [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
+///   [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
+///   If RNG is not present, then
+///   [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
+///   will be used.
+///
+/// # Outputs
+/// - [`PublicKey`] object
+/// - [`PrivateKey`] object
+///
+/// # Errors
+/// Will return a [`KeyGenerationError`] if:
+/// - Given invalid K value
+/// - RNG fails
+///
+/// # Example
+/// ```
+/// # use enc_rust::kem::*;
+/// let (pk, sk) = generate_keypair_768(None)?;
+///
+/// # Ok::<(), enc_rust::errors::KeyGenerationError>(())
+/// ```
+pub fn generate_keypair_768(
+    rng: Option<&mut dyn AcceptableRng>,
+) -> Result<(PublicKey, PrivateKey), KeyGenerationError> {
+    generate_key_pair(rng, K::Three)
+}
 
-    Err(CrystalsError::InvalidK(k).into())
+/// Generates a new keypair for the 1024 Security Parameters.
+///
+/// # Inputs
+/// - `rng`: (Optional) RNG to be used when generating the keypair. Must satisfy the
+///   [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
+///   [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
+///   If RNG is not present, then
+///   [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
+///   will be used.
+///
+/// # Outputs
+/// - [`PublicKey`] object
+/// - [`PrivateKey`] object
+///
+/// # Errors
+/// Will return a [`KeyGenerationError`] if:
+/// - Given invalid K value
+/// - RNG fails
+///
+/// # Example
+/// ```
+/// # use enc_rust::kem::*;
+/// let (pk, sk) = generate_keypair_1024(None)?;
+///
+/// # Ok::<(), enc_rust::errors::KeyGenerationError>(())
+/// ```
+pub fn generate_keypair_1024(
+    rng: Option<&mut dyn AcceptableRng>,
+) -> Result<(PublicKey, PrivateKey), KeyGenerationError> {
+    generate_key_pair(rng, K::Four)
 }
 
 impl PrivateKey {
@@ -189,7 +246,7 @@ impl PrivateKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// let (_, sk) = generate_key_pair(None, 3)?;
+    /// let (_, sk) = generate_keypair_768(None)?;
     /// let pk = sk.get_public_key();
     ///
     /// # Ok::<(), enc_rust::errors::KeyGenerationError>(())
@@ -206,7 +263,7 @@ impl PrivateKey {
     ///
     /// # Inputs
     /// - `bytes`: Buffer for the private key to be packed into. For corresponding
-    /// security levels, `bytes` should be of length:
+    ///   security levels, `bytes` should be of length:
     ///
     /// | Security Level | Length |
     /// |----------------|--------|
@@ -220,7 +277,7 @@ impl PrivateKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// let (_, sk) = generate_key_pair(None, 3).unwrap();
+    /// let (_, sk) = generate_keypair_768(None).unwrap();
     /// let mut sk_bytes = [0u8; 2400];
     /// sk.pack(&mut sk_bytes)?;
     ///
@@ -262,7 +319,7 @@ impl PrivateKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (pk, new_sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (pk, new_sk) = generate_keypair_768(None).unwrap();
     /// # let mut sk_bytes = [0u8; 2400];
     /// # new_sk.pack(&mut sk_bytes)?;
     /// let sk = PrivateKey::unpack(&sk_bytes)?;
@@ -305,7 +362,7 @@ impl PrivateKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (pk, sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (pk, sk) = generate_keypair_768(None).unwrap();
     /// # let (ciphertext_obj, secret) = pk.encapsulate(None, None).unwrap();
     /// # let ciphertext = ciphertext_obj.as_bytes();
     /// let shared_secret = sk.decapsulate(ciphertext)?;
@@ -356,7 +413,7 @@ impl PublicKey {
     ///
     /// # Inputs
     /// - `bytes`: Buffer for the public key to be packed into. For corresponding
-    /// security levels, `bytes` should be of length:
+    ///   security levels, `bytes` should be of length:
     ///
     /// | Security Level | Length |
     /// |----------------|--------|
@@ -370,7 +427,7 @@ impl PublicKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (pk, sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (pk, sk) = generate_keypair_768(None).unwrap();
     /// let mut pk_bytes = [0u8; 1184];
     /// pk.pack(&mut pk_bytes)?;
     ///
@@ -404,7 +461,7 @@ impl PublicKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (new_pk, sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (new_pk, sk) = generate_keypair_768(None).unwrap();
     /// # let mut pk_bytes = [0u8; 1184];
     /// # new_pk.pack(&mut pk_bytes)?;
     /// let pk = PublicKey::unpack(&pk_bytes)?;
@@ -423,11 +480,11 @@ impl PublicKey {
     /// # Inputs
     /// - `seed`: (Optional) a 64 byte slice used as a seed for randomness
     /// - `rng`: (Optional) RNG to be used during encapsulation. Must satisfy the
-    /// [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
-    /// [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
-    /// If RNG is not present, then
-    /// [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
-    /// will be used.
+    ///   [`RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html) and
+    ///   [`CryptoRng`](https://docs.rs/rand_core/latest/rand_core/trait.CryptoRng.html) traits.
+    ///   If RNG is not present, then
+    ///   [`ChaCha20`](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html)
+    ///   will be used.
     ///
     /// # Outputs
     /// - [`Ciphertext`] object
@@ -441,7 +498,7 @@ impl PublicKey {
     /// # Example
     /// ```
     /// # use enc_rust::kem::*;
-    /// # let (pk, sk) = generate_key_pair(None, 3).unwrap();
+    /// # let (pk, sk) = generate_keypair_768(None).unwrap();
     /// let (ciphertext_obj, shared_secret) = pk.encapsulate(None, None)?;
     ///
     /// # Ok::<(), enc_rust::errors::EncryptionDecryptionError>(())

diff --git a/src/lib.rs b/src/lib.rs
@@ -69,7 +69,7 @@
 //!
 //!
 //! fn main() {
-//!     let (pk, sk) = generate_key_pair(None, 3).unwrap();
+//!     let (pk, sk) = generate_keypair_768(None).unwrap();
 //!
 //!     let (ciphertext, alice_secret) = alice(pk);
 //!

diff --git a/src/tests/field_operations.rs b/src/tests/field_operations.rs
@@ -66,7 +66,7 @@ mod field_tests {
             if y < 0 {
                 y += Q as i16;
             }
-            if i < 0 && (-i) % Q as i16 == 0 {
+            if i < 0 && -(i % Q as i16) == 0 {
                 output -= Q as i16;
             }