Merge pull request #43 from entropyxyz/dp-misc-doc-tweaks

Misc tweaks

Cargo.toml

@@ -13,7 +13,7 @@ rust-version = "1.73"
 crypto-bigint = { version = "0.6.0-pre.7", default-features = false, features = ["rand_core"] }
 rand_core = { version = "0.6.4", default-features = false }
 openssl = { version = "0.10.39", optional = true, features = ["vendored"] }
-rug = { version = "1.18", default-features = false, features = ["integer"], optional = true }
+rug = { version = "1.26", default-features = false, features = ["integer"], optional = true }
 
 [dev-dependencies]
 # need `crypto-bigint` with `alloc` to test `BoxedUint`
@@ -30,7 +30,7 @@ num-prime = "0.4.3"
 default = ["default-rng"]
 default-rng = ["rand_core/getrandom"]
 tests-openssl = ["openssl"]
-tests-gmp = ["rug"]
+tests-gmp = ["rug/std"]
 tests-exhaustive = []
 tests-all = ["tests-openssl", "tests-gmp", "tests-exhaustive"]
 

clippy.toml

@@ -0,0 +1 @@
+allow-unwrap-in-tests = true

src/hazmat/lucas.rs

@@ -211,6 +211,7 @@ pub enum LucasCheck {
     /// If either of the following is true:
     /// - any of `V(d*2^r) == 0` for `0 <= r < s`,
     /// - `U(d) == 0`,
+    ///
     /// report the number as prime.
     ///
     /// If the base is [`SelfridgeBase`], known false positives constitute OEIS:A217255[^A217255].
@@ -228,6 +229,7 @@ pub enum LucasCheck {
     /// That is, if either of the following is true:
     /// - any of `V(d*2^r) == 0` for `0 <= r < s`,
     /// - `V(d) == ±2`,
+    ///
     /// report the number as prime.
     ///
     /// Note: the second condition is only checked if `Q == 1`,
@@ -248,6 +250,7 @@ pub enum LucasCheck {
     /// If either of the following is true:
     /// - any of `V(d*2^r) == 0` for `0 <= r < s`,
     /// - `U(d) == 0` and `V(d) == ±2`,
+    ///
     /// report the number as prime.
     ///
     /// Note that this check only differs from [`LucasCheck::Strong`] if `Q == 1`.

src/hazmat/miller_rabin.rs

@@ -6,6 +6,7 @@ use rand_core::CryptoRngCore;
 use super::Primality;
 
 /// Precomputed data used to perform Miller-Rabin primality test[^Pomerance1980].
+///
 /// The numbers that pass it are commonly called "strong probable primes"
 /// (or "strong pseudoprimes" if they are, in fact, composite).
 ///

src/hazmat/primes.rs

@@ -223,10 +223,9 @@ pub(crate) const PRIMES_1024: &[U1024] = &[
     ]),
 ];
 
-// A Cunningham chain (of the first kind) is a sequence of `k` numbers
-// such that `n_{k+1} = n{k} * 2 + 1`, and each `n_k` is prime.
-// We provide pairs `(k, n_0)` here.
-
+/// A Cunningham chain (of the first kind) is a sequence of `k` numbers
+/// such that `n_{k+1} = n_k * 2 + 1`, and each `n_k` is prime.
+/// We provide pairs `(k, n_0)` here.
 pub(crate) const CUNNINGHAM_CHAINS_128: &[(usize, U128)] = &[
     (17, U128::from_be_hex("00000000000000959c603768458440ef")),
     (16, U128::from_be_hex("0000000000001355a29aa8a1159d827f")),

src/lib.rs

@@ -10,7 +10,8 @@
     rust_2018_idioms,
     trivial_casts,
     trivial_numeric_casts,
-    unused_qualifications
+    unused_qualifications,
+    clippy::unwrap_used
 )]
 
 extern crate alloc;

src/presets.rs

@@ -11,7 +11,6 @@ use crate::hazmat::{
 };
 
 /// Returns a random prime of size `bit_length` using [`OsRng`] as the RNG.
-/// If `bit_length` is `None`, the full size of `Uint<L>` is used.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
@@ -22,9 +21,8 @@ pub fn generate_prime<T: Integer + RandomBits + RandomMod>(
     generate_prime_with_rng(&mut OsRng, bit_length, bits_precision)
 }
 
-/// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime)
-/// of size `bit_length` using [`OsRng`] as the RNG.
-/// If `bit_length` is `None`, the full size of `Uint<L>` is used.
+/// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime) of size
+/// `bit_length` using [`OsRng`] as the RNG.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
@@ -35,17 +33,16 @@ pub fn generate_safe_prime<T: Integer + RandomBits + RandomMod>(
     generate_safe_prime_with_rng(&mut OsRng, bit_length, bits_precision)
 }
 
-/// Checks probabilistically if the given number is prime using [`OsRng`] as the RNG.
+/// Probabilistically checks if the given number is prime using [`OsRng`] as the RNG.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
 pub fn is_prime<T: Integer + RandomMod>(num: &T) -> bool {
     is_prime_with_rng(&mut OsRng, num)
 }
 
