Harden scalar encode alphabet mapping

Author: eldryoth

CHANGELOG.md

@@ -14,6 +14,7 @@
 - Added checked encoded-length helpers.
 - Added exact decoded-length helpers.
 - 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.
 - Hardened `decode_vec` to validate input before allocating decoded output.
 - Hardened stream decoders to preserve reader boundaries after terminal padding.

README.md

@@ -180,7 +180,10 @@ Security commitments:
 - No unsafe code in scalar code.
 - Future unsafe SIMD isolated under `src/simd/`.
 - Strict decoding rejects malformed padding and trailing data.
-- Alphabet decode uses branch-minimized scalar arithmetic, but strict decoding is not documented as a cryptographic constant-time API.
+- 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
+  cryptographic constant-time APIs.
 - Legacy compatibility must be opt-in.
 - Release gates include formatting, clippy, tests, Miri when installed, docs, dependency policy, audit, license review, SBOM, and reproducible build checks.
 - Future Kani proofs target in-place decoding bounds and scalar decoder invariants.

SECURITY.md

@@ -36,10 +36,11 @@ The local release gate skips only the large deterministic sweep tests under
 Miri. Those tests still run in the normal stable test suite; Miri focuses on the
 scalar and in-place safety surface that benefits most from interpreter checks.
 
-The scalar decoder avoids obvious alphabet `match` ladders by using
-branch-minimized arithmetic for ASCII classification. This reduces easy
-data-dependent branching, but `base64-ng` does not currently claim a formally
-verified cryptographic constant-time decode API.
+The scalar encoder avoids input-derived alphabet table indexes, and the scalar
+decoder avoids obvious alphabet `match` ladders by using branch-minimized
+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.
 
 Required before unsafe SIMD stabilizes:
 

src/lib.rs

@@ -790,7 +790,7 @@ impl Alphabet for Standard {
 
     #[inline]
     fn decode(byte: u8) -> Option<u8> {
-        decode_ascii_base64(byte, b'+', b'/')
+        decode_ascii_base64(byte, Self::ENCODE[62], Self::ENCODE[63])
     }
 }
 
@@ -803,10 +803,30 @@ impl Alphabet for UrlSafe {
 
     #[inline]
     fn decode(byte: u8) -> Option<u8> {
-        decode_ascii_base64(byte, b'-', b'_')
+        decode_ascii_base64(byte, Self::ENCODE[62], Self::ENCODE[63])
     }
 }
 
+#[inline]
+const fn encode_base64_value<A: Alphabet>(value: u8) -> u8 {
+    encode_ascii_base64(value, A::ENCODE[62], A::ENCODE[63])
+}
+
+#[inline]
+const fn encode_ascii_base64(value: u8, value_62_byte: u8, value_63_byte: u8) -> u8 {
+    let upper = mask_if(value < 26);
+    let lower = mask_if(value.wrapping_sub(26) < 26);
+    let digit = mask_if(value.wrapping_sub(52) < 10);
+    let value_62 = mask_if(value == 0x3e);
+    let value_63 = mask_if(value == 0x3f);
+
+    (value.wrapping_add(b'A') & upper)
+        | (value.wrapping_sub(26).wrapping_add(b'a') & lower)
+        | (value.wrapping_sub(52).wrapping_add(b'0') & digit)
+        | (value_62_byte & value_62)
+        | (value_63_byte & value_63)
+}
+
 #[inline]
 fn decode_ascii_base64(byte: u8, value_62_byte: u8, value_63_byte: u8) -> Option<u8> {
     let upper = mask_if(byte.wrapping_sub(b'A') <= b'Z' - b'A');
@@ -826,8 +846,8 @@ fn decode_ascii_base64(byte: u8, value_62_byte: u8, value_63_byte: u8) -> Option
 }
 
 #[inline]
