Merge branch 'Quant-TheodoreFelix-qtfelix/0.1.2alpha-zeroize-out-buffers' into release/0.1.2alpha. Closes #18

Author: ounsworth

.github/workflows/rust-style.yml

@@ -0,0 +1,28 @@
+name: Rust Style
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: rust-style-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rustfmt:
+    if: github.repository == 'bcgit/bc-rust'
+    name: rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install nightly rustfmt
+        run: |
+          rustup toolchain install nightly --profile minimal --component rustfmt
+          rustup override set nightly
+
+      - name: Check formatting
+        run: cargo fmt --all --check

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

cli/src/encoders_cmd.rs

@@ -1,17 +1,17 @@
 use std::io;
 use std::io::{Read, Write};
 
-use bouncycastle::hex;
 use bouncycastle::base64;
+use bouncycastle::hex;
 
 pub(crate) fn hex_encode_cmd() {
     // Stream from stdin to stdout in chunks of 1 kb
     let mut buf: [u8; 1024] = [0u8; 1024];
     let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     while bytes_read != 0 {
-        io::stdout().write_all(
-            hex::encode(&buf[..bytes_read]).as_bytes()
-        ).expect("Failed to write to stdout");
+        io::stdout()
+            .write_all(hex::encode(&buf[..bytes_read]).as_bytes())
+            .expect("Failed to write to stdout");
 
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
@@ -22,13 +22,12 @@ pub(crate) fn hex_decode_cmd() {
     let mut buf: [u8; 1024] = [0u8; 1024];
     let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     while bytes_read != 0 {
-        let chunk_str: String = String::from_utf8(
-            Vec::from(&buf[..bytes_read])
-        ).expect("Input was not valid utf8.");
+        let chunk_str: String =
+            String::from_utf8(Vec::from(&buf[..bytes_read])).expect("Input was not valid utf8.");
 
-        io::stdout().write_all(
-            &*hex::decode(chunk_str.as_str()).expect("Input was not valid hex.")
-        ).expect("Failed to write to stdout");
+        io::stdout()
+            .write_all(&*hex::decode(chunk_str.as_str()).expect("Input was not valid hex."))
+            .expect("Failed to write to stdout");
 
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
@@ -40,9 +39,9 @@ pub(crate) fn base64_encode_cmd() {
     let mut buf: [u8; 1024] = [0u8; 1024];
     let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     while bytes_read != 0 {
-        io::stdout().write_all(
-            encoder.do_update(&buf[..bytes_read]).as_bytes()
-        ).expect("Failed to write to stdout");
+        io::stdout()
+            .write_all(encoder.do_update(&buf[..bytes_read]).as_bytes())
+            .expect("Failed to write to stdout");
 
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
@@ -54,14 +53,18 @@ pub(crate) fn base64_decode_cmd() {
     let mut decoder = base64::Base64Decoder::new(true);
     let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     while bytes_read != 0 {
-        let chunk_str: String = String::from_utf8(
-            Vec::from(&buf[..bytes_read])
-        ).expect("Input was not valid utf8.");
+        let chunk_str: String =
+            String::from_utf8(Vec::from(&buf[..bytes_read])).expect("Input was not valid utf8.");
 
-        io::stdout().write_all(
-            decoder.do_update(chunk_str.as_str()).expect("Input was not valid base64.").as_slice()
-        ).expect("Failed to write to stdout");
+        io::stdout()
+            .write_all(
+                decoder
+                    .do_update(chunk_str.as_str())
+                    .expect("Input was not valid base64.")
+                    .as_slice(),
+            )
+            .expect("Failed to write to stdout");
 
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
-}
+}

cli/src/helpers.rs

@@ -1,31 +1,31 @@
-use std::{io};
+use bouncycastle::core::key_material::{KeyMaterial, KeyMaterialTrait, KeyType};
+use bouncycastle::core::traits::SecurityStrength;
+use bouncycastle::hex;
 use std::fs::File;
+use std::io;
 use std::io::{Read, Write};
 use std::process::exit;
-use bouncycastle::core::key_material::{KeyMaterial, KeyMaterialTrait, KeyType};
-use bouncycastle::core::traits::{SecurityStrength};
-use bouncycastle::hex;
 
 /// Reads either bin or hex
 pub(crate) fn read_from_file(filename: &str) -> Vec<u8> {
     let file = File::open(&filename);
     if file.is_ok() {
         let mut buf = Vec::<u8>::new();
         match file.unwrap().read_to_end(&mut buf) {
-            Ok(_bytes_read) => { 
+            Ok(_bytes_read) => {
                 // try hex decoding it
                 match hex::decode(&buf) {
-                    Ok(decoded) => { decoded },
+                    Ok(decoded) => decoded,
                     Err(_) => {
                         // well, it's not hex, so return it raw
                         buf
-                    },
+                    }
                 }
-            },
+            }
             Err(_) => {
                 eprintln!("Error: couldn't open file '{}'", &filename);
                 exit(-1);
-            },
+            }
         }
     } else {
         eprintln!("Error: couldn't open file '{}'", &filename);
@@ -35,22 +35,21 @@ pub(crate) fn read_from_file(filename: &str) -> Vec<u8> {
 
 /// Reads either bin or hex
 pub(crate) fn read_from_file_or_stdin(filename: &Option<String>) -> Vec<u8> {
-    
     if filename.is_some() {
         // This already reads either bin or hex
         return read_from_file(filename.as_ref().unwrap());
     }
-    
+
     let mut buf = Vec::<u8>::new();
     io::stdin().read_to_end(&mut buf).expect("Failed to read from stdin");
 
     // try hex decoding it
     match hex::decode(&buf) {
-        Ok(decoded) => { decoded },
+        Ok(decoded) => decoded,
         Err(_) => {
             // well, it's not hex, so return it raw
             buf
-        },
+        }
     }
 }
 
@@ -84,15 +83,15 @@ pub(crate) fn parse_seed<const SEED_LEN: usize>(bytes: &[u8]) -> Result<KeyMater
     // try decoding it as hex first
     let seed_bytes: [u8; SEED_LEN] = match &hex::decode(&bytes) {
         Ok(decoded_bytes) => {
-            if decoded_bytes.len() < SEED_LEN || decoded_bytes.len() > SEED_LEN +1  {
+            if decoded_bytes.len() < SEED_LEN || decoded_bytes.len() > SEED_LEN + 1 {
                 // it was valid hex, but the wrong length
                 return Err(());
             }
             decoded_bytes[..SEED_LEN].try_into().unwrap()
         }
         Err(_) => {
             // it's not hex, so take the fist SEED_LEN bytes of the raw binary
-            if bytes.len() < SEED_LEN || bytes.len() > SEED_LEN +1 {
+            if bytes.len() < SEED_LEN || bytes.len() > SEED_LEN + 1 {
                 return Err(());
             }
             bytes[..SEED_LEN].try_into().unwrap()
@@ -113,4 +112,4 @@ pub(crate) fn parse_seed<const SEED_LEN: usize>(bytes: &[u8]) -> Result<KeyMater
         seed.drop_hazardous_operations();
     }
     Ok(seed)
-}
+}

cli/src/hkdf_cmd.rs

@@ -1,20 +1,22 @@
-use std::{fs, io};
 use std::io::Write;
 use std::process::exit;
+use std::{fs, io};
 
 use bouncycastle::core::key_material::{KeyMaterial, KeyMaterialTrait, KeyType};
 use bouncycastle::hex;
 use bouncycastle::hkdf;
 
-pub(crate) fn hkdf_cmd(hkdfname: &str,
-                       salt: &Option<String>,
-                       salt_file: &Option<String>,
-                       ikm: &Option<String>,
-                       ikm_file: &Option<String>,
-                       additional_input: &Option<String>,
-                       additional_input_file: &Option<String>,
-                       len: usize,
-                       output_hex: bool ) {
+pub(crate) fn hkdf_cmd(
+    hkdfname: &str,
+    salt: &Option<String>,
+    salt_file: &Option<String>,
+    ikm: &Option<String>,
+    ikm_file: &Option<String>,
+    additional_input: &Option<String>,
+    additional_input_file: &Option<String>,
+    len: usize,
+    output_hex: bool,
+) {
     let salt_bytes: Vec<u8>;
     let ikm_bytes: Vec<u8>;
     let additional_input_bytes: Vec<u8>;
@@ -53,7 +55,6 @@ pub(crate) fn hkdf_cmd(hkdfname: &str,
         exit(-1)
     };
 
-
     additional_input_bytes = if additional_input.is_some() {
         hex::decode(additional_input.as_ref().unwrap()).unwrap()
     } else if additional_input.is_some() {
@@ -72,21 +73,24 @@ pub(crate) fn hkdf_cmd(hkdfname: &str,
             h.do_extract_update_bytes(ikm_bytes.as_slice()).unwrap();
             h.do_extract_update_bytes(additional_input_bytes.as_slice()).unwrap();
             h.do_extract_final_out(&mut out_key).unwrap();
-        },
+        }
         "HKDF-SHA512" => {
             let mut h = hkdf::HKDF_SHA512::new();
             h.do_extract_init(&salt_key).unwrap();
             h.do_extract_update_bytes(ikm_bytes.as_slice()).unwrap();
             h.do_extract_update_bytes(additional_input_bytes.as_slice()).unwrap();
             h.do_extract_final_out(&mut out_key).unwrap();
-        },
-        _ => { panic!("{} is not a supported HKDF variant.", hkdfname); }
+        }
+        _ => {
+            panic!("{} is not a supported HKDF variant.", hkdfname);
+        }
     }
 
-
     if output_hex {
         for b in out_key.ref_to_bytes().iter() {
             print!("{b:02x}");
         }
-    } else { io::stdout().write(&out_key.ref_to_bytes()).unwrap(); }
-}
+    } else {
+        io::stdout().write(&out_key.ref_to_bytes()).unwrap();
+    }
+}

cli/src/mac_cmd.rs

@@ -37,21 +37,19 @@ pub(crate) fn mac_cmd(
     key.allow_hazardous_operations();
     key.convert_key_type(KeyType::MACKey).unwrap();
 
-
     // instantiate the MAC object and call do_mac()
     match hmac_variant {
         HMACVariant::SHA256 => {
             let mac = HMAC_SHA256::new_allow_weak_key(&key).unwrap();
             do_mac(mac, verify_val, output_hex);
-        },
+        }
         HMACVariant::SHA512 => {
             let mac = HMAC_SHA512::new_allow_weak_key(&key).unwrap();
             do_mac(mac, verify_val, output_hex);
         }
     }
 }
 
-
 fn do_mac(mut mac: impl MAC, verify_val: &Option<String>, output_hex: bool) {
     // read the content to be MAC'd from stdin
     let mut buf: [u8; 1024] = [0u8; 1024];