#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] //! ZIP archives from untrusted files, read within limits and written. //! //! The `zip` crate does the decoding. This crate is what every reader of a ZIP-based format //! otherwise writes again around it: //! //! - [`Archive::open`] refuses an archive that declares more entries than the caller allows //! before `zip` parses them ([`check_entry_count`]), and tells whether two entries share a name. //! - [`Archive::read`] reads an entry within a per-entry limit and the archive's total //! [`Budget`], counting the bytes that really arrive, not the size the archive declares. //! - [`Writer`] writes stored and deflated entries, ZIP64 where an entry needs it, with the same //! timestamp on every entry so equal input gives equal bytes. //! - [`preflight`] is a stricter check of the whole end-record and central-directory structure //! on the raw bytes, for a caller that wants nothing ambiguous to reach a ZIP reader at all. //! //! Every limit is the caller's number. Entry-name rules (which names are safe, which spellings //! are one part) stay with the format that knows them. #[cfg(doctest)] #[doc = include_str!("../README.md")] struct ReadmeExamples; mod archive; mod guard; mod metadata_reader; pub mod preflight; mod seekable; mod write; pub use archive::{Archive, Limits}; pub use guard::check_entry_count; #[cfg(any(test, feature = "test-support"))] pub use guard::zip64_entry_count_sample; pub use metadata_reader::{Indexing, MetadataReader}; pub use seekable::{InspectError, inspect_seekable}; pub use write::{Compression, Writer}; /// The payload of a ZIP's first entry when it is a stored file named `mimetype` of at most 256 /// bytes: how OpenDocument, EPUB, IDML, OpenRaster and Krita mark their archives so the type is /// readable at a fixed offset without unzipping. pub fn stored_mimetype(bytes: &[u8]) -> Option<&[u8]> { let u16_at = |o: usize| bytes.get(o..o + 2).and_then(|s| <[u8; 2]>::try_from(s).ok()).map(u16::from_le_bytes); let u32_at = |o: usize| bytes.get(o..o + 4).and_then(|s| <[u8; 4]>::try_from(s).ok()).map(u32::from_le_bytes); if u32_at(0)? != 0x0403_4b50 || u16_at(8)? != 0 { return None; } let size = usize::try_from(u32_at(18)?).ok()?; let name_len = usize::from(u16_at(26)?); let extra_len = usize::from(u16_at(28)?); if bytes.get(30..30 + name_len)? != b"mimetype" || size > 256 { return None; } let start = 30 + name_len + extra_len; bytes.get(start..start.checked_add(size)?) } /// Why an archive was not read or not written. #[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)] pub enum Error { /// The bytes are not a ZIP archive the `zip` crate can index. #[error("not a ZIP archive: {0}")] NotZip(String), /// The archive declares more entries than [`Limits::max_entries`]. #[error("the archive declares {declared} entries, more than {limit}")] TooManyEntries { declared: u64, limit: u64 }, /// More end of central directory records than an archive can have. #[error("more than {0} end of central directory records")] TooManyEndRecords(usize), /// An entry declares, or expands to, more than the limit given for it. #[error("{name} is larger than {limit} bytes")] EntryTooLarge { name: String, limit: u64 }, /// The entries read so far have used up [`Limits::max_total_bytes`]. #[error("{name} does not fit in what is left of the {limit} bytes the archive may expand to")] BudgetSpent { name: String, limit: u64 }, /// An entry could not be decoded (a failed checksum, an unknown method, encryption). #[error("{name}: {msg}")] Entry { name: String, msg: String }, /// The archive could not be written. #[error("the ZIP archive could not be written: {0}")] Write(String), } impl Error { /// Was a limit exceeded (as opposed to the archive being broken)? pub fn is_limit(&self) -> bool { matches!(self, Error::TooManyEntries { .. } | Error::TooManyEndRecords(_) | Error::EntryTooLarge { .. } | Error::BudgetSpent { .. }) } } use std::fmt; /// A named limit and the total charged against it so far. /// /// The name is what a breach message should mention ("document", "part", "images"), and the limit /// is the application's own number. The crate never invents either, so one budget can cover a /// whole import and be reported in the application's terms. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Budget { what: &'static str, limit: u64, used: u64, } impl Budget { /// A budget named `what` that admits up to `limit` units in total. pub const fn new(what: &'static str, limit: u64) -> Self { Self { what, limit, used: 0 } } /// Charge `n` units, or refuse without changing the total. /// /// A refused charge leaves the total untouched, so a caller may carry on with a smaller /// charge, and the amount refused is reported in [`Exceeded::requested`]. pub fn charge(&mut self, n: u64) -> Result<(), Exceeded> { if n > self.remaining() { return Err(Exceeded { what: self.what, limit: self.limit, requested: n }); } self.used = self.used.saturating_add(n); Ok(()) } /// The units still available; zero when the budget is exhausted. pub const fn remaining(&self) -> u64 { self.limit.saturating_sub(self.used) } /// The units charged so far. pub const fn used(&self) -> u64 { self.used } /// The limit this budget was created with. pub const fn limit(&self) -> u64 { self.limit } /// The name this budget was created with. pub const fn what(&self) -> &'static str { self.what } } /// A charge that a [`Budget`] refused: what was limited, the limit, and the amount asked for. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Exceeded { /// The budget's name, so a message can say which limit was hit. pub what: &'static str, /// The limit that was already reached. pub limit: u64, /// The amount that did not fit. pub requested: u64, } impl fmt::Display for Exceeded { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "the {} limit is {}; another {} was requested", self.what, self.limit, self.requested) } } impl std::error::Error for Exceeded {} #[cfg(test)] mod tests { use super::*; #[test] fn budgets_charge_and_report_the_remainder() { let mut budget = Budget::new("document", 10); assert_eq!(budget.what(), "document"); assert_eq!(budget.limit(), 10); assert_eq!(budget.remaining(), 10); assert_eq!(budget.used(), 0); assert_eq!(budget.charge(4), Ok(())); assert_eq!(budget.used(), 4); assert_eq!(budget.remaining(), 6); assert_eq!(budget.charge(6), Ok(())); assert_eq!(budget.remaining(), 0); } #[test] fn a_refused_charge_leaves_the_total_untouched() { let mut budget = Budget::new("part", 100); assert_eq!(budget.charge(60), Ok(())); let exceeded = budget.charge(41).err(); assert_eq!(exceeded, Some(Exceeded { what: "part", limit: 100, requested: 41 })); assert_eq!(budget.used(), 60); // The refused amount is not charged, so the budget stays usable. assert_eq!(budget.charge(40), Ok(())); assert_eq!(budget.used(), 100); assert!(budget.charge(1).is_err()); } #[test] fn a_zero_budget_admits_nothing_and_the_message_names_the_limit() { let mut budget = Budget::new("entries", 0); assert_eq!(budget.remaining(), 0); assert_eq!(budget.charge(0), Ok(())); let message = budget.charge(1).err().map(|e| e.to_string()); assert_eq!(message.as_deref(), Some("the entries limit is 0; another 1 was requested")); } #[test] fn a_limit_at_the_maximum_does_not_overflow() { let mut budget = Budget::new("total", u64::MAX); assert_eq!(budget.charge(u64::MAX), Ok(())); assert_eq!(budget.remaining(), 0); assert!(budget.charge(u64::MAX).is_err()); } #[test] #[allow(clippy::unwrap_used, clippy::expect_used)] fn archive_reports_entries_that_alias_the_same_payload() { use std::io::Write as _; let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); let opts = zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); zip.start_file("first", opts).unwrap(); zip.write_all(b"payload").unwrap(); zip.shallow_copy_file("first", "alias").unwrap(); let bytes = zip.finish().unwrap().into_inner(); let mut archive = Archive::open(&bytes, Limits { max_entries: 2, max_total_bytes: 100 }).unwrap(); assert!(archive.has_overlapping_files().unwrap()); } #[test] #[allow(clippy::unwrap_used, clippy::expect_used)] fn archive_can_copy_one_name_at_a_time_by_index() { use std::io::Write as _; let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); let opts = zip::write::SimpleFileOptions::default(); zip.start_file("first", opts).unwrap(); zip.write_all(b"1").unwrap(); zip.start_file("second", opts).unwrap(); zip.write_all(b"2").unwrap(); zip.start_file("folder\\", opts).unwrap(); let bytes = zip.finish().unwrap().into_inner(); let mut archive = Archive::open(&bytes, Limits { max_entries: 3, max_total_bytes: 10 }).unwrap(); assert_eq!(archive.entry_name(0).unwrap().as_deref(), Some("first")); assert_eq!(archive.entry_name(1).unwrap().as_deref(), Some("second")); assert_eq!(archive.entry_is_dir(2).unwrap(), Some(true)); assert_eq!(archive.entry_name(2).unwrap().as_deref(), Some("folder\\")); assert_eq!(archive.entry_name(3).unwrap(), None); } }