-/// Checks probabilistically if the given number is a safe prime
-/// (that is, such that `(n - 1) / 2` is also prime)
-/// using [`OsRng`] as the RNG.
+/// Probabilistically checks if the given number is a safe prime (that is, such that `(n - 1) / 2` is
+/// also prime) using [`OsRng`] as the RNG.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
@@ -54,7 +51,6 @@ pub fn is_safe_prime<T: Integer + RandomMod>(num: &T) -> bool {
 }
 
 /// Returns a random prime of size `bit_length` using the provided RNG.
-/// If `bit_length` is `None`, the full size of `Uint<L>` is used.
 ///
 /// Panics if `bit_length` is less than 2, or greater than the bit size of the target `Uint`.
 ///
@@ -81,9 +77,8 @@ pub fn generate_prime_with_rng<T: Integer + RandomBits + RandomMod>(
 
 /// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime)
 /// of size `bit_length` using the provided RNG.
-/// If `bit_length` is `None`, the full size of `Uint<L>` is used.
 ///
-/// Panics if `bit_length` is less than 3, or is greater than the bit size of the target `Uint`.
+/// Panics if `bit_length` is less than 3, or greater than the bit size of the target `Uint`.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 pub fn generate_safe_prime_with_rng<T: Integer + RandomBits + RandomMod>(
@@ -106,7 +101,7 @@ pub fn generate_safe_prime_with_rng<T: Integer + RandomBits + RandomMod>(
     }
 }
 
-/// Checks probabilistically if the given number is prime using the provided RNG.
+/// Probabilistically checks if the given number is prime using the provided RNG.
 ///
 /// Performed checks:
 /// - Miller-Rabin check with base 2;
@@ -136,15 +131,13 @@ pub fn is_prime_with_rng<T: Integer + RandomMod>(rng: &mut impl CryptoRngCore, n
         return true;
     }
 
-    let odd_num = match Odd::new(num.clone()).into() {
-        Some(x) => x,
-        None => return false,
-    };
-
-    _is_prime_with_rng(rng, &odd_num)
+    match Odd::new(num.clone()).into() {
+        Some(x) => _is_prime_with_rng(rng, &x),
+        None => false,
+    }
 }
 
-/// Checks probabilistically if the given number is a safe prime using the provided RNG.
+/// Probabilistically checks if the given number is a safe prime using the provided RNG.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 pub fn is_safe_prime_with_rng<T: Integer + RandomMod>(
@@ -157,6 +150,10 @@ pub fn is_safe_prime_with_rng<T: Integer + RandomMod>(
     if num == &T::from_limb_like(Limb::from(5u32), num) {
         return true;
     }
+
+    // Safe primes are always of the form 4k + 3 (i.e. n ≡ 3 mod 4)
+    // The last two digits of a binary number give you its value modulo 4.
+    // Primes p=4n+3 will always end in 11​ in binary because p ≡ 3 mod 4.
     if num.as_ref()[0].0 & 3 != 3 {
         return false;
     }
@@ -168,7 +165,7 @@ pub fn is_safe_prime_with_rng<T: Integer + RandomMod>(
     _is_prime_with_rng(rng, &odd_num) && _is_prime_with_rng(rng, &odd_half_num)
 }
 
-/// Checks for primality assuming that `num` is odd.
+/// Checks for primality.
 fn _is_prime_with_rng<T: Integer + RandomMod>(rng: &mut impl CryptoRngCore, num: &Odd<T>) -> bool {
     let mr = MillerRabin::new(num);
 

src/traits.rs

@@ -10,7 +10,6 @@ use crate::{
 /// and primality checking, wrapping the standalone functions ([`is_prime_with_rng`] etc).
 pub trait RandomPrimeWithRng {
     /// Returns a random prime of size `bit_length` using the provided RNG.
-    /// If `bit_length` is `None`, the full size of `Uint<L>` is used.
     ///
     /// Panics if `bit_length` is less than 2, or greater than the bit size of the target `Uint`.
     ///
@@ -23,7 +22,6 @@ pub trait RandomPrimeWithRng {
 
     /// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime)
     /// of size `bit_length` using the provided RNG.
-    /// If `bit_length` is `None`, the full size of `Uint<L>` is used.
     ///
     /// Panics if `bit_length` is less than 3, or greater than the bit size of the target `Uint`.
     ///
@@ -34,18 +32,21 @@ pub trait RandomPrimeWithRng {
         bits_precision: u32,
     ) -> Self;
 
-    /// Checks probabilistically if the given number is prime using the provided RNG.
+    /// Probabilistically checks if the given number is prime using the provided RNG.
     ///
     /// See [`is_prime_with_rng`] for details about the performed checks.
     fn is_prime_with_rng(&self, rng: &mut impl CryptoRngCore) -> bool;
 
-    /// Checks probabilistically if the given number is a safe prime using the provided RNG.
+    /// Probabilistically checks if the given number is a safe prime using the provided RNG.
     ///
     /// See [`is_prime_with_rng`] for details about the performed checks.
     fn is_safe_prime_with_rng(&self, rng: &mut impl CryptoRngCore) -> bool;
 }
 
-impl<T: Integer + RandomBits + RandomMod> RandomPrimeWithRng for T {
+impl<T> RandomPrimeWithRng for T
+where
+    T: Integer + RandomBits + RandomMod,
+{
     fn generate_prime_with_rng(
         rng: &mut impl CryptoRngCore,
         bit_length: u32,