리뷰 반영

- 비공개 mlkem compress 함수 fill(0) 제거 (성능)
- ct conditional_copy_bytes fill(0) 제거 (constant-time 가정 위반 가능)
- core traits의 _out 함수 docstring에 출력 버퍼 zeroize 명시
- sha3 테스트 주석에서 이름과 변경 이력 제거
- 릴리즈 노트의 완료된 TODO 항목을 changelog로 이동

Author: Quant-TheodoreFelix

alpha_0.1.2_release_notes.md

@@ -12,8 +12,6 @@
 * Check out Megan's email May 13 about KeyMaterial: "I was wondering if there might be scope for a closure based
   approach that could
   guarantee encapsulation of the state change from safe to hazardous back to safe again."
-* Anywhere that you have an `_out(.. out: &mut [u8])`, start by zeroizing it with .fill(0); .. a good task for Claude?
-  And should be documented in the style guide?
 * Go back to previous algs and apply memory optimization tricks like internal functions. And add a docs section "Memory
   Usage" that measures with valgrind.
 * Ensure that all crates have `#![forbid(missing_docs)]`
@@ -54,5 +52,7 @@
 
 * ML-DSA
 * Low-Memory ML-DSA -- runs in about 1/10th of the usual memory (~ 30 kb of stack) with only minor performance impact.
+* All public `*_out(.., out: &mut [u8])` functions now begin by zeroizing the entire output buffer with `.fill(0)`,
+  preventing exposure of stale data in oversized output buffers or on early error returns.
 * Github issues resolved:
     * #2, or whatever

crypto/core/src/traits.rs

