blob: 058c3e0a5482957d9fd12a8961aa59d69dbb4121 [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/>.
*/
use crate::{
error::{Error, ErrorImpl},
flags::OpenFlags,
procfs,
syscalls::{self, OpenHow, ResolveFlags},
utils::{fd::proc_threadself_subpath, FdExt, MaybeOwnedFd},
};
use std::{
os::unix::{
fs::MetadataExt,
io::{AsRawFd, BorrowedFd, OwnedFd},
},
path::Path,
};
use rustix::fs::{Access, AtFlags};
/// "We have [`ProcfsHandle`] at home."
///
/// One of the core issues when implementing [`ProcfsHandle`] is that a lot of
/// helper functions used by [`ProcfsHandle`] would really like to be able to
/// use [`ProcfsHandle`] in a re-entrant way to get some extra safety against
/// attacks, while also supporting callers that don't even have a `/proc` handle
/// ready or callers that are not within the [`ProcfsHandle`] implementation and
/// thus can get full safety from [`ProcfsHandle`] itself.
///
/// The main purpose of this type is to allow us to easily indicate this (as
/// opposed to `Option<BorrowedFd<'_>>` everywhere) and provide some helpers to
/// help reduce the complexity of the helper functions.
///
/// In general, you should only be using this for core helper functions used by
/// [`ProcfsHandle`] which need to take a reference to the *root* of `/proc`.
/// Make sure to always use the same [`RawProcfsRoot`] consistently, lest you
/// end up with very weird coherency problems.
///
/// [`ProcfsHandle`]: crate::procfs::ProcfsHandle
#[derive(Copy, Clone, Debug)]
pub(crate) enum RawProcfsRoot<'fd> {
/// Use the global `/proc`. This is unsafe against most attacks, and should
/// only ever really be used for debugging purposes only, such as in
/// [`FdExt::as_unsafe_path_unchecked`].
///
/// [`FdExt::as_unsafe_path_unchecked`]: crate::utils::FdExt::as_unsafe_path_unchecked
UnsafeGlobal,
/// Use this [`BorrowedFd`] as the rootfs of a proc and operate relative to
/// it. This is still somewhat unsafe, depending on what kernel features are
/// available.
UnsafeFd(BorrowedFd<'fd>),
}
impl<'fd> RawProcfsRoot<'fd> {
/// Convert this to a [`MaybeOwnedFd`].
///
/// For [`RawProcfsRoot::UnsafeGlobal`], this requires opening `/proc` and
/// thus allocating a new file handle. For all other variants this should be
/// a very cheap reference conversion.
pub(crate) fn try_into_maybe_owned_fd<'a>(&'a self) -> Result<MaybeOwnedFd<'a, OwnedFd>, Error>
where
'a: 'fd,
{
let fd = match self {
Self::UnsafeGlobal => MaybeOwnedFd::OwnedFd(
syscalls::openat(
syscalls::BADFD,
"/proc",
OpenFlags::O_PATH | OpenFlags::O_DIRECTORY,
0,
)
.map_err(|err| ErrorImpl::RawOsError {
operation: "open /proc handle".into(),
source: err,
})?,
),
Self::UnsafeFd(fd) => MaybeOwnedFd::BorrowedFd(*fd),
};
procfs::verify_is_procfs_root(fd.as_fd())?;
Ok(fd)
}
/// `accessat(procfs_root, path, Access:EXISTS, AtFlags::SYMLINK_NOFOLLOW)`
///
/// Should only be used as an indicative check (namely to see if
/// `/proc/thread-self` exists), and this has no protections against
/// malicious components regardless of what kind of handle it is.
///
/// The only user of this is [`ProcfsBase::into_path`] which only uses it to
/// decide whether `/proc/thread-self` exists.
///
/// [`ProcfsBase::into_path`]: crate::procfs::ProcfsBase::into_path
pub(crate) fn exists_unchecked(&self, path: impl AsRef<Path>) -> Result<(), Error> {
syscalls::accessat(
self.try_into_maybe_owned_fd()?.as_fd(),
path,
Access::EXISTS,
AtFlags::SYMLINK_NOFOLLOW,
)
.map_err(|err| {
ErrorImpl::RawOsError {
operation: "check if subpath exists in raw procfs".into(),
source: err,
}
.into()
})
}
/// Open a subpath within this [`RawProcfsRoot`] using `openat2`.
///
/// `RESOLVE_NO_MAGICLINKS | RESOLVE_NO_XDEV | RESOLVE_BENEATH` are all
/// auto-applied.
fn openat2_beneath(&self, path: impl AsRef<Path>, oflags: OpenFlags) -> Result<OwnedFd, Error> {
let path = path.as_ref();
syscalls::openat2(
self.try_into_maybe_owned_fd()?.as_fd(),
path,
OpenHow {
flags: oflags,
mode: 0,
resolve: (ResolveFlags::RESOLVE_NO_MAGICLINKS
| ResolveFlags::RESOLVE_NO_XDEV
| ResolveFlags::RESOLVE_BENEATH)
.bits(),
},
)
.map_err(|err| {
ErrorImpl::RawOsError {
operation: "open raw procfs subpath".into(),
source: err,
}
.into()
})
}
/// Open a subpath within this [`RawProcfsRoot`] using `openat`.
///
/// A best-effort attempt is made to try to avoid getting tricked by
/// overmounts, but this method does not guarantee protection against
/// bind-mount overmounts.
fn opath_beneath_unchecked(
&self,
path: impl AsRef<Path>,
oflags: OpenFlags,
) -> Result<OwnedFd, Error> {
let path = path.as_ref();
let proc_rootfd = self.try_into_maybe_owned_fd()?;
let proc_rootfd = proc_rootfd.as_fd();
// We split the open into O_PATH+reopen below, which means if O_NOFOLLOW
// is requested (which it always is), we need to apply it to the initial
// O_PATH and not the re-open. If the target is not a symlink,
// everything works fine -- if the target was a symlink the re-open will
// fail with -ELOOP (the same as a one-shot open).
let (opath_oflags, oflags) = (
oflags & OpenFlags::O_NOFOLLOW,
oflags & !OpenFlags::O_NOFOLLOW,
);
// This is technically not safe, but there really is not much we can do
// in practice -- we would need to have a separate copy of the procfs
// resolver code without any mount-id-related protections (or add an
// unsafe_disable_mnt_id_checks argument), and even then it would not
// practically protect against attacks.
//
// An attacker could still bind-mount their own /proc/thread-self/fdinfo
// (after opening hundreds of handles to /proc) on top of our
// /proc/thread-self/fdinfo, at which point they could trivially fake
// fdinfo without the need for symlinks or tmpfs.
//
// At this point, we are just trying to minimise the damage a trivial
// attack on top of a static procfs path can do. An attacker that can
// actively bind-mount on top of /proc/thread-self/fdinfo cannot be
// protected against without openat2(2) or STATX_MNT_ID.
// In order to avoid being tricked into following a trivial symlink or
// bind-mount to a filesystem object that could DoS us when we try to
// O_RDONLY open it below (such as a stale NFS handle), first open it
// with O_PATH then double-check that it is a procfs inode.
let opath = syscalls::openat(proc_rootfd, path, OpenFlags::O_PATH | opath_oflags, 0)
.map_err(|err| ErrorImpl::RawOsError {
operation: "preliminary open raw procfs subpath to check fstype".into(),
source: err,
})?;
// As below, we can't use verify_same_procfs_mnt.
procfs::verify_is_procfs(&opath)?;
// We can't do FdExt::reopen() here because this code is potentially
// called within ProcfsHandle. However, we can just re-open through
// /proc/thread-self/fd/$n directly -- this is not entirely safe
// against bind-mounts but this will make it harder for an attacker
// (they would need to predict the fd number of the transient file
// we just opened, and have the ability to bind-mount over
// magic-links -- which is something that a lot of tools do not
// support).
let file = syscalls::openat_follow(
proc_rootfd,
proc_threadself_subpath(*self, &format!("fd/{}", opath.as_raw_fd())),
oflags,
0,
)
.map_err(|err| ErrorImpl::RawOsError {
operation: "re-open raw procfs subpath".into(),
source: err,
})?;
// As below, we can't use verify_same_procfs_mnt.
procfs::verify_is_procfs(&file)?;
// Finally, verify that the inode numbers match. This is not
// strictly "necessary" (since the opath could be an
// attacker-controlled procfs file), but this could at least detect
// sloppy /proc/self/fd/* overmounts.
if opath.metadata()?.ino() != file.metadata()?.ino() {
Err(ErrorImpl::SafetyViolation {
description: "fd has an inconsistent inode number after re-opening -- probably a manipulated procfs".into(),
})?;
}
Ok(file)
}
/// Open a subpath within this [`RawProcfsRoot`].
///
/// As this method is only really used for `fdinfo`, trailing symlinks are
/// not followed (i.e. [`OpenFlags::O_NOFOLLOW`] is always implied).
pub(crate) fn open_beneath(
&self,
path: impl AsRef<Path>,
mut oflags: OpenFlags,
) -> Result<OwnedFd, Error> {
let path = path.as_ref();
oflags.insert(OpenFlags::O_NOFOLLOW);
let fd = self.openat2_beneath(path, oflags).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.
if syscalls::openat2::openat2_is_not_supported() {
self.opath_beneath_unchecked(path, oflags)
} else {
Err(err)
}
})?;
// As this is called from within fetch_mnt_id as a fallback, the only
// thing we can do here is verify that it is actually procfs. However,
// in practice it will be quite difficult for an attacker to over-mount
// every fdinfo file for a process.
procfs::verify_is_procfs(&fd)?;
Ok(fd)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::error::ErrorKind;
use pretty_assertions::assert_matches;
#[test]
fn exists_unchecked() {
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.exists_unchecked("nonexist")
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ENOENT))),
r#"exists_unchecked("nonexist") -> ENOENT"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.exists_unchecked("uptime")
.map_err(|err| err.kind()),
Ok(()),
r#"exists_unchecked("uptime") -> Ok"#
);
}
#[test]
fn open_beneath() {
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.open_beneath("nonexist", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ENOENT))),
r#"open_beneath("nonexist") -> ENOENT"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.open_beneath("self", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"open_beneath("self") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.open_beneath("self/cwd", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"open_beneath("self/cwd") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.open_beneath("self/status", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Ok(_),
r#"open_beneath("self/status") -> Ok"#
);
}
#[test]
fn openat2_beneath() {
if syscalls::openat2::openat2_is_not_supported() {
return; // skip
}
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.openat2_beneath("nonexist", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ENOENT))),
r#"openat2_beneath("nonexist") -> ENOENT"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.openat2_beneath("self", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"openat2_beneath("self") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.openat2_beneath("self/cwd", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"openat2_beneath("self/cwd") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.openat2_beneath("self/status", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Ok(_),
r#"openat2_beneath("self/status") -> Ok"#
);
}
#[test]
fn opath_beneath_unchecked() {
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.opath_beneath_unchecked("nonexist", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ENOENT))),
r#"opath_beneath_unchecked("nonexist") -> ENOENT"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.opath_beneath_unchecked("self", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"opath_beneath_unchecked("self") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.opath_beneath_unchecked("self/cwd", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Err(ErrorKind::OsError(Some(libc::ELOOP))),
r#"opath_beneath_unchecked("self/cwd") -> ELOOP"#
);
assert_matches!(
RawProcfsRoot::UnsafeGlobal
.opath_beneath_unchecked("self/status", OpenFlags::O_RDONLY)
.map_err(|err| err.kind()),
Ok(_),
r#"opath_beneath_unchecked("self/status") -> Ok"#
);
}
}