crypto-common: FromRng and Generate traits

Replaces all of the previous RNG functionality with traits which map to
either a parameterized RNG (using traits from `rand_core`) or the
system's ambient RNG (using `getrandom`).

Both traits support fallible and infallible operation, with the
infallible version provided by the trait.

We had previously discussed putting something like this in
`hybrid-array`, but I opted not to for a few reasons:

1. Ideally we'd get rid of `hybrid-array` and switch to sufficiently
   powerful const generics instead, so really it's better if it doesn't
   have functionality that's equivalent to core arrays
2. Having traits provides a common API for random generation which is
   reusable across many different types. This implementation provides
   impls for `hybrid-array` (for `u8`, `u32`, and `u64`), but also core
   arrays of `[u8; N]` and the core `u32` and `u64` types.
3. The traits are further reusable for a whole host of types in
   consuming crates, notably `SecretKey`/`SigningKey` types, or KEM
   decapsulation keys.

With this approach we can generate things like symmetric keys and IVs
like:

    type Aes256CbcEnc = cbc::Encryptor<aes::Aes256>;
    let key = Key::<Aes256CbcEnc>::generate();
    let iv = Iv::<Aes256CbcEnc>::generate();

Author: tarcieri

crypto-common/src/from_crypto_rng.rs

@@ -0,0 +1,54 @@
+use hybrid_array::{Array, ArraySize};
+use rand_core::{CryptoRng, TryCryptoRng};
+
+/// Secure random generation using a provided RNG which impls traits from the [`rand_core`] crate.
+pub trait FromCryptoRng: Sized {
+    /// Generate random key using the provided [`CryptoRng`].
+    fn from_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Self {
+        let Ok(ret) = Self::try_from_rng(rng);
+        ret
+    }
+
+    /// Generate random key using the provided [`TryCryptoRng`].
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error>;
+}
+
+impl FromCryptoRng for u32 {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        rng.try_next_u32()
+    }
+}
+
+impl FromCryptoRng for u64 {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        rng.try_next_u64()
+    }
+}
+
+impl<const N: usize> FromCryptoRng for [u8; N] {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        let mut ret = [0u8; N];
+        rng.try_fill_bytes(&mut ret)?;
+        Ok(ret)
+    }
+}
+
+impl<U: ArraySize> FromCryptoRng for Array<u8, U> {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        let mut ret = Self::default();
+        rng.try_fill_bytes(&mut ret)?;
+        Ok(ret)
+    }
+}
+
+impl<U: ArraySize> FromCryptoRng for Array<u32, U> {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        Self::try_from_fn(|_| rng.try_next_u32())
+    }
+}
+
+impl<U: ArraySize> FromCryptoRng for Array<u64, U> {
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        Self::try_from_fn(|_| rng.try_next_u64())
+    }
+}

crypto-common/src/generate.rs

