Add from_*slice_truncated methods to Encoding trait (#1301)

The primary goal here is to make it possible to construct both `Uint`
and `BoxedUint` from slice-based inputs in a generic context,
particularly for implementing the `bits2int` function in the `rfc6979`
crate, but also useful for e.g. `elliptic-curve` when we have field
elements backed by big integers that are larger than the field modulus,
as is the case for NIST P-521.

It was possible to provide a basic impl for these functions in order to
make the change non-breaking (since `Encoding` isn't sealed): it ensures
the provided `bits_precision` matches the `Repr` size, and still
implements big/little endian truncation, but doesn't handle short inputs
and just thunks through `from_be_bytes`/`from_le_bytes`. This is
particularly helpful as currently no impl for `Int` is provided, so it's
using the default.

Author: tarcieri

src/encoding.rs

@@ -1,5 +1,6 @@
 //! Shared encoding support.
 
+use crate::bitlen;
 use core::fmt;
 
 #[cfg(feature = "hybrid-array")]
@@ -56,6 +57,7 @@ pub trait ArrayDecoding {
 }
 
 /// Encoding support.
+// TODO(tarcieri): seal this trait in the next breaking release.
 pub trait Encoding: Sized {
     /// Byte array representation.
     type Repr: AsRef<[u8]>
@@ -81,6 +83,41 @@ pub trait Encoding: Sized {
         }
     }
 
+    /// Decode from the provided big endian bytes, truncating to the least significant bits in the
+    /// event the given amount of data exceeds `bits_precision`.
+    ///
+    /// Implementations may panic if `bits_precision` exceeds their underlying size.
+    #[must_use]
+    fn from_be_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        assert_eq!(bits_precision, bitlen::from_bytes(size_of::<Self::Repr>()));
+        let bytes = truncate_be(bytes, bits_precision);
+        Self::from_be_bytes(bytes.try_into().expect("input too short"))
+    }
+
+    /// Decode from the provided little endian bytes, truncating to the least significant bits in
+    /// the event the given amount of data exceeds `bits_precision`.
+    ///
+    /// Implementations may panic if `bits_precision` exceeds their underlying size.
+    #[must_use]
+    fn from_le_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        assert_eq!(bits_precision, bitlen::from_bytes(size_of::<Self::Repr>()));
+        let bytes = truncate_le(bytes, bits_precision);
+        Self::from_le_bytes(bytes.try_into().expect("input too short"))
+    }
+
+    /// Decode from the provided bytes, interpreting them using the specified [`ByteOrder`],
+    /// truncating to the least significant bits in the event the given amount of data exceeds
+    /// `bits_precision`.
+    ///
+    /// Implementations may panic if `bits_precision` exceeds their underlying size.
+    #[must_use]
+    fn from_slice_truncated(bytes: &[u8], bits_precision: u32, byte_order: ByteOrder) -> Self {
+        match byte_order {
+            ByteOrder::BigEndian => Self::from_be_slice_truncated(bytes, bits_precision),
+            ByteOrder::LittleEndian => Self::from_le_slice_truncated(bytes, bits_precision),
+        }
+    }
+
     /// Encode to big endian bytes.
     #[must_use]
     fn to_be_bytes(&self) -> Self::Repr;
@@ -138,3 +175,25 @@ impl fmt::Display for DecodeError {
 }
 
 impl core::error::Error for DecodeError {}
+
+/// Interpret `bytes` as a big endian integer and extract `bits_precision` number of least
+/// significant bits, returning a truncated input if it exceeds the requested precision.
+pub(crate) fn truncate_be(bytes: &[u8], bits_precision: u32) -> &[u8] {
+    let bytes_precision = bitlen::to_bytes(bits_precision);
+    if bytes.len() > bytes_precision {
+        &bytes[bytes.len().saturating_sub(bytes_precision)..]
+    } else {
+        bytes
+    }
+}
+
+/// Interpret `bytes` as a little endian integer and extract `bits_precision` number of least
+/// significant bits, returning a truncated input if it exceeds the requested precision.
+pub(crate) fn truncate_le(bytes: &[u8], bits_precision: u32) -> &[u8] {
+    let bytes_precision = bitlen::to_bytes(bits_precision);
+    if bytes.len() > bytes_precision {
+        &bytes[..bytes_precision]
+    } else {
+        bytes
+    }
+}

src/limb/encoding.rs

@@ -138,6 +138,16 @@ impl Encoding for Limb {
         Self::from_le_bytes(bytes)
     }
 
