blob: b2c775c910ad1c86eaeb0dafeee165ba40b8e8fa [file] [edit]
// 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)]
//! Resolver implementations for libpathrs.
use crate::{
error::{Error, ErrorImpl, ErrorKind},
flags::{OpenFlags, ResolverFlags},
syscalls,
utils::FdExt,
Handle,
};
use std::{
fs::File,
io::Error as IOError,
os::unix::io::{AsFd, OwnedFd},
path::{Path, PathBuf},
rc::Rc,
};
/// `O_PATH`-based userspace resolver.
pub(crate) mod opath {
mod imp;
pub(crate) use imp::*;
mod symlink_stack;
pub(crate) use symlink_stack::{SymlinkStack, SymlinkStackError};
}
/// `openat2(2)`-based in-kernel resolver.
pub(crate) mod openat2;
/// A limited resolver only used for `/proc` lookups in `ProcfsHandle`.
pub(crate) mod procfs;
/// Maximum number of symlink traversals we will accept.
const MAX_SYMLINK_TRAVERSALS: usize = 128;
/// The backend used for path resolution within a [`Root`] to get a [`Handle`].
///
/// We don't generally recommend specifying this, since libpathrs will
/// automatically detect the best backend for your platform (which is the value
/// returned by `Resolver::default`). However, this can be useful for testing.
///
/// [`Root`]: crate::Root
/// [`Handle`]: crate::Handle
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub(crate) enum ResolverBackend {
/// Use the native `openat2(2)` backend (requires kernel support).
KernelOpenat2,
/// Use the userspace "emulated" backend.
EmulatedOpath,
// TODO: Implement a HardcoreEmulated which does pivot_root(2) and all the
// rest of it. It'd be useful to compare against and for some
// hyper-concerned users.
}
impl Default for ResolverBackend {
fn default() -> Self {
// Only check if there is a cached failure from a previous attempt to
// use openat2 -- we don't want to do a dummy openat2(2) call here in
// Default, since it gets called a lot by C FFI. If openat2(2) is
// unsupported, we will detect it later.
if syscalls::openat2::saw_openat2_failure() {
ResolverBackend::EmulatedOpath
} else {
ResolverBackend::KernelOpenat2
}
}
}
impl ResolverBackend {
/// Checks if the resolver is supported on the current platform.
#[cfg(test)]
pub(crate) fn supported(self) -> bool {
match self {
ResolverBackend::KernelOpenat2 => !syscalls::openat2::openat2_is_not_supported(),
ResolverBackend::EmulatedOpath => true,
}
}
}
/// Resolover backend and its associated flags.
///
/// This is the primary structure used to configure how a given [`Root`] will
/// conduct path resolutions.
///
/// [`Root`]: crate::Root
#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
pub struct Resolver {
/// Underlying resolution backend used.
pub(crate) backend: ResolverBackend,
/// Flags to pass to the resolution backend.
pub flags: ResolverFlags,
}
/// Only used for internal resolver implementations.
#[derive(Debug)]
pub(crate) enum PartialLookup<H, E = Error> {
Complete(H),
Partial {
handle: H,
remaining: PathBuf,
last_error: E,
},
}
impl<H> AsRef<H> for PartialLookup<H> {
fn as_ref(&self) -> &H {
match self {
Self::Complete(handle) => handle,
Self::Partial { handle, .. } => handle,
}
}
}
impl TryInto<Handle> for PartialLookup<Handle> {
type Error = Error;
fn try_into(self) -> Result<Handle, Self::Error> {
match self {
Self::Complete(handle) => Ok(handle),
Self::Partial { last_error, .. } => Err(last_error),
}
}
}
impl TryInto<Handle> for PartialLookup<Rc<OwnedFd>> {
type Error = Error;
fn try_into(self) -> Result<Handle, Self::Error> {
PartialLookup::<Handle>::from(self).try_into()
}
}
impl TryInto<(Handle, Option<PathBuf>)> for PartialLookup<Handle> {
type Error = Error;
fn try_into(self) -> Result<(Handle, Option<PathBuf>), Self::Error> {
match self {
Self::Complete(handle) => Ok((handle, None)),
Self::Partial {
handle,
remaining,
last_error,
} => match last_error.kind() {
ErrorKind::OsError(Some(libc::ENOENT)) => Ok((handle, Some(remaining))),
_ => Err(last_error),
},
}
}
}
impl From<PartialLookup<Rc<OwnedFd>>> for PartialLookup<Handle> {
fn from(result: PartialLookup<Rc<OwnedFd>>) -> Self {
let (rc, partial) = match result {
PartialLookup::Complete(rc) => (rc, None),
PartialLookup::Partial {
handle,
remaining,
last_error,
} => (handle, Some((remaining, last_error))),
};
// We are now sure that there is only a single reference to whatever
// current points to. There is nowhere else we could've stashed a
// reference, and we only do Rc::clone for root (which we've dropped).
let handle = Handle::from_fd(
// MSRV(1.70): Use Rc::into_inner().
Rc::try_unwrap(rc)
.expect("current handle in lookup should only have a single Rc reference"),
);
match partial {
None => Self::Complete(handle),
Some((remaining, last_error)) => Self::Partial {
handle,
remaining,
last_error,
},
}
}
}
impl Resolver {
fn generic_open(
&self,
root: impl AsFd,
path: impl AsRef<Path>,
flags: impl Into<OpenFlags>,
) -> Result<File, Error> {
let flags = flags.into();
// For backends without an accelerated one-shot open()
// implementation, we can just do the lookup+reopen thing in one go.
// For cffi users, this makes plain "open" operations faster.
let handle = self.resolve(root, path, flags.contains(OpenFlags::O_NOFOLLOW))?;
// O_NOFOLLOW makes things a little tricky. Unlike
// FdExt::reopen, we have to support O_NOFOLLOW|O_PATH of
// symlinks, but that is easily emulated by returning the handle
// directly without a reopen.
if handle.metadata()?.is_symlink() {
// If the user also asked for O_DIRECTORY, make sure we
// return the right error.
if flags.contains(OpenFlags::O_DIRECTORY) {
Err(ErrorImpl::OsError {
operation: "emulated openat2".into(),
source: IOError::from_raw_os_error(libc::ENOTDIR),
})?;
}
// If the user requested O_PATH|O_NOFOLLOW, then the only
// option we have is to return the handle we got. Without
// O_EMPTYPATH there is no easy way to apply any extra flags
// a user might've requested.
// TODO: Should we error out if the user asks for extra
// flags that don't match the flags for our handles?
if flags.contains(OpenFlags::O_PATH) {
return Ok(OwnedFd::from(handle).into());
}
// Otherwise, the user asked for O_NOFOLLOW and we saw a
// symlink, so return ELOOP like openat2 would.
Err(ErrorImpl::OsError {
operation: "emulated openat2".into(),
source: IOError::from_raw_os_error(libc::ELOOP),
})?;
}
handle.reopen(flags)
}
pub(crate) fn open(
&self,
root: impl AsFd,
path: impl AsRef<Path>,
flags: impl Into<OpenFlags>,
) -> Result<File, Error> {
let flags = flags.into();
// O_CREAT cannot be emulated by the O_PATH resolver (and in the
// fallback case the flag gets silently ignored unless you also set
// O_EXCL) so we need to explicitly return an error if it is provided.
if flags.intersects(OpenFlags::O_CREAT | OpenFlags::O_EXCL) {
Err(ErrorImpl::InvalidArgument {
name: "oflags".into(),
description: "open flags to one-shot open cannot contain O_CREAT or O_EXCL".into(),
})?
}
match self.backend {
// openat2 can do the lookup and open in one syscall.
ResolverBackend::KernelOpenat2 => {
let root = root.as_fd();
let path = path.as_ref();
openat2::open(root, path, self.flags, flags).or_else(|err| {
// If an error occurred, it could be due to openat2(2) being
// disabled via seccomp or just being unsupported. We check
// this via a dummy openat2(2) chall -- if that fails then
// we fallback to the generic open, otherwise we assume
// openat2(2) failed for a good reason and return that error
// outright.
//
// TODO: Find a way to make this fallback logic a bit less
// repetitive of the other match arm.
if syscalls::openat2::openat2_is_not_supported() {
self.generic_open(root, path, flags)
} else {
Err(err)
}
})
}
// For all other backends, just use the generic fallback.
_ => self.generic_open(root, path, flags),
}
}
#[inline]
pub(crate) fn resolve(
&self,
root: impl AsFd,
path: impl AsRef<Path>,
no_follow_trailing: bool,
) -> Result<Handle, Error> {
match self.backend {
ResolverBackend::KernelOpenat2 => {
let root = root.as_fd();
let path = path.as_ref();
openat2::resolve(root, path, self.flags, no_follow_trailing).or_else(|err| {
// If an error occurred, it could be due to openat2(2) being
// disabled via seccomp or just being unsupported. We check
// this via a dummy openat2(2) chall -- if that fails then
// we fallback to O_PATH, otherwise we assume openat2(2)
// failed for a good reason and return that error outright.
//
// TODO: Find a way to make this fallback logic a bit less
// repetitive of the other match arm.
if syscalls::openat2::openat2_is_not_supported() {
opath::resolve(root, path, self.flags, no_follow_trailing)
} else {
Err(err)
}
})
}
ResolverBackend::EmulatedOpath => {
opath::resolve(root, path, self.flags, no_follow_trailing)
}
}
}
#[inline]
pub(crate) fn resolve_partial(
&self,
root: impl AsFd,
path: impl AsRef<Path>,
no_follow_trailing: bool,
) -> Result<PartialLookup<Handle>, Error> {
match self.backend {
ResolverBackend::KernelOpenat2 => {
let root = root.as_fd();
let path = path.as_ref();
openat2::resolve_partial(root, path, self.flags, no_follow_trailing).or_else(
// If an error occurred, it could be due to openat2(2) being
// disabled via seccomp or just being unsupported. We check
// this via a dummy openat2(2) chall -- if that fails then
// we fallback to O_PATH, otherwise we assume openat2(2)
// failed for a good reason and return that error outright.
//
// TODO: Find a way to make this fallback logic a bit less
// repetitive of the other match arm.
|err| {
if syscalls::openat2::openat2_is_not_supported() {
opath::resolve_partial(root, path, self.flags, no_follow_trailing)
// Rc<File> -> Handle
.map(Into::into)
} else {
Err(err)
}
},
)
}
ResolverBackend::EmulatedOpath => {
opath::resolve_partial(root, path.as_ref(), self.flags, no_follow_trailing)
// Rc<File> -> Handle
.map(Into::into)
}
}
}
}