@@ -30,6 +30,7 @@ pub trait Hash : Default {
 
     /// A static one-shot API that hashes the provided data into the provided output slice.
     /// `data` can be of any length, including zero bytes.
+    /// The entire output buffer is zeroized before the hash output is written.
     /// The return value is the number of bytes written.
     fn hash_out(self, data: &[u8], output: &mut [u8]) -> usize;
 
@@ -50,6 +51,8 @@ pub trait Hash : Default {
     /// If the provided buffer is smaller than the hash's output length, the output will be truncated.
     /// If the provided buffor is larger than the hash's output length, the output  will be placed in
     /// the first [Hash::output_len] bytes.
+    /// The entire output buffer is zeroized before the hash output is written, so any bytes past
+    /// [Hash::output_len] will be 0.
     ///
     /// The return value is the number of bytes written.
     fn do_final_out(self, output: &mut [u8]) -> usize;
@@ -65,6 +68,7 @@ pub trait Hash : Default {
     /// The same as [Hash::do_final_out], but allows for supplying a partial byte as the last input.
     /// Assumes that the input is in the least significant bits (big endian).
     /// will be placed in the first [Hash::output_len] bytes.
+    /// The entire output buffer is zeroized before the hash output is written.
     /// The return value is the number of bytes written.
     fn do_final_partial_bits_out(
         self,
@@ -208,6 +212,7 @@ pub trait KEMPublicKey<const PK_LEN: usize> : PartialEq + Eq + Clone + Debug + D
     /// Write it out to bytes in its standard encoding.
     fn encode(&self) -> [u8; PK_LEN];
     /// Write it out to bytes in its standard encoding.
+    /// The entire output buffer is zeroized before the encoding is written.
     fn encode_out(&self, out: &mut [u8; PK_LEN]) -> usize;
     /// Read it in from bytes in its standard encoding.
     fn from_bytes(bytes: &[u8]) -> Result<Self, KEMError>;
@@ -218,6 +223,7 @@ pub trait KEMPrivateKey<const SK_LEN: usize> : PartialEq + Eq + Clone + Secret +
     /// Write it out to bytes in its standard encoding.
     fn encode(&self) -> [u8; SK_LEN];
     /// Write it out to bytes in its standard encoding.
+    /// The entire output buffer is zeroized before the encoding is written.
     fn encode_out(&self, out: &mut [u8; SK_LEN]) -> usize;
     /// Read it in from bytes in its standard encoding.
     fn from_bytes(bytes: &[u8]) -> Result<Self, KEMError>;
@@ -293,6 +299,8 @@ pub trait MAC: Sized {
     /// Depending on the underlying MAC implementation, NIST may require that the library enforce
     /// a minimum length on the mac output value. See documentation for the underlying implementation
     /// to see conditions under which it throws [MACError::InvalidLength].
+    ///
+    /// The entire output buffer is zeroized before the MAC value is written.
     fn mac_out(self, data: &[u8],out: &mut [u8]) -> Result<usize, MACError>;
 
     /// One-shot API that verifies a MAC for the provided data.
@@ -318,6 +326,8 @@ pub trait MAC: Sized {
     /// Depending on the underlying MAC implementation, NIST may require that the library enforce
     /// a minimum length on the mac output value. See documentation for the underlying implementation
     /// to see conditions under which it throws [MACError::InvalidLength].
+    ///
+    /// The entire output buffer is zeroized before the MAC value is written.
     fn do_final_out(self, out: &mut [u8]) -> Result<usize, MACError>;
 
     /// Internally, this will re-compute the MAC value and then compare it to the provided mac value
@@ -392,6 +402,7 @@ pub trait RNG : Default {
     fn next_bytes(&mut self, len: usize) -> Result<Vec<u8>, RNGError>;
 
     /// Returns the number of bytes written.
+    /// The entire output buffer is zeroized before the random bytes are written.
     fn next_bytes_out(&mut self, out: &mut [u8]) -> Result<usize, RNGError>;
 
     fn fill_keymaterial_out(&mut self, out: &mut impl KeyMaterialTrait) -> Result<usize, RNGError>;
@@ -443,6 +454,7 @@ pub trait PHSignature<
     /// might throw an error, ignore the provided ctx value, or append the ctx to the msg in a non-standard way.
     fn sign_ph(sk: &SK, ph: &[u8; PH_LEN], ctx: Option<&[u8]>) -> Result<[u8; SIG_LEN], SignatureError>;
     /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
+    /// The entire output buffer is zeroized before the signature is written.
     fn sign_ph_out(sk: &SK, ph: &[u8; PH_LEN], ctx: Option<&[u8]>, output: &mut [u8; SIG_LEN]) -> Result<usize, SignatureError>;
     /// On success, returns Ok(())
     /// On failure, returns Err([SignatureError::SignatureVerificationFailed]); may also return other types of [SignatureError] as appropriate (such as for invalid-length inputs).
@@ -501,6 +513,7 @@ pub trait Signature<
     fn sign(sk: &SK, msg: &[u8], ctx: Option<&[u8]>) -> Result<[u8; SIG_LEN], SignatureError>;
 
     /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
+    /// The entire output buffer is zeroized before the signature is written.
     fn sign_out(sk: &SK, msg: &[u8], ctx: Option<&[u8]>, output: &mut [u8; SIG_LEN]) -> Result<usize, SignatureError>;
 
     /* streaming signing API */
@@ -516,6 +529,7 @@ pub trait Signature<
     fn sign_final(self) -> Result<[u8; SIG_LEN], SignatureError>;
 
     /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
+    /// The entire output buffer is zeroized before the signature is written.
     fn sign_final_out(self, output: &mut [u8; SIG_LEN]) -> Result<usize, SignatureError>;
 
     /// On success, returns Ok(())
@@ -543,6 +557,7 @@ pub trait SignaturePublicKey<const PK_LEN: usize> : PartialEq + Eq + Clone + Deb
     /// Write it out to bytes in its standard encoding.
     fn encode(&self) -> [u8; PK_LEN];
     /// Write it out to bytes in its standard encoding.
+    /// The entire output buffer is zeroized before the encoding is written.
     fn encode_out(&self, out: &mut [u8; PK_LEN]) -> usize;
     /// Read it in from bytes in its standard encoding.
     fn from_bytes(bytes: &[u8]) -> Result<Self, SignatureError>;
@@ -553,6 +568,7 @@ pub trait SignaturePrivateKey<const SK_LEN: usize> : PartialEq + Eq + Clone + Se
     /// Write it out to bytes in its standard encoding.
     fn encode(&self) -> [u8; SK_LEN];
     /// Write it out to bytes in its standard encoding.
+    /// The entire output buffer is zeroized before the encoding is written.
     fn encode_out(&self, out: &mut [u8; SK_LEN]) -> usize;
     /// Read it in from bytes in its standard encoding.
     fn from_bytes(bytes: &[u8]) -> Result<Self, SignatureError>;
@@ -583,6 +599,7 @@ pub trait XOF : Default {
 
     /// A static one-shot API that digests the input data and produces `result_len` bytes of output.
     /// Fills the provided output slice.
+    /// The entire output buffer is zeroized before the output is written.
     fn hash_xof_out(self, data: &[u8], output: &mut [u8]) -> usize;
 
     fn absorb(&mut self, data: &[u8]);
@@ -599,13 +616,16 @@ pub trait XOF : Default {
 
     /// Can be called multiple times.
     /// Fills the provided output slice.
+    /// The entire output buffer is zeroized before the output is written.
     fn squeeze_out(&mut self, output: &mut [u8]) -> usize;
 
     /// Squeezes a partial byte from the XOF.
     /// Output will be in the top `num_bits` bits of the returned u8 (ie Big Endian).
     /// This is a final call and consumes self.
     fn squeeze_partial_byte_final(self, num_bits: usize) -> Result<u8, HashError>;
 
+    /// The same as [XOF::squeeze_partial_byte_final], but writes into the provided output byte.
+    /// The output byte is zeroized before the result is written.
     fn squeeze_partial_byte_final_out(
         self,
         num_bits: usize,

crypto/mlkem/src/matrix.rs

@@ -171,8 +171,6 @@ impl<const k: usize> Vector<k>
         // let mut s = self.clone();
         // s.conditional_sub_q();
 
-        out.fill(0);
-
         let mut idx = 0;
         match du {
             10 => { // MLKEM512 and MLKEM 768

crypto/mlkem/src/polynomial.rs

@@ -127,8 +127,6 @@ impl Polynomial {
         // each of the N i16's will take dv bits
         debug_assert_eq!(out.len(), N * (dv as usize) / 8);
 
-        out.fill(0);
-
         let mut t = [0u8; 8];
         let mut idx = 0;
 

crypto/mlkem_lowmemory/src/polynomial.rs

@@ -150,8 +150,6 @@ impl Polynomial {
         // each of the N i16's will take dv bits
         debug_assert_eq!(out.len(), N * (dv as usize) / 8);
 
-        out.fill(0);
-
         let mut t = [0u8; 8];
         let mut idx = 0;
 

crypto/sha3/tests/sha3_tests.rs

@@ -66,10 +66,7 @@ mod sha3_tests {
         assert_eq!(&out, b"\x58\x4c\xc7\x02\xc2\x22\x9a\x0a\xbc\x78\x9b\xfa\x64\xb4\x27\x1f\xb8\xf0\xbb\x78\x67\x15\x88\xb9\xef\x1d\x09\x3e\xa3\xd4\x72\x58\x4c\x6d\x43\xb5\x68\x33\x59\x47\x2f\x44\x1b\x33\x85\x6f\x68\x28\x59\xf0\xc3\x95\x4b\x56\x80\x8f\xd1\xfb\xa0\xb5\x9c\x9d\x19\x54");
         assert_eq!(bytes_written, 64);
 
-        // Q. T. Felix NOTE: With the application of zeroize, the entire output buffer is pre-initialized to 0, 
-        //                   so the bytes after the digest length are now also 0. 
-        //                   Previously, the contract was to leave the trailing bytes untouched, 
-        //                   but this has been changed to fill them with zeros to prevent exposure of stale data.
+        // check that the bytes of an oversized output buffer past the digest length get zeroized.
         let mut out = DUMMY_SEED_512.clone();
         SHA3_256::new().hash_out(DUMMY_SEED_512, &mut out);
         assert!(out[32..].iter().all(|&b| b == 0));

crypto/utils/src/ct.rs

@@ -292,8 +292,6 @@ pub fn conditional_copy_bytes<const LEN: usize>(
     out: &mut [u8; LEN],
     take_a: bool,
 ) {
-    out.fill(0);
-
     // we want the behaviour of
     //  if take_a { 0xFF } else { 0x00 }
     // but without using any branches that could leak timing signals