Fix wrapping shifts and add unbounded shifts (#1160)

This PR makes a couple breaking changes: wrapping shift methods are
updated to behave accordingly with `core`, so the shift value itself is
wrapped at the capacity of the integer instead of the integer becoming
zero when the shift exceeds the capacity. The new
`unbounded_shl`/`unbounded_shr` methods provide support for the old
behavior. The `ShlVartime` and `ShrVartime` traits also get a new method
to support unbounded shifts.

The performance of constant-time `shl`/`shr` methods is improved by only
performing one sub-limb shift instead of multiple.

Fixes #1151

---------

Signed-off-by: Andrew Whitehead <cywolf@gmail.com>

Author: andrewwhitehead

benches/uint.rs

@@ -740,6 +740,26 @@ fn bench_mod_symbols(c: &mut Criterion) {
 fn bench_shl(c: &mut Criterion) {
     let mut group = c.benchmark_group("left shift");
 
+    group.bench_function("shl, U256", |b| {
+        b.iter_batched(|| U256::ONE, |x| x.shl(30), BatchSize::SmallInput);
+    });
+
+    group.bench_function("unbounded_shl, U256", |b| {
+        b.iter_batched(|| U256::ONE, |x| x.unbounded_shl(30), BatchSize::SmallInput);
+    });
+
+    group.bench_function("shl, U2048", |b| {
+        b.iter_batched(|| U2048::ONE, |x| x.shl(1024 + 10), BatchSize::SmallInput);
+    });
+
+    group.bench_function("unbounded_shl, U2048", |b| {
+        b.iter_batched(
+            || U2048::ONE,
+            |x| x.unbounded_shl(1024 + 10),
+            BatchSize::SmallInput,
+        );
+    });
+
     group.bench_function("shl_vartime, small, U2048", |b| {
         b.iter_batched(|| U2048::ONE, |x| x.shl_vartime(10), BatchSize::SmallInput);
     });
@@ -760,16 +780,32 @@ fn bench_shl(c: &mut Criterion) {
         );
     });
 
-    group.bench_function("shl, U2048", |b| {
-        b.iter_batched(|| U2048::ONE, |x| x.shl(1024 + 10), BatchSize::SmallInput);
-    });
-
     group.finish();
 }
 
 fn bench_shr(c: &mut Criterion) {
     let mut group = c.benchmark_group("right shift");
 
+    group.bench_function("shr, U256", |b| {
+        b.iter_batched(|| U256::ONE, |x| x.shr(30), BatchSize::SmallInput);
+    });
+
+    group.bench_function("unbounded_shr, U256", |b| {
+        b.iter_batched(|| U256::ONE, |x| x.unbounded_shr(30), BatchSize::SmallInput);
+    });
+
+    group.bench_function("shr, U2048", |b| {
+        b.iter_batched(|| U2048::ONE, |x| x.shr(1024 + 10), BatchSize::SmallInput);
+    });
+
+    group.bench_function("unbounded_shr, U2048", |b| {
+        b.iter_batched(
+            || U2048::ONE,
+            |x| x.unbounded_shr(1024 + 10),
+            BatchSize::SmallInput,
+        );
+    });
+
     group.bench_function("shr_vartime, small, U2048", |b| {
         b.iter_batched(|| U2048::ONE, |x| x.shr_vartime(10), BatchSize::SmallInput);
     });
@@ -790,10 +826,6 @@ fn bench_shr(c: &mut Criterion) {
         );
     });
 
-    group.bench_function("shr, U2048", |b| {
-        b.iter_batched(|| U2048::ONE, |x| x.shr(1024 + 10), BatchSize::SmallInput);
-    });
-
     group.finish();
 }
 

src/int/shl.rs

