Add constant-time validation APIs

Author: eldryoth

CHANGELOG.md

@@ -6,6 +6,8 @@
 - Added no-alloc validation-only APIs for strict and legacy profiles:
   `validate_result`, `validate`, `validate_legacy_result`, and
   `validate_legacy`.
+- Added constant-time-oriented validation-only APIs:
+  `ct::CtEngine::validate_result` and `ct::CtEngine::validate`.
 - Added dependency-free line-wrapped encoding with `LineWrap`, `LineEnding`,
   checked wrapped-length calculation, caller-owned output APIs, clear-tail
   wrapping, and `alloc` convenience helpers.

README.md

@@ -458,10 +458,10 @@ Security commitments:
   untrusted length metadata should never require a panic.
 - Scalar encode avoids input-derived alphabet table indexes, and scalar decode
   uses branch-minimized arithmetic. A separate `ct` module provides a
-  constant-time-oriented scalar decode path for callers that need a narrower
-  timing target. Its malformed-input errors are intentionally non-localized,
-  clear-tail variants clear caller-owned buffers on error, and it is not
-  documented as a formally verified cryptographic constant-time API.
+  constant-time-oriented scalar validation and decode path for callers that
+  need a narrower timing target. Its malformed-input errors are intentionally
+  non-localized, clear-tail variants clear caller-owned buffers on error, and
+  it is not documented as a formally verified cryptographic constant-time API.
 - Clear-tail encode/decode variants are available for callers that want
   best-effort cleanup of unused caller-owned buffers without adding a runtime
   dependency.

docs/CONSTANT_TIME.md

