Harden Tokio cancellation cleanup

Author: eldryoth

CHANGELOG.md

@@ -11,13 +11,18 @@
   release-toolchain pin.
 - Updated test-only byte iteration syntax for the Rust `1.97.0` Clippy policy.
 - Updated constant-time assembly evidence parsing for Rust `1.97.0`'s default
-  v0 symbol mangling while preserving legacy-symbol compatibility.
+  v0 symbol mangling while preserving legacy-symbol compatibility and requiring
+  concrete text-section definitions for both formats.
 - Updated `base64-ng-bytes` to `bytes` `1.12.1` and
   `base64-ng-sanitization` to exact-pinned `sanitization` `1.2.4`.
 - Pinned GitHub Actions to the latest audited releases: checkout `v6.0.2`,
   rust-cache `v2.9.1`, and install-action `v2.83.0`.
 - Added exact-version cargo-nextest installation and the 210-test nextest suite
   to GitHub CI, with install-action fallback disabled.
+- Hardened Tokio companion cleanup with volatile wipes for fixed reader
+  buffers and RAII-wiped read-all allocations that also cover cancellation.
+- Bounded Tokio limited-helper over-read to one lookahead byte and documented
+  the adjacent-frame contract.
 - Pinned documented release-tool installs to the audited current versions,
   including cargo-nextest `0.9.140` and cargo-fuzz `0.13.2`.
 - Deferred the stronger RISC-V RVV proof and backend-admission review to

README.md

@@ -384,7 +384,10 @@ assert!(decoded.subtle_verify(b"hello"));
 `base64-ng-tokio` provides read-all/write-all async helpers and manual
 `AsyncRead`/`AsyncWrite` streaming adapters for applications that already use
 Tokio. Prefer the `*_limited` helper variants for request or frame boundaries
-controlled by a peer:
+controlled by a peer. Read-all temporary allocations are RAII-wiped on return,
+error, and cancellation. Limited helpers may consume one lookahead byte to
+detect overflow, so use an already bounded reader when adjacent input must
+remain unread:
 
 ```toml
 [dependencies]

crates/base64-ng-tokio/README.md

@@ -33,6 +33,11 @@ variants when input size is controlled by a peer or request boundary. Writer
 shutdown is the finalization boundary: call `AsyncWriteExt::shutdown` to encode
 or validate a final partial quantum.
 
+Read-all helper allocations are RAII-wiped on success, error, and cancellation.
+Limited helpers consume no more than the configured limit plus one lookahead
+byte used to detect overflow. Use a separately bounded reader or a streaming
+adapter when an adjacent frame's first byte must remain unread.
+
 ```rust
 use base64_ng::STANDARD;
 use base64_ng_tokio::{encode_reader_to_writer_limited, EncoderReader, EncoderWriter};

crates/base64-ng-tokio/src/lib.rs

@@ -18,11 +18,12 @@
 //!
 //! # Security
 //!
-//! The read-all helpers use temporary `Vec<u8>` allocations and the normal
-//! strict decode path. They wipe those temporary vectors before returning, but
-//! they are not constant-time-oriented token validators or high-assurance
-//! secret decoders. For secret-bearing async frames, collect a bounded frame
-//! under the application's approved memory policy and decode through
+//! The read-all helpers use RAII-guarded temporary `Vec<u8>` allocations and
+//! the normal strict decode path. The guards wipe initialized bytes and spare
+//! capacity on ordinary return, I/O error, or future cancellation. They are
+//! not constant-time-oriented token validators or high-assurance secret
+//! decoders. For secret-bearing async frames, collect a bounded frame under
+//! the application's approved memory policy and decode through
 //! `base64_ng::ct`, staged CT decode, `base64-ng-derive`, or
 //! `base64-ng-sanitization`.
 
