feat: Add by_index_with_options() for ignoring encryption (#439)

Author: b-spencer

src/lib.rs

@@ -34,7 +34,7 @@
 #![allow(unexpected_cfgs)] // Needed for cfg(fuzzing) on nightly as of 2024-05-06
 pub use crate::compression::{CompressionMethod, SUPPORTED_COMPRESSION_METHODS};
 pub use crate::read::HasZipMetadata;
-pub use crate::read::ZipArchive;
+pub use crate::read::{ZipArchive, ZipReadOptions};
 pub use crate::spec::{ZIP64_BYTES_THR, ZIP64_ENTRY_THR};
 pub use crate::types::{AesMode, DateTime};
 pub use crate::write::ZipWriter;

src/read.rs

@@ -1053,14 +1053,16 @@ impl<R: Read + Seek> ZipArchive<R> {
     ) -> ZipResult<ZipFile<'_, R>> {
         self.index_for_path(path)
             .ok_or(ZipError::FileNotFound)
-            .and_then(|index| self.by_index_with_optional_password(index, Some(password)))
+            .and_then(|index| {
+                self.by_index_with_options(index, ZipReadOptions::new().password(Some(password)))
+            })
     }
 
     /// Search for a file entry by path
     pub fn by_path<T: AsRef<Path>>(&mut self, path: T) -> ZipResult<ZipFile<'_, R>> {
         self.index_for_path(path)
             .ok_or(ZipError::FileNotFound)
-            .and_then(|index| self.by_index_with_optional_password(index, None))
+            .and_then(|index| self.by_index_with_options(index, ZipReadOptions::new()))
     }
 
     /// Get the index of a file entry by path, if it's present.
@@ -1116,7 +1118,7 @@ impl<R: Read + Seek> ZipArchive<R> {
         let Some(index) = self.shared.files.get_index_of(name) else {
             return Err(ZipError::FileNotFound);
         };
-        self.by_index_with_optional_password(index, password)
+        self.by_index_with_options(index, ZipReadOptions::new().password(password))
     }
 
     /// Get a contained file by index, decrypt with given password
@@ -1137,12 +1139,12 @@ impl<R: Read + Seek> ZipArchive<R> {
         file_number: usize,
         password: &[u8],
     ) -> ZipResult<ZipFile<'_, R>> {
-        self.by_index_with_optional_password(file_number, Some(password))
+        self.by_index_with_options(file_number, ZipReadOptions::new().password(Some(password)))
     }
 
     /// Get a contained file by index
     pub fn by_index(&mut self, file_number: usize) -> ZipResult<ZipFile<'_, R>> {
-        self.by_index_with_optional_password(file_number, None)
+        self.by_index_with_options(file_number, ZipReadOptions::new())
     }
 
     /// Get a contained file by index without decompressing it
@@ -1159,25 +1161,36 @@ impl<R: Read + Seek> ZipArchive<R> {
         })
     }
 
