crypto-common: Generate trait

Replaces all of the previous RNG functionality with a `Generate` trait
which has the same basic shape as the existing methods, but allows types
to impl only `try_from_rng` and receive provided versions of all of the
other methods:

- `generate`: infallible generation using system RNG with panic on error
- `try_generate`: fallible version of above with RNG error `Result`s
- `from_rng`: infallible generation with RNG parameter that panics on
  error

The `generate` and `try_generate` methods are available when the
`getrandom` feature is enabled.

Impls are provided for `hybrid_array::Array<u8, U>`.

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();

The trait is also intended to be impl'd by consuming crates for other
key generation use cases, e.g. `RsaPrivateKey`, `dsa::SigningKey`,
`ecdsa::SigningKey`, or KEM decapsulation keys.

Author: tarcieri

crypto-common/Cargo.toml

@@ -20,7 +20,7 @@ getrandom = { version = "0.3", optional = true, default-features = false }
 rand_core = { version = "0.10.0-rc-2", optional = true }
 
 [features]
-getrandom = ["dep:getrandom"]
+getrandom = ["rand_core", "dep:getrandom"]
 rand_core = ["dep:rand_core"]
 zeroize = ["hybrid-array/zeroize"]
 

crypto-common/src/generate.rs

@@ -0,0 +1,89 @@
+use hybrid_array::{Array, ArraySize};
+use rand_core::{CryptoRng, TryCryptoRng};
+
+#[cfg(feature = "getrandom")]
+mod sys_rng;
+
+#[cfg(feature = "getrandom")]
+pub use sys_rng::RngError;
+
+/// 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.
+    #[cfg(feature = "getrandom")]
+    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.
+    #[cfg(feature = "getrandom")]
+    fn try_generate() -> Result<Self, RngError> {
+        Self::try_from_rng(&mut sys_rng::SysRng)
+    }
+
+    /// 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 Generate for u32 {
+    #[inline]
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        rng.try_next_u32()
+    }
+}
+
+impl Generate for u64 {
+    #[inline]
+    fn try_from_rng<R: TryCryptoRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error> {
+        rng.try_next_u64()
+    }
+}
+
+impl<const N: usize> Generate for [u8; N] {
+    #[inline]
+    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> Generate for Array<u8, U> {
+    #[inline]
+    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> Generate for Array<u32, U> {
+    #[inline]
+    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> Generate for Array<u64, U> {
+    #[inline]
+    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/sys_rng.rs

@@ -0,0 +1,42 @@
+use core::fmt;
+use rand_core::{TryCryptoRng, TryRngCore};
+
+/// An RNG over the operating-system's random data source
+// TODO(tarcieri): replace this with `SysRng` from `getrandom` when a v0.4 prerelease is available
+#[derive(Clone, Copy, Debug, Default)]
+pub(crate) struct SysRng;
+
+impl TryRngCore for SysRng {
+    type Error = RngError;
+
+    #[inline]
+    fn try_next_u32(&mut self) -> Result<u32, RngError> {
+        getrandom::u32().map_err(RngError)
+    }
+
+    #[inline]
+    fn try_next_u64(&mut self) -> Result<u64, RngError> {
+        getrandom::u64().map_err(RngError)
+    }
+
+    #[inline]
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), RngError> {
+        getrandom::fill(dest).map_err(RngError)
+    }
+}
+
+impl TryCryptoRng for SysRng {}
+
+/// Errors occurring internally within the system's ambient cryptographically secure RNG.
+// TODO(tarcieri): switch to `getrandom::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 {}

crypto-common/src/lib.rs

@@ -12,11 +12,15 @@
 /// Hazardous materials.
 pub mod hazmat;
 
-#[cfg(feature = "getrandom")]
-pub use getrandom;
+/// Secure random generation using the system's ambient RNG
+#[cfg(feature = "rand_core")]
+mod generate;
 
 #[cfg(feature = "rand_core")]
-pub use rand_core;
+pub use {generate::Generate, rand_core};
+
+#[cfg(feature = "getrandom")]
+pub use {generate::RngError, getrandom};
 
 pub use hybrid_array as array;
 pub use hybrid_array::typenum;
@@ -27,9 +31,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 +179,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 +206,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 +230,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.