crypto-bigint: add rand feature (#508)

Adds initial support for random number generation, for both `UInt` and
`Limb`.

Also adds a `UInt::random_mod` function which generates a random number
within the range of a provided modulus using rejection sampling.

crypto-bigint/Cargo.toml

@@ -17,13 +17,18 @@ readme = "README.md"
 [dependencies]
 generic-array = { version = "0.14", optional = true }
 subtle = { version = "2.4", default-features = false }
+
+# optional dependencies
+rand_core = { version = "0.6", optional = true }
 zeroize = { version = "1", optional = true,  default-features = false }
 
 [dev-dependencies]
 hex-literal = "0.3"
 
 [features]
+default = ["rand"]
 alloc = []
+rand = ["rand_core"]
 
 [package.metadata.docs.rs]
 all-features = true

crypto-bigint/src/limb.rs

@@ -7,6 +7,9 @@ mod from;
 mod mul;
 mod sub;
 
+#[cfg(feature = "rand")]
+mod rand;
+
 use core::fmt;
 use subtle::{Choice, ConditionallySelectable};
 

crypto-bigint/src/limb/rand.rs

@@ -0,0 +1,20 @@
+//! Random number generator support
+
+use super::Limb;
+use rand_core::{CryptoRng, RngCore};
+
+impl Limb {
+    /// Generate a random limb
+    #[cfg(target_pointer_width = "32")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "rand")))]
+    pub fn random(mut rng: impl CryptoRng + RngCore) -> Self {
+        Self(rng.next_u32())
+    }
+
+    /// Generate a random limb
+    #[cfg(target_pointer_width = "64")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "rand")))]
+    pub fn random(mut rng: impl CryptoRng + RngCore) -> Self {
+        Self(rng.next_u64())
+    }
+}

crypto-bigint/src/uint.rs

@@ -15,6 +15,9 @@ mod sub;
 #[cfg(feature = "generic-array")]
 mod array;
 
+#[cfg(feature = "rand")]
+mod rand;
+
 use crate::{Concat, Encoding, Limb, Split};
 use core::fmt;
 use subtle::{Choice, ConditionallySelectable};

crypto-bigint/src/uint/rand.rs

@@ -0,0 +1,41 @@
+//! Random number generator support
+
+use super::UInt;
+use crate::Limb;
+use rand_core::{CryptoRng, RngCore};
+use subtle::ConstantTimeLess;
+
+#[cfg_attr(docsrs, doc(cfg(feature = "rand")))]
+impl<const LIMBS: usize> UInt<LIMBS> {
+    /// Generate a cryptographically secure random [`UInt`].
+    pub fn random(mut rng: impl CryptoRng + RngCore) -> Self {
+        let mut limbs = [Limb::default(); LIMBS];
+
+        for limb in &mut limbs {
+            *limb = Limb::random(&mut rng)
+        }
+
+        limbs.into()
+    }
+
+    /// Generate a cryptographically secure random [`UInt`] which is less than
+    /// a given `modulus`.
+    ///
+    /// This function uses rejection sampling, a method which produces an
+    /// unbiased distribution of in-range values provided the underlying
+    /// [`CryptoRng`] is unbiased, but runs in variable-time.
+    ///
+    /// The variable-time nature of the algorithm should not pose a security
+    /// issue so long as the underlying random number generator is truly a
+    /// [`CryptoRng`], where previous outputs are unrelated to subsequent
+    /// outputs and do not reveal information about the RNG's internal state.
+    pub fn random_mod(mut rng: impl CryptoRng + RngCore, modulus: &Self) -> Self {
+        loop {
+            let n = Self::random(&mut rng);
+
+            if n.ct_lt(&modulus).into() {
+                return n;
+            }
+        }
+    }
+}