@@ -0,0 +1,78 @@
+use core::fmt;
+use hybrid_array::{Array, ArraySize};
+
+/// Secure random generation using the system's ambient RNG.
+pub trait Generate: Sized {
+    /// Randomly generate a value of this type using the system's ambient cryptographically secure
+    /// random number generator.
+    ///
+    /// # Panics
+    /// This method will panic in the event the system's ambient RNG experiences an internal
+    /// failure.
+    ///
+    /// This shouldn't happen on most modern operating systems.
+    fn generate() -> Self {
+        Self::try_generate().expect("RNG failure")
+    }
+
+    /// Randomly generate a value of this type using the system's ambient cryptographically secure
+    /// random number generator.
+    ///
+    /// # Errors
+    /// Returns [`RngError`] in the event the system's ambient RNG experiences an internal failure.
+    fn try_generate() -> Result<Self, RngError>;
+}
+
+/// Errors occurring internally within the system's ambient cryptographically secure RNG.
+// TODO(tarcieri): switch to `getrandom::Error` when it impls `core::error::Error`?
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct RngError(getrandom::Error);
+
+impl fmt::Display for RngError {
+    #[inline]
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
+        write!(f, "{}", &self.0)
+    }
+}
+
+impl core::error::Error for RngError {}
+
+impl Generate for u32 {
+    fn try_generate() -> Result<Self, RngError> {
+        getrandom::u32().map_err(RngError)
+    }
+}
+
+impl Generate for u64 {
+    fn try_generate() -> Result<Self, RngError> {
+        getrandom::u64().map_err(RngError)
+    }
+}
+
+impl<const N: usize> Generate for [u8; N] {
+    fn try_generate() -> Result<Self, RngError> {
+        let mut ret = [0u8; N];
+        getrandom::fill(&mut ret).map_err(RngError)?;
+        Ok(ret)
+    }
+}
+
+impl<U: ArraySize> Generate for Array<u8, U> {
+    fn try_generate() -> Result<Self, RngError> {
+        let mut ret = Self::default();
+        getrandom::fill(&mut ret).map_err(RngError)?;
+        Ok(ret)
+    }
+}
+
+impl<U: ArraySize> Generate for Array<u32, U> {
+    fn try_generate() -> Result<Self, RngError> {
+        Self::try_from_fn(|_| u32::try_generate())
+    }
+}
+
+impl<U: ArraySize> Generate for Array<u64, U> {
+    fn try_generate() -> Result<Self, RngError> {
+        Self::try_from_fn(|_| u64::try_generate())
+    }
+}

crypto-common/src/lib.rs

@@ -12,11 +12,21 @@
 /// Hazardous materials.
 pub mod hazmat;
 
+/// Secure random generation using a provided RNG
+#[cfg(feature = "rand_core")]
+mod from_crypto_rng;
+
+/// Secure random generation using the system's ambient RNG
 #[cfg(feature = "getrandom")]
-pub use getrandom;
+mod generate;
 
 #[cfg(feature = "rand_core")]
-pub use rand_core;
+pub use {from_crypto_rng::FromCryptoRng, rand_core};
+#[cfg(feature = "getrandom")]
+pub use {
+    generate::{Generate, RngError},
+    getrandom,
+};
 
 pub use hybrid_array as array;
 pub use hybrid_array::typenum;
@@ -27,9 +37,6 @@ use hybrid_array::{
     typenum::{Diff, Sum, Unsigned},
 };
 
-#[cfg(feature = "rand_core")]
-use rand_core::{CryptoRng, TryCryptoRng};
-
 /// Block on which [`BlockSizeUser`] implementors operate.
 pub type Block<B> = Array<u8, <B as BlockSizeUser>::BlockSize>;
 
@@ -178,35 +185,6 @@ pub trait KeyInit: KeySizeUser + Sized {
             .map(Self::new)
             .map_err(|_| InvalidLength)
     }
-
-    /// Generate random key using the operating system's secure RNG.
-    #[cfg(feature = "getrandom")]
-    #[inline]
-    fn generate_key() -> Result<Key<Self>, getrandom::Error> {
-        let mut key = Key::<Self>::default();
-        getrandom::fill(&mut key)?;
-        Ok(key)
-    }
-
-    /// Generate random key using the provided [`CryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn generate_key_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Key<Self> {
-        let mut key = Key::<Self>::default();
-        rng.fill_bytes(&mut key);
-        key
-    }
-
-    /// Generate random key using the provided [`TryCryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn try_generate_key_with_rng<R: TryCryptoRng + ?Sized>(
-        rng: &mut R,
-    ) -> Result<Key<Self>, R::Error> {
-        let mut key = Key::<Self>::default();
-        rng.try_fill_bytes(&mut key)?;
-        Ok(key)
-    }
 }
 
 /// Types which can be initialized from key and initialization vector (nonce).
@@ -234,93 +212,6 @@ pub trait KeyIvInit: KeySizeUser + IvSizeUser + Sized {
         let iv = <&Iv<Self>>::try_from(iv).map_err(|_| InvalidLength)?;
         Ok(Self::new(key, iv))
     }