-    fn by_index_with_optional_password(
+    /// Get a contained file by index with options.
+    pub fn by_index_with_options(
         &mut self,
         file_number: usize,
-        mut password: Option<&[u8]>,
+        mut options: ZipReadOptions<'_>,
     ) -> ZipResult<ZipFile<'_, R>> {
         let (_, data) = self
             .shared
             .files
             .get_index(file_number)
             .ok_or(ZipError::FileNotFound)?;
 
-        match (password, data.encrypted) {
-            (None, true) => return Err(ZipError::UnsupportedArchive(ZipError::PASSWORD_REQUIRED)),
-            (Some(_), false) => password = None, //Password supplied, but none needed! Discard.
-            _ => {}
+        if options.ignore_encryption_flag {
+            // Always use no password when we're ignoring the encryption flag.
+            options.password = None;
+        } else {
+            // Require and use the password only if the file is encrypted.
+            match (options.password, data.encrypted) {
+                (None, true) => {
+                    return Err(ZipError::UnsupportedArchive(ZipError::PASSWORD_REQUIRED))
+                }
+                // Password supplied, but none needed! Discard.
+                (Some(_), false) => options.password = None,
+                _ => {}
+            }
         }
         let limit_reader = find_content(data, &mut self.reader)?;
 
-        let crypto_reader = make_crypto_reader(data, limit_reader, password, data.aes_mode)?;
+        let crypto_reader =
+            make_crypto_reader(data, limit_reader, options.password, data.aes_mode)?;
 
         Ok(ZipFile {
             data: Cow::Borrowed(data),
@@ -1555,6 +1568,38 @@ pub trait HasZipMetadata {
     fn get_metadata(&self) -> &ZipFileData;
 }
 
+/// Options for reading a file from an archive.
+#[derive(Default)]
+pub struct ZipReadOptions<'a> {
+    /// The password to use when decrypting the file.  This is ignored if not required.
+    password: Option<&'a [u8]>,
+
+    /// Ignore the value of the encryption flag and proceed as if the file were plaintext.
+    ignore_encryption_flag: bool,
+}
+
+impl<'a> ZipReadOptions<'a> {
+    /// Create a new set of options with the default values.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Set the password, if any, to use.  Return for chaining.
+    #[must_use]
+    pub fn password(mut self, password: Option<&'a [u8]>) -> Self {
+        self.password = password;
+        self
+    }
+
+    /// Set the ignore encryption flag.  Return for chaining.
+    #[must_use]
+    pub fn ignore_encryption_flag(mut self, ignore: bool) -> Self {
+        self.ignore_encryption_flag = ignore;
+        self
+    }
+}
+
 /// Methods for retrieving information on zip files
 impl<'a, R: Read> ZipFile<'a, R> {
     pub(crate) fn take_raw_reader(&mut self) -> io::Result<io::Take<&'a mut R>> {
@@ -2065,6 +2110,7 @@ fn generate_chrono_datetime(datetime: &DateTime) -> Option<chrono::NaiveDateTime
 
 #[cfg(test)]
 mod test {
+    use crate::read::ZipReadOptions;
     use crate::result::ZipResult;
     use crate::write::SimpleFileOptions;
     use crate::CompressionMethod::Stored;
@@ -2374,4 +2420,23 @@ mod test {
         }
         Ok(())
     }
+
+    #[test]
+    fn test_ignore_encryption_flag() -> ZipResult<()> {
+        let mut reader = ZipArchive::new(Cursor::new(include_bytes!(
+            "../tests/data/ignore_encryption_flag.zip"
+        )))?;
+
+        // Get the file entry by ignoring its encryption flag.
+        let mut file =
+            reader.by_index_with_options(0, ZipReadOptions::new().ignore_encryption_flag(true))?;
+        let mut contents = String::new();
+        assert_eq!(file.name(), "plaintext.txt");
+
+        // The file claims it is encrypted, but it is not.
+        assert!(file.encrypted());
+        file.read_to_string(&mut contents)?; // ensures valid UTF-8
+        assert_eq!(contents, "This file is not encrypted.\n");
+        Ok(())
+    }
 }

tests/data/ignore_encryption_flag.zip

@@ -101,6 +101,22 @@ fn encrypted_file() {
         file.read_to_end(&mut data).unwrap();
         assert_eq!(data, "abcdefghijklmnopqrstuvwxyz123456789".as_bytes());
     }
+
+    // Again, but with the options API.
+    {
+        use zip::read::ZipReadOptions;
+
+        // Correct password, read contents
+        let mut file = archive
+            .by_index_with_options(0, ZipReadOptions::new().password(Some("test".as_bytes())))
+            .unwrap();
+        let file_name = file.enclosed_name().unwrap();
+        assert_eq!(file_name, std::path::PathBuf::from("test.txt"));
+
+        let mut data = Vec::new();
+        file.read_to_end(&mut data).unwrap();
+        assert_eq!(data, "abcdefghijklmnopqrstuvwxyz123456789".as_bytes());
+    }
 }
 
 #[test]