New feature: Suspendable (serializable state) (#48)

* initial trait defn for SerializableState

* sha2 impls SerializableState

* rustfmt

* Incorporating Nikola and David's feedback

* An in-progress SHA3 object can now be serialized

* Impl'd SerializableState for MLDSA, and some quality-of-life fixes for the impl for SHA2 and SHA3.

* rustfmt

* Impl'd SerializableState for MLDSA-lowmemory.

* Impl'd SerializableKeyedState for HMAC.

* Fixed a bug in HMAC that could cause panics.

* Implemented Suspendable for HKDF and a bunch of other tidy-up.

* rustfmt

* HMAC now impl's Drop like it should.

* Adjusted the Suspendable version checker to allow future versions from the same patch stream

* HKDF now explicitly carries a lib_ver tag

* Fixed Keccak corrupt-state rejection, Hashfactory honest Algorithm left as a TODO, left version number bumping as a TODO, passed #6 wycheproof randomized case, suspend and serialize sha2/sha3/shake regressions (#48)

* rustfmt of all code changes in (#48)

* tweaks

---------

Co-authored-by: officialfrancismendoza <francissamuelmendoza7@gmail.com>

Author: ounsworth

QUALITY_AND_STYLE.md

@@ -12,6 +12,10 @@ lib.rs for all crates needs to contain: `#![forbid(missing_docs)]`, `#![no_std]`
 
 All primitives must be accompanied by a CLI in `/cli`.
 
+All algorithms with a state that is exercised across multiple API calls -- typically through a `do_update()`,
+`do_final()` pattern -- should implement SerializableState so that the user can pause the execution of this algorithm to
+a cache and resume later.
+
 # Quality
 
 ## Tests

alpha_0.1.2_release_notes.md

@@ -38,11 +38,21 @@
 
 # 0.1.2 Features / Changelog
 
+## Major features
+
 * New algorithms added to crypto/ :
     * mldsa (FIPS 204)
     * mldsa-lowmemory -- runs in about 1/10th of the usual memory (~ 30 kb of stack) with comparable performance impact.
     * mlkem (FIPS 203)
     * mlkem-lowmemory -- runs in about 1/4th of the usual memory (~ 12 kb of stack) with comparable performance impact.
+* New traits [Suspendable] and [SuspendableKeyed] allow algorithms with a streaming API (`do_update()` ->
+  `do_final()`) to be suspended to a small byte array and then resumed later, potentially from a different host and
+  potentially across versions of the library. The intended use case is if you are processing a large input that depends
+  on one or more network round-trips and you wish to suspend to a cache and potentially transfer to a new host while
+  waiting for network IO.
+
+## Minor features / bug fixes
+
 * All public `*_out(.., out: &mut [u8])` functions now begin by zeroizing the entire output buffer with `.fill(0)`,
   preventing exposure of stale data in oversized output buffers or on early error returns.
 * Reworked the way KeyMaterial hazardous operations work; instead of a stateful .allow_hazardous_operations() /

crypto/core-test-framework/src/lib.rs

@@ -14,6 +14,7 @@ pub mod kdf;
 pub mod kem;
 pub mod mac;
 pub mod signature;
+pub mod suspendable_state;
 pub mod symmetric_ciphers;
 
 mod fixed_seed_rng;

crypto/core-test-framework/src/suspendable_state.rs

@@ -0,0 +1,179 @@
+use bouncycastle_core::errors::SuspendableError;
+use bouncycastle_core::suspendable_state::{LIB_VERSION, SemVer};
+use bouncycastle_core::traits::{Suspendable, SuspendableKeyed};
+
+pub struct TestFrameworkSuspendableState {}
+
+impl TestFrameworkSuspendableState {
+    pub fn new() -> Self {
+        Self {}
+    }
+
+    /// Test all the members of trait SerializableState.
+    ///
+    /// Expects ta be handed an instance of the object that has some in-progress state to be serialized.
+    pub fn test<const SERIALIZED_STATE_LEN: usize, S: Suspendable<SERIALIZED_STATE_LEN> + Clone>(
+        &self,
+        instance: &S,
+    ) {
+        // There's not a lot we can test here in the abstract, but we can test a few things to
+        // ensure that the SerializableState trait has been impl'd correctly.
+
+        // we need to work on a clone because .serialize_state() moves self, which you can't do on a
+        // borrowed instance.
+        let instance_clone = instance.clone();
+
+        // You can serialize and then deserialize the state.
+        let serialized_state = instance_clone.suspend();
+        assert_eq!(serialized_state.len(), SERIALIZED_STATE_LEN);
+
+        let _deserialized_state = S::from_suspended(serialized_state).unwrap();
+
+        // The serialized state MUST include a prefix indicating the current version of the library.
+        let state_sized: [u8; 3] = serialized_state[..3].try_into().unwrap();
+        assert_eq!(SemVer::from(state_sized), LIB_VERSION);
+
+        // All implementations MUST reject a serialized state from lib ver 0.0.0
+        // This doesn't really serve any purpose except testing that all impl's have properly
+        // used the helper functions.
+        let mut ver0_serialized_state = serialized_state.clone();
+        ver0_serialized_state[..3].copy_from_slice(&[0, 0, 0]);
+        match S::from_suspended(ver0_serialized_state) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        // All implementations MUST reject a serialized state from a future MAJOR or MINOR version.
+        let mut future_ver = LIB_VERSION;
+        future_ver.major += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        match S::from_suspended(futurever_serialized_state) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        let mut future_ver = LIB_VERSION;
+        future_ver.minor += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        match S::from_suspended(futurever_serialized_state) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        // but should accept anything on the same patch stream.
+        let mut future_ver = LIB_VERSION;
+        future_ver.patch += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        let _deserialized_state = S::from_suspended(futurever_serialized_state).unwrap();
+
+        // ... even up to patch 255
+        let mut future_ver = LIB_VERSION;
+        future_ver.patch = 255;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        let _deserialized_state = S::from_suspended(futurever_serialized_state).unwrap();
+    }
+}
+
+pub struct TestFrameworkSuspendableKeyedState {}
+
+impl TestFrameworkSuspendableKeyedState {
+    pub fn new() -> Self {
+        Self {}
+    }
+
+    /// Test all the members of trait SerializableState.
+    ///
+    /// Expects ta be handed an instance of the object that has some in-progress state to be serialized.
+    pub fn test<
+        const SERIALIZED_STATE_LEN: usize,
+        S: SuspendableKeyed<SERIALIZED_STATE_LEN> + Clone,
+    >(
+        &self,
+        instance: &S,
+        key: &S::Key,
+    ) {
+        // There's not a lot we can test here in the abstract, but we can test a few things to
+        // ensure that the SerializableState trait has been impl'd correctly.
+
+        // we need to work on a clone because .serialize_state() moves self, which you can't do on a
+        // borrowed instance.
+        let instance_clone = instance.clone();
+
+        // You can serialize and then deserialize the state.
+        let serialized_state = instance_clone.suspend();
+        assert_eq!(serialized_state.len(), SERIALIZED_STATE_LEN);
+
+        let _deserialized_state = S::from_suspended(serialized_state, key).unwrap();
+
+        // The serialized state MUST include a prefix indicating the current version of the library.
+        let state_sized: [u8; 3] = serialized_state[..3].try_into().unwrap();
+        assert_eq!(SemVer::from(state_sized), LIB_VERSION);
+
+        // All implementations MUST reject a serialized state from lib ver 0.0.0
+        // This doesn't really serve any purpose except testing that all impl's have properly
+        // used the helper functions.
+        let mut ver0_serialized_state = serialized_state.clone();
+        ver0_serialized_state[..3].copy_from_slice(&[0, 0, 0]);
+        match S::from_suspended(ver0_serialized_state, key) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        // All implementations MUST reject a serialized state from a future MAJOR or MINOR version.
+        let mut future_ver = LIB_VERSION;
+        future_ver.major += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        match S::from_suspended(futurever_serialized_state, key) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        let mut future_ver = LIB_VERSION;
+        future_ver.minor += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        match S::from_suspended(futurever_serialized_state, key) {
+            Err(SuspendableError::IncompatibleVersion) => { /* good */ }
+            _ => {
+                panic!("Expected IncompatibleVersion error")
+            }
+        }
+
+        // but should accept anything on the same patch stream.
+        let mut future_ver = LIB_VERSION;
+        future_ver.patch += 1;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        let _deserialized_state = S::from_suspended(futurever_serialized_state, key).unwrap();
+
+        // ... even up to patch 255
+        let mut future_ver = LIB_VERSION;
+        future_ver.patch = 255;
+        let mut futurever_serialized_state = serialized_state.clone();
+        futurever_serialized_state[..3]
+            .copy_from_slice(&[future_ver.major, future_ver.minor, future_ver.patch]);
+        let _deserialized_state = S::from_suspended(futurever_serialized_state, key).unwrap();
+    }
+}

crypto/core/src/errors.rs

@@ -72,6 +72,14 @@ pub enum RNGError {
     KeyMaterialError(KeyMaterialError),
 }
 
+#[derive(Debug)]
+pub enum SuspendableError {
+    /// The serialized state was produced by a library version incompatible with this one.
+    IncompatibleVersion,
+    /// The serialized state is malformed or corrupt.
+    InvalidData,
+}
+
 #[derive(Debug)]
 pub enum SignatureError {
     GenericError(&'static str),

crypto/core/src/key_material.rs

@@ -50,7 +50,7 @@
 //!
 //! See [do_hazardous_operations] for documentation and sample code.
 
-use crate::errors::KeyMaterialError;
+use crate::errors::{KeyMaterialError, SuspendableError};
 use crate::traits::{RNG, Secret, SecurityStrength};
 use bouncycastle_utils::{ct, min};
 
@@ -222,10 +222,15 @@ pub struct KeyMaterial<const KEY_LEN: usize> {
 
 impl<const KEY_LEN: usize> Secret for KeyMaterial<KEY_LEN> {}
 
+// The explicit `#[repr(u8)]` discriminants are the stable on-the-wire encoding used by
+// `SerializableState` implementations (see the `TryFrom<u8>` impl below). Pin each value to its
+// variant name: reordering variants is fine, but never reuse or renumber an existing discriminant,
+// or previously-serialized states will be misread.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[repr(u8)]
 pub enum KeyType {
     /// The KeyMaterial is zeroized and MUST NOT be used for any cryptographic operation in this state.
-    Zeroized,
+    Zeroized = 0,
 
     /// The KeyMaterial contains non-zero data of unknown key type.
     /// A KeyMaterial of key type Unknown will always have a [SecurityStrength] of [SecurityStrength::None].
@@ -235,19 +240,36 @@ pub enum KeyType {
     /// and must be done within a [do_hazardous_operations] closure.
     /// If you want to import key material directly into a known key type, use [KeyMaterial::from_bytes_as_type],
     /// which does not require a hazardous operations closure.
-    Unknown,
+    Unknown = 1,
 
     /// The KeyMaterial contains data of full entropy and can be safely converted to any other key type.
-    CryptographicRandom,
+    CryptographicRandom = 2,
 
     /// A seed for asymmetric private keys, RNGs, and other seed-based cryptographic objects.
-    Seed,
+    Seed = 3,
 
     /// A MAC key.
-    MACKey,
+    MACKey = 4,
 
     /// A key for a symmetric block or stream cipher.
-    SymmetricCipherKey,
+    SymmetricCipherKey = 5,
+}
+
+impl TryFrom<u8> for KeyType {
+    type Error = SuspendableError;
+
+    /// Inverse of `self as u8`; rejects unrecognized discriminants with [SuspendableError::InvalidData].
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        Ok(match value {
+            0 => Self::Zeroized,
+            1 => Self::Unknown,
+            2 => Self::CryptographicRandom,
+            3 => Self::Seed,
+            4 => Self::MACKey,
+            5 => Self::SymmetricCipherKey,
+            _ => return Err(SuspendableError::InvalidData),
+        })
+    }
 }
 
 impl<const KEY_LEN: usize> Default for KeyMaterial<KEY_LEN> {

crypto/core/src/lib.rs

@@ -7,4 +7,5 @@
 
 pub mod errors;
 pub mod key_material;
+pub mod suspendable_state;
 pub mod traits;