-
-    /// Generate random key using the operating system's secure RNG.
-    #[cfg(feature = "getrandom")]
-    #[inline]
-    fn generate_key() -> Result<Key<Self>, getrandom::Error> {
-        let mut key = Key::<Self>::default();
-        getrandom::fill(&mut key)?;
-        Ok(key)
-    }
-
-    /// Generate random key using the provided [`CryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn generate_key_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Key<Self> {
-        let mut key = Key::<Self>::default();
-        rng.fill_bytes(&mut key);
-        key
-    }
-
-    /// Generate random key using the provided [`TryCryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn try_generate_key_with_rng<R: TryCryptoRng + ?Sized>(
-        rng: &mut R,
-    ) -> Result<Key<Self>, R::Error> {
-        let mut key = Key::<Self>::default();
-        rng.try_fill_bytes(&mut key)?;
-        Ok(key)
-    }
-
-    /// Generate random IV using the operating system's secure RNG.
-    #[cfg(feature = "getrandom")]
-    #[inline]
-    fn generate_iv() -> Result<Iv<Self>, getrandom::Error> {
-        let mut iv = Iv::<Self>::default();
-        getrandom::fill(&mut iv)?;
-        Ok(iv)
-    }
-
-    /// Generate random IV using the provided [`CryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn generate_iv_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Iv<Self> {
-        let mut iv = Iv::<Self>::default();
-        rng.fill_bytes(&mut iv);
-        iv
-    }
-
-    /// Generate random IV using the provided [`TryCryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn try_generate_iv_with_rng<R: TryCryptoRng + ?Sized>(
-        rng: &mut R,
-    ) -> Result<Iv<Self>, R::Error> {
-        let mut iv = Iv::<Self>::default();
-        rng.try_fill_bytes(&mut iv)?;
-        Ok(iv)
-    }
-
-    /// Generate random key and IV using the operating system's secure RNG.
-    #[cfg(feature = "getrandom")]
-    #[inline]
-    fn generate_key_iv() -> Result<(Key<Self>, Iv<Self>), getrandom::Error> {
-        let key = Self::generate_key()?;
-        let iv = Self::generate_iv()?;
-        Ok((key, iv))
-    }
-
-    /// Generate random key and IV using the provided [`CryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn generate_key_iv_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> (Key<Self>, Iv<Self>) {
-        let key = Self::generate_key_with_rng(rng);
-        let iv = Self::generate_iv_with_rng(rng);
-        (key, iv)
-    }
-
-    /// Generate random key and IV using the provided [`TryCryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn try_generate_key_iv_with_rng<R: TryCryptoRng + ?Sized>(
-        rng: &mut R,
-    ) -> Result<(Key<Self>, Iv<Self>), R::Error> {
-        let key = Self::try_generate_key_with_rng(rng)?;
-        let iv = Self::try_generate_iv_with_rng(rng)?;
-        Ok((key, iv))
-    }
 }
 
 /// Types which can be initialized from another type (usually block ciphers).
@@ -345,35 +236,6 @@ pub trait InnerIvInit: InnerUser + IvSizeUser + Sized {
         let iv = <&Iv<Self>>::try_from(iv).map_err(|_| InvalidLength)?;
         Ok(Self::inner_iv_init(inner, iv))
     }
-
-    /// Generate random IV using the operating system's secure RNG.
-    #[cfg(feature = "getrandom")]
-    #[inline]
-    fn generate_iv() -> Result<Iv<Self>, getrandom::Error> {
-        let mut iv = Iv::<Self>::default();
-        getrandom::fill(&mut iv)?;
-        Ok(iv)
-    }
-
-    /// Generate random IV using the provided [`CryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn generate_iv_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Iv<Self> {
-        let mut iv = Iv::<Self>::default();
-        rng.fill_bytes(&mut iv);
-        iv
-    }
-
-    /// Generate random IV using the provided [`TryCryptoRng`].
-    #[cfg(feature = "rand_core")]
-    #[inline]
-    fn try_generate_iv_with_rng<R: TryCryptoRng + ?Sized>(
-        rng: &mut R,
-    ) -> Result<Iv<Self>, R::Error> {
-        let mut iv = Iv::<Self>::default();
-        rng.try_fill_bytes(&mut iv)?;
-        Ok(iv)
-    }
 }
 
 /// Trait for loading current IV state.