Skip to main content

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}