blob: a5d13cebbdee0bfaf0c5055240443e9015c2a7aa [file]
// 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/>.
*/
//! libpathrs provides a series of primitives for Linux programs to safely
//! handle path operations inside an untrusted directory tree. [There are
//! countless examples of security vulnerabilities caused by bad handling of
//! paths][avoidable-issues]; this library provides an easy-to-use set of VFS
//! APIs to avoid those kinds of issues.
//!
//! The idea is that a [`Root`] handle is like a handle for resolution inside a
//! [`chroot(2)`], with [`Handle`] being an `O_PATH` descriptor which you can
//! "upgrade" to a proper [`File`]. However this library acts far more
//! efficiently than spawning a new process and doing a full [`chroot(2)`] for
//! every operation.
//!
//! [avoidable-issues]: https://github.com/cyphar/libpathrs/blob/main/docs/avoidable-vulnerabilities.md
//! [`chroot(2)`]: http://man7.org/linux/man-pages/man2/chroot.2.html
//! [`File`]: std::fs::File
//! [`ProcfsHandle`]: crate::procfs::ProcfsHandle
//!
//! # Example
//!
//! The recommended usage of libpathrs looks something like this:
//!
//! ```
//! # use pathrs::{error::Error, flags::OpenFlags, Root};
//! # fn main() -> Result<(), Error> {
//! let (root_path, unsafe_path) = ("/path/to/root", "/etc/passwd");
//! # let root_path = "/";
//! // Get a root handle for resolution.
//! let root = Root::open(root_path)?;
//! // Resolve the path.
//! let handle = root.resolve(unsafe_path)?;
//! // Upgrade the handle to a full std::fs::File.
//! let file = handle.reopen(OpenFlags::O_RDONLY)?;
//!
//! // Or, in one line:
//! let file = root.resolve(unsafe_path)?
//! .reopen(OpenFlags::O_RDONLY)?;
//! # Ok(())
//! # }
//! ```
//!
//! # Kernel Support
//!
//! At the moment, `libpathrs` only works on Linux as it was designed around
//! Linux-only APIs that are necessary to provide safe path operations. In
//! future, we plan to expand support for other Unix-like operating systems.
//!
//! Please consult the [markdown documentation][kernel-feature-list] for the
//! latest information about what kernel features are supported and recommended
//! minimum kernel versions.
//!
//! [kernel-feature-list]: https://github.com/cyphar/libpathrs/blob/main/docs/kernel-features.md
// libpathrs only supports Linux at the moment.
#![cfg(target_os = "linux")]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(clippy::all)]
#![deny(missing_debug_implementations)]
// We use this the coverage_attribute when doing coverage runs.
// <https://github.com/rust-lang/rust/issues/84605>
#![cfg_attr(coverage, feature(coverage_attribute))]
/// The `CARGO_PKG_VERSION` of the pathrs crate.
///
/// This constant is mainly intended for our internal tests and should not be
/// used by other users, as it may be removed or changed in the future.
#[doc(hidden)]
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
// `Handle` implementation.
mod handle;
#[doc(inline)]
pub use handle::*;
// `Root` implementation.
mod root;
#[doc(inline)]
pub use root::*;
pub mod error;
pub mod flags;
pub mod procfs;
// Resolver backend implementations.
mod resolvers;
// C API.
#[cfg(feature = "capi")]
mod capi;
// Internally used helpers.
mod syscalls;
mod utils;
// Library tests.
#[cfg(test)]
mod tests;