New feature: Suspendable (serializable state)

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;

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;

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;

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;

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;

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;

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;

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;