Propagate random bits generation errors through the hazmat level

fjarri · fjarri · commit 0f9dd03609c0 · 2025-03-16T13:01:14.000-07:00
diff --git a/src/error.rs b/src/error.rs
@@ -0,0 +1,31 @@
+use core::fmt;
+
+/// Errors returned by the crate's API.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Error {
+    /// The requested bit length of the candidate is larger than the maximum size of the target integer type.
+    BitLengthTooLarge {
+        /// The requested bit length.
+        bit_length: u32,
+        /// The maximum size of the integer type.
+        bits_precision: u32,
+    },
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
+        match self {
+            Error::BitLengthTooLarge {
+                bit_length,
+                bits_precision,
+            } => write!(
+                f,
+                concat![
+                    "The requested bit length of the candidate ({}) ",
+                    "is larger than the maximum size of the target integer type ({})."
+                ],
+                bit_length, bits_precision
+            ),
+        }
+    }
+}
diff --git a/src/generic.rs b/src/generic.rs
@@ -1,6 +1,6 @@
 use rand_core::CryptoRng;
 
-use crate::hazmat::SieveFactory;
+use crate::{hazmat::SieveFactory, Error};
 
 /// Sieves through the results of `sieve_factory` and returns the first item for which `predicate` is `true`.
 ///
@@ -9,7 +9,7 @@ pub fn sieve_and_find<R, S>(
     rng: &mut R,
     sieve_factory: S,
     predicate: impl Fn(&mut R, &S::Item) -> bool,
-) -> Option<S::Item>
+) -> Result<Option<S::Item>, Error>
 where
     S: SieveFactory,
     R: CryptoRng + ?Sized,
@@ -18,16 +18,19 @@ where
     // Unlike the parallel version, it is avoidable here.
 
     let mut sieve_factory = sieve_factory;
-    let mut sieve = sieve_factory.make_sieve(rng, None)?;
+    let mut sieve = match sieve_factory.make_sieve(rng, None)? {
+        Some(sieve) => sieve,
+        None => return Ok(None),
+    };
 
     loop {
         if let Some(value) = sieve.find(|num| predicate(rng, num)) {
-            return Some(value);
+            return Ok(Some(value));
         }
-        if let Some(new_sieve) = sieve_factory.make_sieve(rng, Some(&sieve)) {
+        if let Some(new_sieve) = sieve_factory.make_sieve(rng, Some(&sieve))? {
             sieve = new_sieve;
         } else {
-            return None;
+            return Ok(None);
         }
     }
 }
@@ -37,7 +40,7 @@ mod tests {
     use rand_core::{CryptoRng, OsRng, TryRngCore};
 
     use super::sieve_and_find;
-    use crate::hazmat::SieveFactory;
+    use crate::{hazmat::SieveFactory, Error};
 
     #[test]
     fn test_exhaustable_sieve_factory() {
@@ -54,22 +57,22 @@ mod tests {
                 &mut self,
                 _rng: &mut R,
                 previous_sieve: Option<&Self::Sieve>,
-            ) -> Option<Self::Sieve> {
+            ) -> Result<Option<Self::Sieve>, Error> {
                 self.count += 1;
                 if previous_sieve.is_none() {
-                    Some(self.count * 10..(self.count * 10 + 2))
+                    Ok(Some(self.count * 10..(self.count * 10 + 2)))
                 } else {
-                    None
+                    Ok(None)
                 }
             }
         }
 
         let factory = TestSieveFactory { count: 0 };
         let result = sieve_and_find(&mut OsRng.unwrap_mut(), factory, |_rng, num| *num == 11);
-        assert!(result.is_some());
+        assert!(result.unwrap().is_some());
 
         let factory = TestSieveFactory { count: 0 };
         let result = sieve_and_find(&mut OsRng.unwrap_mut(), factory, |_rng, num| *num == 20);
-        assert!(result.is_none());
+        assert!(result.unwrap().is_none());
     }
 }
diff --git a/src/hazmat/sieve.rs b/src/hazmat/sieve.rs
@@ -6,10 +6,10 @@ use core::marker::PhantomData;
 use core::num::{NonZero, NonZeroU32};
 
 use crypto_bigint::{Integer, Odd, RandomBits, RandomBitsError};
-use rand_core::{CryptoRng, TryCryptoRng};
+use rand_core::CryptoRng;
 
-use crate::hazmat::precomputed::{SmallPrime, LAST_SMALL_PRIME, RECIPROCALS, SMALL_PRIMES};
-use crate::presets::Flavor;
+use super::precomputed::{SmallPrime, LAST_SMALL_PRIME, RECIPROCALS, SMALL_PRIMES};
+use crate::{error::Error, presets::Flavor};
 
 /// Decide how prime candidates are manipulated by setting certain bits before primality testing,
 /// influencing the range of the prime.