-fn mask_if(condition: bool) -> u8 {
-    0u8.wrapping_sub(u8::from(condition))
+const fn mask_if(condition: bool) -> u8 {
+    0u8.wrapping_sub(condition as u8)
 }
 
 /// A zero-sized Base64 engine parameterized by alphabet and padding policy.
@@ -920,10 +940,10 @@ where
             let b1 = input[read + 1];
             let b2 = input[read + 2];
 
-            output[write] = A::ENCODE[(b0 >> 2) as usize];
-            output[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-            output[write + 2] = A::ENCODE[(((b1 & 0b0000_1111) << 2) | (b2 >> 6)) as usize];
-            output[write + 3] = A::ENCODE[(b2 & 0b0011_1111) as usize];
+            output[write] = encode_base64_value::<A>(b0 >> 2);
+            output[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+            output[write + 2] = encode_base64_value::<A>(((b1 & 0b0000_1111) << 2) | (b2 >> 6));
+            output[write + 3] = encode_base64_value::<A>(b2 & 0b0011_1111);
 
             read += 3;
             write += 4;
@@ -933,8 +953,8 @@ where
             0 => {}
             1 => {
                 let b0 = input[read];
-                output[write] = A::ENCODE[(b0 >> 2) as usize];
-                output[write + 1] = A::ENCODE[((b0 & 0b0000_0011) << 4) as usize];
+                output[write] = encode_base64_value::<A>(b0 >> 2);
+                output[write + 1] = encode_base64_value::<A>((b0 & 0b0000_0011) << 4);
                 write += 2;
                 if PAD {
                     output[write] = b'=';
@@ -944,9 +964,9 @@ where
             2 => {
                 let b0 = input[read];
                 let b1 = input[read + 1];
-                output[write] = A::ENCODE[(b0 >> 2) as usize];
-                output[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-                output[write + 2] = A::ENCODE[((b1 & 0b0000_1111) << 2) as usize];
+                output[write] = encode_base64_value::<A>(b0 >> 2);
+                output[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+                output[write + 2] = encode_base64_value::<A>((b1 & 0b0000_1111) << 2);
                 if PAD {
                     output[write + 3] = b'=';
                 }
@@ -974,10 +994,10 @@ where
             let b1 = input[read + 1];
             let b2 = input[read + 2];
 
-            output[write] = A::ENCODE[(b0 >> 2) as usize];
-            output[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-            output[write + 2] = A::ENCODE[(((b1 & 0b0000_1111) << 2) | (b2 >> 6)) as usize];
-            output[write + 3] = A::ENCODE[(b2 & 0b0011_1111) as usize];
+            output[write] = encode_base64_value::<A>(b0 >> 2);
+            output[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+            output[write + 2] = encode_base64_value::<A>(((b1 & 0b0000_1111) << 2) | (b2 >> 6));
+            output[write + 3] = encode_base64_value::<A>(b2 & 0b0011_1111);
 
             read += 3;
             write += 4;
@@ -987,8 +1007,8 @@ where
             0 => {}
             1 => {
                 let b0 = input[read];
-                output[write] = A::ENCODE[(b0 >> 2) as usize];
-                output[write + 1] = A::ENCODE[((b0 & 0b0000_0011) << 4) as usize];
+                output[write] = encode_base64_value::<A>(b0 >> 2);
+                output[write + 1] = encode_base64_value::<A>((b0 & 0b0000_0011) << 4);
                 write += 2;
                 if PAD {
                     output[write] = b'=';
@@ -999,9 +1019,9 @@ where
             2 => {
                 let b0 = input[read];
                 let b1 = input[read + 1];
-                output[write] = A::ENCODE[(b0 >> 2) as usize];
-                output[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-                output[write + 2] = A::ENCODE[((b1 & 0b0000_1111) << 2) as usize];
+                output[write] = encode_base64_value::<A>(b0 >> 2);
+                output[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+                output[write + 2] = encode_base64_value::<A>((b1 & 0b0000_1111) << 2);
                 write += 3;
                 if PAD {
                     output[write] = b'=';
@@ -1093,14 +1113,14 @@ where
                 let b0 = buffer[read];
                 if PAD {
                     write -= 4;
-                    buffer[write] = A::ENCODE[(b0 >> 2) as usize];
-                    buffer[write + 1] = A::ENCODE[((b0 & 0b0000_0011) << 4) as usize];
+                    buffer[write] = encode_base64_value::<A>(b0 >> 2);
+                    buffer[write + 1] = encode_base64_value::<A>((b0 & 0b0000_0011) << 4);
                     buffer[write + 2] = b'=';
                     buffer[write + 3] = b'=';
                 } else {
                     write -= 2;
-                    buffer[write] = A::ENCODE[(b0 >> 2) as usize];
-                    buffer[write + 1] = A::ENCODE[((b0 & 0b0000_0011) << 4) as usize];
+                    buffer[write] = encode_base64_value::<A>(b0 >> 2);
+                    buffer[write + 1] = encode_base64_value::<A>((b0 & 0b0000_0011) << 4);
                 }
             }
             2 => {
@@ -1109,15 +1129,17 @@ where
                 let b1 = buffer[read + 1];
                 if PAD {
                     write -= 4;
-                    buffer[write] = A::ENCODE[(b0 >> 2) as usize];
-                    buffer[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-                    buffer[write + 2] = A::ENCODE[((b1 & 0b0000_1111) << 2) as usize];
+                    buffer[write] = encode_base64_value::<A>(b0 >> 2);
+                    buffer[write + 1] =
+                        encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+                    buffer[write + 2] = encode_base64_value::<A>((b1 & 0b0000_1111) << 2);
                     buffer[write + 3] = b'=';
                 } else {
                     write -= 3;
-                    buffer[write] = A::ENCODE[(b0 >> 2) as usize];
-                    buffer[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-                    buffer[write + 2] = A::ENCODE[((b1 & 0b0000_1111) << 2) as usize];
+                    buffer[write] = encode_base64_value::<A>(b0 >> 2);
+                    buffer[write + 1] =
+                        encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+                    buffer[write + 2] = encode_base64_value::<A>((b1 & 0b0000_1111) << 2);
                 }
             }
             _ => unreachable!(),
@@ -1130,10 +1152,10 @@ where
             let b1 = buffer[read + 1];
             let b2 = buffer[read + 2];
 
-            buffer[write] = A::ENCODE[(b0 >> 2) as usize];
-            buffer[write + 1] = A::ENCODE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize];
-            buffer[write + 2] = A::ENCODE[(((b1 & 0b0000_1111) << 2) | (b2 >> 6)) as usize];
-            buffer[write + 3] = A::ENCODE[(b2 & 0b0011_1111) as usize];
+            buffer[write] = encode_base64_value::<A>(b0 >> 2);
+            buffer[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+            buffer[write + 2] = encode_base64_value::<A>(((b1 & 0b0000_1111) << 2) | (b2 >> 6));
+            buffer[write + 3] = encode_base64_value::<A>(b2 & 0b0011_1111);
         }
 
         debug_assert_eq!(write, 0);