zip/read/extract.rs
1//! Extraction
2
3use crate::result::{ZipResult, invalid};
4use crate::{ZipArchive, result::ZipError};
5use std::ffi::OsStr;
6use std::io::{self, Read, Seek};
7use std::path::Path;
8
9use indexmap::IndexMap;
10
11/// Upper bound on the uncompressed size of a symlink entry.
12///
13/// A symlink target is a filesystem path, so its length is bounded by the
14/// platform (`PATH_MAX` is 4096 on Linux) no matter what the archive says. The
15/// uncompressed size stored in the central directory is attacker-controlled,
16/// so entries above this bound are rejected rather than pre-allocated.
17pub(crate) const MAX_SYMLINK_TARGET_LEN: u64 = 4096;
18
19/// Symlink extract action
20#[derive(Debug, Default, Copy, Clone)]
21pub enum SymlinkExtractAction {
22 /// Omit symlinks.
23 NoExtract,
24 /// Convert symlinks to text file
25 ExtractAsFile,
26 /// Convert symlinks to text file as utf8
27 #[cfg_attr(not(any(unix, windows)), default)]
28 ExtractAsFileUtf8,
29 /// Extract symlinks if the recursive target is in the destination folder (default on Unix and Windows, but not possible on other platforms).
30 #[cfg(any(unix, windows))]
31 #[default]
32 ExtractRecursiveInFolder,
33 /// Extract symlinks if the _direct_ target is in the destination folder (i.e. it can point to a pre-existing symlink that in turn points outside the folder).
34 #[cfg(any(unix, windows))]
35 ExtractInFolder,
36 /// Extract symlinks with no restrictions.
37 #[cfg(any(unix, windows))]
38 ExtractNoRestrictions,
39}
40
41/// Extract options
42#[derive(Debug, Default)]
43#[non_exhaustive]
44pub struct ExtractOptions {
45 pub(crate) symlink_action: SymlinkExtractAction,
46}
47
48impl ExtractOptions {
49 /// Set the symlink action
50 #[must_use]
51 pub fn symlink_action(self, symlink_action: SymlinkExtractAction) -> Self {
52 Self {
53 symlink_action,
54 ..self
55 }
56 }
57}
58
59pub(crate) fn make_writable_dir_all<T: AsRef<Path>>(outpath: T) -> Result<(), ZipError> {
60 use std::fs;
61 fs::create_dir_all(outpath.as_ref())?;
62 #[cfg(unix)]
63 {
64 // Dirs must be writable until all normal files are extracted
65 use std::os::unix::fs::PermissionsExt;
66 std::fs::set_permissions(
67 outpath.as_ref(),
68 std::fs::Permissions::from_mode(
69 0o700 | std::fs::metadata(outpath.as_ref())?.permissions().mode(),
70 ),
71 )?;
72 }
73 Ok(())
74}
75
76#[cfg(unix)]
77pub(crate) fn make_symlink_impl<T>(
78 outpath: &Path,
79 target_str: &str,
80 _existing_files: &IndexMap<Box<[u8]>, T>,
81) -> ZipResult<()> {
82 std::os::unix::fs::symlink(Path::new(&target_str), outpath)?;
83 Ok(())
84}
85
86#[cfg(windows)]
87pub(crate) fn make_symlink_impl<T>(
88 outpath: &Path,
89 target_str: &str,
90 existing_files: &IndexMap<Box<[u8]>, T>,
91) -> ZipResult<()> {
92 use crate::format::functions::is_dir;
93 let target = Path::new(OsStr::new(&target_str));
94 let target_is_dir_from_archive =
95 is_dir(target_str.as_bytes()) && existing_files.contains_key(target_str.as_bytes());
96 let target_is_dir = if target_is_dir_from_archive {
97 true
98 } else if let Ok(meta) = std::fs::metadata(target) {
99 meta.is_dir()
100 } else {
101 false
102 };
103 if target_is_dir {
104 std::os::windows::fs::symlink_dir(target, outpath)?;
105 } else {
106 std::os::windows::fs::symlink_file(target, outpath)?;
107 }
108 Ok(())
109}
110
111#[cfg(any(windows, unix))]
112pub(crate) fn make_symlink<T>(
113 base: &Path, // canonicalized destination directory
114 outpath: &Path,
115 target: &[u8],
116 #[cfg_attr(not(any(windows, unix)), allow(unused))] existing_files: &IndexMap<Box<[u8]>, T>,
117 symlink_action: SymlinkExtractAction,
118) -> ZipResult<()> {
119 let Ok(target_str) = std::str::from_utf8(target) else {
120 return Err(invalid!("Invalid UTF-8 as symlink target"));
121 };
122
123 // Check where the symlink would resolve to before creating it. A relative target
124 // is resolved from the parent of the symlink itself, exactly as the OS would.
125 let target_path = Path::new(target_str);
126 let (start, rest) = if target_path.is_absolute() {
127 let Some(rest) = crate::path::strip_base_prefix(base, target_path) else {
128 return Err(invalid!(
129 "make_symlink: Symlink target escapes the destination directory"
130 ));
131 };
132 (base, rest)
133 } else {
134 // A Windows target such as `C:foo` (relative to the current directory of a
135 // drive) or `\foo` (relative to the root of the current drive) is neither
136 // absolute nor safely relative: the OS resolves it from somewhere other than
137 // the parent of the symlink, so there is nothing meaningful to check here.
138 if target_path.components().any(|component| {
139 matches!(
140 component,
141 std::path::Component::Prefix(_) | std::path::Component::RootDir
142 )
143 }) {
144 return Err(invalid!("Invalid symlink target path"));
145 }
146 let parent = outpath.parent().unwrap_or(base);
147 if !parent.starts_with(base) {
148 return Err(invalid!("Symlink is not inside the destination directory"));
149 }
150 (parent, target_path)
151 };
152
153 // ExtractNoRestrictions is allowed outside (no restrictions) - but it uses
154 // [`make_symlink_impl`] directly
155 // ExtractRecursiveInFolder is allowed outside (it will be checked that the symlink fall in the
156 // folder)
157 #[cfg(any(windows, unix))]
158 let allow_outside = matches!(
159 symlink_action,
160 SymlinkExtractAction::ExtractNoRestrictions
161 | SymlinkExtractAction::ExtractRecursiveInFolder
162 );
163 #[cfg(not(any(windows, unix)))]
164 let allow_outside = false;
165 if allow_outside {
166 // For ExtractRecursiveInFolder: the literal path may leave `base` (e.g.
167 // `../sibling`), but it must canonicalize (following real filesystem symlinks) back into `base`.
168 #[cfg(any(unix, windows))]
169 if matches!(
170 symlink_action,
171 SymlinkExtractAction::ExtractRecursiveInFolder
172 ) {
173 // Try to canonicalize the resolved path so that symlinks in the filesystem
174 // that point back inside `base` are followed.
175 let abs_to_canonicalize = if target_path.is_absolute() {
176 target_path
177 } else {
178 &start.join(target_path)
179 };
180 match std::fs::canonicalize(abs_to_canonicalize) {
181 Ok(canonical) => {
182 if !canonical.starts_with(base) {
183 return Err(invalid!("Path escapes the destination directory"));
184 }
185 }
186 Err(_) => {
187 crate::path::resolve_enclosed(
188 base,
189 start,
190 rest.components().map(|c| c.as_os_str().to_os_string()),
191 false,
192 )?;
193 }
194 }
195 }
196 } else {
197 crate::path::resolve_enclosed(
198 base,
199 start,
200 rest.components().map(|c| c.as_os_str().to_os_string()),
201 false, // only checking here, so nothing is created
202 )?;
203 }
204
205 make_symlink_impl(outpath, target_str, existing_files)
206}
207
208/// Wasm and others
209#[cfg(not(any(windows, unix)))]
210pub(crate) fn make_symlink<T>(
211 // No symlink is created on these targets, so there is nothing to contain.
212 _base: &Path,
213 outpath: &Path,
214 target: &[u8],
215 #[cfg_attr(not(any(windows, unix)), allow(unused))] existing_files: &IndexMap<Box<[u8]>, T>,
216 _symlink_action: SymlinkExtractAction,
217) -> ZipResult<()> {
218 make_symlink_as_file_utf8(outpath, target)?;
219 Ok(())
220}
221
222pub(crate) fn make_symlink_as_file_utf8(outpath: &Path, target: &[u8]) -> ZipResult<()> {
223 let Ok(_) = std::str::from_utf8(target) else {
224 return Err(invalid!("Invalid UTF-8 as symlink target"));
225 };
226 make_symlink_as_file(outpath, target)?;
227 Ok(())
228}
229
230pub(crate) fn make_symlink_as_file(outpath: &Path, target: &[u8]) -> std::io::Result<()> {
231 use std::fs::File;
232 use std::io::Write;
233 let output = File::create(outpath);
234 output?.write_all(target)?;
235 Ok(())
236}
237
238#[cfg(unix)]
239pub(crate) fn set_permissions_no_follow_symlink(
240 path: &Path,
241 mode: std::fs::Permissions,
242) -> std::io::Result<()> {
243 use std::fs;
244 if fs::symlink_metadata(path)?.file_type().is_symlink() {
245 #[cfg(any(
246 target_os = "macos",
247 target_os = "freebsd",
248 target_os = "openbsd",
249 target_os = "netbsd",
250 target_os = "dragonfly"
251 ))]
252 {
253 // These are the only platforms where permission bits on symlinks themselves are meaningful.
254
255 use nix::fcntl::AT_FDCWD;
256 use nix::sys::stat::{FchmodatFlags, Mode, fchmodat};
257 use std::os::unix::fs::PermissionsExt;
258
259 // `mode_t` is `u16` on macOS, FreeBSD and DragonFly, but `u32` on NetBSD and OpenBSD.
260 let mode = Mode::from_bits_truncate(mode.mode() as nix::libc::mode_t);
261
262 // Use fchmodat with the flag telling it NOT to follow the symlink
263 fchmodat(AT_FDCWD, path, mode, FchmodatFlags::NoFollowSymlink)?;
264 }
265 } else {
266 fs::set_permissions(path, mode)?;
267 }
268 Ok(())
269}
270
271/// Store all entries which specify a numeric "mode" which is familiar to POSIX operating systems.
272#[derive(Default, Debug)]
273struct UnixFileModes {
274 #[cfg(unix)]
275 map: std::collections::BTreeMap<std::path::PathBuf, u32>,
276 #[cfg(not(unix))]
277 read_only_set: std::collections::BTreeSet<std::path::PathBuf>,
278}
279
280impl UnixFileModes {
281 pub fn add_mode(&mut self, path: std::path::PathBuf, mode: u32) {
282 // We don't print a warning or consider it remotely out of the ordinary to receive two
283 // separate modes for the same path (e.g. entries named `a` and `./a`): just take the
284 // later one, as the later file's contents are what's on disk.
285 #[cfg(unix)]
286 self.map.insert(path, mode);
287 #[cfg(not(unix))]
288 if mode & 0o222 == 0 {
289 self.read_only_set.insert(path);
290 } else {
291 self.read_only_set.remove(&path);
292 }
293 }
294
295 #[cfg(unix)]
296 // Child nodes will be sorted later lexicographically, so reversing the order puts them first.
297 pub fn all_perms_with_children_first(
298 self,
299 ) -> impl IntoIterator<Item = (std::path::PathBuf, std::fs::Permissions)> {
300 use std::os::unix::fs::PermissionsExt;
301 self.map
302 .into_iter()
303 .rev()
304 .map(|(p, m)| (p, std::fs::Permissions::from_mode(m)))
305 }
306
307 #[cfg(not(unix))]
308 // Child nodes will be sorted later lexicographically, so reversing the order puts them first.
309 pub fn all_read_only_with_children_first(self) -> impl IntoIterator<Item = std::path::PathBuf> {
310 self.read_only_set.into_iter().rev()
311 }
312}
313
314impl<R: Read + Seek> ZipArchive<R> {
315 /// Extract a Zip archive into a directory, overwriting files if they
316 /// already exist. Paths are sanitized with [`ZipFile::enclosed_name`](crate::read::ZipFile::enclosed_name).
317 ///
318 /// Symbolic links are only created, and only followed, if their target resolves to a path
319 /// inside the destination directory. Paths are resolved one component at a time, and the
320 /// target of every symlink encountered is resolved in the same way, so a symlink cannot be
321 /// used as an intermediate component to reach outside the destination directory. Note that
322 /// this does not protect against another process concurrently modifying the destination
323 /// directory during extraction.
324 ///
325 /// Extraction is not atomic. If an error is encountered, some of the files
326 /// may be left on disk. However, on Unix targets, no newly-created directories with part but
327 /// not all of their contents extracted will be readable, writable or usable as process working
328 /// directories by any non-root user except you.
329 ///
330 /// On Unix and Windows, symbolic links are extracted correctly. On other platforms such as
331 /// WebAssembly, symbolic links aren't supported, so they're extracted as normal files
332 /// containing the target path in UTF-8.
333 pub fn extract<P: AsRef<Path>>(&mut self, directory: P) -> ZipResult<()> {
334 self.extract_internal(
335 directory,
336 None::<fn(&Path) -> bool>,
337 ExtractOptions::default(),
338 )
339 }
340 /// Same as extract but with options
341 pub fn extract_with_options<P: AsRef<Path>>(
342 &mut self,
343 directory: P,
344 extract_options: ExtractOptions,
345 ) -> ZipResult<()> {
346 self.extract_internal(directory, None::<fn(&Path) -> bool>, extract_options)
347 }
348
349 /// Extracts a Zip archive into a directory in the same fashion as
350 /// [`ZipArchive::extract`], but detects a "root" directory in the archive
351 /// (a single top-level directory that contains the rest of the archive's
352 /// entries) and extracts its contents directly.
353 ///
354 /// For a sensible default `filter`, you can use [`crate::read::root_dir_common_filter`].
355 /// For a custom `filter`, see [`RootDirFilter`].
356 ///
357 /// See [`ZipArchive::root_dir`] for more information on how the root
358 /// directory is detected and the meaning of the `filter` parameter.
359 ///
360 /// ## Example
361 ///
362 /// Imagine a Zip archive with the following structure:
363 ///
364 /// ```text
365 /// root/file1.txt
366 /// root/file2.txt
367 /// root/sub/file3.txt
368 /// root/sub/subsub/file4.txt
369 /// ```
370 ///
371 /// If the archive is extracted to `foo` using [`ZipArchive::extract`],
372 /// the resulting directory structure will be:
373 ///
374 /// ```text
375 /// foo/root/file1.txt
376 /// foo/root/file2.txt
377 /// foo/root/sub/file3.txt
378 /// foo/root/sub/subsub/file4.txt
379 /// ```
380 ///
381 /// If the archive is extracted to `foo` using
382 /// [`ZipArchive::extract_unwrapped_root_dir`], the resulting directory
383 /// structure will be:
384 ///
385 /// ```text
386 /// foo/file1.txt
387 /// foo/file2.txt
388 /// foo/sub/file3.txt
389 /// foo/sub/subsub/file4.txt
390 /// ```
391 ///
392 /// ## Example - No Root Directory
393 ///
394 /// Imagine a Zip archive with the following structure:
395 ///
396 /// ```text
397 /// root/file1.txt
398 /// root/file2.txt
399 /// root/sub/file3.txt
400 /// root/sub/subsub/file4.txt
401 /// other/file5.txt
402 /// ```
403 ///
404 /// Due to the presence of the `other` directory,
405 /// [`ZipArchive::extract_unwrapped_root_dir`] will extract this in the same
406 /// fashion as [`ZipArchive::extract`] as there is now no "root directory."
407 pub fn extract_unwrapped_root_dir<P: AsRef<Path>>(
408 &mut self,
409 directory: P,
410 root_dir_filter: impl RootDirFilter,
411 ) -> ZipResult<()> {
412 self.extract_internal(directory, Some(root_dir_filter), ExtractOptions::default())
413 }
414
415 fn extract_internal<P: AsRef<Path>>(
416 &mut self,
417 directory: P,
418 root_dir_filter: Option<impl RootDirFilter>,
419 extract_options: ExtractOptions,
420 ) -> ZipResult<()> {
421 use std::fs;
422
423 fs::create_dir_all(&directory)?;
424 let directory = directory.as_ref().canonicalize()?;
425
426 let root_dir = root_dir_filter
427 .and_then(|filter| {
428 self.root_dir(&filter)
429 .transpose()
430 .map(|root_dir| root_dir.map(|root_dir| (root_dir, filter)))
431 })
432 .transpose()?;
433
434 // If we have a root dir, simplify the path components to be more
435 // appropriate for passing to `safe_prepare_path`
436 let root_dir = root_dir
437 .as_ref()
438 .map(|(root_dir, filter)| {
439 crate::path::simplified_components(root_dir)
440 .ok_or_else(|| {
441 // Should be unreachable
442 debug_assert!(false, "Invalid root dir path");
443
444 invalid!("Invalid root dir path")
445 })
446 .map(|root_dir| (root_dir, filter))
447 })
448 .transpose()?;
449
450 let mut files_by_unix_mode = UnixFileModes::default();
451
452 for i in 0..self.len() {
453 let mut file = self.by_index(i)?;
454
455 let mut outpath = directory.clone();
456 /* TODO: the control flow of this method call and subsequent expectations about the
457 * values in this loop is extremely difficult to follow. It also appears to
458 * perform a nested loop upon extracting every single file entry? Why does it
459 * accept two arguments that point to the same directory path, one mutable? */
460 file.safe_prepare_path(directory.as_ref(), &mut outpath, root_dir.as_ref())?;
461
462 if file.is_symlink() {
463 // `file.size()` is the uncompressed size declared in the central
464 // directory, i.e. attacker-controlled. A symlink target is a
465 // path, so an entry claiming more than `MAX_SYMLINK_TARGET_LEN`
466 // bytes is malformed. Reject it instead of reserving -- and then
467 // reading -- the declared size, which would otherwise let a
468 // small archive exhaust memory or abort the process.
469 let declared_len = file.size();
470 if declared_len > MAX_SYMLINK_TARGET_LEN {
471 return Err(invalid!(
472 "symlink target declares {} bytes, more than the {} byte limit",
473 declared_len,
474 MAX_SYMLINK_TARGET_LEN
475 ));
476 }
477 let mut target = Vec::with_capacity(declared_len as usize);
478 file.read_to_end(&mut target)?;
479 drop(file);
480 match extract_options.symlink_action {
481 SymlinkExtractAction::NoExtract => {
482 // do nothing
483 }
484 SymlinkExtractAction::ExtractAsFile => {
485 make_symlink_as_file(&outpath, &target)?;
486 }
487 SymlinkExtractAction::ExtractAsFileUtf8 => {
488 make_symlink_as_file_utf8(&outpath, &target)?;
489 }
490 #[cfg(any(unix, windows))]
491 SymlinkExtractAction::ExtractRecursiveInFolder => {
492 make_symlink(
493 directory.as_ref(),
494 &outpath,
495 &target,
496 &self.shared.files,
497 extract_options.symlink_action,
498 )?;
499 }
500 #[cfg(any(unix, windows))]
501 SymlinkExtractAction::ExtractInFolder => {
502 make_symlink(
503 directory.as_ref(),
504 &outpath,
505 &target,
506 &self.shared.files,
507 extract_options.symlink_action,
508 )?;
509 }
510 #[cfg(any(unix, windows))]
511 SymlinkExtractAction::ExtractNoRestrictions => {
512 let Ok(target_str) = std::str::from_utf8(&target) else {
513 return Err(invalid!("Invalid UTF-8 as symlink target"));
514 };
515 make_symlink_impl(&outpath, target_str, &self.shared.files)?;
516 }
517 }
518 } else if file.is_dir() {
519 make_writable_dir_all(&outpath)?;
520 // Check for real permissions, which we'll set in a second pass.
521 if let Some(mode) = file.unix_mode() {
522 files_by_unix_mode.add_mode(outpath, mode);
523 }
524 } else {
525 let mut outfile = fs::File::create(&outpath)?;
526 io::copy(&mut file, &mut outfile)?;
527 // Set original timestamp.
528 #[cfg(feature = "chrono")]
529 if let Some(last_modified) = file.last_modified()
530 && let Some(t) = last_modified.datetime_to_systemtime()
531 {
532 outfile.set_modified(t)?;
533 }
534 #[cfg(not(unix))]
535 if file.is_read_only() {
536 let mut permissions = outfile.metadata()?.permissions();
537 permissions.set_readonly(true);
538 outfile.set_permissions(permissions)?;
539 }
540 #[cfg(unix)]
541 if let Some(mode) = file.unix_mode() {
542 use std::os::unix::fs::PermissionsExt;
543 outfile.set_permissions(fs::Permissions::from_mode(mode))?;
544 }
545 }
546 }
547
548 // Ensure we update children's permissions before making a parent unwritable.
549 #[cfg(unix)]
550 for (path, perms) in files_by_unix_mode.all_perms_with_children_first() {
551 set_permissions_no_follow_symlink(&path, perms)?;
552 }
553 #[cfg(not(unix))]
554 for path in files_by_unix_mode.all_read_only_with_children_first() {
555 let metadata = fs::symlink_metadata(&path)?;
556 if metadata.is_dir() {
557 let mut permissions = metadata.permissions();
558 permissions.set_readonly(true);
559 fs::set_permissions(path, permissions)?;
560 }
561 }
562
563 Ok(())
564 }
565}
566
567/// A filter that determines whether an entry should be ignored when searching
568/// for the root directory of a Zip archive.
569///
570/// Returns `true` if the entry should be considered, and `false` if it should
571/// be ignored.
572///
573/// See [`root_dir_common_filter`] for a sensible default filter.
574pub trait RootDirFilter: Fn(&Path) -> bool {}
575impl<F: Fn(&Path) -> bool> RootDirFilter for F {}
576
577/// Common filters when finding the root directory of a Zip archive.
578///
579/// This filter is a sensible default for most use cases and filters out common
580/// system files that are usually irrelevant to the contents of the archive.
581///
582/// Currently, the filter ignores:
583/// - `/__MACOSX/`
584/// - `/.DS_Store`
585/// - `/Thumbs.db`
586///
587/// **This function is not guaranteed to be stable and may change in future versions.**
588///
589/// # Example
590///
591/// ```rust
592/// # use std::path::Path;
593/// assert!(zip::read::root_dir_common_filter(Path::new("foo.txt")));
594/// assert!(!zip::read::root_dir_common_filter(Path::new(".DS_Store")));
595/// assert!(!zip::read::root_dir_common_filter(Path::new("Thumbs.db")));
596/// assert!(!zip::read::root_dir_common_filter(Path::new("__MACOSX")));
597/// assert!(!zip::read::root_dir_common_filter(Path::new("__MACOSX/foo.txt")));
598/// ```
599#[must_use]
600pub fn root_dir_common_filter(path: &Path) -> bool {
601 const COMMON_FILTER_ROOT_FILES: &[&str] = &[".DS_Store", "Thumbs.db"];
602
603 if path.starts_with("__MACOSX") {
604 return false;
605 }
606
607 if path.components().count() == 1
608 && path.file_name().is_some_and(|file_name| {
609 COMMON_FILTER_ROOT_FILES
610 .iter()
611 .map(OsStr::new)
612 .any(|cmp| cmp == file_name)
613 })
614 {
615 return false;
616 }
617
618 true
619}