♻️ Replace GCM header offset arithmetic with StreamHeader newtype

ChanTsune · ChanTsune · commit 9607f5b59ecb · 2026-07-13T10:52:47.000+09:00
CipherContext was an untagged union whose iv/key meaning depended on the
mode field, with the 43-byte stream header layout duplicated across the
write-side builder, its re-parser, and the read side. StreamHeader now
owns the layout (to_bytes/try_from_bytes, including the segment size
range check), and CipherPayload makes the block/GCM distinction a tagged
enum, removing gcm_stream_params and its panicking slice expects.
diff --git a/lib/src/archive/write.rs b/lib/src/archive/write.rs
@@ -379,7 +379,7 @@ impl<W: Write> Archive<W> {
         (ChunkType::SHED, header.to_bytes()).write_chunk_in(&mut self.inner)?;
         if let Some(WriteCipher { context: c, .. }) = &context.cipher {
             (ChunkType::PHSF, c.phsf.as_bytes()).write_chunk_in(&mut self.inner)?;
-            (ChunkType::SDAT, c.iv.as_slice()).write_chunk_in(&mut self.inner)?;
+            (ChunkType::SDAT, c.prefix_bytes().as_slice()).write_chunk_in(&mut self.inner)?;
         }
         self.inner.flush()?;
         let max_chunk_size = self.max_chunk_size;
@@ -593,7 +593,7 @@ where
     let context = get_writer_context(option, &header.to_bytes(), StreamKind::PerEntry)?;
     if let Some(WriteCipher { context: c, .. }) = &context.cipher {
         (ChunkType::PHSF, c.phsf.as_bytes()).write_chunk_in(inner)?;
-        (ChunkType::FDAT, &c.iv[..]).write_chunk_in(inner)?;
+        (ChunkType::FDAT, c.prefix_bytes().as_slice()).write_chunk_in(inner)?;
     }
     let inner = {
         let writer = ChunkStreamWriter::new(ChunkType::FDAT, inner, max_chunk_size);
diff --git a/lib/src/cipher.rs b/lib/src/cipher.rs
@@ -7,7 +7,7 @@ mod stream;
 
 use crate::io::TryIntoInner;
 pub(crate) use aead::{
-    DEFAULT_SEGMENT_SIZE, MAX_SEGMENT_SIZE, STREAM_HEADER_LEN, StreamKind, derive_stream_key,
+    DEFAULT_SEGMENT_SIZE, STREAM_HEADER_LEN, StreamHeader, StreamKind, derive_stream_key,
 };
 #[cfg(test)]
 pub(crate) use aead::{GCM_TAG_LEN, segment_nonce};
diff --git a/lib/src/cipher/aead.rs b/lib/src/cipher/aead.rs
@@ -6,6 +6,7 @@
 //! `PHSF` bytes; each segment's 96-bit nonce is derived from the stream's nonce
 //! prefix, a segment counter, and a final-segment marker.
 
+use crate::error::AeadError;
 use hkdf::Hkdf;
 use sha2::{Digest, Sha256};
 
@@ -15,6 +16,36 @@ pub(crate) const MAX_SEGMENT_SIZE: u32 = 67_108_864; // 64 MiB
 pub(crate) const DEFAULT_SEGMENT_SIZE: u32 = 1_048_576; // 1 MiB
 const DOMAIN_TAG: &[u8; 13] = b"PNA-STREAM-v1";
 
+/// On-wire GCM stream header: `salt(32) || nonce_prefix(7) || segment_size(u32 BE)`.
+#[derive(Debug)]
+pub(crate) struct StreamHeader {
+    pub(crate) salt: [u8; 32],
+    pub(crate) nonce_prefix: [u8; 7],
+    pub(crate) segment_size: u32,
+}
+
+impl StreamHeader {
+    pub(crate) fn to_bytes(&self) -> [u8; STREAM_HEADER_LEN] {
+        let mut bytes = [0u8; STREAM_HEADER_LEN];
+        bytes[..32].copy_from_slice(&self.salt);
+        bytes[32..39].copy_from_slice(&self.nonce_prefix);
+        bytes[39..43].copy_from_slice(&self.segment_size.to_be_bytes());
+        bytes
+    }
+
+    pub(crate) fn try_from_bytes(bytes: &[u8; STREAM_HEADER_LEN]) -> Result<Self, AeadError> {
+        let segment_size = u32::from_be_bytes(bytes[39..43].try_into().unwrap());
+        if segment_size == 0 || segment_size > MAX_SEGMENT_SIZE {
+            return Err(AeadError::Malformed("segment size out of range"));
+        }
+        Ok(Self {
+            salt: bytes[..32].try_into().unwrap(),
+            nonce_prefix: bytes[32..39].try_into().unwrap(),
+            segment_size,
+        })
+    }
+}
+
 #[derive(Copy, Clone, Debug)]
 pub(crate) enum StreamKind {
     PerEntry,
@@ -94,6 +125,67 @@ mod tests {
         0xc5, 0xbf, 0x34, 0x00, 0x72, 0x08, 0xd5, 0xb8, 0x87, 0x18, 0x58, 0x65,
     ];
 
+    #[test]
+    fn stream_header_roundtrips_through_bytes() {
+        let header = StreamHeader {
+            salt: [0xA5; 32],
+            nonce_prefix: [0x5A; 7],
+            segment_size: 0x01020304,
+        };
+        let bytes = header.to_bytes();
+        assert_eq!(bytes[..32], [0xA5; 32]);
+        assert_eq!(bytes[32..39], [0x5A; 7]);
+        assert_eq!(bytes[39..43], [0x01, 0x02, 0x03, 0x04]);
+        let parsed = StreamHeader::try_from_bytes(&bytes).unwrap();
+        assert_eq!(parsed.salt, header.salt);
+        assert_eq!(parsed.nonce_prefix, header.nonce_prefix);
+        assert_eq!(parsed.segment_size, header.segment_size);
+    }
+
+    #[test]
+    fn stream_header_rejects_zero_segment_size() {
+        let bytes = StreamHeader {
+            salt: [0; 32],
+            nonce_prefix: [0; 7],
+            segment_size: 0,
+        }
+        .to_bytes();
+        assert!(matches!(
+            StreamHeader::try_from_bytes(&bytes),
+            Err(AeadError::Malformed(_))
+        ));
+    }
+
+    #[test]
+    fn stream_header_rejects_oversized_segment_size() {
+        let bytes = StreamHeader {
+            salt: [0; 32],
+            nonce_prefix: [0; 7],
+            segment_size: MAX_SEGMENT_SIZE + 1,
+        }
+        .to_bytes();
+        assert!(matches!(
+            StreamHeader::try_from_bytes(&bytes),
+            Err(AeadError::Malformed(_))
+        ));
+    }
+
+    #[test]
+    fn stream_header_accepts_boundary_segment_sizes() {
+        for segment_size in [1, MAX_SEGMENT_SIZE] {
+            let bytes = StreamHeader {
+                salt: [0; 32],
+                nonce_prefix: [0; 7],
+                segment_size,
+            }
+            .to_bytes();
+            assert_eq!(
+                StreamHeader::try_from_bytes(&bytes).unwrap().segment_size,
+                segment_size
+            );
+        }
+    }
+
     #[test]
     fn hkdf_sha256_rfc5869_test_case_1() {
         let ikm = [0x0bu8; 22];
diff --git a/lib/src/entry/builder.rs b/lib/src/entry/builder.rs
@@ -216,7 +216,7 @@ impl EntryBuilder {
         let writer = get_writer(FlattenWriter::new(), &context)?;
         let (iv, phsf) = match context.cipher {
             None => (None, None),
-            Some(WriteCipher { context: c, .. }) => (Some(c.iv), Some(c.phsf)),
+            Some(WriteCipher { context: c, .. }) => (Some(c.prefix_bytes()), Some(c.phsf)),
         };
         Ok(Self {
             data: Some(writer),
@@ -234,7 +234,7 @@ impl EntryBuilder {
         writer.write_all(source.as_bytes())?;
         let (iv, phsf) = match context.cipher {
             None => (None, None),
-            Some(WriteCipher { context: c, .. }) => (Some(c.iv), Some(c.phsf)),
+            Some(WriteCipher { context: c, .. }) => (Some(c.prefix_bytes()), Some(c.phsf)),
         };
         Ok(Self {
             data: Some(writer),
@@ -595,7 +595,7 @@ impl SolidEntryBuilder {
         let writer = get_writer(FlattenWriter::new(), &context)?;
         let (iv, phsf) = match context.cipher {
             None => (None, None),
-            Some(WriteCipher { context: c, .. }) => (Some(c.iv), Some(c.phsf)),
+            Some(WriteCipher { context: c, .. }) => (Some(c.prefix_bytes()), Some(c.phsf)),
         };
         Ok(Self {
             header,
diff --git a/lib/src/entry/read.rs b/lib/src/entry/read.rs
@@ -4,8 +4,8 @@ use crate::{
     CipherMode, Compression, Encryption,
     cipher::{
         Ctr128BEReader, DecryptCbcAes256Reader, DecryptCbcCamellia256Reader,
-        DecryptGcmAes256Reader, DecryptGcmCamellia256Reader, DecryptReader, MAX_SEGMENT_SIZE,
-        STREAM_HEADER_LEN, StreamKind, derive_stream_key,
+        DecryptGcmAes256Reader, DecryptGcmCamellia256Reader, DecryptReader, STREAM_HEADER_LEN,
+        StreamHeader, StreamKind, derive_stream_key,
     },
     compress::DecompressReader,
     error::AeadError,
@@ -86,21 +86,17 @@ pub(crate) fn decrypt_reader<R: Read>(
                             e
                         }
                     })?;
-                    let stream_salt: [u8; 32] = header[..32].try_into().unwrap();
-                    let nonce_prefix: [u8; 7] = header[32..39].try_into().unwrap();
-                    let segment_size = u32::from_be_bytes(header[39..43].try_into().unwrap());
-                    // Checked before the password KDF runs, so a malformed stream
-                    // fails without paying the (deliberately expensive) Argon2id cost.
-                    if segment_size == 0 || segment_size > MAX_SEGMENT_SIZE {
-                        return Err(AeadError::Malformed("segment size out of range").into());
-                    }
+                    // Parsed (and the segment size range-checked) before the
+                    // password KDF runs, so a malformed stream fails without
+                    // paying the (deliberately expensive) Argon2id cost.
+                    let header = StreamHeader::try_from_bytes(&header)?;
                     let k_master = derive_key(s, password)?;
                     if k_master.as_bytes().len() != 32 {
                         return Err(AeadError::Malformed("K_master is not 32 bytes").into());
                     }
                     let k_stream = derive_stream_key(
                         k_master.as_bytes(),
-                        &stream_salt,
+                        &header.salt,
                         kind,
                         header_chunk_data,
                         s.as_bytes(),
@@ -109,14 +105,14 @@ pub(crate) fn decrypt_reader<R: Read>(
                         Encryption::Aes => DecryptReader::GcmAes(DecryptGcmAes256Reader::new(
                             reader,
                             &k_stream,
-                            nonce_prefix,
-                            segment_size,
+                            header.nonce_prefix,
+                            header.segment_size,
                         )),
                         _ => DecryptReader::GcmCamellia(DecryptGcmCamellia256Reader::new(
                             reader,
                             &k_stream,
-                            nonce_prefix,
-                            segment_size,
+                            header.nonce_prefix,
+                            header.segment_size,
                         )),
                     }
                 }
diff --git a/lib/src/entry/write.rs b/lib/src/entry/write.rs
