| // SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later | |
| /* | |
| * libpathrs: safe path resolution on Linux | |
| * Copyright (C) 2019-2025 SUSE LLC | |
| * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com> | |
| * | |
| * == MPL-2.0 == | |
| * | |
| * This Source Code Form is subject to the terms of the Mozilla Public | |
| * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| * file, You can obtain one at https://mozilla.org/MPL/2.0/. | |
| * | |
| * Alternatively, this Source Code Form may also (at your option) be used | |
| * under the terms of the GNU Lesser General Public License Version 3, as | |
| * described below: | |
| * | |
| * == LGPL-3.0-or-later == | |
| * | |
| * This program is free software: you can redistribute it and/or modify it | |
| * under the terms of the GNU Lesser General Public License as published by | |
| * the Free Software Foundation, either version 3 of the License, or (at | |
| * your option) any later version. | |
| * | |
| * This program is distributed in the hope that it will be useful, but | |
| * WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General | |
| * Public License for more details. | |
| * | |
| * You should have received a copy of the GNU Lesser General Public License | |
| * along with this program. If not, see <https://www.gnu.org/licenses/>. | |
| */ | |
| #![forbid(unsafe_code)] | |
| use crate::{ | |
| error::{Error, ErrorExt, ErrorImpl}, | |
| flags::{OpenFlags, RenameFlags, ResolverFlags}, | |
| resolvers::Resolver, | |
| syscalls::{self, FrozenFd}, | |
| utils::{self, PathIterExt}, | |
| Handle, | |
| }; | |
| use std::{ | |
| fs::{File, Permissions}, | |
| io::Error as IOError, | |
| os::unix::{ | |
| ffi::OsStrExt, | |
| fs::PermissionsExt, | |
| io::{AsFd, BorrowedFd, OwnedFd}, | |
| }, | |
| path::{Path, PathBuf}, | |
| }; | |
| use rustix::{ | |
| fs::{self as rustix_fs, AtFlags, FileType}, | |
| io::Errno, | |
| }; | |
| /// An inode type to be created with [`Root::create`]. | |
| #[derive(Clone, Debug)] | |
| #[non_exhaustive] | |
| pub enum InodeType { | |
| /// Ordinary file, as in [`creat(2)`]. | |
| /// | |
| /// [`creat(2)`]: http://man7.org/linux/man-pages/man2/creat.2.html | |
| // XXX: It is possible to support non-O_EXCL O_CREAT with the native | |
| // backend. But it's unclear whether we should expose it given it's | |
| // only supported on native-kernel systems. | |
| File(Permissions), | |
| /// Directory, as in [`mkdir(2)`]. | |
| /// | |
| /// [`mkdir(2)`]: http://man7.org/linux/man-pages/man2/mkdir.2.html | |
| Directory(Permissions), | |
| /// Symlink with the given path, as in [`symlinkat(2)`]. | |
| /// | |
| /// Note that symlinks can contain any arbitrary `CStr`-style string (it | |
| /// doesn't need to be a real pathname). We don't do any verification of the | |
| /// target name. | |
| /// | |
| /// [`symlinkat(2)`]: http://man7.org/linux/man-pages/man2/symlinkat.2.html | |
| Symlink(PathBuf), | |
| /// Hard-link to the given path, as in [`linkat(2)`]. | |
| /// | |
| /// The provided path is resolved within the [`Root`]. It is currently | |
| /// not supported to hardlink a file inside the [`Root`]'s tree to a file | |
| /// outside the [`Root`]'s tree. | |
| // XXX: Should we ever support that? | |
| /// | |
| /// [`linkat(2)`]: http://man7.org/linux/man-pages/man2/linkat.2.html | |
| Hardlink(PathBuf), | |
| /// Named pipe (aka FIFO), as in [`mkfifo(3)`]. | |
| /// | |
| /// [`mkfifo(3)`]: http://man7.org/linux/man-pages/man3/mkfifo.3.html | |
| Fifo(Permissions), | |
| /// Character device, as in [`mknod(2)`] with `S_IFCHR`. | |
| /// | |
| /// [`mknod(2)`]: http://man7.org/linux/man-pages/man2/mknod.2.html | |
| CharacterDevice(Permissions, rustix_fs::Dev), | |
| /// Block device, as in [`mknod(2)`] with `S_IFBLK`. | |
| /// | |
| /// [`mknod(2)`]: http://man7.org/linux/man-pages/man2/mknod.2.html | |
| BlockDevice(Permissions, rustix_fs::Dev), | |
| // XXX: Does this really make sense? | |
| //// "Detached" unix socket, as in [`mknod(2)`] with `S_IFSOCK`. | |
| //// | |
| //// [`mknod(2)`]: http://man7.org/linux/man-pages/man2/mknod.2.html | |
| //DetachedSocket(), | |
| } | |
| /// The inode type for [`RootRef::remove_inode`]. This only used internally | |
| /// within libpathrs. | |
| #[derive(Clone, Copy, Debug)] | |
| enum RemoveInodeType { | |
| Regular, // ~AT_REMOVEDIR | |
| Directory, // AT_REMOVEDIR | |
| } | |
| /// A handle to the root of a directory tree. | |
| /// | |
| /// # Safety | |
| /// | |
| /// At the time of writing, it is considered a **very bad idea** to open a | |
| /// [`Root`] inside a possibly-attacker-controlled directory tree. While we do | |
| /// have protections that should defend against it (for both drivers), it's far | |
| /// more dangerous than just opening a directory tree which is not inside a | |
| /// potentially-untrusted directory. | |
| /// | |
| /// # Errors | |
| /// | |
| /// If at any point an attack is detected during the execution of a [`Root`] | |
| /// method, an error will be returned. The method of attack detection is | |
| /// multi-layered and operates through explicit `/proc/self/fd` checks as well | |
| /// as (in the case of the native backend) kernel-space checks that will trigger | |
| /// `-EXDEV` in certain attack scenarios. | |
| /// | |
| /// Additionally, if this root directory is moved then any subsequent operations | |
| /// will fail with a `SafetyViolation` error since it's not obvious | |
| /// whether there is an attacker or if the path was moved innocently. This | |
| /// restriction might be relaxed in the future. | |
| // TODO: Fix the SafetyViolation link once we expose ErrorKind. | |
| #[derive(Debug)] | |
| pub struct Root { | |
| /// The underlying `O_PATH` [`OwnedFd`] for this root handle. | |
| inner: OwnedFd, | |
| /// The underlying [`Resolver`] to use for all operations underneath this | |
| /// root. This affects not just [`resolve`] but also all other methods which | |
| /// have to implicitly resolve a path underneath [`Root`]. | |
| /// | |
| /// [`resolve`]: Self::resolve | |
| resolver: Resolver, | |
| } | |
| impl Root { | |
| /// Open a [`Root`] handle. | |
| /// | |
| /// The resolver backend used by this handle is chosen at runtime based on | |
| /// which resolvers are supported by the running kernel. | |
| /// | |
| /// # Errors | |
| /// | |
| /// `path` must be an existing directory, and must (at the moment) be a | |
| /// fully-resolved pathname with no symlink components. This restriction | |
| /// might be relaxed in the future. | |
| #[doc(alias = "pathrs_open_root")] | |
| pub fn open(path: impl AsRef<Path>) -> Result<Self, Error> { | |
| let file = syscalls::openat( | |
| syscalls::AT_FDCWD, | |
| path, | |
| OpenFlags::O_PATH | OpenFlags::O_DIRECTORY, | |
| 0, | |
| ) | |
| .map_err(|err| ErrorImpl::RawOsError { | |
| operation: "open root handle".into(), | |
| source: err, | |
| })?; | |
| Ok(Self::from_fd(file)) | |
| } | |
| /// Wrap an [`OwnedFd`] into a [`Root`]. | |
| /// | |
| /// The [`OwnedFd`] should be a file descriptor referencing a directory, | |
| /// otherwise all [`Root`] operations will fail. | |
| /// | |
| /// The configuration is set to the system default and should be configured | |
| /// prior to usage, if appropriate. | |
| #[inline] | |
| pub fn from_fd(fd: impl Into<OwnedFd>) -> Self { | |
| Self { | |
| inner: fd.into(), | |
| resolver: Default::default(), | |
| } | |
| } | |
| /// Borrow this [`Root`] as a [`RootRef`]. | |
| /// | |
| /// The [`ResolverFlags`] of the [`Root`] are inherited by the [`RootRef`] | |
| /// byt are not shared ([`Root::set_resolver_flags`] does not affect | |
| /// existing [`RootRef`]s or [`RootRef`]s not created using | |
| /// [`Root::as_ref`]). | |
| // XXX: We can't use Borrow/Deref for this because HandleRef takes a | |
| // lifetime rather than being a pure reference. Ideally we would use | |
| // Deref but it seems that won't be possible in standard Rust for a | |
| // long time, if ever... | |
| #[inline] | |
| pub fn as_ref(&self) -> RootRef<'_> { | |
| RootRef { | |
| inner: self.as_fd(), | |
| resolver: self.resolver, | |
| } | |
| } | |
| /// Get the current [`ResolverFlags`] for this [`Root`]. | |
| #[inline] | |
| pub fn resolver_flags(&self) -> ResolverFlags { | |
| self.resolver.flags | |
| } | |
| /// Set the [`ResolverFlags`] for all operations in this [`Root`]. | |
| /// | |
| /// Note that this only affects this instance of [`Root`]. Neither other | |
| /// [`Root`] instances nor existing [`RootRef`] references to this [`Root`] | |
| /// will have their [`ResolverFlags`] unchanged. | |
| #[inline] | |
| pub fn set_resolver_flags(&mut self, flags: ResolverFlags) -> &mut Self { | |
| self.resolver.flags = flags; | |
| self | |
| } | |
| /// Set the [`ResolverFlags`] for all operations in this [`Root`]. | |
| /// | |
| /// This is identical to [`Root::set_resolver_flags`] except that it can | |
| /// more easily be used with chaining to configure a [`Root`] in a single | |
| /// line: | |
| /// | |
| /// ```rust | |
| /// # use pathrs::{Root, flags::ResolverFlags}; | |
| /// # let tmpdir = tempfile::TempDir::new()?; | |
| /// # let rootdir = &tmpdir; | |
| /// let root = Root::open(rootdir)?.with_resolver_flags(ResolverFlags::NO_SYMLINKS); | |
| /// // Continue to use root. | |
| /// # let _ = tmpdir; // make sure it is not dropped early | |
| /// # Ok::<(), anyhow::Error>(()) | |
| /// ``` | |
| /// | |
| /// If you want to temporarily set flags just for a small set of operations, | |
| /// you should use [`Root::as_ref`] to create a temporary [`RootRef`] and | |
| /// use [`RootRef::with_resolver_flags`] instead. | |
| #[inline] | |
| pub fn with_resolver_flags(mut self, flags: ResolverFlags) -> Self { | |
| self.set_resolver_flags(flags); | |
| self | |
| } | |
| /// Create a copy of an existing [`Root`]. | |
| /// | |
| /// The new handle is completely independent from the original, but | |
| /// references the same underlying file and has the same configuration. | |
| #[inline] | |
| pub fn try_clone(&self) -> Result<Root, Error> { | |
| self.as_ref().try_clone() | |
| } | |
| /// Within the given [`Root`]'s tree, resolve `path` and return a | |
| /// [`Handle`]. | |
| /// | |
| /// All symlink path components are scoped to [`Root`]. Trailing symlinks | |
| /// *are* followed, if you want to get a handle to a symlink use | |
| /// [`resolve_nofollow`]. | |
| /// | |
| /// # Errors | |
| /// | |
| /// If `path` doesn't exist, or an attack was detected during resolution, a | |
| /// corresponding [`Error`] will be returned. If no error is returned, then | |
| /// the path is guaranteed to have been reachable from the root of the | |
| /// directory tree and thus have been inside the root at one point in the | |
| /// resolution. | |
| /// | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_resolve")] | |
| #[inline] | |
| pub fn resolve(&self, path: impl AsRef<Path>) -> Result<Handle, Error> { | |
| self.as_ref().resolve(path) | |
| } | |
| /// Identical to [`resolve`], except that *trailing* symlinks are *not* | |
| /// followed. | |
| /// | |
| /// If the trailing component is a symlink [`resolve_nofollow`] will return | |
| /// a handle to the symlink itself. This is effectively equivalent to | |
| /// `O_NOFOLLOW`. | |
| /// | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_resolve_nofollow")] | |
| #[inline] | |
| pub fn resolve_nofollow(&self, path: impl AsRef<Path>) -> Result<Handle, Error> { | |
| self.as_ref().resolve_nofollow(path) | |
| } | |
| /// Open a path without creating an intermediate [`Handle`] object. | |
| /// | |
| /// This is effectively just shorthand for [`resolve`] followed by | |
| /// [`Handle::reopen`]. However, some resolvers (such as the `openat2` | |
| /// resolver) can implement [`open_subpath`] slightly more efficiently than | |
| /// naively doing a two-step open operation with [`Handle::reopen`]. If you | |
| /// wish to create an [`OpenFlags::O_PATH`] file handle, it probably makes | |
| /// more sense to use [`resolve`] or [`resolve_nofollow`]. | |
| /// | |
| /// If `flags` contains [`OpenFlags::O_NOFOLLOW`] and the path refers to a | |
| /// symlink then this method will match the behaviour of [`openat2`] (this | |
| /// is in contrast to [`Handle::reopen`] which does not permit re-opening a | |
| /// handle to a symlink): | |
| /// | |
| /// * If `flags` also contains [`OpenFlags::O_PATH`] then the returned file | |
| /// is equivalent to the [`Handle`] that would've been returned from | |
| /// [`resolve_nofollow`]. | |
| /// * Otherwise, an error will be returned to match the behaviour of | |
| /// [`OpenFlags::O_NOFOLLOW`] when encountering a trailing symlink. | |
| /// | |
| /// [`openat2`]: https://man7.org/linux/man-pages/man2/openat2.2.html | |
| /// [`open_subpath`]: Self::open_subpath | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_open")] | |
| #[inline] | |
| pub fn open_subpath( | |
| &self, | |
| path: impl AsRef<Path>, | |
| flags: impl Into<OpenFlags>, | |
| ) -> Result<File, Error> { | |
| self.as_ref().open_subpath(path, flags) | |
| } | |
| /// Get the target of a symlink within a [`Root`]. | |
| /// | |
| /// **NOTE**: The returned path is not modified to be "safe" outside of the | |
| /// root. You should not use this path for doing further path lookups -- use | |
| /// [`resolve`] instead. | |
| /// | |
| /// This method is just shorthand for calling `readlinkat(2)` on the handle | |
| /// returned by [`resolve_nofollow`]. | |
| /// | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_readlink")] | |
| #[inline] | |
| pub fn readlink(&self, path: impl AsRef<Path>) -> Result<PathBuf, Error> { | |
| self.as_ref().readlink(path) | |
| } | |
| /// Within the [`Root`]'s tree, create an inode at `path` as specified by | |
| /// `inode_type`. | |
| /// | |
| /// # Errors | |
| /// | |
| /// In addition to the regular filesystem errors that can be returned, note | |
| /// that if the path already exists (regardless of the type of the existing | |
| /// inode), [`EEXIST`] will be returned. | |
| /// | |
| /// [`EEXIST`]: std::io::ErrorKind::AlreadyExists | |
| #[doc(alias = "pathrs_inroot_mkdir")] | |
| #[doc(alias = "pathrs_inroot_mknod")] | |
| #[doc(alias = "pathrs_inroot_symlink")] | |
| #[doc(alias = "pathrs_inroot_hardlink")] | |
| #[inline] | |
| pub fn create(&self, path: impl AsRef<Path>, inode_type: &InodeType) -> Result<(), Error> { | |
| self.as_ref().create(path, inode_type) | |
| } | |
| /// Create an [`InodeType::File`] within the [`Root`]'s tree at `path` with | |
| /// the mode given by `perm`, and return a [`Handle`] to the newly-created | |
| /// file. | |
| /// | |
| /// However, unlike the trivial way of doing the above: | |
| /// | |
| /// ```dead_code | |
| /// root.create(path, inode_type)?; | |
| /// // What happens if the file is replaced here!? | |
| /// let handle = root.resolve(path, perm)?; | |
| /// ``` | |
| /// | |
| /// [`create_file`] guarantees that the returned [`Handle`] is the same as | |
| /// the file created by the operation. This is only possible to guarantee | |
| /// for ordinary files because there is no [`O_CREAT`]-equivalent for other | |
| /// inode types. | |
| /// | |
| /// # Errors | |
| /// | |
| /// Mostly identical to [`create`], except that an error will only be | |
| /// returned if the path already exists if and only if [`OpenFlags::O_EXCL`] | |
| /// is set in `flags`. | |
| /// | |
| /// [`create`]: Self::create | |
| /// [`create_file`]: Self::create_file | |
| /// [`O_CREAT`]: http://man7.org/linux/man-pages/man2/open.2.html | |
| #[doc(alias = "pathrs_inroot_creat")] | |
| #[doc(alias = "pathrs_inroot_create")] | |
| #[inline] | |
| pub fn create_file( | |
| &self, | |
| path: impl AsRef<Path>, | |
| flags: impl Into<OpenFlags>, | |
| perm: &Permissions, | |
| ) -> Result<File, Error> { | |
| self.as_ref().create_file(path, flags, perm) | |
| } | |
| /// Within the [`Root`]'s tree, create a directory and any of its parent | |
| /// component if they are missing. This is effectively equivalent to | |
| /// [`std::fs::create_dir_all`], Go's [`os.MkdirAll`], or Unix's `mkdir -p`. | |
| /// | |
| /// The provided set of [`Permissions`] only applies to path components | |
| /// created by this function, existing components will not have their | |
| /// permissions modified. In addition, if the provided path already exists | |
| /// and is a directory, this function will return successfully. | |
| /// | |
| /// The returned [`Handle`] is an `O_DIRECTORY` handle referencing the | |
| /// created directory (due to kernel limitations, we cannot guarantee that | |
| /// the handle is the exact directory created and not a similar-looking | |
| /// directory that was swapped in by an attacker, but we do as much | |
| /// validation as possible to make sure the directory is functionally | |
| /// identical to the directory we would've created). | |
| /// | |
| /// # Errors | |
| /// | |
| /// This method will return an error if any of the path components in the | |
| /// provided path were invalid (non-directory components or dangling symlink | |
| /// components) or if certain exchange attacks were detected. | |
| /// | |
| /// If an error occurs, it is possible for any number of the directories in | |
| /// `path` to have been created despite this method returning an error. | |
| /// | |
| /// [`os.MkdirAll`]: https://pkg.go.dev/os#MkdirAll | |
| #[doc(alias = "pathrs_inroot_mkdir_all")] | |
| #[inline] | |
| pub fn mkdir_all(&self, path: impl AsRef<Path>, perm: &Permissions) -> Result<Handle, Error> { | |
| self.as_ref().mkdir_all(path, perm) | |
| } | |
| /// Within the [`Root`]'s tree, remove the empty directory at `path`. | |
| /// | |
| /// Any existing [`Handle`]s to `path` will continue to work as before, | |
| /// since Linux does not invalidate file handles to unlinked files (though, | |
| /// directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist, was not actually a directory, or was a | |
| /// non-empty directory an error will be returned. In order to remove a | |
| /// directory and all of its children, you can use [`remove_all`]. | |
| /// | |
| /// [`remove_all`]: Self::remove_all | |
| #[doc(alias = "pathrs_inroot_rmdir")] | |
| #[inline] | |
| pub fn remove_dir(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| self.as_ref().remove_dir(path) | |
| } | |
| /// Within the [`Root`]'s tree, remove the file (any non-directory inode) at | |
| /// `path`. | |
| /// | |
| /// Any existing [`Handle`]s to `path` will continue to work as before, | |
| /// since Linux does not invalidate file handles to unlinked files (though, | |
| /// directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist or was actually a directory an error will be | |
| /// returned. In order to remove a path regardless of its type (even if it | |
| /// is a non-empty directory), you can use [`remove_all`]. | |
| /// | |
| /// [`remove_all`]: Self::remove_all | |
| #[doc(alias = "pathrs_inroot_unlink")] | |
| #[inline] | |
| pub fn remove_file(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| self.as_ref().remove_file(path) | |
| } | |
| /// Within the [`Root`]'s tree, recursively delete the provided `path` and | |
| /// any children it contains if it is a directory. This is effectively | |
| /// equivalent to [`std::fs::remove_dir_all`], Go's [`os.RemoveAll`], or | |
| /// Unix's `rm -r`. | |
| /// | |
| /// Any existing [`Handle`]s to paths within `path` will continue to work as | |
| /// before, since Linux does not invalidate file handles to unlinked files | |
| /// (though, directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist or some other error occurred during the | |
| /// deletion process an error will be returned. | |
| /// | |
| /// [`os.RemoveAll`]: https://pkg.go.dev/os#RemoveAll | |
| #[doc(alias = "pathrs_inroot_remove_all")] | |
| #[inline] | |
| pub fn remove_all(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| self.as_ref().remove_all(path) | |
| } | |
| /// Within the [`Root`]'s tree, perform a rename with the given `source` and | |
| /// `directory`. The `flags` argument is passed directly to | |
| /// [`renameat2(2)`]. | |
| /// | |
| /// # Errors | |
| /// | |
| /// The error rules are identical to [`renameat2(2)`]. | |
| /// | |
| /// [`renameat2(2)`]: http://man7.org/linux/man-pages/man2/renameat2.2.html | |
| #[doc(alias = "pathrs_inroot_rename")] | |
| pub fn rename( | |
| &self, | |
| source: impl AsRef<Path>, | |
| destination: impl AsRef<Path>, | |
| rflags: RenameFlags, | |
| ) -> Result<(), Error> { | |
| self.as_ref().rename(source, destination, rflags) | |
| } | |
| } | |
| impl From<OwnedFd> for Root { | |
| /// Shorthand for [`Root::from_fd`]. | |
| fn from(fd: OwnedFd) -> Self { | |
| Self::from_fd(fd) | |
| } | |
| } | |
| impl From<Root> for OwnedFd { | |
| /// Unwrap a [`Root`] to reveal the underlying [`OwnedFd`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for file descriptor | |
| /// passing or otherwise transmitting file descriptor information. It is not | |
| /// safe to use this [`OwnedFd`] directly to do filesystem operations. | |
| /// Please use the provided [`Root`] methods. | |
| fn from(root: Root) -> Self { | |
| root.inner | |
| } | |
| } | |
| impl AsFd for Root { | |
| /// Access the underlying file descriptor for a [`Root`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for tests and other | |
| /// code to check the status of the underlying [`OwnedFd`] without having to | |
| /// use [`OwnedFd::from`]. It is not safe to use this [`BorrowedFd`] | |
| /// directly to do filesystem operations. Please use the provided [`Root`] | |
| /// methods. | |
| #[inline] | |
| fn as_fd(&self) -> BorrowedFd<'_> { | |
| self.inner.as_fd() | |
| } | |
| } | |
| /// Borrowed version of [`Root`]. | |
| /// | |
| /// Unlike [`Root`], when [`RootRef`] is dropped the underlying file descriptor | |
| /// is *not* closed. This is mainly useful for programs and libraries that have | |
| /// to do operations on [`&File`][File]s and [`BorrowedFd`]s passed from | |
| /// elsewhere. | |
| /// | |
| /// [File]: std::fs::File | |
| // TODO: Is there any way we can restructure this to use Deref so that we don't | |
| // need to copy all of the methods into Handle? Probably not... Maybe GATs | |
| // will eventually support this but we'd still need a GAT-friendly Deref. | |
| #[derive(Copy, Clone, Debug)] | |
| pub struct RootRef<'fd> { | |
| inner: BorrowedFd<'fd>, | |
| // TODO: Drop this and switch to builder-pattern. | |
| resolver: Resolver, | |
| } | |
| impl RootRef<'_> { | |
| /// Wrap a [`BorrowedFd`] into a [`RootRef`]. | |
| /// | |
| /// The [`BorrowedFd`] should be a file descriptor referencing a directory, | |
| /// otherwise all [`Root`] operations will fail. | |
| /// | |
| /// The configuration is set to the system default and should be configured | |
| /// prior to usage, if appropriate. | |
| pub fn from_fd(inner: BorrowedFd<'_>) -> RootRef<'_> { | |
| RootRef { | |
| inner, | |
| resolver: Default::default(), | |
| } | |
| } | |
| /// Get the current [`ResolverFlags`] for this [`RootRef`]. | |
| #[inline] | |
| pub fn resolver_flags(&self) -> ResolverFlags { | |
| self.resolver.flags | |
| } | |
| /// Set the [`ResolverFlags`] for all operations in this [`RootRef`]. | |
| /// | |
| /// Note that this only affects this instance of [`RootRef`]. Neither the | |
| /// original [`Root`] nor any other [`RootRef`] references to the same | |
| /// underlying [`Root`] will have their [`ResolverFlags`] unchanged. | |
| /// | |
| /// [`RootRef::clone`] also copies the current [`ResolverFlags`] of the | |
| /// [`RootRef`]. | |
| #[inline] | |
| pub fn set_resolver_flags(&mut self, flags: ResolverFlags) -> &mut Self { | |
| self.resolver.flags = flags; | |
| self | |
| } | |
| /// Set the [`ResolverFlags`] for all operations in this [`RootRef`]. | |
| /// | |
| /// This is identical to [`RootRef::set_resolver_flags`] except that it can | |
| /// more easily be used with chaining to configure a [`RootRef`] in a single | |
| /// line: | |
| /// | |
| /// ```rust | |
| /// # use std::{ | |
| /// # fs::{Permissions, File}, | |
| /// # os::unix::{ | |
| /// # fs::PermissionsExt, | |
| /// # io::{AsFd, OwnedFd}, | |
| /// # }, | |
| /// # }; | |
| /// # use pathrs::{RootRef, flags::ResolverFlags, InodeType}; | |
| /// # let tmpdir = tempfile::TempDir::new()?; | |
| /// # let rootdir = &tmpdir; | |
| /// let fd: OwnedFd = File::open(rootdir)?.into(); | |
| /// let root = RootRef::from_fd(fd.as_fd()) | |
| /// .with_resolver_flags(ResolverFlags::NO_SYMLINKS); | |
| /// | |
| /// // Continue to use RootRef. | |
| /// # let perm = Permissions::from_mode(0o755); | |
| /// root.mkdir_all("foo/bar/baz", &perm)?; | |
| /// root.create("one", &InodeType::Directory(perm))?; | |
| /// root.remove_all("foo")?; | |
| /// # let _ = tmpdir; // make sure it is not dropped early | |
| /// # Ok::<(), anyhow::Error>(()) | |
| /// ``` | |
| /// | |
| /// The other primary usecase for [`RootRef::with_resolver_flags`] is with | |
| /// [`Root::as_ref`] to temporarily set some flags for a single one-line or | |
| /// a few operations without modifying the original [`Root`] resolver flags: | |
| /// | |
| /// ```rust | |
| /// # use std::{fs::Permissions, os::unix::fs::PermissionsExt}; | |
| /// # use pathrs::{Root, flags::ResolverFlags, InodeType}; | |
| /// # let tmpdir = tempfile::TempDir::new()?; | |
| /// # let rootdir = &tmpdir; | |
| /// let root = Root::open(rootdir)?; | |
| /// # let perm = Permissions::from_mode(0o755); | |
| /// | |
| /// // Apply ResolverFlags::NO_SYMLINKS for a single operation. | |
| /// root.as_ref() | |
| /// .with_resolver_flags(ResolverFlags::NO_SYMLINKS) | |
| /// .mkdir_all("foo/bar/baz", &perm)?; | |
| /// | |
| /// // Create a temporary RootRef to do multiple operations. | |
| /// let root2 = root | |
| /// .as_ref() | |
| /// .with_resolver_flags(ResolverFlags::NO_SYMLINKS); | |
| /// root2.create("one", &InodeType::Directory(perm))?; | |
| /// root2.remove_all("foo")?; | |
| /// # let _ = tmpdir; // make sure it is not dropped early | |
| /// # Ok::<(), anyhow::Error>(()) | |
| /// ``` | |
| #[inline] | |
| pub fn with_resolver_flags(mut self, flags: ResolverFlags) -> Self { | |
| self.set_resolver_flags(flags); | |
| self | |
| } | |
| /// Create a copy of a [`RootRef`]. | |
| /// | |
| /// Note that (unlike [`BorrowedFd::clone`]) this method creates a full copy | |
| /// of the underlying file descriptor and thus is more equivalent to | |
| /// [`BorrowedFd::try_clone_to_owned`]. | |
| /// | |
| /// To create a shallow copy of a [`RootRef`], you can use [`Clone::clone`] | |
| /// (or just [`Copy`]). | |
| // TODO: We might need to call this something other than try_clone(), since | |
| // it's a little too easy to confuse with Clone::clone() but we also | |
| // really want to have Copy. | |
| pub fn try_clone(&self) -> Result<Root, Error> { | |
| Ok(Root { | |
| inner: self | |
| .as_fd() | |
| .try_clone_to_owned() | |
| .map_err(|err| ErrorImpl::OsError { | |
| operation: "clone underlying root file".into(), | |
| source: err, | |
| })?, | |
| resolver: self.resolver, | |
| }) | |
| } | |
| /// Within the given [`RootRef`]'s tree, resolve `path` and return a | |
| /// [`Handle`]. | |
| /// | |
| /// All symlink path components are scoped to [`RootRef`]. Trailing symlinks | |
| /// *are* followed, if you want to get a handle to a symlink use | |
| /// [`resolve_nofollow`]. | |
| /// | |
| /// # Errors | |
| /// | |
| /// If `path` doesn't exist, or an attack was detected during resolution, a | |
| /// corresponding [`Error`] will be returned. If no error is returned, then | |
| /// the path is guaranteed to have been reachable from the root of the | |
| /// directory tree and thus have been inside the root at one point in the | |
| /// resolution. | |
| /// | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_resolve")] | |
| #[inline] | |
| pub fn resolve(&self, path: impl AsRef<Path>) -> Result<Handle, Error> { | |
| self.resolver.resolve(self, path, false) | |
| } | |
| /// Identical to [`resolve`], except that *trailing* symlinks are *not* | |
| /// followed. | |
| /// | |
| /// If the trailing component is a symlink [`resolve_nofollow`] will return | |
| /// a handle to the symlink itself. This is effectively equivalent to | |
| /// `O_NOFOLLOW`. | |
| /// | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_resolve_nofollow")] | |
| #[inline] | |
| pub fn resolve_nofollow(&self, path: impl AsRef<Path>) -> Result<Handle, Error> { | |
| self.resolver.resolve(self, path, true) | |
| } | |
| /// Open a path without creating an intermediate [`Handle`] object. | |
| /// | |
| /// This is effectively just shorthand for [`resolve`] followed by | |
| /// [`Handle::reopen`]. However, some resolvers (such as the `openat2` | |
| /// resolver) can implement [`open_subpath`] slightly more efficiently than | |
| /// naively doing a two-step open operation with [`Handle::reopen`]. If you | |
| /// wish to create an [`OpenFlags::O_PATH`] file handle, it probably makes | |
| /// more sense to use [`resolve`] or [`resolve_nofollow`]. | |
| /// | |
| /// If `flags` contains [`OpenFlags::O_NOFOLLOW`] and the path refers to a | |
| /// symlink then this method will match the behaviour of [`openat2`] (this | |
| /// is in contrast to [`Handle::reopen`] which does not permit re-opening a | |
| /// handle to a symlink): | |
| /// | |
| /// * If `flags` also contains [`OpenFlags::O_PATH`] then the returned file | |
| /// is equivalent to the [`Handle`] that would've been returned from | |
| /// [`resolve_nofollow`]. | |
| /// * Otherwise, an error will be returned to match the behaviour of | |
| /// [`OpenFlags::O_NOFOLLOW`] when encountering a trailing symlink. | |
| /// | |
| /// [`openat2`]: https://man7.org/linux/man-pages/man2/openat2.2.html | |
| /// [`open_subpath`]: Self::open_subpath | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_open")] | |
| #[inline] | |
| pub fn open_subpath( | |
| &self, | |
| path: impl AsRef<Path>, | |
| flags: impl Into<OpenFlags>, | |
| ) -> Result<File, Error> { | |
| self.resolver.open(self, path, flags) | |
| } | |
| /// Resolve the parent of a given path. This is used internally when | |
| /// implementing operations that operate on the parent directory, such as | |
| /// operations that: | |
| /// | |
| /// * Create new inodes (i.e. the target path doesn't already exist). | |
| /// * Are implemented with syscalls that do not allow us to use | |
| /// `AT_EMPTY_PATH` or an equivalent (such as [`rename`]) even though the | |
| /// path exists. | |
| /// | |
| /// The returned tuple is `(dir, name, trailing_slash)` (i.e. a handle to | |
| /// *parent* directory, basename of the path, and a `bool` indicating | |
| /// whether the original path had a trailing slash). It is up to the caller | |
| /// to decide what the correct handling of `trailing_slash` is (but if it is | |
| /// ignored by the caller then trailing slashes will be ignored wholesale). | |
| /// | |
| /// If you expect the target path to exist already, then | |
| /// [`resolve_exists_parent`] may be more suitable. | |
| /// | |
| /// [`rename`]: Self::rename | |
| /// [`resolve_exists_parent`]: Self::resolve_exists_parent | |
| fn resolve_parent<'p>( | |
| &self, | |
| path: &'p Path, | |
| ) -> Result<(OwnedFd, Option<&'p Path>, bool), Error> { | |
| let (path, trailing_slash) = utils::path_strip_trailing_slash(path); | |
| let (parent, name) = utils::path_split(path).wrap("split path into (parent, name)")?; | |
| // All users of resolve_parent require the basename to be an actual | |
| // pathname (as opposed to being empty or a special name like "." or | |
| // ".."), so return an error here if that is the path we got. | |
| let name = match name.map(|p| (p, p.as_os_str().as_bytes())) { | |
| // We stripped any trailing slashes, so there cannot be an empty | |
| // basename. | |
| None | Some((_, b"." | b"..")) => { | |
| return Ok(( | |
| self.inner | |
| .try_clone_to_owned() | |
| .map_err(|err| ErrorImpl::OsError { | |
| operation: "clone root".into(), | |
| source: err, | |
| })?, | |
| None, | |
| trailing_slash, | |
| )); | |
| } | |
| Some((name, _)) => name, | |
| }; | |
| let dir = self | |
| .resolve(parent) | |
| .wrap("resolve parent directory")? | |
| .into(); | |
| Ok((dir, Some(name), trailing_slash)) | |
| } | |
| /// Equivalent to [`resolve_parent`], except that we assume that the target | |
| /// exists and so if `path` has a trailing slash we verify that the target | |
| /// path is actually a directory. | |
| /// | |
| /// If you need more complicated handling, use [`resolve_parent`]. | |
| /// | |
| /// [`resolve_parent`]: Self::resolve_parent | |
| fn resolve_exists_parent<'p>( | |
| &self, | |
| path: &'p Path, | |
| ) -> Result<(OwnedFd, Option<&'p Path>), Error> { | |
| let (dir, name, trailing_slash) = self.resolve_parent(path)?; | |
| if trailing_slash { | |
| let stat = syscalls::fstatat(&dir, name.unwrap_or(Path::new(""))).map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "check trailing slash path is a directory".into(), | |
| source: err, | |
| } | |
| })?; | |
| if !FileType::from_raw_mode(stat.st_mode).is_dir() { | |
| Err(ErrorImpl::OsError { | |
| operation: "verify trailing slash path".into(), | |
| source: IOError::from_raw_os_error(libc::ENOTDIR), | |
| })?; | |
| } | |
| } | |
| Ok((dir, name)) | |
| } | |
| /// Get the target of a symlink within a [`RootRef`]. | |
| /// | |
| /// **NOTE**: The returned path is not modified to be "safe" outside of the | |
| /// root. You should not use this path for doing further path lookups -- use | |
| /// [`resolve`] instead. | |
| /// | |
| /// This method is just shorthand for calling `readlinkat(2)` on the handle | |
| /// returned by [`resolve_nofollow`]. | |
| /// | |
| /// [`resolve`]: Self::resolve | |
| /// [`resolve_nofollow`]: Self::resolve_nofollow | |
| #[doc(alias = "pathrs_inroot_readlink")] | |
| pub fn readlink(&self, path: impl AsRef<Path>) -> Result<PathBuf, Error> { | |
| let link = self | |
| .resolve_nofollow(path) | |
| .wrap("resolve symlink O_NOFOLLOW for readlink")?; | |
| syscalls::readlinkat(link, "").map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "readlink resolve symlink".into(), | |
| source: err, | |
| } | |
| .into() | |
| }) | |
| } | |
| /// Within the [`RootRef`]'s tree, create an inode at `path` as specified by | |
| /// `inode_type`. | |
| /// | |
| /// # Errors | |
| /// | |
| /// In addition to the regular filesystem errors that can be returned, note | |
| /// that if the path already exists (regardless of the type of the existing | |
| /// inode), [`EEXIST`] will be returned. | |
| /// | |
| /// [`EEXIST`]: std::io::ErrorKind::AlreadyExists | |
| #[doc(alias = "pathrs_inroot_mkdir")] | |
| #[doc(alias = "pathrs_inroot_mknod")] | |
| #[doc(alias = "pathrs_inroot_symlink")] | |
| #[doc(alias = "pathrs_inroot_hardlink")] | |
| pub fn create(&self, path: impl AsRef<Path>, inode_type: &InodeType) -> Result<(), Error> { | |
| // The path doesn't exist yet, so we need to get a safe reference to the | |
| // parent and just operate on the final (slashless) component. | |
| let (dir, name, trailing_slash) = self | |
| .resolve_parent(path.as_ref()) | |
| .wrap("resolve file creation path")?; | |
| let name = name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "file creation path is /".into(), | |
| })?; | |
| // The trailing slash behaviour depends on what inode type we are making | |
| // (to mirror Linux's behaviour). In particular, mkdir("non-exist/") is | |
| // legal. | |
| if trailing_slash && !matches!(inode_type, InodeType::Directory(_)) { | |
| Err(ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "file creation path has trailing slash".into(), | |
| })?; | |
| } | |
| match inode_type { | |
| InodeType::File(perm) => { | |
| let mode = perm.mode() & !libc::S_IFMT; | |
| syscalls::mknodat(dir, name, libc::S_IFREG | mode, 0) | |
| } | |
| InodeType::Directory(perm) => { | |
| let mode = perm.mode() & !libc::S_IFMT; | |
| syscalls::mkdirat(dir, name, mode) | |
| } | |
| InodeType::Symlink(target) => { | |
| // No need to touch target. | |
| syscalls::symlinkat(target, dir, name) | |
| } | |
| InodeType::Hardlink(target) => { | |
| let (olddir, oldname, trailing_slash) = self | |
| .resolve_parent(target) | |
| .wrap("resolve hardlink source path")?; | |
| let oldname = oldname.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "target".into(), | |
| description: "hardlink source path is /".into(), | |
| })?; | |
| // Directories cannot be a hardlink target, so indiscriminately | |
| // block trailing slashes for the target path. | |
| if trailing_slash { | |
| Err(ErrorImpl::InvalidArgument { | |
| name: "target".into(), | |
| description: "hardlink target path has trailing slash".into(), | |
| })?; | |
| } | |
| syscalls::linkat(olddir, oldname, dir, name, AtFlags::empty()) | |
| } | |
| InodeType::Fifo(perm) => { | |
| let mode = perm.mode() & !libc::S_IFMT; | |
| syscalls::mknodat(dir, name, libc::S_IFIFO | mode, 0) | |
| } | |
| InodeType::CharacterDevice(perm, dev) => { | |
| let mode = perm.mode() & !libc::S_IFMT; | |
| syscalls::mknodat(dir, name, libc::S_IFCHR | mode, *dev) | |
| } | |
| InodeType::BlockDevice(perm, dev) => { | |
| let mode = perm.mode() & !libc::S_IFMT; | |
| syscalls::mknodat(dir, name, libc::S_IFBLK | mode, *dev) | |
| } | |
| } | |
| .map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "pathrs create".into(), | |
| source: err, | |
| } | |
| .into() | |
| }) | |
| } | |
| /// Create an [`InodeType::File`] within the [`RootRef`]'s tree at `path` | |
| /// with the mode given by `perm`, and return a [`Handle`] to the | |
| /// newly-created file. | |
| /// | |
| /// However, unlike the trivial way of doing the above: | |
| /// | |
| /// ```dead_code | |
| /// root.create(path, inode_type)?; | |
| /// // What happens if the file is replaced here!? | |
| /// let handle = root.resolve(path, perm)?; | |
| /// ``` | |
| /// | |
| /// [`create_file`] guarantees that the returned [`Handle`] is the same as | |
| /// the file created by the operation. This is only possible to guarantee | |
| /// for ordinary files because there is no [`O_CREAT`]-equivalent for other | |
| /// inode types. | |
| /// | |
| /// # Errors | |
| /// | |
| /// Mostly identical to [`create`], except that an error will only be | |
| /// returned if the path already exists if and only if [`OpenFlags::O_EXCL`] | |
| /// is set in `flags`. | |
| /// | |
| /// [`create`]: Self::create | |
| /// [`create_file`]: Self::create_file | |
| /// [`O_CREAT`]: http://man7.org/linux/man-pages/man2/open.2.html | |
| #[doc(alias = "pathrs_inroot_creat")] | |
| #[doc(alias = "pathrs_inroot_create")] | |
| pub fn create_file( | |
| &self, | |
| path: impl AsRef<Path>, | |
| flags: impl Into<OpenFlags>, | |
| perm: &Permissions, | |
| ) -> Result<File, Error> { | |
| let mut flags = flags.into(); | |
| // O_TMPFILE needs special handling -- the pathname is not the name of a | |
| // new file (thus requiring us to resolve the parent). Instead, it names | |
| // a directory on a filesystem where an unnamed temporary file should be | |
| // created. | |
| if flags.contains(OpenFlags::O_TMPFILE) { | |
| // TODO: Ideally we could just do this with open_subpath() or | |
| // resolver.open() but they don't take Permissions... | |
| let dir = self.resolve(path.as_ref())?; | |
| return syscalls::openat(dir, ".", flags, perm.mode()) | |
| .map_err(|err| { | |
| { | |
| ErrorImpl::RawOsError { | |
| operation: "pathrs create tmpfile".into(), | |
| source: err, | |
| } | |
| } | |
| .into() | |
| }) | |
| .map(Into::into); | |
| } | |
| // The path doesn't exist yet, so we need to get a safe reference to the | |
| // parent and just operate on the final (slashless) component. | |
| let (dir, name, trailing_slash) = self | |
| .resolve_parent(path.as_ref()) | |
| .wrap("resolve O_CREAT file creation path")?; | |
| let name = name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "file creation path is /".into(), | |
| })?; | |
| // For obvious reasons, we cannot O_CREAT a directory. | |
| if trailing_slash { | |
| Err(ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "O_CREAT file creation path has trailing slash".into(), | |
| })?; | |
| } | |
| // XXX: openat2(2) supports doing O_CREAT on trailing symlinks without | |
| // O_NOFOLLOW. We might want to expose that here, though because it | |
| // can't be done with the emulated backend that might be a bad idea. | |
| flags.insert(OpenFlags::O_CREAT); | |
| let fd = syscalls::openat(dir, name, flags, perm.mode()).map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "pathrs create_file".into(), | |
| source: err, | |
| } | |
| })?; | |
| Ok(fd.into()) | |
| } | |
| /// Within the [`RootRef`]'s tree, create a directory and any of its parent | |
| /// component if they are missing. | |
| /// | |
| /// This is effectively equivalent to [`std::fs::create_dir_all`], Go's | |
| /// [`os.MkdirAll`], or Unix's `mkdir -p`. | |
| /// | |
| /// The provided set of [`Permissions`] only applies to path components | |
| /// created by this function, existing components will not have their | |
| /// permissions modified. In addition, if the provided path already exists | |
| /// and is a directory, this function will return successfully. | |
| /// | |
| /// The returned [`Handle`] is an `O_DIRECTORY` handle referencing the | |
| /// created directory (due to kernel limitations, we cannot guarantee that | |
| /// the handle is the exact directory created and not a similar-looking | |
| /// directory that was swapped in by an attacker, but we do as much | |
| /// validation as possible to make sure the directory is functionally | |
| /// identical to the directory we would've created). | |
| /// | |
| /// # Errors | |
| /// | |
| /// This method will return an error if any of the path components in the | |
| /// provided path were invalid (non-directory components or dangling symlink | |
| /// components) or if certain exchange attacks were detected. | |
| /// | |
| /// If an error occurs, it is possible for any number of the directories in | |
| /// `path` to have been created despite this method returning an error. | |
| /// | |
| /// [`os.MkdirAll`]: https://pkg.go.dev/os#MkdirAll | |
| #[doc(alias = "pathrs_inroot_mkdir_all")] | |
| pub fn mkdir_all(&self, path: impl AsRef<Path>, perm: &Permissions) -> Result<Handle, Error> { | |
| if perm.mode() & !0o7777 != 0 { | |
| Err(ErrorImpl::InvalidArgument { | |
| name: "perm".into(), | |
| description: "mode cannot contain non-0o7777 bits".into(), | |
| })? | |
| } | |
| // Linux silently ignores S_IS[UG]ID if passed to mkdirat(2), and a lot | |
| // of libraries just ignore these flags. However, ignoring them as a new | |
| // library seems less than ideal -- users shouldn't set flags that are | |
| // no-ops because they might not notice they are no-ops. | |
| if perm.mode() & !0o1777 != 0 { | |
| Err(ErrorImpl::InvalidArgument { | |
| name: "perm".into(), | |
| description: | |
| "mode contains setuid or setgid bits that are silently ignored by mkdirat" | |
| .into(), | |
| })? | |
| } | |
| let (handle, remaining) = self | |
| .resolver | |
| .resolve_partial(self, path.as_ref(), false) | |
| .and_then(TryInto::try_into)?; | |
| // Re-open the handle with O_DIRECTORY to make sure it's a directory we | |
| // can use as well as to make sure we return an O_DIRECTORY regardless | |
| // of whether there are any remaining components (for consistency). | |
| let mut current = handle | |
| .reopen(OpenFlags::O_DIRECTORY) | |
| .with_wrap(|| format!("cannot re-open {} with O_DIRECTORY", FrozenFd::from(handle)))?; | |
| // For the remaining | |
| let remaining_parts = remaining | |
| .iter() | |
| .flat_map(PathIterExt::raw_components) | |
| .map(|p| p.to_os_string()) | |
| // Skip over no-op entries. | |
| .filter(|part| !part.is_empty() && part.as_bytes() != b".") | |
| .collect::<Vec<_>>(); | |
| // If the path contained ".." components after the end of the "real" | |
| // components, we simply error out. We could try to safely resolve ".." | |
| // here but that would add a bunch of extra logic for something that | |
| // it's not clear even needs to be supported. | |
| // | |
| // We also can't just do something like filepath.Clean(), because ".." | |
| // could erase dangling symlinks and produce a path that doesn't match | |
| // what the user asked for. | |
| if remaining_parts.iter().any(|part| part.as_bytes() == b"..") { | |
| Err(ErrorImpl::OsError { | |
| operation: "mkdir_all remaining components".into(), | |
| source: IOError::from_raw_os_error(libc::ENOENT), | |
| }) | |
| .with_wrap(|| { | |
| format!("yet-to-be-created path {remaining:?} contains '..' components") | |
| })? | |
| } | |
| // For the remaining components, create a each component one-by-one. | |
| for part in remaining_parts { | |
| if part.as_bytes().contains(&b'/') { | |
| Err(ErrorImpl::SafetyViolation { | |
| description: "remaining component for mkdir contains '/'".into(), | |
| })?; | |
| } | |
| // Try to create the component first, to reduce the risk of races | |
| // where the inode gets created between the openat() check and then | |
| // the fallback mkdirat(). An attacker could delete the inode, of | |
| // course, but we can just error out in that case. | |
| // | |
| // mkdirat(2) does not follow trailing symlinks (even if it is a | |
| // dangling symlink with only a trailing component missing), so we | |
| // can safely create the final component without worrying about | |
| // symlink-exchange attacks. | |
| if let Err(err) = syscalls::mkdirat(¤t, &part, perm.mode()) { | |
| // If we got EEXIST then either the directory existed before or | |
| // a racing Root::mkdir_all created the directory before us. We | |
| // can safely continue because the following openat() will only | |
| // succeed if it is a directory at open()-time (and not another | |
| // inode type an attacker might've swapped in). | |
| if err.errno() != Errno::EXIST { | |
| Err(ErrorImpl::RawOsError { | |
| operation: "create next directory component".into(), | |
| source: err, | |
| })?; | |
| } | |
| } | |
| // Get a handle to the directory we just created. Unfortunately we | |
| // can't do an atomic create+open (a-la O_CREAT) with mkdirat(), so | |
| // a separate O_DIRECTORY|O_NOFOLLOW is the best we can do. | |
| let next = syscalls::openat( | |
| ¤t, | |
| &part, | |
| OpenFlags::O_NOFOLLOW | OpenFlags::O_DIRECTORY, | |
| 0, | |
| ) | |
| .map_err(|err| ErrorImpl::RawOsError { | |
| operation: "open newly created directory".into(), | |
| source: err, | |
| })?; | |
| // Unfortunately, we cannot create a directory and open it | |
| // atomically (a-la O_CREAT). This means an attacker could swap our | |
| // newly created directory with one they have. Ideally we would | |
| // verify that the directory "looks right" by checking the owner, | |
| // mode, and whether it is empty. | |
| // | |
| // However, it turns out that trying to do this correctly is more | |
| // complicated than you might expect. Basic Unix DACs are mostly | |
| // trivial to emulate, but POSIX ACLs and filesystem-specific mount | |
| // options can affect ownership and modes in unexpected ways, | |
| // resulting in spurious errors. In addition, some pseudofilesystems | |
| // (like cgroupfs) create non-empty directories so requiring new | |
| // directories be empty would result in spurious errors. | |
| // | |
| // Ultimately, the semantics of Root::mkdir_all() permit reusing an | |
| // existing directory that an attacker created beforehand, so | |
| // verifying that directories we create weren't swapped really | |
| // doesn't seem to provide any practical benefit. | |
| // Keep walking. | |
| current = next.into(); | |
| } | |
| Ok(Handle::from_fd(current)) | |
| } | |
| /// Within the [`RootRef`]'s tree, remove the inode of type `inode_type` at | |
| /// `path`. | |
| /// | |
| /// Any existing [`Handle`]s to `path` will continue to work as before, | |
| /// since Linux does not invalidate file handles to unlinked files (though, | |
| /// directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist, was not actually `inode_type`, or was a | |
| /// non-empty directory an error will be returned. In order to remove a path | |
| /// regardless of whether it exists, its type, or if it it's a non-empty | |
| /// directory, you can use [`remove_all`]. | |
| /// | |
| /// [`remove_all`]: Self::remove_all | |
| fn remove_inode(&self, path: &Path, inode_type: RemoveInodeType) -> Result<(), Error> { | |
| // unlinkat(2) doesn't let us remove an inode using just a handle (for | |
| // obvious reasons -- on Unix hardlinks mean that "unlink this file" | |
| // doesn't make sense without referring to a specific directory entry). | |
| let (dir, name, trailing_slash) = self | |
| .resolve_parent(path.as_ref()) | |
| .wrap("resolve file removal path")?; | |
| let name = name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "file removal path is /".into(), | |
| })?; | |
| let flags = match inode_type { | |
| RemoveInodeType::Regular => { | |
| if trailing_slash { | |
| Err(ErrorImpl::OsError { | |
| operation: "file removal path cannot have trailing slash".into(), | |
| source: IOError::from_raw_os_error(libc::ENOTDIR), | |
| })?; | |
| } | |
| AtFlags::empty() | |
| } | |
| RemoveInodeType::Directory => AtFlags::REMOVEDIR, | |
| }; | |
| syscalls::unlinkat(dir, name, flags).map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "pathrs remove".into(), | |
| source: err, | |
| } | |
| .into() | |
| }) | |
| } | |
| /// Within the [`RootRef`]'s tree, remove the empty directory at `path`. | |
| /// | |
| /// Any existing [`Handle`]s to `path` will continue to work as before, | |
| /// since Linux does not invalidate file handles to unlinked files (though, | |
| /// directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist, was not actually a directory, or was a | |
| /// non-empty directory an error will be returned. In order to remove a | |
| /// directory and all of its children, you can use [`remove_all`]. | |
| /// | |
| /// [`remove_all`]: Self::remove_all | |
| #[doc(alias = "pathrs_inroot_rmdir")] | |
| #[inline] | |
| pub fn remove_dir(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| self.remove_inode(path.as_ref(), RemoveInodeType::Directory) | |
| } | |
| /// Within the [`RootRef`]'s tree, remove the file (any non-directory inode) | |
| /// at `path`. | |
| /// | |
| /// Any existing [`Handle`]s to `path` will continue to work as before, | |
| /// since Linux does not invalidate file handles to unlinked files (though, | |
| /// directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist or was actually a directory an error will be | |
| /// returned. In order to remove a path regardless of its type (even if it | |
| /// is a non-empty directory), you can use [`remove_all`]. | |
| /// | |
| /// [`remove_all`]: Self::remove_all | |
| #[doc(alias = "pathrs_inroot_unlink")] | |
| #[inline] | |
| pub fn remove_file(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| self.remove_inode(path.as_ref(), RemoveInodeType::Regular) | |
| } | |
| /// Within the [`RootRef`]'s tree, recursively delete the provided `path` | |
| /// and any children it contains if it is a directory. This is effectively | |
| /// equivalent to [`std::fs::remove_dir_all`], Go's [`os.RemoveAll`], or | |
| /// Unix's `rm -r`. | |
| /// | |
| /// Any existing [`Handle`]s to paths within `path` will continue to work as | |
| /// before, since Linux does not invalidate file handles to unlinked files | |
| /// (though, directory handling is not as simple). | |
| /// | |
| /// # Errors | |
| /// | |
| /// If the path does not exist or some other error occurred during the | |
| /// deletion process an error will be returned. | |
| /// | |
| /// [`os.RemoveAll`]: https://pkg.go.dev/os#RemoveAll | |
| #[doc(alias = "pathrs_inroot_remove_all")] | |
| pub fn remove_all(&self, path: impl AsRef<Path>) -> Result<(), Error> { | |
| // Ignore trailing slashes -- we want to support handling trailing | |
| // slashes for directories, but adding resolve_exists_parent-like | |
| // verification logic to remove_all() is a bit much. So we just ignore | |
| // trailing slashes entirely. | |
| // | |
| // For what it's worth, this matches the behaviour of Go's os.RemoveAll | |
| // and GNU's "rm -rf". | |
| let (dir, name, _) = self | |
| .resolve_parent(path.as_ref()) | |
| .wrap("resolve remove-all path")?; | |
| // TODO: We can probably support removing "/" or "." in the future by | |
| // simply removing all children and not removing the top-level | |
| // directory. | |
| let name = name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "path".into(), | |
| description: "remove all path is /".into(), | |
| })?; | |
| utils::remove_all(&dir, name) | |
| } | |
| /// Within the [`RootRef`]'s tree, perform a rename with the given `source` | |
| /// and `directory`. The `flags` argument is passed directly to | |
| /// [`renameat2(2)`]. | |
| /// | |
| /// # Errors | |
| /// | |
| /// The error rules are identical to [`renameat2(2)`]. | |
| /// | |
| /// [`renameat2(2)`]: http://man7.org/linux/man-pages/man2/renameat2.2.html | |
| #[doc(alias = "pathrs_inroot_rename")] | |
| pub fn rename( | |
| &self, | |
| source: impl AsRef<Path>, | |
| destination: impl AsRef<Path>, | |
| rflags: RenameFlags, | |
| ) -> Result<(), Error> { | |
| // renameat2(2) doesn't let us rename paths using AT_EMPTY_PATH handles. | |
| // Note that the source must always exist, and we do want to verify the | |
| // trailing path is correct. | |
| let (src_dir, src_name) = self | |
| .resolve_exists_parent(source.as_ref()) | |
| .wrap("resolve rename source path")?; | |
| let src_name = src_name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "source".into(), | |
| description: "rename source path is /".into(), | |
| })?; | |
| // However, target path handling is unfortunately a little more | |
| // complicated. Ideally we want to match the native trailing-slash | |
| // behaviour of renameat2(2) to avoid confusion. | |
| let (dst_dir, dst_name) = if rflags.contains(RenameFlags::RENAME_EXCHANGE) { | |
| // For RENAME_EXCHANGE, the target simply must exist and can be a | |
| // different type from the source. Trailing slashes are only allowed | |
| // if the target path is a directory. | |
| self.resolve_exists_parent(destination.as_ref()) | |
| } else { | |
| // For all other renames, trailing slashes on the *target* path are | |
| // only allowed if the *source* path is a directory. (Also, if the | |
| // target path exists, it must be a directory but this is implicitly | |
| // handled by renameat2(2) and so we don't need to check it here.) | |
| self.resolve_parent(destination.as_ref()) | |
| .and_then(|(dir, name, trailing_slash)| { | |
| if trailing_slash { | |
| let src_stat = syscalls::fstatat(&src_dir, src_name).map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "check rename source path is a directory".into(), | |
| source: err, | |
| } | |
| })?; | |
| if !FileType::from_raw_mode(src_stat.st_mode).is_dir() { | |
| Err(ErrorImpl::OsError { | |
| operation: "destination path has trailing slash but source is not a directory".into(), | |
| source: IOError::from_raw_os_error(libc::ENOTDIR), | |
| })?; | |
| } | |
| } | |
| Ok((dir, name)) | |
| }) | |
| } | |
| .wrap("resolve rename destination path")?; | |
| let dst_name = dst_name.ok_or_else(|| ErrorImpl::InvalidArgument { | |
| name: "destination".into(), | |
| description: "rename destination path is /".into(), | |
| })?; | |
| syscalls::renameat2(src_dir, src_name, dst_dir, dst_name, rflags).map_err(|err| { | |
| ErrorImpl::RawOsError { | |
| operation: "pathrs rename".into(), | |
| source: err, | |
| } | |
| .into() | |
| }) | |
| } | |
| } | |
| impl<'fd> From<BorrowedFd<'fd>> for RootRef<'fd> { | |
| /// Shorthand for [`RootRef::from_fd`]. | |
| fn from(fd: BorrowedFd<'fd>) -> Self { | |
| Self::from_fd(fd) | |
| } | |
| } | |
| impl AsFd for RootRef<'_> { | |
| /// Access the underlying file descriptor for a [`RootRef`]. | |
| /// | |
| /// **Note**: This method is primarily intended to allow for tests and other | |
| /// code to check the status of the underlying file descriptor. It is not | |
| /// safe to use this [`BorrowedFd`] directly to do filesystem operations. | |
| /// Please use the provided [`RootRef`] methods. | |
| #[inline] | |
| fn as_fd(&self) -> BorrowedFd<'_> { | |
| self.inner.as_fd() | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use crate::{resolvers::ResolverBackend, Root, RootRef}; | |
| use std::os::unix::io::{AsFd, AsRawFd, OwnedFd}; | |
| use anyhow::Error; | |
| use pretty_assertions::assert_eq; | |
| impl Root { | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn resolver_backend(&self) -> ResolverBackend { | |
| self.resolver.backend | |
| } | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn set_resolver_backend(&mut self, backend: ResolverBackend) -> &mut Self { | |
| self.resolver.backend = backend; | |
| self | |
| } | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn with_resolver_backend(mut self, backend: ResolverBackend) -> Self { | |
| self.set_resolver_backend(backend); | |
| self | |
| } | |
| } | |
| impl RootRef<'_> { | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn resolver_backend(&self) -> ResolverBackend { | |
| self.resolver.backend | |
| } | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn set_resolver_backend(&mut self, backend: ResolverBackend) -> &mut Self { | |
| self.resolver.backend = backend; | |
| self | |
| } | |
| // TODO: Should we make this public? Is there any real benefit? | |
| #[inline] | |
| pub(crate) fn with_resolver_backend(mut self, backend: ResolverBackend) -> Self { | |
| self.set_resolver_backend(backend); | |
| self | |
| } | |
| } | |
| #[test] | |
| fn from_fd() -> Result<(), Error> { | |
| let root = Root::open(".")?; | |
| let root_ref1 = root.as_ref(); | |
| let root_ref2 = RootRef::from_fd(root.as_fd()); | |
| assert_eq!( | |
| root.as_fd().as_raw_fd(), | |
| root_ref1.as_fd().as_raw_fd(), | |
| "Root::as_ref should have the same underlying fd" | |
| ); | |
| assert_eq!( | |
| root.as_fd().as_raw_fd(), | |
| root_ref2.as_fd().as_raw_fd(), | |
| "RootRef::from_fd should have the same underlying fd" | |
| ); | |
| Ok(()) | |
| } | |
| #[test] | |
| fn into_from_ownedfd() -> Result<(), Error> { | |
| let root = Root::open(".")?; | |
| let root_fd = root.as_fd().as_raw_fd(); | |
| let owned: OwnedFd = root.into(); | |
| let owned_fd = owned.as_fd().as_raw_fd(); | |
| let root2: Root = owned.into(); | |
| let root2_fd = root2.as_fd().as_raw_fd(); | |
| assert_eq!( | |
| root_fd, owned_fd, | |
| "OwnedFd::from(root) should have same underlying fd", | |
| ); | |
| assert_eq!( | |
| root_fd, root2_fd, | |
| "Root -> OwnedFd -> Root roundtrip should have same underlying fd", | |
| ); | |
| Ok(()) | |
| } | |
| } |