@@ -56,20 +57,15 @@ where
     R: AsyncRead + Unpin + ?Sized,
     W: AsyncWrite + Unpin + ?Sized,
 {
-    let mut input = Vec::new();
-    reader.read_to_end(&mut input).await?;
-    let mut output = match engine.encode_vec(&input).map_err(encode_io_error) {
-        Ok(output) => output,
-        Err(error) => {
-            wipe_bytes(&mut input);
-            return Err(error);
-        }
-    };
+    let mut input = WipingVec::new();
+    reader.read_to_end(input.as_mut_vec()).await?;
+    let output = WipingVec::from_vec(
+        engine
+            .encode_vec(input.as_slice())
+            .map_err(encode_io_error)?,
+    );
     let written = output.len() as u64;
-    let result = writer.write_all(&output).await;
-    wipe_bytes(&mut input);
-    wipe_bytes(&mut output);
-    result?;
+    writer.write_all(output.as_slice()).await?;
     Ok(written)
 }
 
@@ -95,19 +91,14 @@ where
     R: AsyncRead + Unpin + ?Sized,
     W: AsyncWrite + Unpin + ?Sized,
 {
-    let mut input = read_to_end_limited(reader, max_input_len).await?;
-    let mut output = match engine.encode_vec(&input).map_err(encode_io_error) {
-        Ok(output) => output,
-        Err(error) => {
-            wipe_bytes(&mut input);
-            return Err(error);
-        }
-    };
+    let input = read_to_end_limited(reader, max_input_len).await?;
+    let output = WipingVec::from_vec(
+        engine
+            .encode_vec(input.as_slice())
+            .map_err(encode_io_error)?,
+    );
     let written = output.len() as u64;
-    let result = writer.write_all(&output).await;
-    wipe_bytes(&mut input);
-    wipe_bytes(&mut output);
-    result?;
+    writer.write_all(output.as_slice()).await?;
     Ok(written)
 }
 
@@ -130,20 +121,15 @@ where
     R: AsyncRead + Unpin + ?Sized,
     W: AsyncWrite + Unpin + ?Sized,
 {
-    let mut input = Vec::new();
-    reader.read_to_end(&mut input).await?;
-    let mut output = match engine.decode_vec(&input).map_err(decode_io_error) {
-        Ok(output) => output,
-        Err(error) => {
-            wipe_bytes(&mut input);
-            return Err(error);
-        }
-    };
+    let mut input = WipingVec::new();
+    reader.read_to_end(input.as_mut_vec()).await?;
+    let output = WipingVec::from_vec(
+        engine
+            .decode_vec(input.as_slice())
+            .map_err(decode_io_error)?,
+    );
     let written = output.len() as u64;
-    let result = writer.write_all(&output).await;
-    wipe_bytes(&mut input);
-    wipe_bytes(&mut output);
-    result?;
+    writer.write_all(output.as_slice()).await?;
     Ok(written)
 }
 
@@ -169,19 +155,14 @@ where
     R: AsyncRead + Unpin + ?Sized,
     W: AsyncWrite + Unpin + ?Sized,
 {
-    let mut input = read_to_end_limited(reader, max_input_len).await?;
-    let mut output = match engine.decode_vec(&input).map_err(decode_io_error) {
-        Ok(output) => output,
-        Err(error) => {
-            wipe_bytes(&mut input);
-            return Err(error);
-        }
-    };
+    let input = read_to_end_limited(reader, max_input_len).await?;
+    let output = WipingVec::from_vec(
+        engine
+            .decode_vec(input.as_slice())
+            .map_err(decode_io_error)?,
+    );
     let written = output.len() as u64;
-    let result = writer.write_all(&output).await;
-    wipe_bytes(&mut input);
-    wipe_bytes(&mut output);
-    result?;
+    writer.write_all(output.as_slice()).await?;
     Ok(written)
 }
 
@@ -227,37 +208,85 @@ fn wipe_bytes(bytes: &mut [u8]) {
     base64_ng::secure_wipe(bytes);
 }
 
