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

Author: ounsworth

alpha_0.1.2_release_notes.md

@@ -45,10 +45,11 @@
     * 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 SerializeState and SerializeKeyedState 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. 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 suspect and potentially transfer to a new host while waiting for network IO.
+* 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
 

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

@@ -13,8 +13,8 @@ pub mod hash;
 pub mod kdf;
 pub mod kem;
 pub mod mac;
-pub mod serializable_state;
 pub mod signature;
+pub mod suspendable_state;
 
 mod fixed_seed_rng;
 pub use fixed_seed_rng::FixedSeedRNG;

…test-framework/src/serializable_state.rs …-test-framework/src/suspendable_state.rscrypto/core-test-framework/src/serializable_state.rs renamed to crypto/core-test-framework/src/suspendable_state.rs crypto/core-test-framework/src/serializable_state.rs renamed to crypto/core-test-framework/src/suspendable_state.rs

@@ -1,21 +1,18 @@
 use bouncycastle_core::errors::SerializedStateError;
 use bouncycastle_core::serializable_state::{LIB_VERSION, SemVer};
-use bouncycastle_core::traits::{SerializableKeyedState, SerializableState};
+use bouncycastle_core::traits::{Suspendable, SuspendableKeyed};
 
-pub struct TestFrameworkSerializableState {}
+pub struct TestFrameworkSuspendableState {}
 