@@ -9,22 +9,30 @@ impl<const LIMBS: usize> Int<LIMBS> {
     /// # Panics
     /// - if `shift >= Self::BITS`.
     #[must_use]
+    #[track_caller]
     pub const fn shl(&self, shift: u32) -> Self {
         Self(Uint::shl(&self.0, shift))
     }
 
     /// Computes `self << shift` in variable time.
     ///
+    /// NOTE: this operation is variable time with respect to `shift` *ONLY*.
+    ///
+    /// When used with a fixed `shift`, this function is constant-time with respect to `self`.
+    ///
     /// # Panics
     /// - if `shift >= Self::BITS`.
+    #[inline(always)]
     #[must_use]
+    #[track_caller]
     pub const fn shl_vartime(&self, shift: u32) -> Self {
         Self(Uint::shl_vartime(&self.0, shift))
     }
 
     /// Computes `self << shift`.
     ///
     /// Returns `None` if `shift >= Self::BITS`.
+    #[inline(always)]
     #[must_use]
     pub const fn overflowing_shl(&self, shift: u32) -> CtOption<Self> {
         Self::from_uint_opt(self.0.overflowing_shl(shift))
@@ -50,13 +58,38 @@ impl<const LIMBS: usize> Int<LIMBS> {
 
     /// Computes `self << shift` in a panic-free manner, returning zero if the shift exceeds the
     /// precision.
+    #[inline(always)]
     #[must_use]
-    pub const fn wrapping_shl(&self, shift: u32) -> Self {
-        Self(self.0.wrapping_shl(shift))
+    pub const fn unbounded_shl(&self, shift: u32) -> Self {
+        Self(self.0.unbounded_shl(shift))
     }
 
     /// Computes `self << shift` in variable-time in a panic-free manner, returning zero if the
     /// shift exceeds the precision.
+    ///
+    /// NOTE: this operation is variable time with respect to `shift` *ONLY*.
+    ///
+    /// When used with a fixed `shift`, this function is constant-time with respect to `self`.
+    #[inline(always)]
+    #[must_use]
+    pub const fn unbounded_shl_vartime(&self, shift: u32) -> Self {
+        Self(self.0.unbounded_shl_vartime(shift))
+    }
+
+    /// Computes `self << shift` in a panic-free manner, reducing shift modulo the type's width.
+    #[inline(always)]
+    #[must_use]
+    pub const fn wrapping_shl(&self, shift: u32) -> Self {
+        Self(self.0.wrapping_shl(shift))
+    }
+
+    /// Computes `self << shift` in variable-time in a panic-free manner, reducing shift modulo
+    /// the type's width.
+    ///
+    /// NOTE: this operation is variable time with respect to `shift` *ONLY*.
+    ///
+    /// When used with a fixed `shift`, this function is constant-time with respect to `self`.
+    #[inline(always)]
     #[must_use]
     pub const fn wrapping_shl_vartime(&self, shift: u32) -> Self {
         Self(self.0.wrapping_shl_vartime(shift))
@@ -106,6 +139,10 @@ impl<const LIMBS: usize> ShlVartime for Int<LIMBS> {
         self.overflowing_shl_vartime(shift)
     }
 
+    fn unbounded_shl_vartime(&self, shift: u32) -> Self {
+        self.unbounded_shl_vartime(shift)
+    }
+
     fn wrapping_shl_vartime(&self, shift: u32) -> Self {
         self.wrapping_shl_vartime(shift)
     }
@@ -170,8 +207,8 @@ mod tests {
     }
 
     #[test]
-    #[should_panic(expected = "`shift` within the bit size of the integer")]
-    fn shl256() {
+    #[should_panic(expected = "`shift` exceeds upper bound")]
+    fn shl_bounds_panic() {
         let _ = N << 256;
     }
 
@@ -180,17 +217,31 @@ mod tests {
         assert_eq!(N << 64, SIXTY_FOUR);
     }
 
+    #[test]
+    fn unbounded_shl() {
+        assert_eq!(I256::MAX.unbounded_shl(257), I256::ZERO);
+        assert_eq!(I256::MIN.unbounded_shl(257), I256::ZERO);
+        assert_eq!(
+            ShlVartime::unbounded_shl_vartime(&I256::MAX, 257),
+            I256::ZERO
+        );
+        assert_eq!(
+            ShlVartime::unbounded_shl_vartime(&I256::MIN, 257),
+            I256::ZERO
+        );
+    }
+
     #[test]
     fn wrapping_shl() {
-        assert_eq!(I256::MAX.wrapping_shl(257), I256::ZERO);
-        assert_eq!(I256::MIN.wrapping_shl(257), I256::ZERO);
+        assert_eq!(I256::MAX.wrapping_shl(257), I256::MAX.shl(1));
+        assert_eq!(I256::MIN.wrapping_shl(257), I256::MIN.shl(1));
         assert_eq!(
             ShlVartime::wrapping_shl_vartime(&I256::MAX, 257),
-            I256::ZERO
+            I256::MAX.shl(1)
         );
         assert_eq!(
             ShlVartime::wrapping_shl_vartime(&I256::MIN, 257),
-            I256::ZERO
+            I256::MIN.shl(1)
         );
     }
 }