-async fn read_to_end_limited<R>(reader: &mut R, max_input_len: usize) -> io::Result<Vec<u8>>
+struct WipingVec(Vec<u8>);
+
+impl WipingVec {
+    fn new() -> Self {
+        Self(Vec::new())
+    }
+
+    fn with_capacity(capacity: usize) -> Self {
+        Self(Vec::with_capacity(capacity))
+    }
+
+    fn from_vec(bytes: Vec<u8>) -> Self {
+        Self(bytes)
+    }
+
+    fn as_slice(&self) -> &[u8] {
+        &self.0
+    }
+
+    fn as_mut_vec(&mut self) -> &mut Vec<u8> {
+        &mut self.0
+    }
+
+    fn len(&self) -> usize {
+        self.0.len()
+    }
+}
+
+impl Drop for WipingVec {
+    fn drop(&mut self) {
+        // Initialize the existing spare capacity without reallocating so the
+        // reviewed wipe primitive covers the complete allocation.
+        self.0.resize(self.0.capacity(), 0);
+        wipe_bytes(&mut self.0);
+        self.0.clear();
+    }
+}
+
+struct WipingArray<const N: usize>([u8; N]);
+
+impl<const N: usize> WipingArray<N> {
+    const fn new() -> Self {
+        Self([0; N])
+    }
+}
+
+impl<const N: usize> Drop for WipingArray<N> {
+    fn drop(&mut self) {
+        wipe_bytes(&mut self.0);
+    }
+}
+
+async fn read_to_end_limited<R>(reader: &mut R, max_input_len: usize) -> io::Result<WipingVec>
 where
     R: AsyncRead + Unpin + ?Sized,
 {
-    let mut input = Vec::with_capacity(max_input_len.min(READ_ALL_EAGER_CAP));
-    let mut chunk = [0u8; 8192];
+    let mut input = WipingVec::with_capacity(max_input_len.min(READ_ALL_EAGER_CAP));
+    let mut chunk = WipingArray::<8192>::new();
 
     loop {
-        let read = match reader.read(&mut chunk).await {
-            Ok(read) => read,
-            Err(error) => {
-                wipe_bytes(&mut chunk);
-                wipe_bytes(&mut input);
-                return Err(error);
-            }
+        let remaining = max_input_len - input.len();
+        let read_cap = if remaining < chunk.0.len() {
+            remaining + 1
+        } else {
+            chunk.0.len()
         };
+        let read = reader.read(&mut chunk.0[..read_cap]).await?;
         if read == 0 {
-            wipe_bytes(&mut chunk);
             return Ok(input);
         }
 
-        if read > max_input_len.saturating_sub(input.len()) {
-            wipe_bytes(&mut chunk);
-            wipe_bytes(&mut input);
+        if read > remaining {
             return Err(io::Error::new(
                 io::ErrorKind::InvalidData,
                 "base64-ng-tokio input exceeds configured limit",
             ));
         }
 
-        input.extend_from_slice(&chunk[..read]);
-        wipe_bytes(&mut chunk);
+        input.0.extend_from_slice(&chunk.0[..read]);
+        wipe_bytes(&mut chunk.0);
     }
 }

crates/base64-ng-tokio/src/readers.rs

@@ -71,9 +71,9 @@ where
     }
 
     fn clear_buffers(&mut self) {
-        self.pending.fill(0);
+        wipe_bytes(&mut self.pending);
         self.pending_len = 0;
-        self.output.fill(0);
+        wipe_bytes(&mut self.output);
         self.output_pos = 0;
         self.output_len = 0;
     }
@@ -289,9 +289,9 @@ where
     }
 
     fn clear_buffers(&mut self) {
-        self.pending.fill(0);
+        wipe_bytes(&mut self.pending);
         self.pending_len = 0;
-        self.output.fill(0);
+        wipe_bytes(&mut self.output);
         self.output_pos = 0;
         self.output_len = 0;
     }

crates/base64-ng-tokio/tests/tokio.rs

@@ -28,6 +28,16 @@ impl ScriptedReader {
             actions: actions.into_iter().collect(),
         }
     }