@@ -65,6 +65,10 @@ pub mod ct {
     pub const URL_SAFE_NO_PAD: CtEngine<UrlSafe, false>;
 
     impl<A, const PAD: bool> CtEngine<A, PAD> {
+        pub fn validate_result(&self, input: &[u8]) -> Result<(), DecodeError>;
+
+        pub fn validate(&self, input: &[u8]) -> bool;
+
         pub fn decode_slice(
             &self,
             input: &[u8],

docs/PLAN.md

@@ -316,7 +316,7 @@ the zero-runtime-dependency stance.
   symbols, padding conflicts, ASCII constraints, and deterministic errors.
 - Add line-wrapping encode support for PEM/MIME/common caller-selected wrapping
   policies, including CRLF and LF output.
-- Add validate-only APIs for strict, legacy, profile-aware, and
+- Completed validate-only APIs for strict, legacy, profile-aware, and
   constant-time-oriented validation use cases.
 - Completed zero-dependency stack-backed output helpers for short encoded
   values.

src/lib.rs

@@ -1266,7 +1266,10 @@ pub mod stream {
 /// content through one opaque error. It is not documented as a formally
 /// verified cryptographic constant-time API.
 pub mod ct {
-    use super::{Alphabet, DecodeError, Standard, UrlSafe, ct_decode_in_place, ct_decode_slice};
+    use super::{
+        Alphabet, DecodeError, Standard, UrlSafe, ct_decode_in_place, ct_decode_slice,
+        ct_validate_decode,
+    };
     use core::marker::PhantomData;
 
     /// Standard Base64 constant-time-oriented decoder with padding.
@@ -1299,6 +1302,42 @@ pub mod ct {
             }
         }
 
+        /// Validates `input` without writing decoded bytes.
+        ///
+        /// This uses the same constant-time-oriented symbol mapping and opaque
+        /// malformed-input error behavior as [`Self::decode_slice`]. Input
+        /// length, padding length, and final success or failure remain public.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use base64_ng::ct;
+        ///
+        /// ct::STANDARD.validate_result(b"aGVsbG8=").unwrap();
+        /// assert!(ct::STANDARD.validate_result(b"aGVsbG8").is_err());
+        /// ```
+        pub fn validate_result(&self, input: &[u8]) -> Result<(), DecodeError> {
+            ct_validate_decode::<A, PAD>(input)
+        }
+
+        /// Returns whether `input` is valid for this constant-time-oriented
+        /// decoder.
+        ///
+        /// This is a convenience wrapper around [`Self::validate_result`].
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use base64_ng::ct;
+        ///
+        /// assert!(ct::URL_SAFE_NO_PAD.validate(b"-_8"));
+        /// assert!(!ct::URL_SAFE_NO_PAD.validate(b"+/8"));
+        /// ```
+        #[must_use]
+        pub fn validate(&self, input: &[u8]) -> bool {
+            self.validate_result(input).is_ok()
+        }
+
         /// Decodes `input` into `output`, returning the number of bytes
         /// written.
         ///
@@ -4345,6 +4384,126 @@ fn ct_decode_in_place<A: Alphabet, const PAD: bool>(
     }
 }
 
+fn ct_validate_decode<A: Alphabet, const PAD: bool>(input: &[u8]) -> Result<(), DecodeError> {
+    if input.is_empty() {
+        return Ok(());
+    }
+
+    if PAD {
+        ct_validate_padded::<A>(input)
+    } else {
+        ct_validate_unpadded::<A>(input)
+    }
+}
+
+fn ct_validate_padded<A: Alphabet>(input: &[u8]) -> Result<(), DecodeError> {
+    if !input.len().is_multiple_of(4) {
+        return Err(DecodeError::InvalidLength);
+    }
+
+    let padding = ct_padding_len(input);
+    let mut invalid_byte = 0u8;
+    let mut invalid_padding = 0u8;
+    let mut read = 0;
+
+    while read < input.len() {
+        let is_last = read + 4 == input.len();
+        let b0 = input[read];
+        let b1 = input[read + 1];
+        let b2 = input[read + 2];
+        let b3 = input[read + 3];
+        let (_, valid0) = ct_decode_ascii_base64::<A>(b0);
+        let (v1, valid1) = ct_decode_ascii_base64::<A>(b1);
+        let (v2, valid2) = ct_decode_ascii_base64::<A>(b2);
+        let (_, valid3) = ct_decode_ascii_base64::<A>(b3);
+
+        invalid_byte |= !valid0;
+        invalid_byte |= !valid1;
+
+        if is_last && padding == 2 {
+            invalid_padding |= ct_mask_nonzero_u8(v1 & 0b0000_1111);
+        } else if is_last && padding == 1 {
+            invalid_byte |= !valid2;
+            invalid_padding |= ct_mask_eq_u8(b2, b'=');
+            invalid_padding |= ct_mask_nonzero_u8(v2 & 0b0000_0011);
+        } else {
+            invalid_byte |= !valid2;
+            invalid_byte |= !valid3;
+            invalid_padding |= ct_mask_eq_u8(b2, b'=');
+            invalid_padding |= ct_mask_eq_u8(b3, b'=');
+        }
+
+        read += 4;
+    }
+
+    report_ct_error(invalid_byte, invalid_padding)
+}
+
+fn ct_validate_unpadded<A: Alphabet>(input: &[u8]) -> Result<(), DecodeError> {
+    if input.len() % 4 == 1 {
+        return Err(DecodeError::InvalidLength);
+    }
+
+    let mut invalid_byte = 0u8;
+    let mut invalid_padding = 0u8;
+    let mut read = 0;
+
+    while read + 4 <= input.len() {
+        let b0 = input[read];
+        let b1 = input[read + 1];
+        let b2 = input[read + 2];
+        let b3 = input[read + 3];
+        let (_, valid0) = ct_decode_ascii_base64::<A>(b0);
+        let (_, valid1) = ct_decode_ascii_base64::<A>(b1);
+        let (_, valid2) = ct_decode_ascii_base64::<A>(b2);
+        let (_, valid3) = ct_decode_ascii_base64::<A>(b3);
+
+        invalid_byte |= !valid0;
+        invalid_byte |= !valid1;
+        invalid_byte |= !valid2;
+        invalid_byte |= !valid3;
+        invalid_padding |= ct_mask_eq_u8(b0, b'=');
+        invalid_padding |= ct_mask_eq_u8(b1, b'=');
+        invalid_padding |= ct_mask_eq_u8(b2, b'=');
+        invalid_padding |= ct_mask_eq_u8(b3, b'=');
+
+        read += 4;
+    }
+
+    match input.len() - read {
+        0 => {}
+        2 => {
+            let b0 = input[read];
+            let b1 = input[read + 1];
+            let (_, valid0) = ct_decode_ascii_base64::<A>(b0);
+            let (v1, valid1) = ct_decode_ascii_base64::<A>(b1);
+            invalid_byte |= !valid0;
+            invalid_byte |= !valid1;
+            invalid_padding |= ct_mask_eq_u8(b0, b'=');
+            invalid_padding |= ct_mask_eq_u8(b1, b'=');
+            invalid_padding |= ct_mask_nonzero_u8(v1 & 0b0000_1111);
+        }
+        3 => {
+            let b0 = input[read];
+            let b1 = input[read + 1];
+            let b2 = input[read + 2];
+            let (_, valid0) = ct_decode_ascii_base64::<A>(b0);
+            let (_, valid1) = ct_decode_ascii_base64::<A>(b1);
+            let (v2, valid2) = ct_decode_ascii_base64::<A>(b2);
+            invalid_byte |= !valid0;
+            invalid_byte |= !valid1;
+            invalid_byte |= !valid2;
+            invalid_padding |= ct_mask_eq_u8(b0, b'=');
+            invalid_padding |= ct_mask_eq_u8(b1, b'=');
+            invalid_padding |= ct_mask_eq_u8(b2, b'=');
+            invalid_padding |= ct_mask_nonzero_u8(v2 & 0b0000_0011);
+        }
+        _ => return Err(DecodeError::InvalidLength),
+    }
+
+    report_ct_error(invalid_byte, invalid_padding)
+}
+
 fn ct_decode_padded<A: Alphabet>(input: &[u8], output: &mut [u8]) -> Result<usize, DecodeError> {
     if !input.len().is_multiple_of(4) {
         return Err(DecodeError::InvalidLength);

tests/rfc4648.rs

@@ -438,6 +438,60 @@ fn ct_decoder_matches_strict_for_canonical_inputs() {
     }
 }
 
+#[test]
+fn ct_validate_matches_constant_time_decode_policy() {
+    for input_len in 0..64 {
+        let mut input = [0u8; 64];
+        for (index, byte) in input.iter_mut().enumerate() {
+            *byte = (index * 17 + input_len * 7) as u8;
+        }
+        let input = &input[..input_len];
+
+        let mut encoded_buf = [0u8; 128];
+
+        let encoded_len = STANDARD.encode_slice(input, &mut encoded_buf).unwrap();
+        let encoded = &encoded_buf[..encoded_len];
+        assert_eq!(ct::STANDARD.validate_result(encoded), Ok(()));
+        assert!(ct::STANDARD.validate(encoded));
+
+        let encoded_len = STANDARD_NO_PAD
+            .encode_slice(input, &mut encoded_buf)
+            .unwrap();
+        let encoded = &encoded_buf[..encoded_len];
+        assert_eq!(ct::STANDARD_NO_PAD.validate_result(encoded), Ok(()));
+        assert!(ct::STANDARD_NO_PAD.validate(encoded));
+
+        let encoded_len = URL_SAFE.encode_slice(input, &mut encoded_buf).unwrap();
+        let encoded = &encoded_buf[..encoded_len];
+        assert_eq!(ct::URL_SAFE.validate_result(encoded), Ok(()));
+        assert!(ct::URL_SAFE.validate(encoded));
+
+        let encoded_len = URL_SAFE_NO_PAD
+            .encode_slice(input, &mut encoded_buf)
+            .unwrap();
+        let encoded = &encoded_buf[..encoded_len];
+        assert_eq!(ct::URL_SAFE_NO_PAD.validate_result(encoded), Ok(()));
+        assert!(ct::URL_SAFE_NO_PAD.validate(encoded));
+    }
+
+    assert_eq!(
+        ct::STANDARD.validate_result(b"AA-A"),
+        Err(DecodeError::InvalidInput)
+    );
+    assert_eq!(
+        ct::STANDARD.validate_result(b"Zh=="),
+        Err(DecodeError::InvalidInput)
+    );
+    assert_eq!(
+        ct::STANDARD_NO_PAD.validate_result(b"Zg=="),
+        Err(DecodeError::InvalidInput)
+    );
+    assert_eq!(
+        ct::STANDARD.validate_result(b"Zg"),
+        Err(DecodeError::InvalidLength)
+    );
+}
+
 #[test]
 fn ct_decoder_rejects_malformed_inputs() {
     let mut output = [0u8; 8];