-impl TestFrameworkSerializableState {
+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: SerializableState<SERIALIZED_STATE_LEN> + Clone,
-    >(
+    pub fn test<const SERIALIZED_STATE_LEN: usize, S: Suspendable<SERIALIZED_STATE_LEN> + Clone>(
         &self,
         instance: &S,
     ) {
@@ -27,10 +24,10 @@ impl TestFrameworkSerializableState {
         let instance_clone = instance.clone();
 
         // You can serialize and then deserialize the state.
-        let serialized_state = instance_clone.serialize_state();
+        let serialized_state = instance_clone.suspend();
         assert_eq!(serialized_state.len(), SERIALIZED_STATE_LEN);
 
-        let _deserialized_state = S::from_serialized_state(serialized_state).unwrap();
+        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();
@@ -41,7 +38,7 @@ impl TestFrameworkSerializableState {
         // 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_serialized_state(ver0_serialized_state) {
+        match S::from_suspended(ver0_serialized_state) {
             Err(SerializedStateError::IncompatibleVersion) => { /* good */ }
             _ => {
                 panic!("Expected IncompatibleVersion error")
@@ -54,7 +51,7 @@ impl TestFrameworkSerializableState {
         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_serialized_state(futurever_serialized_state) {
+        match S::from_suspended(futurever_serialized_state) {
             Err(SerializedStateError::IncompatibleVersion) => { /* good */ }
             _ => {
                 panic!("Expected IncompatibleVersion error")
@@ -63,9 +60,9 @@ impl TestFrameworkSerializableState {
     }
 }
 
-pub struct TestFrameworkSerializableKeyedState {}
+pub struct TestFrameworkSuspendableKeyedState {}
 
-impl TestFrameworkSerializableKeyedState {
+impl TestFrameworkSuspendableKeyedState {
     pub fn new() -> Self {
         Self {}
     }
@@ -75,7 +72,7 @@ impl TestFrameworkSerializableKeyedState {
     /// 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: SerializableKeyedState<SERIALIZED_STATE_LEN> + Clone,
+        S: SuspendableKeyed<SERIALIZED_STATE_LEN> + Clone,
     >(
         &self,
         instance: &S,
@@ -89,10 +86,10 @@ impl TestFrameworkSerializableKeyedState {
         let instance_clone = instance.clone();
 
         // You can serialize and then deserialize the state.
-        let serialized_state = instance_clone.serialize_state();
+        let serialized_state = instance_clone.suspend();
         assert_eq!(serialized_state.len(), SERIALIZED_STATE_LEN);
 
-        let _deserialized_state = S::from_serialized_state(serialized_state, key).unwrap();
+        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();
@@ -103,7 +100,7 @@ impl TestFrameworkSerializableKeyedState {
         // 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_serialized_state(ver0_serialized_state, key) {
+        match S::from_suspended(ver0_serialized_state, key) {
             Err(SerializedStateError::IncompatibleVersion) => { /* good */ }
             _ => {
                 panic!("Expected IncompatibleVersion error")
@@ -116,7 +113,7 @@ impl TestFrameworkSerializableKeyedState {
         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_serialized_state(futurever_serialized_state, key) {
+        match S::from_suspended(futurever_serialized_state, key) {
             Err(SerializedStateError::IncompatibleVersion) => { /* good */ }
             _ => {
                 panic!("Expected IncompatibleVersion error")

crypto/core/src/errors.rs

@@ -78,7 +78,7 @@ pub enum SerializedStateError {
     IncompatibleVersion,
     /// The serialized state is malformed or corrupt.
     InvalidData,
-    /// The key supplied to [crate::traits::SerializableKeyedState::from_serialized_state] does not
+    /// The key supplied to [crate::traits::SuspendableKeyed::from_suspended] does not
     /// match the key the state was created with (it is bound to a different public-key hash `tr`).
     IncorrectKey,
 }

crypto/core/src/traits.rs

@@ -488,8 +488,8 @@ pub trait RNG {
 #[allow(drop_bounds)]
 pub trait Secret: Drop + Debug + Display {}
 
-/// Allows a stateful object to serialize its state so that it can be paused and resumed later,
-/// potentially from a different host.
+/// Allows a stateful object to suspend its operation by serializing its state into a byte array
+///so that it can be resumed later, potentially from a different host.
 ///
 /// This is intended for situations where an object is being used through its streaming API
 /// (do_update, do_final) and the operation wants to be paused to a cache, for example while waiting
@@ -499,54 +499,56 @@ pub trait Secret: Drop + Debug + Display {}
 /// will be more straightforward.
 ///
 /// The serialized state MAY contain short-term sensitive values such as nonces or IVs,
-/// but it MUST NOT include a serialized private key. Keyed algorithms MUST instead impl
-/// [SerializableKeyedState] which requires the key to be supplied independently at the time of deserialization.
-pub trait SerializableState<const SERIALIZED_STATE_LEN: usize>: Sized {
-    /// Serialize the state of the object.
+/// but it MUST NOT include a serialized private key.
+/// Keyed algorithms MUST instead impl
+/// [SuspendableKeyed] which requires the key to be supplied independently at the time of deserialization.
+pub trait Suspendable<const SERIALIZED_STATE_LEN: usize>: Sized {
+    /// Suspend operation by serializing out the state of the object.
     ///
     /// Note that this consumes `self` to prevent accidentally continuing to use the object after serialization.
     /// If you want to do this intentionally, then you will need to clone the object before serializing it.
     ///
     /// The serialized state MUST include a prefix indicating the version of the library that serialized it.
-    fn serialize_state(self) -> [u8; SERIALIZED_STATE_LEN];
+    fn suspend(self) -> [u8; SERIALIZED_STATE_LEN];
 
-    /// Create a new object from a serialized state.
+    /// Resume operation from a serialized state.
     ///
     /// Deserializers SHOULD check the version and reject serialized states from incompatible versions
     /// (including rejecting serializations from a future version of the library).
     /// For example, if a given object made a breaking change to its serialization in version 1.2.3, then its
     /// deserializer should reject serialized states from that version or older.
-    fn from_serialized_state(
-        serialized_state: [u8; SERIALIZED_STATE_LEN],
+    fn from_suspended(
+        state: [u8; SERIALIZED_STATE_LEN],
     ) -> Result<Self, SerializedStateError>;
 }
 
-/// Similar to [SerializableState] in that it allows a stateful object to serialize its state so that
-/// it can be paused and resumed later, potentially from a different host.
+/// Similar to [Suspendable] in that it allows a stateful object to suspend its operation by
+/// serializing its state into a byte array so that it can be resumed later, potentially from a different host.
 ///
 /// The difference is that this trait is for keyed algorithms -- MACs, symmetric ciphers, signatures, etc --
-/// which require a private key. For security reasons, the private key is not included in the serialized state
+/// which require a private key in order to resume successfully.
+/// For security reasons, the private key is not included in the serialized state
 /// and must be provided separately as part of the deserialization process.
-pub trait SerializableKeyedState<const SERIALIZED_STATE_LEN: usize>: Sized {
+pub trait SuspendableKeyed<const SERIALIZED_STATE_LEN: usize>: Sized {
     /// The type of key that must be re-supplied to resume this object.
     type Key: ?Sized;
 
-    /// Serialize the state of the object.
+    /// Suspend operation by serializing out the state of the object.
     ///
     /// Note that this consumes `self` to prevent accidentally continuing to use the object after serialization.
     /// If you want to do this intentionally, then you will need to clone the object before serializing it.
     ///
     /// The serialized state MUST include a prefix indicating the version of the library that serialized it.
-    fn serialize_state(self) -> [u8; SERIALIZED_STATE_LEN];
+    fn suspend(self) -> [u8; SERIALIZED_STATE_LEN];
 
-    /// Create a new object from a serialized state.
+    /// Resume operation from a serialized state and the key.
     ///
     /// Deserializers SHOULD check the version and reject serialized states from incompatible versions
     /// (including rejecting serializations from a future version of the library).
     /// For example, if a given object made a breaking change to its serialization in version 1.2.3, then its
     /// deserializer should reject serialized states from that version or older.
-    fn from_serialized_state(
-        serialized_state: [u8; SERIALIZED_STATE_LEN],
+    fn from_suspended(
+        state: [u8; SERIALIZED_STATE_LEN],
         key: &Self::Key,
     ) -> Result<Self, SerializedStateError>;
 }