@@ -33,18 +33,26 @@ pub enum SetBits {
 ///
 /// Returns an error variant if `bit_length` is greater than the maximum allowed for `T`
 /// (applies to fixed-length types).
-pub fn random_odd_integer<T, R>(
-    rng: &mut R,
-    bit_length: NonZeroU32,
-    set_bits: SetBits,
-) -> Result<Odd<T>, RandomBitsError<R::Error>>
+pub fn random_odd_integer<T, R>(rng: &mut R, bit_length: NonZeroU32, set_bits: SetBits) -> Result<Odd<T>, Error>
 where
     T: Integer + RandomBits,
-    R: TryCryptoRng + ?Sized,
+    R: CryptoRng + ?Sized,
 {
     let bit_length = bit_length.get();
 
-    let mut random = T::try_random_bits(rng, bit_length)?;
+    let mut random = T::try_random_bits(rng, bit_length).map_err(|err| match err {
+        RandomBitsError::RandCore(_) => unreachable!("`rng` impls `CryptoRng` and therefore is infallible"),
+        RandomBitsError::BitsPrecisionMismatch { .. } => {
+            unreachable!("we are not requesting a specific `bits_precision`")
+        }
+        RandomBitsError::BitLengthTooLarge {
+            bit_length,
+            bits_precision,
+        } => Error::BitLengthTooLarge {
+            bit_length,
+            bits_precision,
+        },
+    })?;
 
     // Make it odd
     // `bit_length` is non-zero, so the 0-th bit exists.
@@ -302,11 +310,13 @@ pub trait SieveFactory {
     /// Makes a sieve given an RNG and the previous exhausted sieve (if any).
     ///
     /// Returning `None` signals that the prime generation should stop.
-    fn make_sieve<R: CryptoRng + ?Sized>(
+    fn make_sieve<R>(
         &mut self,
         rng: &mut R,
         previous_sieve: Option<&Self::Sieve>,
-    ) -> Option<Self::Sieve>;
+    ) -> Result<Option<Self::Sieve>, Error>
+    where
+        R: CryptoRng + ?Sized;
 }
 
 /// A sieve returning numbers that are not multiples of a set of small factors.
@@ -366,18 +376,20 @@ where
 {
     type Item = T;
     type Sieve = SmallPrimesSieve<T>;
-    fn make_sieve<R: CryptoRng + ?Sized>(
+    fn make_sieve<R>(
         &mut self,
         rng: &mut R,
         _previous_sieve: Option<&Self::Sieve>,
-    ) -> Option<Self::Sieve> {
-        let start =
-            random_odd_integer::<T, _>(rng, self.max_bit_length, self.set_bits).expect("random_odd_integer() failed");
-        Some(SmallPrimesSieve::new(
+    ) -> Result<Option<Self::Sieve>, Error>
+    where
+        R: CryptoRng + ?Sized,
+    {
+        let start = random_odd_integer::<T, _>(rng, self.max_bit_length, self.set_bits)?;
+        Ok(Some(SmallPrimesSieve::new(
             start.get(),
             self.max_bit_length,
             self.safe_primes,
-        ))
+        )))
     }
 }
 
@@ -391,7 +403,7 @@ mod tests {
     use crypto_bigint::U64;
     use num_prime::nt_funcs::factorize64;
     use rand_chacha::ChaCha8Rng;
-    use rand_core::{OsRng, SeedableRng};
+    use rand_core::{OsRng, SeedableRng, TryRngCore};
 
     use super::{random_odd_integer, SetBits, SmallPrimesSieve, SmallPrimesSieveFactory};
     use crate::{hazmat::precomputed::SMALL_PRIMES, Flavor};
@@ -500,7 +512,7 @@ mod tests {
     #[test]
     fn random_below_max_length() {
         for _ in 0..10 {
-            let r = random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(50).unwrap(), SetBits::Msb)
+            let r = random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(50).unwrap(), SetBits::Msb)
                 .unwrap()
                 .get();
             assert_eq!(r.bits(), 50);
@@ -509,7 +521,9 @@ mod tests {
 
     #[test]
     fn random_odd_uint_too_many_bits() {
-        assert!(random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(65).unwrap(), SetBits::Msb).is_err());
+        assert!(
+            random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(65).unwrap(), SetBits::Msb).is_err()
+        );
     }
 
     #[test]
@@ -549,27 +563,31 @@ mod tests {
     #[test]
     fn set_bits() {
         for _ in 0..10 {
-            let x = random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(64).unwrap(), SetBits::Msb).unwrap();
+            let x =
+                random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(64).unwrap(), SetBits::Msb).unwrap();
             assert!(bool::from(x.bit(63)));
         }
 
         for _ in 0..10 {
-            let x = random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(64).unwrap(), SetBits::TwoMsb).unwrap();
+            let x = random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(64).unwrap(), SetBits::TwoMsb)
+                .unwrap();
             assert!(bool::from(x.bit(63)));
             assert!(bool::from(x.bit(62)));
         }
 
         // 1 in 2^30 chance of spurious failure... good enough?
         assert!((0..30)
-            .map(|_| { random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(64).unwrap(), SetBits::None).unwrap() })
+            .map(|_| {
+                random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(64).unwrap(), SetBits::None).unwrap()
+            })
             .any(|x| !bool::from(x.bit(63))));
     }
 
     #[test]
     fn set_two_msb_small_bit_length() {
         // Check that when technically there isn't a second most significant bit,
         // `random_odd_integer()` still returns a number.
-        let x = random_odd_integer::<U64, _>(&mut OsRng, NonZero::new(1).unwrap(), SetBits::TwoMsb)
+        let x = random_odd_integer::<U64, _>(&mut OsRng.unwrap_mut(), NonZero::new(1).unwrap(), SetBits::TwoMsb)
             .unwrap()
             .get();
         assert_eq!(x, U64::ONE);
diff --git a/src/lib.rs b/src/lib.rs
@@ -16,12 +16,14 @@
 
 extern crate alloc;
 
+mod error;
 mod generic;
 pub mod hazmat;
 mod presets;
 
 #[cfg(feature = "multicore")]
 pub mod multicore;
 
+pub use error::Error;
 pub use generic::sieve_and_find;
 pub use presets::{fips_is_prime, is_prime, random_prime, Flavor};
diff --git a/src/multicore.rs b/src/multicore.rs
@@ -5,6 +5,7 @@ use rand_core::CryptoRng;
 use rayon::iter::{ParallelBridge, ParallelIterator};
 
 use crate::{
+    error::Error,
     hazmat::{SetBits, SieveFactory, SmallPrimesSieveFactory},
     presets::{is_prime, Flavor},
 };
@@ -13,7 +14,12 @@ use crate::{
 /// and returns the first item for which `predicate` is `true`.
 ///
 /// If `sieve_factory` signals that no more results can be created, returns `None`.
-pub fn sieve_and_find<R, S, F>(rng: &mut R, sieve_factory: S, predicate: F, threadcount: usize) -> Option<S::Item>
+pub fn sieve_and_find<R, S, F>(
+    rng: &mut R,
+    sieve_factory: S,
+    predicate: F,
+    threadcount: usize,
+) -> Result<Option<S::Item>, Error>
 where
     R: CryptoRng + Clone + Send + Sync,
     S: Send + Sync + SieveFactory,
@@ -27,13 +33,16 @@ where
         .expect("If the platform can spawn threads, then this call will work.");
 
     let mut iter_rng = rng.clone();
-    let iter = SieveIterator::new(&mut iter_rng, sieve_factory)?;
+    let iter = match SieveIterator::new(&mut iter_rng, sieve_factory)? {
+        Some(iter) => iter,
+        None => return Ok(None),
+    };
 
     threadpool.install(|| {
-        iter.par_bridge().find_any(|c| {
+        Ok(iter.par_bridge().find_any(|c| {
             let mut rng = rng.clone();
             predicate(&mut rng, c)
-        })
+        }))
     })
 }
 
@@ -52,14 +61,17 @@ where
     S: SieveFactory,
 {
     /// Creates a new chained iterator producing results from sieves returned from `sieve_factory`.
-    pub fn new(rng: &'a mut R, sieve_factory: S) -> Option<Self> {
+    pub fn new(rng: &'a mut R, sieve_factory: S) -> Result<Option<Self>, Error> {
         let mut sieve_factory = sieve_factory;
-        let sieve = sieve_factory.make_sieve(rng, None)?;
-        Some(Self {
+        let sieve = match sieve_factory.make_sieve(rng, None)? {
+            Some(sieve) => sieve,
+            None => return Ok(None),
+        };
+        Ok(Some(Self {
             sieve_factory,
             rng,
             sieve,
-        })
+        }))
     }
 }
 
@@ -76,7 +88,10 @@ where
                 return Some(result);
             }
 
-            self.sieve = self.sieve_factory.make_sieve(self.rng, Some(&self.sieve))?;
+            self.sieve = self
+                .sieve_factory
+                .make_sieve(self.rng, Some(&self.sieve))
+                .expect("the first attempt to make a sieve succeeded, so the next ones should too")?;
         }
     }
 }
@@ -99,6 +114,7 @@ where
         |_rng, candidate| is_prime(flavor, candidate),
         threadcount,
     )
+    .unwrap_or_else(|err| panic!("Error generating random candidates: {}", err))
     .expect("will produce a result eventually")
 }
 
diff --git a/src/presets.rs b/src/presets.rs