+
+    fn remaining_data_len(&self) -> usize {
+        self.actions
+            .iter()
+            .map(|action| match action {
+                ReadAction::Data(bytes) => bytes.len(),
+                ReadAction::Error | ReadAction::Pending => 0,
+            })
+            .sum()
+    }
 }
 
 impl AsyncRead for ScriptedReader {
@@ -135,6 +145,22 @@ async fn limited_decode_reports_oversized_input_before_writing() {
     assert_eq!(output, b"untouched");
 }
 
+#[tokio::test]
+async fn limited_helpers_consume_at_most_limit_plus_one_byte() {
+    let input_len = 16_384;
+    let limit = 100;
+    let mut input = ScriptedReader::new([ReadAction::Data(vec![b'x'; input_len])]);
+    let mut output = b"untouched".to_vec();
+
+    let error = encode_reader_to_writer_limited(&STANDARD, &mut input, &mut output, limit)
+        .await
+        .unwrap_err();
+
+    assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
+    assert_eq!(input.remaining_data_len(), input_len - limit - 1);
+    assert_eq!(output, b"untouched");
+}
+
 #[tokio::test]
 async fn limited_reader_helpers_round_trip_at_limit() {
     let mut input = &b"hello"[..];

docs/ASYNC.md

@@ -12,6 +12,13 @@ input size before writing output. Its `EncoderReader`, `DecoderReader`,
 `EncoderWriter`, and `DecoderWriter` adapters use explicit state machines,
 fixed internal buffers, and drop cleanup.
 
+Read-all helper allocations are held behind RAII guards before the first
+suspension point. Their initialized bytes and spare capacity are wiped on
+success, I/O error, or future cancellation. Limited helpers request at most the
+remaining allowance plus one lookahead byte. Generic `AsyncRead` cannot return
+that lookahead byte to the source; callers that must preserve adjacent framed
+input should provide an already bounded reader or use a streaming adapter.
+
 ## Current Status
 
 - The `stream` feature provides `std::io` streaming wrappers.
@@ -22,7 +29,7 @@ fixed internal buffers, and drop cleanup.
   the crate today.
 - `base64-ng-tokio` provides optional read-all/write-all helpers for projects
   that already admit Tokio. Prefer its limited helpers for peer-controlled
-  input.
+  input. Their temporary allocations use cancellation-safe RAII cleanup.
 - `base64-ng-tokio` also provides streaming adapters: `EncoderReader`,
   `DecoderReader`, `EncoderWriter`, and `DecoderWriter`.
 - Async writer shutdown is the finalization boundary. Call

docs/CT_ASM_REVIEW.md

@@ -43,8 +43,9 @@ Review focus:
 - Does generated code keep the scalar ct path independent from SIMD dispatch?
 - Does `ct_error_gate_barrier` remain a separate non-inlined symbol in release
   and LTO artifacts before opaque malformed-input reporting?
-- Do the automated symbol checks find the required boundaries under both
-  legacy Rust mangling and Rust `1.97.0`'s default v0 mangling?
+- Do the automated symbol checks find concrete text-section definitions for
+  the required boundaries under both legacy Rust mangling and Rust `1.97.0`'s
+  default v0 mangling?
 - Does `constant_time_eq_public_len` remain a separate non-inlined symbol in
   release and LTO artifacts, and does the equal-length loop scan all bytes
   rather than lowering into an early-exit compare?

release-notes/RELEASE_NOTES_1.3.7.md

@@ -14,13 +14,18 @@ the `base64-ng` crate family.
   the release-toolchain pin.
 - Updated test-only byte iteration syntax for Rust `1.97.0` Clippy.
 - Updated the constant-time assembly evidence parser for Rust `1.97.0`'s v0
-  symbols while retaining compatibility with legacy Rust symbol mangling.
+  symbols while retaining compatibility with legacy Rust symbol mangling and
+  requiring concrete text-section definitions for both formats.
 - Updated the optional bytes and sanitization companions to `bytes` `1.12.1`
   and exact-pinned `sanitization` `1.2.4`.
 - Pinned GitHub Actions to checkout `v6.0.2`, rust-cache `v2.9.1`, and
   install-action `v2.83.0`, using their verified release commits.
 - Added the 210-test nextest suite to GitHub CI and disabled install-action
   fallback installation.
+- Hardened Tokio reader-buffer cleanup and made read-all temporary allocations
+  wipe through RAII on success, error, and cancellation.
+- Limited oversized-input detection to one lookahead byte and documented the
+  adjacent-frame behavior for generic `AsyncRead` sources.
 - Pinned documented release/deep-check tool versions to the current audited
   releases, including cargo-nextest `0.9.140` and cargo-fuzz `0.13.2`.
 - Scheduled the stronger RISC-V RVV proof and backend-admission review for