+    #[inline]
+    fn from_be_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_be_slice_truncated(bytes, bits_precision)
+    }
+
+    #[inline]
+    fn from_le_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_le_slice_truncated(bytes, bits_precision)
+    }
+
     #[inline]
     fn to_be_bytes(&self) -> Self::Repr {
         self.to_be_bytes()

src/uint/boxed/encoding.rs

@@ -262,20 +262,28 @@ impl BoxedUint {
 impl Encoding for BoxedUint {
     type Repr = Box<[u8]>;
 
-    fn to_be_bytes(&self) -> Self::Repr {
-        BoxedUint::to_be_bytes(self)
+    fn from_be_bytes(bytes: Self::Repr) -> Self {
+        Self::from_be_slice_vartime(&bytes)
     }
 
-    fn to_le_bytes(&self) -> Self::Repr {
-        BoxedUint::to_le_bytes(self)
+    fn from_le_bytes(bytes: Self::Repr) -> Self {
+        Self::from_le_slice_vartime(&bytes)
     }
 
-    fn from_be_bytes(bytes: Self::Repr) -> Self {
-        BoxedUint::from_be_slice_vartime(&bytes)
+    fn from_be_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_be_slice_truncated(bytes, bits_precision)
     }
 
-    fn from_le_bytes(bytes: Self::Repr) -> Self {
-        BoxedUint::from_le_slice_vartime(&bytes)
+    fn from_le_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_le_slice_truncated(bytes, bits_precision)
+    }
+
+    fn to_be_bytes(&self) -> Self::Repr {
+        Self::to_be_bytes(self)
+    }
+
+    fn to_le_bytes(&self) -> Self::Repr {
+        Self::to_le_bytes(self)
     }
 }
 

src/uint/encoding.rs

@@ -6,7 +6,10 @@ mod der;
 mod rlp;
 
 use super::Uint;
-use crate::{ByteOrder, DecodeError, EncodedSize, Encoding, Limb, Word, bitlen};
+use crate::{
+    ByteOrder, DecodeError, EncodedSize, Encoding, Limb, Word, bitlen,
+    encoding::{truncate_be, truncate_le},
+};
 use core::{fmt, ops::Deref};
 
 #[cfg(feature = "alloc")]
@@ -324,19 +327,15 @@ impl<const LIMBS: usize> Uint<LIMBS> {
 ///
 /// Fills the supplied `limbs` with the decoded `bytes` after truncating to `bits_precision`.
 pub(crate) fn fill_limbs_from_be_slice_truncated(
-    mut bytes: &[u8],
+    bytes: &[u8],
     limbs: &mut [Limb],
     bits_precision: u32,
 ) -> Result<(), DecodeError> {
     if bitlen::from_limbs(limbs.len()) < bits_precision {
         return Err(DecodeError::Precision);
     }
 
-    let bytes_precision = bitlen::to_bytes(bits_precision);
-    if bytes.len() > bytes_precision {
-        bytes = &bytes[bytes.len().saturating_sub(bytes_precision)..];
-    }
-
+    let bytes = truncate_be(bytes, bits_precision);
     for (chunk, limb) in bytes.rchunks(Limb::BYTES).zip(limbs.iter_mut()) {
         *limb = Limb::from_be_slice(chunk);
     }
@@ -350,19 +349,15 @@ pub(crate) fn fill_limbs_from_be_slice_truncated(
 ///
 /// Fills the supplied `limbs` with the decoded `bytes` after truncating to `bits_precision`.
 pub(crate) fn fill_limbs_from_le_slice_truncated(
-    mut bytes: &[u8],
+    bytes: &[u8],
     limbs: &mut [Limb],
     bits_precision: u32,
 ) -> Result<(), DecodeError> {
     if bitlen::from_limbs(limbs.len()) < bits_precision {
         return Err(DecodeError::Precision);
     }
 
-    let bytes_precision = bitlen::to_bytes(bits_precision);
-    if bytes.len() > bytes_precision {
-        bytes = &bytes[..bytes_precision];
-    }
-
+    let bytes = truncate_le(bytes, bits_precision);
     for (chunk, limb) in bytes.chunks(Limb::BYTES).zip(limbs.iter_mut()) {
         *limb = Limb::from_le_slice(chunk);
     }
@@ -577,6 +572,16 @@ impl<const LIMBS: usize> Encoding for Uint<LIMBS> {
         Self::from_le_slice(bytes.as_ref())
     }
 
+    #[inline]
+    fn from_be_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_be_slice_truncated(bytes, bits_precision)
+    }
+
+    #[inline]
+    fn from_le_slice_truncated(bytes: &[u8], bits_precision: u32) -> Self {
+        Self::from_le_slice_truncated(bytes, bits_precision)
+    }
+
     #[inline]
     fn to_be_bytes(&self) -> Self::Repr {
         self.to_be_bytes()