Make encoded length overflow recoverable

Author: eldryoth

CHANGELOG.md

@@ -13,6 +13,8 @@
 - Added `std::io::Read` streaming decoder behind the `stream` feature.
 - Added checked encoded-length helpers.
 - Added exact decoded-length helpers.
+- Changed public encoded-length helpers to return recoverable overflow errors
+  instead of panicking.
 - Hardened decode errors to report absolute input indexes.
 - Hardened scalar encode to avoid input-derived alphabet table indexes.
 - Hardened alphabet decode to avoid branch-heavy match ladders.

README.md

@@ -67,10 +67,14 @@ base64-ng = { version = "0.1", default-features = false }
 ## Example
 
 ```rust
-use base64_ng::{STANDARD, encoded_len};
+use base64_ng::{STANDARD, checked_encoded_len};
 
 let input = b"hello";
-let mut encoded = [0u8; encoded_len(5, true)];
+const ENCODED_CAPACITY: usize = match checked_encoded_len(5, true) {
+    Some(len) => len,
+    None => panic!("encoded length overflow"),
+};
+let mut encoded = [0u8; ENCODED_CAPACITY];
 let written = STANDARD.encode_slice(input, &mut encoded).unwrap();
 assert_eq!(&encoded[..written], b"aGVsbG8=");
 
@@ -180,6 +184,8 @@ Security commitments:
 - No unsafe code in scalar code.
 - Future unsafe SIMD isolated under `src/simd/`.
 - Strict decoding rejects malformed padding and trailing data.
+- Public encoded-length overflow is recoverable through `Result` or `Option`;
+  untrusted length metadata should never require a panic.
 - Scalar encode avoids input-derived alphabet table indexes, and scalar decode
   uses branch-minimized arithmetic. These paths are hardened against obvious
   timing pitfalls, but they are not documented as formally verified

SECURITY.md

@@ -42,6 +42,10 @@ arithmetic for ASCII classification. This reduces easy timing pitfalls, but
 `base64-ng` does not currently claim a formally verified cryptographic
 constant-time encode or decode API.
 
+Public encoded-length helpers report overflow with `Result` or `Option` rather
+than panicking. Code that handles untrusted length metadata should use these
+helpers before allocating or accepting framed payloads.
+
 Required before unsafe SIMD stabilizes:
 
 - Scalar/SIMD differential tests.

src/lib.rs

@@ -16,10 +16,14 @@
 //! Encode and decode with caller-owned buffers:
 //!
 //! ```
-//! use base64_ng::{STANDARD, encoded_len};
+//! use base64_ng::{STANDARD, checked_encoded_len};
 //!
 //! let input = b"hello";
-//! let mut encoded = [0u8; encoded_len(5, true)];
+//! const ENCODED_CAPACITY: usize = match checked_encoded_len(5, true) {
+//!     Some(len) => len,
+//!     None => panic!("encoded length overflow"),
+//! };
+//! let mut encoded = [0u8; ENCODED_CAPACITY];
 //! let encoded_len = STANDARD.encode_slice(input, &mut encoded).unwrap();
 //! assert_eq!(&encoded[..encoded_len], b"aGVsbG8=");
 //!
@@ -679,25 +683,22 @@ pub const URL_SAFE_NO_PAD: Engine<UrlSafe, false> = Engine::new();
 
 /// Returns the encoded length for an input length and padding policy.
 ///
-/// # Panics
-///
-/// Panics if the encoded length would overflow `usize`. Use
-/// [`checked_encoded_len`] when handling untrusted length metadata without an
-/// actual input slice.
+/// This function returns [`EncodeError::LengthOverflow`] instead of panicking.
+/// Use [`checked_encoded_len`] when an `Option<usize>` is more convenient.
 ///
 /// # Examples
 ///
 /// ```
 /// use base64_ng::encoded_len;
 ///
-/// assert_eq!(encoded_len(5, true), 8);
-/// assert_eq!(encoded_len(5, false), 7);
+/// assert_eq!(encoded_len(5, true).unwrap(), 8);
+/// assert_eq!(encoded_len(5, false).unwrap(), 7);
+/// assert!(encoded_len(usize::MAX, true).is_err());
 /// ```
-#[must_use]
-pub const fn encoded_len(input_len: usize, padded: bool) -> usize {
+pub const fn encoded_len(input_len: usize, padded: bool) -> Result<usize, EncodeError> {
     match checked_encoded_len(input_len, padded) {
-        Some(len) => len,
-        None => panic!("encoded base64 length overflows usize"),
+        Some(len) => Ok(len),
+        None => Err(EncodeError::LengthOverflow),
     }
 }
 
@@ -869,8 +870,7 @@ where
     }
 
     /// Returns the encoded length for this engine's padding policy.
-    #[must_use]
-    pub const fn encoded_len(&self, input_len: usize) -> usize {
+    pub const fn encoded_len(&self, input_len: usize) -> Result<usize, EncodeError> {
         encoded_len(input_len, PAD)
     }
 
@@ -890,10 +890,10 @@ where
 
     /// Encodes a fixed-size input into a fixed-size output array in const contexts.
     ///
-    /// Stable Rust does not yet allow this API to return `[u8; encoded_len(N)]`
-    /// directly. Instead, the caller supplies the output length through the
-    /// destination type and this function panics during const evaluation if the
-    /// length is wrong.
+    /// Stable Rust does not yet allow this API to return an array whose length
+    /// is computed from `INPUT_LEN` directly. Instead, the caller supplies the
+    /// output length through the destination type and this function panics
+    /// during const evaluation if the length is wrong.
     ///
     /// # Panics
     ///

tests/rfc4648.rs

@@ -1,6 +1,6 @@
 use base64_ng::{
     DecodeError, EncodeError, STANDARD, STANDARD_NO_PAD, URL_SAFE, URL_SAFE_NO_PAD,
-    checked_encoded_len, decoded_capacity, decoded_len,
+    checked_encoded_len, decoded_capacity, decoded_len, encoded_len,
 };
 
 #[cfg(feature = "stream")]
@@ -143,6 +143,14 @@ fn decoded_len_rejects_bad_lengths_and_padding() {
 
 #[test]
 fn checked_encoded_len_reports_overflow() {
+    assert_eq!(
+        encoded_len(usize::MAX, true),
+        Err(EncodeError::LengthOverflow)
+    );
+    assert_eq!(
+        STANDARD.encoded_len(usize::MAX),
+        Err(EncodeError::LengthOverflow)
+    );
     assert_eq!(checked_encoded_len(usize::MAX, true), None);
     assert_eq!(checked_encoded_len(usize::MAX, false), None);
     assert_eq!(STANDARD.checked_encoded_len(usize::MAX), None);
@@ -699,7 +707,7 @@ fn assert_in_place_encode_matches_slice<A, const PAD: bool>(
 ) where
     A: base64_ng::Alphabet,
 {
-    let required = engine.encoded_len(input.len());
+    let required = engine.encoded_len(input.len()).unwrap();
     let mut expected = [0u8; 4];
     let expected_len = engine.encode_slice(input, &mut expected).unwrap();
     assert_eq!(required, expected_len);
@@ -718,7 +726,7 @@ fn assert_equivalent_round_trip<A, const PAD: bool>(
 ) where
     A: base64_ng::Alphabet,
 {
-    let encoded_len = engine.encoded_len(input.len());
+    let encoded_len = engine.encoded_len(input.len()).unwrap();
     let mut encoded = vec![0u8; encoded_len];
     let written = engine.encode_slice(input, &mut encoded).unwrap();
     assert_eq!(written, encoded_len);